LLM输出乱成一锅粥？Guidance约束生成框架让JSON/XML/代码100%合规输出🔥

核心功能

Guidance是微软研究院开源的LLM约束生成框架，GitHub已斩获18000+星，专门解决大模型输出格式不可控的老大难问题。它的核心能力是在token级别过滤无效输出，让模型从物理上就无法生成不符合规则的内容。

具体来说，Guidance能做这几件事：用正则表达式约束输出格式（邮箱、日期、手机号一次到位）；用上下文无关文法生成复杂嵌套结构；通过select()函数把模型输出锁定在固定选项里；还有一个很少被提到的Token Healing机制，自动修复tokenization边界问题，告别莫名其妙的双空格和截断。

多步骤工作流也是它的强项。用Python的@guidance装饰器就能把生成逻辑封装成可复用函数，ReAct Agent、思维链推理、实体抽取这些复杂流程，写起来跟普通Python代码没什么两样。

适用平台

Guidance作为一个Python库，天然适合嵌入各类AI编程工作流。如果你在用Cursor、GitHub Copilot、Claude Code或OpenAI Codex写代码，把Guidance的约束生成逻辑作为Skill加载进来，AI助手能更精准地理解你的结构化输出需求，生成的代码质量直接上一个台阶。

对于使用Gemini Code Assist、文心快码、腾讯云CodeBuddy、华为云CodeArts的开发者，Guidance同样是处理数据管道、API响应解析等场景的”最强外挂”。它支持OpenAI、Anthropic Claude、本地Transformers模型和llama.cpp，几乎覆盖所有主流后端，接入成本极低。

实操代码示例

最常见的场景：保证JSON输出100%合法。

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

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

with system():
    lm += 'You generate valid JSON.'

with user():
    lm += 'Generate a user profile with name, age, and email.'

with assistant():
    lm += '''{
    "name": ''' + gen('name', regex=r'"[A-Za-z ]+"', max_tokens=30) + ''',
    "age": ''' + gen('age', regex=r'[0-9]+', max_tokens=3) + ''',
    "email": ''' + gen('email', regex=r'"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}"', max_tokens=50) + '''
}'''

用select()做分类任务，彻底杜绝模型输出”Positive”、”POSITIVE”、”pos”这种乱七八糟的变体：

from guidance import models, select

lm = models.Anthropic('claude-sonnet-4-5-20250929')
text = 'This product is amazing!'

lm += f'Text: {text}'
lm += 'Sentiment: ' + select(['positive', 'negative', 'neutral'], name='sentiment')

print(lm['sentiment'])  # 只会是这三个之一

优势分析

跟同类工具比，Guidance的差异化优势很明显。Instructor擅长Pydantic验证但不支持正则约束；Outlines支持JSON Schema但Token Healing是缺项；LMQL语法偏SQL风格，学习曲线陡。Guidance把正则约束、文法支持、Token Healing、本地模型兼容四件事同时做好，这个组合在同类框架里是独一份。

性能上也有实测数据支撑：相比传统提示词方式，约束生成的延迟降低30-50%。原因很直接——模型不会在无效token上浪费算力，也不需要反复重试，直接走向合法输出的最短路径。文法编译结果会被缓存，第二次调用几乎没有额外开销。

应用场景

• 数据抽取流水线：从非结构化文本里提取人名、机构、日期、地点，每个字段用正则锁死格式，下游数据库直接入库，省掉清洗步骤。
• API响应生成：后端服务需要LLM返回固定格式的JSON，用Guidance替代”让模型自己想”的方式，彻底消灭解析异常。
• 自动化测试数据生成：批量生成符合业务规则的测试用例，邮箱格式、ID格式、日期范围全部受控。
• ReAct Agent构建：多轮工具调用场景下，用select()约束Action选择，防止模型幻觉出不存在的工具名。
• 内容审核分类：把分类标签锁死在预定义列表里，输出结果直接对接下游逻辑，不需要额外的标准化处理。

最佳实践

几个工程落地时容易踩的坑，提前说清楚。

正则约束要适度，别写得太严。^(John|Jane)$这种极端约束会让模型生成速度大幅下降，甚至卡死。合理的做法是约束格式而不是约束内容，比如用[A-Za-z ]+约束名字格式，而不是枚举所有可能的名字。

单行输出记得加stop=''，这是最容易被忽略的参数。不加的话模型可能一口气生成好几行，后续解析会出问题。

把高频使用的生成模式封装成@guidance函数，而不是每次都重写一遍。这不只是代码整洁的问题，复用函数还能让Guidance更好地做内部优化。

本地模型用户注意：Transformers后端和llama.cpp后端的约束生成效果最好，因为Guidance能直接操控logits。API模型（OpenAI、Anthropic）走的是不同路径，部分高级约束功能可能有差异，上线前务必做充分测试。

如果你的项目里有大量类似的Skill需要管理和复用，Skill优仓提供了一个统一的存储和分发平台，把Guidance这类框架封装成标准Skill之后，团队成员可以直接拉取使用，避免每个项目重复造轮子。