guidance

指南：受约束的大模型生成

何时使用此技能

在以下情况下使用 Guidance：

• 通过正则表达式或语法控制大模型输出语法
• 确保生成有效的 JSON/XML/代码
• 与传统提示词方法相比降低延迟
• 强制采用结构化格式（日期、电子邮件、ID 等）
• 使用 Python 风格的控制流构建多步工作流
• 通过语法约束防止输出无效内容

安装

# Base installation
pip install guidance

# With specific backends
pip install guidance[transformers]  # Hugging Face models
pip install guidance[llama_cpp]     # llama.cpp models

快速开始

基本示例：结构化生成

from guidance import models, gen

# Load model (supports OpenAI, Transformers, llama.cpp)
lm = models.OpenAI("gpt-4")

# Generate with constraints
result = lm + "The capital of France is " + gen("capital", max_tokens=5)

print(result["capital"])  # "Paris"

使用 Anthropic Claude

from guidance import models, gen, system, user, assistant

# Configure Claude
lm = models.Anthropic("claude-sonnet-4-5-20250929")

# Use context managers for chat format
with system():
    lm += "You are a helpful assistant."

with user():
    lm += "What is the capital of France?"

with assistant():
    lm += gen(max_tokens=20)

核心概念

1. 上下文管理器

Guidance 使用 Python 风格的上下文管理器进行聊天式交互。

from guidance import system, user, assistant, gen

lm = models.Anthropic("claude-sonnet-4-5-20250929")

# System message
with system():
    lm += "You are a JSON generation expert."

# User message
with user():
    lm += "Generate a person object with name and age."

# Assistant response
with assistant():
    lm += gen("response", max_tokens=100)

print(lm["response"])

优点：

• 自然的聊天流程
• 清晰的角色区分
• 易于阅读和维护

2. 受约束的生成

Guidance 使用正则表达式或语法确保输出符合指定模式。

正则表达式约束

from guidance import models, gen

lm = models.Anthropic("claude-sonnet-4-5-20250929")

