Instructor
用 Pydantic 模型从任意 LLM 稳定获取结构化 JSON，自动校验并重试。
- Star 数
- ★ 14k
- 最近更新
- 1 天前
- License
- MIT
- 主语言
- Python
- FA 评分
- 55/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台OpenAI API · Claude API
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- Python 后端工程师需要从客服对话、邮件等自然语言文本中抽取姓名、年龄、地址等字段并写入数据库。
- 不适合
- 希望用内置框架直接构建复杂智能体的团队
- 不愿引入 Pydantic 与 Python 依赖栈的业务系统
- 源码审查
- 55/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Instructor 是一个 Python 库，用于把大语言模型的自由文本输出约束为经过 Pydantic 校验的结构化对象。它通过 instructor.from_provider 统一接入 OpenAI、Anthropic、Google、Ollama 等提供方，调用时传入 response_model 即可获得类型安全的返回值。内置自动重试机制，在 Pydantic 校验失败时携带错误信息重新请求；通过 Partial 包装器支持流式返回逐步补全的对象；并原生处理嵌套模型与字段校验器。该库以 MIT 协议开源，通过 pip、uv 或 poetry 安装，作为依赖集成到调用方自己的 Python 应用中，本身不提供独立服务或托管端点。
Instructor 读取调用方定义的 Pydantic BaseModel，据此约束 LLM 输出。开发者用 instructor.from_provider("openai/gpt-4o-mini") 创建带补丁的客户端，再调用 client.chat.completions.create(response_model=User, messages=[...])，该库负责生成或注入对应的 JSON Schema/工具调用参数，发起模型请求，解析返回内容并构造 Pydantic 实例。若字段校验（含 @field_validator）失败，会按 max_retries 参数携带错误消息重新请求。传入 response_model=Partial[User] 并设置 stream=True 时，会逐步产出只填充了部分字段的对象。对嵌套模型如 List[Address] 自动递归处理。
- Python 后端工程师需要从客服对话、邮件等自然语言文本中抽取姓名、年龄、地址等字段并写入数据库。
- 数据团队要从非结构化文档中批量提取商品名称、价格、库存状态等结构化记录。
- 应用开发者希望在 OpenAI、Anthropic、Ollama 之间切换模型时保持同一套提取代码不变。
- 需要在流式响应中向前端逐字展示结构化对象生成进度的产品团队。
- 希望用 Pydantic 校验规则（如年龄必须为正）保证模型输出合法性的质量工程师。
- 在本地用 Ollama 运行模型、不希望数据出内网的隐私敏感项目。
如何安装或部署这个 Agent？
需要 Python 环境与对应模型提供方的访问凭据。使用包管理器安装：
pip install instructor或使用 uv / poetry：
uv add instructor
poetry add instructor安装后需准备所调用模型的 API 密钥（如 OpenAI 的 OPENAI_API_KEY），或本地运行 Ollama 等模型服务。
如何使用这个 Agent？
定义 Pydantic 模型，通过 from_provider 指定提供方与模型，并传入 response_model：
import instructor
from pydantic import BaseModel
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)也可直接传入 API 密钥，或切换到其他提供方：
client = instructor.from_provider("anthropic/claude-3-5-sonnet", api_key="sk-ant-...")
client = instructor.from_provider("ollama/llama3.2")启用自动重试与流式输出：
user = client.chat.completions.create(
response_model=User,
messages=[{"role": "user", "content": "..."}],
max_retries=3,
)
from instructor import Partial
for partial_user in client.chat.completions.create(
response_model=Partial[User],
messages=[{"role": "user", "content": "..."}],
stream=True,
):
print(partial_user)这个 Agent 有哪些优点和局限？
- 以 Pydantic 模型为中心，天然获得类型提示、IDE 补全与字段级校验能力。
- 校验失败时自动携带错误信息重试，减少手写解析与容错代码。
- from_provider 统一接口覆盖 OpenAI、Anthropic、Google、Ollama、Groq 等提供方，切换成本低。
- Partial 与 stream=True 支持流式产出逐步补全的对象，适合实时展示。
- 递归处理嵌套模型，无需手写复杂 JSON Schema。
- MIT 协议开源，可通过 pip、uv、poetry 直接集成进现有 Python 项目。
- 仅提供 Python 原语库，TypeScript、Ruby、Go、Rust 等版本为独立实现，需另行评估一致性。
- 依赖外部 LLM 提供方；实际成本取决于所选模型与调用量，且需要网络与 API 密钥。
- README 未给出内置可观测性、工具编排或评测能力，复杂智能体流程需自行搭建或改用 PydanticAI。
- 调用方需自行承担提供方 SDK 版本与模型命名变化带来的适配工作。
这个 Agent 与同类方案有什么区别？
README 明确对比了三类替代方案：与原始 JSON 模式相比，Instructor 提供自动校验、重试、流式与嵌套对象支持；与 LangChain/LlamaIndex 相比，它专注于结构化抽取，更轻量、更快、更易调试；与自研方案相比，强调已被大量开发者使用并覆盖边缘情况。README 同时建议需要完整智能体运行时、内置可观测性与可分享追踪时改用 PydanticAI。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Instructor 当前 | 55 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 14k | 1 天前 | Python | OpenAI API · Claude API |
| Adaline Gateway | 69 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 607 | 2 个月前 | TypeScript | OpenAI API · Claude API |
| Pydantic AI | 65 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 21k | 今天 | Python | OpenAI API · Claude API |
| Mirascope | 55 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 1.5k | 今天 | Python | Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
信任维度：文档对数据流向有一定说明（usage.md 明确 token 累计、缓存命中与 provider 计费差异，cli/usage.md 对遗留估算给出警告），依赖版本在 pyproject.toml 中设有上下界，属中等水平。但 least_privilege 仅得 1：库默认会 patch 客户端并自动重试，README 示例直接以 api_key 明文传入，未提示最小权限或密钥管理；user_confirmation 仅 1：自动重试与缓存命中均无显式用户确认机制；sensitive_data_handling 仅 1：未见对 PII/日志脱敏的说明；external_effects 仅 1：会向外部 LLM provider 发起真实请求并产生费用，但无成本护栏说明；rollback 仅 1：无回滚/撤销机制描述；source_attribution 得 2：LICENSE 与作者、贡献者链接清晰。
可靠性：self_consistency 得 2，文档与代码结构基本一致，但 README 与 getting-started 在 client.create 与 client.chat.completions.create 两种调用风格间并存，存在轻微不一致；dependency_availability 得 2，pyproject.toml 依赖有明确版本区间且 requirements.txt 锁定，但未声明已知漏洞缓解；failure_messages 得 2，文档展示 IncompleteOutputException 与验证重试反馈，属普通可用水平。
适应性：audience_and_scenarios 得 2，覆盖多 provider、多语言实现与 FastAPI/async 场景；capability_boundaries 得 2，README 明确建议复杂 agent 场景改用 PydanticAI，边界清晰；trigger_precision 仅 1，作为库而非 agent，触发条件依赖调用方，文档未系统说明何时该用哪种 mode；environment_fit 得 2，声明 Python 3.9+ 与多 provider extras。
惯例：information_architecture 得 2，docs 目录结构清晰；install_notes 得 2，安装与 extras 说明充分；naming_stability 仅 1，README 与 getting-started 混用 from_provider 与旧式 patch/from_openai，且仓库 URL 在 567-labs 与 jxnl 间不一致；examples_and_faq 得 2，FAQ 与示例丰富；known_limitations 得 2，usage.md 与 cli/usage.md 明确列出计费与累计限制；license 得 3，MIT 全文完整；versioning_changelog 仅 1，pyproject 有版本号但无 CHANGELOG 文件；maintenance_responsibility 仅 1，维护者邮箱列出但发布者身份未经验证，更新路径不明确。
有效性：output_usability 得 3，直接返回类型化 Pydantic 对象，输出可用性高；marginal_value 得 2，相较手写 JSON 解析有明确增益，但同类库竞争激烈；cost_benefit 得 2，文档提示 token 优化与缓存，但自动重试可能放大成本，未见成本护栏。
可验证性：claim_traceability 仅 1，README 声称 3M+ 月下载、10K+ stars、1000+ 贡献者及 OpenAI/Google 等公司使用，均无仓库内证据支撑；cross_source_corroboration 仅 1，测试文件存在但未在本次静态审查中执行，无法交叉印证；fact_inference_separation 仅 1，营销性表述与事实性说明混杂，未明确区分。
- README 中的下载量、star 数、贡献者数及大厂使用声明缺乏仓库内证据，属营销性表述，不应作为可靠性依据。
- 库默认自动重试并 patch 客户端，可能放大 API 成本；README 示例以明文 api_key 传参，需自行落实密钥管理与最小权限。
- 仓库 URL 在 567-labs 与 jxnl 之间不一致，发布者身份未经验证，更新与维护路径不明确。
- 文档混用 from_provider 与旧式 patch/from_openai 调用风格，迁移时需注意命名稳定性。
- 本次为静态审查，未执行任何测试或运行，测试质量与确定性未经验证。