用途
Instructor 用于从大语言模型(LLM)的响应中可靠地提取结构化数据。当你需要把 LLM 的自由文本输出转换为有类型、可校验的结构化对象时,可以使用它。典型需求包括:可靠地从 LLM 响应中抽取结构化数据、依据 Pydantic 模式自动校验输出、在校验失败时自动重试并处理错误、以类型安全的方式解析复杂 JSON、流式处理部分结果,以及用一致的 API 支持多个 LLM 提供商。
主要能力
响应模型(基于 Pydantic)
响应模型定义 LLM 输出的结构与校验规则。支持:
- 基础模型:使用 Python 类型提示获得类型安全,自动校验(如 word_count > 0),通过 Field 描述实现自文档化,并支持 IDE 自动补全。
- 嵌套模型:模型字段可以是另一个 Pydantic 模型,例如 Person 包含 Address。
- 可选字段:使用 Optional 或默认值,LLM 无需提供这些字段。
- 枚举约束:使用 Enum 限定字段只能取固定值,例如情感分析只允许 positive、negative、neutral。
校验
Pydantic 会自动校验 LLM 输出,校验失败时 Instructor 会重试。支持:
- 内置校验器:如 Field 的 min_length、max_length、ge、le,以及 EmailStr、HttpUrl 等类型。
- 自定义校验器:使用 field_validator 对单个字段编写校验逻辑,例如日期格式、数值范围。
- 模型级校验:使用 model_validator 对多个字段之间的关系进行校验,例如确保结束日期晚于开始日期。
自动重试
当校验失败时,Instructor 会自动重试,并把错误信息反馈给 LLM。流程为:LLM 生成输出 → Pydantic 校验 → 若无效则将错误信息发回 LLM → LLM 根据错误反馈再次尝试 → 重复直到达到 max_retries(默认 3 次)。
流式输出
支持实时处理部分结果:
- 流式部分对象:使用 create_partial 在 LLM 生成过程中逐步获得部分更新的对象,可用于实时更新 UI。
- 流式可迭代对象:使用 create_iterable 在列表项生成时逐个处理,例如逐个处理生成的任务。
多提供商支持
提供一致的 API 支持多个 LLM 提供商,包括 Anthropic Claude 和 OpenAI。
使用方式
安装
基础安装:
pip install instructor
按提供商安装:
pip install "instructor[anthropic]" # Anthropic Claude
pip install "instructor[openai]" # OpenAI
pip install "instructor[all]" # 所有提供商
快速开始(Anthropic 示例)
import instructor
from pydantic import BaseModel
from anthropic import Anthropic
class User(BaseModel):
name: str
age: int
email: str
client = instructor.from_anthropic(Anthropic())
user = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[{
"role": "user",
"content": "John Doe is 30 years old. His email is john@example.com"
}],
response_model=User
)
print(user.name) # "John Doe"
print(user.age) # 30
print(user.email) # "john@example.com"
快速开始(OpenAI 示例)
from openai import OpenAI
client = instructor.from_openai(OpenAI())
user = client.chat.completions.create(
model="gpt-4o-mini",
response_model=User,
messages=[{"role": "user", "content": "Extract: Alice, 25, alice@email.com"}]
)
自动重试示例
user = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[{
"role": "user",
"content": "Extract user from: John, age unknown"
}],
response_model=User,
max_retries=3 # 默认 3 次
)
流式部分对象示例
from instructor import Partial
class Story(BaseModel):
title: str
content: str
tags: list[str]
for partial_story in client.messages.create_partial(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[{
"role": "user",
"content": "Write a short sci-fi story"
}],
response_model=Story
):
print(f"Title: {partial_story.title}")
print(f"Content so far: {partial_story.content[:100]}...")
流式可迭代对象示例
class Task(BaseModel):
title: str
priority: str
tasks = client.messages.create_iterable(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[{
"role": "user",
"content": "Generate 10 project tasks"
}],
response_model=Task
)
for task in tasks:
print(f"- {task.title} ({task.priority})")
适用场景
- 需要结构化、经过校验的输出。
- 希望获得类型安全和 IDE 支持。
- 需要自动重试机制。
- 构建数据抽取系统。
最佳实践
- 使用清晰的字段描述,避免模糊命名。
- 使用适当的校验约束取值范围。
- 在提示中提供示例格式。
- 对固定类别使用枚举。
- 优雅处理缺失数据,使用可选字段和默认值。
与其他方案对比
资料中给出的对比表显示:
- 类型安全:Instructor 支持,手动 JSON 不支持,LangChain 部分支持,DSPy 支持。
- 自动校验:Instructor 支持,手动 JSON 和 LangChain 不支持,DSPy 有限支持。
- 自动重试:Instructor 支持,手动 JSON 和 LangChain 不支持,DSPy 支持。
- 流式:Instructor 支持,手动 JSON 不支持,LangChain 支持,DSPy 不支持。
- 多提供商:Instructor 支持,手动 JSON 需手动处理,LangChain 和 DSPy 支持。
- 学习曲线:Instructor 低,手动 JSON 低,LangChain 中,DSPy 高。
选择 Instructor 的情形:需要结构化且经过校验的输出、希望类型安全和 IDE 支持、需要自动重试、构建数据抽取系统。
选择其他方案的情形:DSPy 适合需要提示优化;LangChain 适合构建复杂链;手动方式适合简单的一次性抽取。
限制与注意事项
- 资料中未提供具体的收费、价格或平台信息。
- 资料中未提供性能或效果数据。
- 版本相关细节可能已过时,应以所安装版本的官方文档为准。
- 不要向外部 API 发送私有或敏感数据,除非获得用户同意。
- 涉及花钱、占用共享 GPU 或云配额、触及个人或患者数据、或不可撤销的操作前应先询问。
- 若指令中的函数、标志或端点在实际安装版本中不存在,应查阅该版本自身文档并告知用户,不要臆造 API。
资源
- 文档:https://python.useinstructor.com
- GitHub:https://github.com/jxnl/instructor
- Cookbook:https://python.useinstructor.com/examples
- Discord:提供社区支持
参考文件
- references/validation.md - 高级校验模式
- references/providers.md - 提供商特定配置
- references/examples.md - 真实用例
- references/provider-configuration.md - 提供商配置
- references/common-patterns.md - 常见模式
- references/advanced-features.md - 高级功能
- references/error-handling.md - 错误处理