Guidance 的设计理念 Prompt 工程的一个核心矛盾：你希望 LLM 严格遵循格式，但 LLM 本质上是在"续写文本"，格式控制全靠提示词的"软约束"。Microsoft Guidance 提出了另一种思路——用模板语言硬约束 LLM 的输出结构。
Guidance 不是让 LLM “生成一个 JSON”，而是在 token 层面强制 LLM “先输出 {"，再输出 key，再输出 "："，以此类推。这种约束式生成从根本上消除了格式错误。
核心语法 基础模板 from guidance import models, gen, system, user, assistant # 加载模型 lm = models.LlamaCpp("models/Llama-3-8B-Instruct-Q4_K_M.gguf", n_gpu_layers=35) # 使用角色标签 with system(): lm += "你是一个有帮助的助手。" with user(): lm += "解释量子纠缠。" with assistant(): lm += gen("response", max_tokens=200) print(lm["response"]) 变量插值 topic = "量子计算" difficulty = "初学者" lm = lm + f"请用{difficulty}能理解的方式解释{topic}。" + gen("answer", max_tokens=300) 条件逻辑 from guidance import guidance @guidance def answer_question(lm, question, use_cot=True): if use_cot: lm += "\n让我一步步思考。\n" lm += gen("reasoning", max_tokens=200) + "\n" lm += "因此，答案是：" lm += gen("answer", max_tokens=100) else: lm += "\n答案：" lm += gen("answer", max_tokens=100) return lm lm += answer_question("光合作用的原理是什么？", use_cot=True) 循环 @guidance def generate_questions(lm, topic, n=3): lm += f"关于{topic}的{n}个问题：\n" for i in range(n): lm += f"\n{i+1}. " lm += gen(f"question_{i}", max_tokens=50, stop=["\n", "?"]) lm += "?" return lm lm += generate_questions("机器学习", n=5) 结构化输出保证 JSON 保证输出 import guidance from guidance import json @guidance def extract_entity(lm, text): lm += f"从以下文本中提取实体信息：\n{text}\n" lm += json("entity", schema={ "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "integer"}, "occupation": {"type": "string"} }, "required": ["name", "age", "occupation"] }) return lm lm += extract_entity("李四今年30岁，是一名软件工程师") # 输出保证是合法 JSON，因为 Guidance 在 token 层面约束了结构 正则约束 from guidance import regex @guidance def generate_phone(lm): lm += "电话号码：" lm += regex(pattern=r"\d{3}-\d{3}-\d{4}") return lm # 输出格式保证为 XXX-XXX-XXXX 选择题约束 from guidance import select @guidance def classify(lm, text): lm += f"文本：{text}\n类别：" lm += select(options=["正面", "负面", "中性"], name="sentiment") return lm # LLM 只能输出这三个选项之一，不可能输出其他内容 与传统 Prompt 工程对比 格式可靠性 方法 JSON 成功率 格式控制方式 容错能力 手写 Prompt ~85% 软约束（提示词） 无 Function Calling ~95% API 约束 需手动 Guidance ~100% Token 级硬约束 内置 代码对比：生成结构化产品信息 传统 Prompt 方式：
...
