outlines

Outlines：结构化文本生成

何时使用此技能

在以下情况下使用 Outlines：

• 保证生成内容具有有效的 JSON/XML/代码结构
• 使用 Pydantic 模型生成类型安全的输出
• 支持本地模型（Transformers、llama.cpp、vLLM）
• 以零开销结构化生成最大化推理速度
• 自动根据 JSON Schema 生成内容
• 在语法层面控制 Token 采样

安装

# Base installation
pip install outlines

# With specific backends
pip install outlines transformers  # Hugging Face models
pip install outlines llama-cpp-python  # llama.cpp
pip install outlines vllm  # vLLM for high-throughput

快速入门

基本示例：分类

import outlines
from typing import Literal

# Load model
model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")

# Generate with type constraint
prompt = "Sentiment of 'This product is amazing!': "
generator = outlines.generate.choice(model, ["positive", "negative", "neutral"])
sentiment = generator(prompt)

print(sentiment)  # "positive" (guaranteed one of these)

使用 Pydantic 模型

from pydantic import BaseModel
import outlines

class User(BaseModel):
    name: str
    age: int
    email: str

model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")

# Generate structured output
prompt = "Extract user: John Doe, 30 years old, [email protected]"
generator = outlines.generate.json(model, User)
user = generator(prompt)

print(user.name)   # "John Doe"
print(user.age)    # 30
print(user.email)  # "[email protected]"

核心概念

1. 受约束的 Token 采样

Outlines 使用有限状态机（FSM）在 Logit 层面约束 Token 生成。

工作原理：

1. 将 Schema（JSON/Pydantic/正则表达式）转换为上下文无关语法（CFG）
2. 将 CFG 转换为有限状态机（FSM）
3. 在生成过程中，于每一步过滤无效 Token
4. 仅存在一个有效 Token 时直接快进

优势：

• 零开销：在 Token 层面进行过滤
• 速度提升：跳过确定性路径
• 保证有效性：不可能生成无效输出

import outlines

# Pydantic model -> JSON schema -> CFG -> FSM
class Person(BaseModel):
    name: str
    age: int

model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")

# Behind the scenes:
# 1. Person -> JSON schema
# 2. JSON schema -> CFG
# 3. CFG -> FSM
# 4. FSM filters tokens during generation

generator = outlines.generate.json(model, Person)
result = generator("Generate person: Alice, 25")

2. 结构化生成器

Outlines 为不同的输出类型提供专用生成器。

选项生成器

# Multiple choice selection
generator = outlines.generate.choice(
    model,
    ["positive", "negative", "neutral"]
)

sentiment = generator("Review: This is great!")
# Result: One of the three choices

JSON 生成器

from pydantic import BaseModel

class Product(BaseModel):
    name: str
    price: float
    in_stock: bool

# Generate valid JSON matching schema
generator = outlines.generate.json(model, Product)
product = generator("Extract: iPhone 15, $999, available")

# Guaranteed valid Product instance
print(type(product))  # <class '__main__.Product'>

正则表达式生成器

# Generate text matching regex
generator = outlines.generate.regex(
    model,
    r"[0-9]{3}-[0-9]{3}-[0-9]{4}"  # Phone number pattern
)

phone = generator("Generate phone number:")
# Result: "555-123-4567" (guaranteed to match pattern)

整数/浮点数生成器

# Generate specific numeric types
int_generator = outlines.generate.integer(model)
age = int_generator("Person's age:")  # Guaranteed integer

float_generator = outlines.generate.float(model)
price = float_generator("Product price:")  # Guaranteed float

3. 模型后端

Outlines 支持多种本地后端和基于 API 的后端。

Transformers（Hugging Face）

import outlines

# Load from Hugging Face
model = outlines.models.transformers(
    "microsoft/Phi-3-mini-4k-instruct",
    device="cuda"  # Or "cpu"
)

# Use with any generator
generator = outlines.generate.json(model, YourModel)

llama.cpp

# Load GGUF model
model = outlines.models.llamacpp(
    "./models/llama-3.1-8b-instruct.Q4_K_M.gguf",
    n_gpu_layers=35
)

generator = outlines.generate.json(model, YourModel)

vLLM（高吞吐量）

# For production deployments
model = outlines.models.vllm(
    "meta-llama/Llama-3.1-8B-Instruct",
    tensor_parallel_size=2  # Multi-GPU
)

generator = outlines.generate.json(model, YourModel)

OpenAI（支持有限）

# Basic OpenAI support
model = outlines.models.openai(
    "gpt-4o-mini",
    api_key="your-api-key"
)

# Note: Some features limited with API models
generator = outlines.generate.json(model, YourModel)

4. Pydantic 集成

Outlines 提供一流的 Pydantic 支持，并可自动转换 Schema。

基本模型

from pydantic import BaseModel, Field

class Article(BaseModel):
    title: str = Field(description="Article title")
    author: str = Field(description="Author name")
    word_count: int = Field(description="Number of words", gt=0)
    tags: list[str] = Field(description="List of tags")

model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")
generator = outlines.generate.json(model, Article)

article = generator("Generate article about AI")
print(article.title)
print(article.word_count)  # Guaranteed > 0

嵌套模型

class Address(BaseModel):
    street: str
    city: str
    country: str

class Person(BaseModel):
    name: str
    age: int
    address: Address  # Nested model

