instructor
通过 Pydantic 模型定义，让任意 LLM 输出结构化、经过验证的 Python 对象
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
通过 Pydantic 模型定义，让任意 LLM 输出结构化、经过验证的 Python 对象
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
图1：567-labs 组织头像
想象你是一位厨师，收到了顾客各种千奇百怪的口头订单——有人用方言说，有人说得含糊，有人边说边改。你需要把这些随意的话语转化成一份结构清晰的厨房工单：菜名、数量、口味、特殊要求，一项项必须精准对应，不能有半点歧义。
这就是 LLM 在实际应用中最让人头疼的问题：模型能理解你的意思，但吐出来的往往是自由发挥的文本，而不是程序可以直接使用的结构化数据。Instructor 做的事情，就是给 LLM 加装一个翻译官，把随意的人类语言自动转化成精准的代码对象。
Instructor 由 Jason Liu 创立，由 567-labs 团队维护。项目最早源于作者在实际生产环境中处理 LLM 输出的痛苦经历：每次想让 AI 提取合同关键条款、生成用户画像、或者从评论中提取情感标签，都要写大量 JSON 解析代码、验证逻辑、重试机制。这些代码重复、脆弱、难以维护。
作者选择站在 Pydantic 的肩膀上解决这个问题。Pydantic 是 Python 生态中事实标准的数据验证库，通过类型注解（Type Hints）可以在运行时自动校验数据结构，任何不符合定义的值都会触发明确的报错。Instructor 将 Pydantic 的验证能力与 LLM 输出无缝对接，让模型自然学会按照你定义的格式输出。
项目目前保持极高的社区活跃度：GitHub 超过 13,000 颗星，PyPI 月下载量超过 300 万次，已被 OpenAI、Google、Microsoft、AWS 等公司的团队在实际产品中使用。
图2：Jason Liu（Instructor 创始人）
Instructor 的使用哲学极为简洁——先定义数据结构，再提问。开发者只需要用 Pydantic 定义一个 BaseModel，然后通过 Instructor 的客户端调用任意 LLM，返回结果直接就是一个经过验证的 Python 对象，无需手动解析 JSON、无需处理边界情况。
from pydantic import BaseModel
import instructor
class User(BaseModel):
name: str
age: int
client = instructor.from_provider("openai/gpt-4o-mini")
user = client.chat.completions.create(
response_model=User,
messages=[{"role": "user", "content": "John is 25 years old"}],
)
print(user) # User(name='John', age=25)
这段代码完成了传统方案需要几十行才能实现的工作。Instructor 内部自动完成以下步骤：
这是 Instructor 最核心的差异化能力。当模型第一次输出不符合验证规则时（比如字段缺失、类型错误），Instructor 会把 Pydantic 的报错信息作为上下文反馈给模型，要求模型根据错误信息修正输出。这个过程全自动进行，开发者无需编写任何重试逻辑。
from pydantic import BaseModel, field_validator
class User(BaseModel):
name: str
age: int
@field_validator('age')
def validate_age(cls, v):
if v < 0:
raise ValueError('Age must be positive')
return v
# Instructor 自动重试 3 次直到 age >= 0
user = client.chat.completions.create(
response_model=User,
messages=[{"role": "user", "content": "John is -5 years old"}],
max_retries=3,
)
Instructor 抽象掉了不同 LLM 提供商的 API 差异。通过 from_provider() 工厂方法，可以用同一套代码接入 OpenAI GPT-4o、Anthropic Claude、Google Gemini、Ollama 本地模型，甚至支持直接传入 API Key，无需配置环境变量。这种设计让应用在模型之间切换成本极低。
# 切换模型只需改一个字符串
client = instructor.from_provider("anthropic/claude-3-5-sonnet")
client = instructor.from_provider("google/gemini-pro")
client = instructor.from_provider("ollama/llama3.2") # 本地运行
Instructor 支持流式输出（Streaming），可以在模型生成完整答案的过程中逐步获得 Partial 对象，实现打字机效果。对于嵌套的复杂数据结构（如带地址的用户信息），Instructor 自动处理多层级的 JSON 解析和验证，无需额外代码。
Instructor 的架构围绕 Pydantic v2 的新特性重新设计，核心依赖包括：
代码采用模块化设计，核心逻辑分布在 instructor/ 包下。from_provider() 工厂根据 provider 字符串动态选择对应的适配器（Adapter），每种 Provider 适配器负责将 Instructor 的统一调用接口翻译为该 Provider 的 API 格式，同时处理 Provider 特定的输出解析逻辑。这种设计使得添加新 Provider 的成本极低，社区已经贡献了数十种 Provider 适配器。
代码质量较高：有完整的单元测试（pytest with unit 标记）和集成测试（integration 标记），在 CI/CD 中通过 pre-commit 钩子执行 ruff 代码检查。测试覆盖率通过 .coveragerc 配置管理。
Instructor 并非银弹，存在几个值得关注的局限：
1. 依赖外部 LLM API：作为 SDK 库，Instructor 本身不运行模型，必须调用外部 API。这带来了成本（每次调用都要付 LLM 提供商费用）和延迟（网络请求耗时）问题。对于需要完全本地化部署的场景，Instructor 只能配合 Ollama 等本地推理服务使用，效果取决于本地模型能力。
2. 重试机制的代价：自动重试虽然提升了可靠性，但在验证规则复杂或 LLM 质量较差时，可能产生 2-3 倍的额外 API 调用，间接增加成本和延迟。开发者需要在可靠性与成本之间权衡配置重试次数。
3. 准确性天花板：Instructor 的输出质量本质上受制于底层 LLM 的能力。对于模糊、歧义或信息缺失的输入，即使有重试机制，模型也可能无法给出正确结果。这是当前所有 LLM 应用面临的共同挑战。
4. 与 PydanticAI 的关系：Pydantic 官方团队推出了 PydanticAI，作为 Instructor 的官方升级版，定位更偏向 Agent 场景。Instructor 官方文档甚至主动推荐需要 Agent 能力时使用 PydanticAI。两者未来如何演进值得关注。
Instructor 的理念已延伸到 Python 之外，形成了多语言实现矩阵：
多语言支持意味着不同技术栈的团队都可以使用 Instructor 的核心理念，不必为了引入这个库而切换主力语言。
Instructor 代表的 Schema-first LLM 调用模式，正在成为 LLM 应用开发的主流范式。在 RAG（检索增强生成）系统、数据提取管道、内容审核流水线等场景中，结构化输出是不可替代的基础需求。Instructor 用极简的 API 封装了这个需求，让开发者可以把精力集中在业务逻辑上。
项目的高速增长（从 10K 到 13K stars 的跃升、300 万月下载量）说明市场对这个方向有强烈需求。随着 OpenAI Anthropic Google 等厂商陆续推出官方的 Function Calling / Structured Output API，Instructor 等中间件的定位也在演进——它们的价值正在从解决 API 能力不足转向提供统一的跨 Provider 接口和重试验证层。
如果你正在构建任何需要从 LLM 获取结构化数据的应用，Instructor 值得优先考虑。