# Constrain to valid email format
lm += "Email: " + gen("email", regex=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")

# Constrain to date format (YYYY-MM-DD)
lm += "Date: " + gen("date", regex=r"\d{4}-\d{2}-\d{2}")

# Constrain to phone number
lm += "Phone: " + gen("phone", regex=r"\d{3}-\d{3}-\d{4}")

print(lm["email"])  # Guaranteed valid email
print(lm["date"])   # Guaranteed YYYY-MM-DD format

工作原理：

• 将正则表达式转换为令牌级语法
• 在生成过程中筛除无效令牌
• 模型只能生成符合模式的输出

选择约束

from guidance import models, gen, select

lm = models.Anthropic("claude-sonnet-4-5-20250929")

# Constrain to specific choices
lm += "Sentiment: " + select(["positive", "negative", "neutral"], name="sentiment")

# Multiple-choice selection
lm += "Best answer: " + select(
    ["A) Paris", "B) London", "C) Berlin", "D) Madrid"],
    name="answer"
)

print(lm["sentiment"])  # One of: positive, negative, neutral
print(lm["answer"])     # One of: A, B, C, or D

3. 令牌修复

Guidance 会自动“修复”提示词与生成内容之间的令牌边界。

**问题：**分词会产生不自然的边界。

# Without token healing
prompt = "The capital of France is "
# Last token: " is "
# First generated token might be " Par" (with leading space)
# Result: "The capital of France is  Paris" (double space!)

**解决方案：**Guidance 回退一个令牌并重新生成。

from guidance import models, gen

lm = models.Anthropic("claude-sonnet-4-5-20250929")

# Token healing enabled by default
lm += "The capital of France is " + gen("capital", max_tokens=5)
# Result: "The capital of France is Paris" (correct spacing)

优点：

• 自然的文本边界
• 不会出现不自然的空格问题
• 更好的模型表现（模型看到的是自然的令牌序列）

4. 基于语法的生成

使用上下文无关语法定义复杂结构。

from guidance import models, gen

lm = models.Anthropic("claude-sonnet-4-5-20250929")

# JSON grammar (simplified)
json_grammar = """
{
    "name": <gen name regex="[A-Za-z ]+" max_tokens=20>,
    "age": <gen age regex="[0-9]+" max_tokens=3>,
    "email": <gen email regex="[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}" max_tokens=50>
}
"""

# Generate valid JSON
lm += gen("person", grammar=json_grammar)

print(lm["person"])  # Guaranteed valid JSON structure

适用场景：

• 复杂的结构化输出
• 嵌套数据结构
• 编程语言语法
• 特定领域语言

5. Guidance 函数

使用 @guidance 装饰器创建可复用的生成模式。

from guidance import guidance, gen, models

@guidance
def generate_person(lm):
    """Generate a person with name and age."""
    lm += "Name: " + gen("name", max_tokens=20, stop="\n")
    lm += "\nAge: " + gen("age", regex=r"[0-9]+", max_tokens=3)
    return lm

# Use the function
lm = models.Anthropic("claude-sonnet-4-5-20250929")
lm = generate_person(lm)

print(lm["name"])
print(lm["age"])

有状态函数：

@guidance(stateless=False)
def react_agent(lm, question, tools, max_rounds=5):
    """ReAct agent with tool use."""
    lm += f"Question: {question}\n\n"

    for i in range(max_rounds):
        # Thought
        lm += f"Thought {i+1}: " + gen("thought", stop="\n")

        # Action
        lm += "\nAction: " + select(list(tools.keys()), name="action")

        # Execute tool
        tool_result = tools[lm["action"]]()
        lm += f"\nObservation: {tool_result}\n\n"

        # Check if done
        lm += "Done? " + select(["Yes", "No"], name="done")
        if lm["done"] == "Yes":
            break

    # Final answer
    lm += "\nFinal Answer: " + gen("answer", max_tokens=100)
    return lm

后端配置

Anthropic Claude

from guidance import models

lm = models.Anthropic(
    model="claude-sonnet-4-5-20250929",
    api_key="your-api-key"  # Or set ANTHROPIC_API_KEY env var
)

OpenAI

lm = models.OpenAI(
    model="gpt-4o-mini",
    api_key="your-api-key"  # Or set OPENAI_API_KEY env var
)

本地模型（Transformers）

from guidance.models import Transformers

lm = Transformers(
    "microsoft/Phi-4-mini-instruct",
    device="cuda"  # Or "cpu"
)

本地模型（llama.cpp）

from guidance.models import LlamaCpp

lm = LlamaCpp(
    model_path="/path/to/model.gguf",
    n_ctx=4096,
    n_gpu_layers=35
)

常见模式

详情、代码示例和参数表： references/common-patterns.md。如果此步骤适用，请阅读该文件。

最佳实践

1. 使用正则表达式验证格式

# ✅ Good: Regex ensures valid format
lm += "Email: " + gen("email", regex=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")

# ❌ Bad: Free generation may produce invalid emails
lm += "Email: " + gen("email", max_tokens=50)

2. 使用 select() 处理固定类别

# ✅ Good: Guaranteed valid category
lm += "Status: " + select(["pending", "approved", "rejected"], name="status")

# ❌ Bad: May generate typos or invalid values
lm += "Status: " + gen("status", max_tokens=20)

3. 利用令牌修复

# Token healing is enabled by default
# No special action needed - just concatenate naturally
lm += "The capital is " + gen("capital")  # Automatic healing

4. 使用 stop 序列

# ✅ Good: Stop at newline for single-line outputs
lm += "Name: " + gen("name", stop="\n")

# ❌ Bad: May generate multiple lines
lm += "Name: " + gen("name", max_tokens=50)

5. 创建可复用函数

# ✅ Good: Reusable pattern
@guidance
def generate_person(lm):
    lm += "Name: " + gen("name", stop="\n")
    lm += "\nAge: " + gen("age", regex=r"[0-9]+")
    return lm

# Use multiple times
lm = generate_person(lm)
lm += "\n\n"
lm = generate_person(lm)

6. 平衡约束

# ✅ Good: Reasonable constraints
lm += gen("name", regex=r"[A-Za-z ]+", max_tokens=30)

# ❌ Too strict: May fail or be very slow
lm += gen("name", regex=r"^(John|Jane)$", max_tokens=10)

与替代方案的比较

特性	Guidance	Instructor	Outlines	LMQL
正则表达式约束	✅ 是	❌ 否	✅ 是	✅ 是
语法支持	✅ CFG	❌ 否	✅ CFG	✅ CFG
Pydantic 验证	❌ 否	✅ 是	✅ 是	❌ 否
令牌修复	✅ 是	❌ 否	✅ 是	❌ 否
本地模型	✅ 是	⚠️ 有限	✅ 是	✅ 是
API 模型	✅ 是	✅ 是	⚠️ 有限	✅ 是
Python 风格语法	✅ 是	✅ 是	✅ 是	❌ 类 SQL
学习曲线	低	低	中	高

何时选择 Guidance：

• 需要正则表达式或语法约束
• 希望使用令牌修复
• 使用控制流构建复杂工作流
• 使用本地模型（Transformers、llama.cpp）
• 偏好 Python 风格的语法

何时选择替代方案：

• Instructor：需要 Pydantic 验证和自动重试
• Outlines：需要 JSON Schema 验证
• LMQL：偏好声明式查询语法

性能特点

延迟降低：

• 对于受约束的输出，比传统提示词快 30-50%
• 令牌修复可减少不必要的重新生成
• 语法约束可防止生成无效令牌

内存使用：

• 与不受约束的生成相比，额外开销极小
• 首次使用后会缓存语法编译结果
• 推理时可高效筛选令牌

令牌效率：

• 防止在无效输出上浪费令牌
• 无需重试循环
• 直接生成有效输出

资源

• 文档：https://guidance.readthedocs.io
• GitHub：https://github.com/guidance-ai/guidance
• 笔记本：https://github.com/guidance-ai/guidance/tree/main/notebooks
• Discord：可获得社区支持

另请参阅

• references/constraints.md - 全面的正则表达式和语法模式
• references/backends.md - 特定后端的配置
• references/examples.md - 可用于生产环境的示例

Agent 操作流程

1. 检查环境。 确认框架版本、模型提供商、API 密钥和速率限制。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值，都应询问而不是猜测。
3. 先运行小规模版本。 使用已知输入测试单次调用或调用链，并检查原始输出。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 在小型标注数据集上进行评估；根据架构检查结构化输出；记录提示词和响应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
输出与预期架构不符	添加验证和重试，收紧架构，或简化提示词。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查阅已安装版本自身的文档（help()、--help、官方文档），进行调整，并告知用户。切勿编造 API。
必需的输入、标识符或参数含义不明确	询问用户，或在运行前明确说明所采用的假设。

完整性规则

• 切勿编造结果、参数、标识符、引文或统计数据。如果某项内容无法运行或验证，请如实说明。
• 未经用户同意，切勿向外部 API 发送私人或敏感数据。
• 此处与版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 涉及费用、占用共享 GPU 或云配额、处理个人或患者数据，或无法撤销的操作前，请先征求同意。