Microsoft Guidance 模板评测：控制 LLM 输出格式

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)

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 格式：
{"name": "...", "price": ..., "category": "..."}

文本：{text}"""

response = llm(prompt)
# 可能输出：好的，这是JSON：{...}  ← 格式错误
# 可能输出：{"name": "...", "price": "贵"}  ← 类型错误
import json
try:
    data = json.loads(response)
    price = float(data["price"])  # 可能崩溃
except:
    # 陷入错误处理的泥潭...

@guidance
def extract_product(lm, text):
    lm += f"提取产品信息：\n{text}\n"
    lm += json("product", schema={
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "price": {"type": "number"},
            "category": {"type": "string"}
        },
        "required": ["name", "price", "category"]
    })
    return lm

result = lm + extract_product(text)
import json
product = json.loads(result["product"])
# 100% 保证合法 JSON，price 一定是数字

# 使用 select 时，Guidance 只计算选项 token 的概率
# 而非整个词表，推理速度更快

import time

# 自由生成
start = time.time()
lm + gen("answer", max_tokens=100)
free_time = time.time() - start

# 约束生成（select）
start = time.time()
lm + select(options=["A", "B", "C", "D"], name="choice")
constrained_time = time.time() - start

print(f"自由生成: {free_time:.2f}s")
print(f"约束生成: {constrained_time:.2f}s")
# 约束生成通常快 3-5 倍

@guidance
def rag_pipeline(lm, question, documents):
    # 检索阶段
    lm += "相关文档：\n"
    for i, doc in enumerate(documents):
        lm += f"[{i+1}] {doc}\n"
    
    # 判断是否需要更多信息
    lm += "\n信息是否足够回答问题？"
    lm += select(options=["是", "否"], name="sufficient")
    
    # 条件分支
    if lm["sufficient"] == "是":
        lm += "\n回答："
        lm += gen("answer", max_tokens=200)
    else:
        lm += "\n需要补充什么信息？"
        lm += gen("missing", max_tokens=50)
    
    return lm

# 获取生成 token 的概率
lm += gen("token", max_tokens=1)
logprobs = lm.get_logprobs("token")
# 可以用于置信度评估

@guidance
def multi_turn_chat(lm, messages):
    for msg in messages:
        if msg["role"] == "user":
            with user():
                lm += msg["content"]
        elif msg["role"] == "assistant":
            with assistant():
                lm += msg["content"]
    
    with assistant():
        lm += gen("response", max_tokens=300)
    
    return lm

# 开启日志查看实际 Prompt
from guidance import set_logger
import logging
set_logger(logging.DEBUG)