guidance

Guidance：一个让AI"听话"变成可编程技术的语言范式

从"AI说啥是啥"到"AI说我想让它说啥"

你是否有这样的困扰：花了大价钱调用大模型API，让它生成一个JSON结构化数据，结果它要么给你返回一堆废话，要么格式完全对不上，一次次重试不仅浪费Token，还让人心态爆炸。

Guidance 解决的就是这个痛点。它是一种专门为控制大语言模型输出而设计的编程范式，最初由微软研究院开发并开源，如今已成为控制AI输出的主流工具之一，在GitHub上已积累超过21,000颗星。

图1：Guidance 约束生成示例，通过语法直接控制输出结构

背景故事：为什么需要 Guidance

在 Guidance 出现之前，开发者对AI输出的控制手段非常有限：

• 提示词工程（Prompt Engineering）：靠"哄"模型听话，效果不稳定，一次次调prompt像抽奖
• 后处理正则：模型输出后再用正则表达式解析，正确率低、鲁棒性差
• 微调（Fine-tuning）：成本高、周期长，改个格式就得重新训练

Guidance 的核心思路是：不再事后补救，而是让模型在生成过程中就遵守规则。它通过一套类似正则+CFG（上下文无关文法）的语法，在生成阶段就约束token采样过程，从根本上保证输出格式。

类比理解：就像给模型装上了"格式控制器"

如果说普通提示词是"口头要求"（"请给我返回一个JSON"），那么 Guidance 就是一份"技术合同"——它用语法精确描述期望的输出结构，模型必须按合同办事，不允许自由发挥。

打个比方：传统提示词就像对厨师说"随便做"，Guidance 则像给了一份详细的食谱配方——每一步放多少盐、火候多少、时间多久，都精确规定。

核心功能

1. 约束生成（Constrained Generation）

这是 Guidance 的灵魂。通过语法标记，可以精确控制模型输出的每一个 token：

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

with system():
    lm += "你是一个天气助手"

with user():
    lm += "今天北京天气怎么样？"

with assistant():
    lm += '{"city": "北京", "weather": '
    lm += gen(max_tokens=20, name="weather")  # 约束在JSON内生成
    lm += ', "temperature": '
    lm += gen(max_tokens=10)  # 继续约束
    lm += '}'

生成的JSON结构是固定的，模型只能填充具体内容，无法"跑偏"。

2. 选择约束（Select）

强制模型在给定选项中选择，而不是自由发挥：

lm += "情绪分类：" + select(["正面", "负面", "中性"], name="sentiment")

3. 循环与条件控制

支持 Python 式的循环和条件判断，可以根据模型输出动态控制后续生成：

# 循环生成直到满足条件
with while_(condition):
    lm += gen(max_tokens=50)

4. 多后端支持

Guidance 并不是绑定某个特定模型的工具，而是一个通用框架，支持多种推理后端：

后端	说明
Transformers	Hugging Face Transformers 模型，本地GPU推理
llama.cpp	量化模型，低显存运行
OpenAI	GPT-4、GPT-3.5 等 API
Azure AI	Azure OpenAI 服务
ONNX Runtime	GPU 加速推理

这种开放架构让开发者可以在不同场景下灵活切换——本地测试用 Transformers，生产环境用 OpenAI API。

5. Jupyter Notebook 交互界面

如果是在 Jupyter Notebook 环境中运行，Guidance 会自动渲染为交互式可视化 widget，不仅能看到纯文本输出，还能看到模型的思考过程和状态变化：

图2：Jupyter Notebook 中的 Guidance 可视化界面

技术架构

Guidance 的源码组织非常清晰：

guidance/
  _ast.py          # 抽象语法树，定义语法节点
  _grammar.py      # 文法解析器
  _parser.py       # 解析器实现
  _guidance.py      # 核心运行引擎
  models/          # 多后端模型适配层
  library/         # 内置语法库
  resources/       # 资源文件
  visual/          # 可视化渲染

核心依赖非常轻量：Jinja2（模板引擎）、Pydantic（数据验证）、numpy（数值计算），以及核心的 llguidance（Rust实现的高性能约束采样库）。

架构亮点：Guidance 将性能敏感的约束采样逻辑下沉到 Rust (llguidance crate)，Python 层只负责语法解析和流程控制。这种设计让它既能享受 Python 的灵活性，又能保持高性能。

上手体验

Guidance 的安装极为简单：

pip install guidance

一个最简单的例子（5分钟可跑通）：

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

phi_lm = Transformers("microsoft/Phi-4-mini-instruct")

lm = phi_lm
with system():
    lm += "你是一个有帮助的助手"

with user():
    lm += "1+1等于几？"

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

print(lm)

如果是本地推理，需要自行准备模型文件；如果使用 OpenAI API，只需设置 OPENAI_API_KEY 环境变量即可。

局限与争议

1. 对基础模型能力依赖强：约束生成只能保证格式，无法保证内容质量——如果模型本身对某个领域知识不足，输出仍然可能是错的
2. 延迟与成本的权衡：严格约束会减少模型"自由发挥"的空间，在某些需要创造性的场景下可能反而限制了输出质量
3. 维护者变更为独立组织：Guidance 最早是微软内部项目，后来独立为 guidance-ai 组织运营，虽然依然活跃，但商业支持不如以前明朗

行业意义

Guidance 代表的，是一种从"提示词工程"到"编程式AI控制"的范式转变。随着 AI 模型能力的不断提升，如何可靠地、可重复地使用 AI 将成为工程化的核心需求。Guidance 正是这个方向上最具代表性的开源实践之一。

它的 Star 增长曲线反映了整个 AI Agent 领域的爆发——越来越多的开发者意识到，仅靠"调 Prompt" 已经无法满足生产级 AI 应用的需求，必须有更可靠的结构化控制手段。

---

分析基于 guidance-ai/guidance GitHub 仓库（MIT License），数据采集时间：2026-05-26。