generator = outlines.generate.json(model, Person)
person = generator("Generate person in New York")

print(person.address.city)  # "New York"

枚举和字面量

from enum import Enum
from typing import Literal

class Status(str, Enum):
    PENDING = "pending"
    APPROVED = "approved"
    REJECTED = "rejected"

class Application(BaseModel):
    applicant: str
    status: Status  # Must be one of enum values
    priority: Literal["low", "medium", "high"]  # Must be one of literals

generator = outlines.generate.json(model, Application)
app = generator("Generate application")

print(app.status)  # Status.PENDING (or APPROVED/REJECTED)

常见模式

详细信息、代码示例和参数表：references/common-patterns.md。适用此步骤时请阅读。

后端配置

详细信息、代码示例和参数表：references/backend-configuration.md。适用此步骤时请阅读。

最佳实践

1. 使用具体类型

# ✅ Good: Specific types
class Product(BaseModel):
    name: str
    price: float  # Not str
    quantity: int  # Not str
    in_stock: bool  # Not str

# ❌ Bad: Everything as string
class Product(BaseModel):
    name: str
    price: str  # Should be float
    quantity: str  # Should be int

2. 添加约束

from pydantic import Field

# ✅ Good: With constraints
class User(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    age: int = Field(ge=0, le=120)
    email: str = Field(pattern=r"^[\w\.-]+@[\w\.-]+\.\w+$")

# ❌ Bad: No constraints
class User(BaseModel):
    name: str
    age: int
    email: str

3. 使用枚举表示类别

# ✅ Good: Enum for fixed set
class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"

class Task(BaseModel):
    title: str
    priority: Priority

# ❌ Bad: Free-form string
class Task(BaseModel):
    title: str
    priority: str  # Can be anything

4. 在提示词中提供上下文

# ✅ Good: Clear context
prompt = """
Extract product information from the following text.
Text: iPhone 15 Pro costs $999 and is currently in stock.
Product:
"""

# ❌ Bad: Minimal context
prompt = "iPhone 15 Pro costs $999 and is currently in stock."

5. 处理可选字段

from typing import Optional

# ✅ Good: Optional fields for incomplete data
class Article(BaseModel):
    title: str  # Required
    author: Optional[str] = None  # Optional
    date: Optional[str] = None  # Optional
    tags: list[str] = []  # Default empty list

# Can succeed even if author/date missing

与其他方案的比较

功能	Outlines	Instructor	Guidance	LMQL
Pydantic 支持	✅ 原生	✅ 原生	❌ 不支持	❌ 不支持
JSON Schema	✅ 支持	✅ 支持	⚠️ 有限	✅ 支持
正则表达式约束	✅ 支持	❌ 不支持	✅ 支持	✅ 支持
本地模型	✅ 完整	⚠️ 有限	✅ 完整	✅ 完整
API 模型	⚠️ 有限	✅ 完整	✅ 完整	✅ 完整
零开销	✅ 是	❌ 否	⚠️ 部分	✅ 是
自动重试	❌ 否	✅ 是	❌ 否	❌ 否
学习曲线	低	低	低	高

何时选择 Outlines：

• 使用本地模型（Transformers、llama.cpp、vLLM）
• 需要最高推理速度
• 需要 Pydantic 模型支持
• 要求零开销结构化生成
• 控制 Token 采样过程

何时选择其他方案：

• Instructor：需要支持自动重试的 API 模型
• Guidance：需要 Token 修复和复杂工作流
• LMQL：偏好声明式查询语法

性能特点

速度：

• 零开销：结构化生成与不受约束的生成一样快
• 快进优化：跳过确定性 Token
• 比生成后验证方案快 1.2-2 倍

内存：

• 每个 Schema 编译一次 FSM（并缓存）
• 运行时开销极小
• 搭配 vLLM 可高效实现高吞吐量

准确性：

• 输出 100% 有效（由 FSM 保证）
• 无需重试循环
• 确定性 Token 过滤

资源

• 文档：https://outlines-dev.github.io/outlines
• GitHub：https://github.com/outlines-dev/outlines
• Discord：https://discord.gg/R9DSu34mGd
• 博客：https://blog.dottxt.co

另请参阅

• references/json_generation.md - 全面的 JSON 和 Pydantic 模式
• references/backends.md - 特定后端的配置
• references/examples.md - 可用于生产环境的示例

Agent 操作流程

1. 检查环境。 确认框架版本、模型提供商、API 密钥和速率限制。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问用户，而不是猜测。
3. 先运行小规模测试。 使用已知输入测试单次调用或调用链，并检查原始输出。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 在小型标注集上进行评估；检查结构化输出是否符合其架构；记录提示词和响应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生这种情况	请这样做
输出与预期架构不匹配	添加验证和重试，收紧架构，或简化提示词。
这些说明中的函数、标志或端点在已安装的版本中不存在	查看已安装版本自身的文档（help()、--help、官方文档），进行调整，并告知用户。切勿捏造 API。
必需的输入、标识符或参数存在歧义	询问用户，或在运行前明确说明所作假设。

诚信准则

• 切勿伪造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请直截了当地说明。
• 未经用户同意，切勿将私人或敏感数据发送到外部 API。
• 此处与特定版本相关的细节可能已经过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、消耗共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，执行前请先征求同意。