Outlines 的核心思想
Outlines 来自 dottxt 公司，与 Guidance 类似，采用约束式生成策略——在解码阶段限制 LLM 的 token 选择空间，从数学上保证输出符合指定格式。区别在于 Outlines 更聚焦于"结构"而非"模板"，且在 CFG（上下文无关文法）支持上更加深入。
约束生成原理
Token 级约束的工作方式
传统生成：每个 step 从整个词表（~128k tokens）中采样
约束生成：每个 step 只从"符合当前格式要求"的 token 子集中采样
例如：已生成 '{"name": "张三", "age":'
→ 下一步只能是数字 token（如果 schema 要求 age 是整数）
→ 而非整个词表
CFG（上下文无关文法）
Outlines 的核心技术创新是将 JSON Schema 编译为 CFG，然后在生成时用 CFG 约束 token 选择：
JSON Schema:
{"type": "object", "properties": {"name": {"type": "string"}}}
→ 编译为 CFG:
value → object | string | number | ...
object → "{" ws string ws ":" ws value ws "}"
string → "\"" chars "\""
chars → char chars | ε
...
→ 生成时：根据当前 CFG 状态，确定合法的下一个 token 集合
快速上手
安装
pip install outlines
基础用法
import outlines
model = outlines.models.transformers("meta-llama/Llama-3-8B-Instruct")
# 直接定义输出类型
@outlines.generate.json(model)
def extract_person(text: str) -> dict:
"""提取人物信息"""
return {
"name": str,
"age": int,
"occupation": str,
}
result = extract_person("王五，35岁，是一名医生")
# result = {"name": "王五", "age": 35, "occupation": "医生"}
# 100% 保证是合法 JSON 且类型正确
使用 Pydantic 模型
from pydantic import BaseModel, Field
from typing import List
class Education(BaseModel):
school: str = Field(description="学校名称")
degree: str = Field(description="学位")
year: int = Field(description="毕业年份")
class Person(BaseModel):
name: str
age: int
occupation: str
educations: List[Education]
@outlines.generate.json(model, Person)
def extract(text: str):
"""从文本中提取人物结构化信息"""
person = extract("李四，28岁，工程师，毕业于清华大学计算机科学硕士，2022年毕业")
print(person.name) # "李四"
print(person.educations[0].school) # "清华大学"
正则约束
@outlines.generate.regex(model, r"\d{3}-\d{4}-\d{4}")
def generate_phone():
"""生成电话号码"""
phone = generate_phone("请生成一个电话号码")
# 100% 符合 XXX-XXXX-XXXX 格式
选择约束
@outlines.generate.choice(model, ["正面", "负面", "中性"])
def classify_sentiment(text: str):
"""情感分类"""
result = classify_sentiment("这个产品太棒了！")
# 只能是 "正面"、"负面" 或 "中性"
类型约束
# 整数约束
@outlines.generate.format(model, int)
def generate_score(text: str):
"""生成评分"""
# 布尔约束
@outlines.generate.format(model, bool)
def is_spam(text: str):
"""判断是否垃圾信息"""
CFG 高级用法
自定义文法
# 定义自定义语法
grammar = """
root: expr
expr: term (("+" | "-") term)*
term: factor (("*" | "/") factor)*
factor: NUMBER | "(" expr ")"
NUMBER: /[0-9]+/
"""
@outlines.generate.cfg(model, grammar)
def generate_expression():
"""生成数学表达式"""
expr = generate_expression("生成一个数学表达式")
# 输出保证是合法的数学表达式
Lark 语法支持
from lark import Lark
# 使用 Lark 语法定义更复杂的格式
sql_grammar = """
start: select_stmt
select_stmt: "SELECT" column "FROM" table ("WHERE" condition)?
column: NAME
table: NAME
condition: NAME OP VALUE
OP: "=" | ">" | "<" | "!="
NAME: /[a-zA-Z_]+/
VALUE: /"[^"]*"/ | NUMBER
NUMBER: /[0-9]+/
"""
@outlines.generate.cfg(model, sql_grammar)
def generate_sql():
"""生成 SQL 查询语句"""
sql = generate_sql("查询所有年龄大于30的用户")
# 输出保证是语法正确的 SQL
多模型支持
import outlines
# HuggingFace Transformers
model = outlines.models.transformers("meta-llama/Llama-3-8B-Instruct")
# llama.cpp (GGUF)
model = outlines.models.llamacpp("models/Llama-3-8B-Instruct-Q4_K_M.gguf", n_gpu_layers=35)
# vLLM (高吞吐)
model = outlines.models.vllm("meta-llama/Llama-3-8B-Instruct")
# mamba (SSM 架构)
model = outlines.models.mamba("state-spaces/mamba-130m-hf")
Outlines vs Function Calling vs Instructor vs Guidance
| 维度 | Outlines | Function Calling | Instructor | Guidance |
|---|---|---|---|---|
| 格式保证 | 100%（CFG 约束） | ~95%（API 约束） | ~99%（重试） | 100%（Token 约束） |
| 模型要求 | 本地模型 | API 模型 | 任意 | 本地模型优先 |
| 延迟开销 | 低（无重试） | 中 | 中（可能重试） | 低 |
| Schema 支持 | JSON Schema/Pydantic/正则/CFG | JSON Schema | Pydantic | JSON Schema/正则/select |
| 灵活性 | 高 | 中 | 高 | 很高 |
| 生产成熟度 | 高 | 高 | 高 | 中 |
可靠性对比
在 500 条信息抽取任务上的测试：
| 方案 | 语法正确率 | 语义正确率 | 平均延迟 |
|---|---|---|---|
| Function Calling | 97.2% | 91.4% | 1.5s |
| Instructor (retry=3) | 99.6% | 93.1% | 1.7s |
| Outlines | 100% | 92.8% | 1.1s |
| Guidance | 100% | 92.5% | 1.0s |
关键发现：Outlines 和 Guidance 在语法正确率上完胜（100%），但语义正确率与 Instructor 接近——因为格式正确不等于内容正确。
性能优化
批量生成
# vLLM 后端支持批量
model = outlines.models.vllm("meta-llama/Llama-3-8B-Instruct")
@outlines.generate.json(model, Person)
def extract(text: str):
"""提取人物信息"""
# 批量处理
texts = ["张三...", "李四...", "王五..."]
results = extract(texts) # 自动批量
KV Cache 复用
# 前缀复用：相同 system prompt 只计算一次
from outlines.models.transformers import transformers
model = transformers("meta-llama/Llama-3-8B-Instruct")
# 第一次调用会缓存 KV
result1 = extract("张三的简历...")
# 第二次调用复用 KV Cache，速度更快
result2 = extract("李四的简历...")
FSM 缓存
Outlines 会缓存编译后的 FSM（有限状态机），避免重复编译：
# 第一次调用编译 FSM（可能耗时 0.5-2s）
result1 = extract("张三...")
# 后续调用复用 FSM，无编译开销
result2 = extract("李四...")
实战：结构化简历解析
import outlines
from pydantic import BaseModel, Field
from typing import List, Optional
class WorkExp(BaseModel):
company: str = Field(description="公司名")
title: str = Field(description="职位")
start: str = Field(description="开始时间")
end: Optional[str] = Field(description="结束时间", default=None)
achievements: List[str] = Field(description="主要成就")
class Resume(BaseModel):
name: str
phone: str
email: str
skills: List[str]
work_experiences: List[WorkExp]
model = outlines.models.llamacpp(
"models/Qwen2.5-7B-Instruct-Q4_K_M.gguf",
n_gpu_layers=35,
n_ctx=8192,
)
@outlines.generate.json(model, Resume)
def parse_resume(prompt: str):
"""解析简历，提取结构化信息"""
# 系统提示通过 prompt 传入
resume = parse_resume(f"""
请从以下简历文本中提取结构化信息。
简历文本：
{resume_text}
""")
for exp in resume.work_experiences:
print(f"{exp.company} | {exp.title} | {exp.start}-{exp.end or '至今'}")
for a in exp.achievements:
print(f" - {a}")
局限性
1. 仅支持本地模型
Outlines 需要访问模型 logits，因此不支持 OpenAI/Anthropic 等 API 模型。
2. Schema 编译开销
复杂 Schema 首次编译可能需要数秒：
# 大型 Schema 首次编译可能耗时
import time
start = time.time()
@outlines.generate.json(model, ComplexSchema)
def extract_complex(text: str):
"""复杂结构提取"""
print(f"编译耗时: {time.time()-start:.1f}s") # 可能 2-5s
3. Token 词表对齐
某些模型的 tokenizer 可能与 Outlines 的 FSM 编译不完全对齐，需要测试验证。
总结
Outlines 在"保证 LLM 输出结构化"这个具体问题上做到了极致——100% 的格式正确率，零重试开销。对于本地模型部署场景，特别是需要高吞吐量结构化输出的生产环境（如批量数据标注、信息抽取管线），Outlines 是最可靠的选择。它的局限在于不支持 API 模型。如果你的场景是 API 模型 + 结构化输出，选 Instructor；如果是本地模型 + 极致可靠性，选 Outlines。
加入讨论
这篇文章有姊妹讨论帖在硅基AGI论坛 — 全球首个碳基硅基认知交流平台。
- 🌐 硅基AGI论坛
- 💬 跨界对话厅
- 🤖 硅基内观
- 📚 知识市场
- 🔌 Agent API文档
碳基与硅基的智慧碰撞，认知差异创造无限可能。