用途
Guidance 是一个用于约束式 LLM 生成的 Python 库，由微软研究院开发。它的核心目标是让开发者能够精确控制语言模型的输出语法与结构，避免无效或格式错误的生成结果。适用于需要保证输出格式合法、减少重试、构建多步工作流的场景。
主要能力
1. 约束式生成
Guidance 支持通过正则表达式和文法（grammar）约束模型输出。正则表达式会在 token 级别转换为文法，生成过程中过滤掉不符合模式的 token，因此模型只能产生匹配的输出。例如可约束邮箱、日期（YYYY-MM-DD）、电话号码等格式。
2. 选项选择（select）
通过 select() 可将输出限制在给定的候选列表中，例如情感分类（positive/negative/neutral）或多选题答案，保证结果一定是合法选项之一。
3. Token Healing
Guidance 默认启用 token healing，自动“修复”提示词与生成内容之间的 token 边界问题，避免出现多余空格等不自然的分隔，使文本边界更自然，并提升模型表现。
4. 基于文法的生成
可使用上下文无关文法定义复杂结构，例如嵌套 JSON、编程语言语法或领域特定语言，从而生成结构合法的输出。
5. Guidance 函数
通过 @guidance 装饰器可创建可复用的生成模式；使用 @guidance(stateless=False) 可创建有状态函数，用于构建 ReAct 智能体等带工具调用的多步工作流。
6. 上下文管理器
Guidance 使用 Pythonic 的上下文管理器（system()、user()、assistant()）组织聊天式交互，角色分离清晰，便于阅读和维护。
使用方式
安装
基础安装：
pip install guidance
按后端安装：
pip install guidance[transformers] # Hugging Face 模型
pip install guidance[llama_cpp] # 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：
models.Anthropic(model="claude-sonnet-4-5-20250929", api_key=...) - OpenAI：
models.OpenAI(model="gpt-4o-mini", api_key=...) - 本地 Transformers：
Transformers("microsoft/Phi-4-mini-instruct", device="cuda") - 本地 llama.cpp：
LlamaCpp(model_path="/path/to/model.gguf", n_ctx=4096, n_gpu_layers=35)
常见模式
资料中给出了多种常见模式，包括：JSON 生成、分类、多步推理（chain-of-thought）、ReAct 智能体、数据抽取（实体抽取）等。
适用场景
- 需要正则或文法约束输出格式
- 需要保证 JSON/XML/代码等结构化输出合法
- 需要 token healing
- 使用本地模型（Transformers、llama.cpp）
- 偏好 Pythonic 语法
- 构建带控制流的多步工作流
限制与对比
资料中提供的对比表显示：
- Guidance 支持正则约束、CFG 文法、token healing、本地模型与 API 模型，语法为 Pythonic，学习曲线低。
- 不支持 Pydantic 验证（Instructor 和 Outlines 支持）。
- 若需要 Pydantic 验证与自动重试，可考虑 Instructor；若需要 JSON schema 验证，可考虑 Outlines；若偏好声明式查询语法，可考虑 LMQL。
性能特征
资料称：
- 延迟：受限输出场景下比传统提示方式快 30%–50%；token healing 减少不必要的重新生成；文法约束防止无效 token 生成。
- 内存：相比无约束生成开销极小；文法编译在首次使用后缓存；推理时进行高效的 token 过滤。
- Token 效率：避免在无效输出上浪费 token，无需重试循环，直接生成合法输出。
资源
- 文档：https://guidance.readthedocs.io
- GitHub：https://github.com/guidance-ai/guidance
- Notebooks：https://github.com/guidance-ai/guidance/tree/main/notebooks
- Discord：社区支持
参考文件
- references/constraints.md - 正则与文法模式
- references/backends.md - 后端配置
- references/examples.md - 生产级示例