guidance

用途

Guidance 用于对 LLM 的输出进行语法层面的约束，确保生成结果严格符合指定格式。它适合需要控制输出结构、保证 JSON/XML/代码有效性、减少无效生成和重试的场景。

主要能力

正则约束：通过 regex 参数限制生成内容匹配特定模式，如邮箱、日期、电话号码等。
选择约束：使用 select() 将输出限定在预定义的选项列表中，适用于分类、多选题等。
文法约束：支持上下文无关文法（CFG），可定义复杂的嵌套结构，如 JSON、编程语言语法。
Token Healing：自动修复提示词与生成内容之间的 token 边界，避免多余空格或错误拼接。
上下文管理器：使用 system()、user()、assistant() 等上下文管理器构建对话式交互。
可复用函数：通过 @guidance 装饰器定义可复用的生成模式，支持有状态函数。
多后端支持：兼容 OpenAI、Anthropic Claude、Transformers、llama.cpp 等模型后端。

使用方式

安装：

pip install guidance

按需安装后端依赖：

pip install guidance[transformers]
pip install guidance[llama_cpp]

基本示例：

from guidance import models, gen

lm = models.OpenAI("gpt-4")
result = lm + "The capital of France is " + gen("capital", max_tokens=5)
print(result["capital"])

使用 Anthropic Claude 的对话格式：

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

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

with system():
    lm += "You are a helpful assistant."

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

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

正则约束示例：

lm += "Email: " + gen("email", regex=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")
lm += "Date: " + gen("date", regex=r"\d{4}-\d{2}-\d{2}")

选择约束示例：

from guidance import select
lm += "Sentiment: " + select(["positive", "negative", "neutral"], name="sentiment")

定义可复用函数：

from guidance import guidance, gen

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

适用场景

生成严格有效的 JSON/XML/代码
数据提取（实体、日期、地点等）
文本分类与情感分析
多步骤推理与链式思考
ReAct 智能体与工具调用
需要本地模型（Transformers、llama.cpp）的约束生成

限制

不提供 Pydantic 验证（与 Instructor 不同）
需要根据后端安装额外依赖
过于严格的约束可能导致生成失败或速度变慢
具体性能数据（如延迟降低百分比）来自资料描述，实际效果可能因模型和任务而异

资源

文档：https://guidance.readthedocs.io
GitHub：https://github.com/guidance-ai/guidance
Notebooks：https://github.com/guidance-ai/guidance/tree/main/notebooks

技能介绍

用途

主要能力

使用方式

适用场景

限制

资源