Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Instructor：面向 LLM 的结构化输出

从任意 LLM 获取可靠的 JSON。基于 Pydantic 构建，提供验证、类型安全与 IDE 支持。

import instructor
from pydantic import BaseModel


# Define what you want
class User(BaseModel):
    name: str
    age: int


# Extract it from natural language
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)

就这么简单。 无需 JSON 解析、错误处理或重试。只需定义一个模型，即可获得结构化数据。

快速抽取用 Instructor，需要 Agent 时用 PydanticAI。 Instructor 让 schema 优先的流程保持简单、低成本。如果你的应用需要更丰富的 Agent 运行、内置可观测性（observability）或可共享的 trace，试试 PydanticAI. PydanticAI 是 Pydantic 团队官方的 Agent 运行时，在沿用相同 Pydantic 模型的同时，提供类型化工具、可回放数据集、评估（evals）以及生产级仪表盘。深入阅读 PydanticAI 文档 了解它如何扩展 Instructor 风格的工作流。

为什么选择 Instructor？

从 LLM 获取结构化数据很难。你需要：

1. 编写复杂的 JSON schema
2. 处理验证错误
3. 重试失败的抽取
4. 解析非结构化响应
5. 应对不同提供商的 API

Instructor 用一个简单的接口搞定这一切：

不用 Instructor

使用 Instructor

response = openai.chat.completions.create( model="gpt-5.4-mini", messages=[{"role": "user", "content": "..."}], tools=[ { "type": "function", "function": { "name": "extract_user", "parameters": { "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "integer"}, }, }, }, } ], ) # Parse response tool_call = response.choices[0].message.tool_calls[0] user_data = json.loads(tool_call.function.arguments) # Validate manually if "name" not in user_data: # Handle error... pass

client = instructor.from_provider("openai/gpt-5.4-mini") user = client.chat.completions.create( response_model=User, messages=[{"role": "user", "content": "..."}], ) # That's it! user is validated and typed

几秒即可完成安装

pip install instructor

或使用你的包管理器：

uv add instructor
poetry add instructor

适配所有主流提供商

同一份代码可用于任意 LLM 提供商：

# OpenAI
client = instructor.from_provider("openai/gpt-4o")

# Anthropic
client = instructor.from_provider("anthropic/claude-3-5-sonnet")

# Google
client = instructor.from_provider("google/gemini-pro")

# Ollama (local)
client = instructor.from_provider("ollama/llama3.2")

# With API keys directly (no environment variables needed)
client = instructor.from_provider("openai/gpt-4o", api_key="sk-...")
client = instructor.from_provider("anthropic/claude-3-5-sonnet", api_key="sk-ant-...")
client = instructor.from_provider("groq/llama-3.1-8b-instant", api_key="gsk_...")

# All use the same API!
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

生产就绪特性

自动重试

验证失败时会带上错误信息自动重试：

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 automatically retries when validation fails
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)
    # User(name=None, age=None)
    # User(name="John", age=None)
    # User(name="John", age=25)

嵌套对象

抽取复杂的嵌套数据结构：

from typing import List


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


class User(BaseModel):
    name: str
    age: int
    addresses: List[Address]


# Instructor handles nested objects automatically
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

生产环境在用

受到超过 10 万名开发者和企业的信赖，他们正在构建 AI 应用：

• 每月 300 万+ 次下载
• 1 万+ GitHub star
• 1000+ 社区贡献者

使用 Instructor 的公司包括 OpenAI、Google、Microsoft、AWS 等团队的许多 YC 创业公司。

快速上手

基础抽取

从任意文本中抽取结构化数据：

from pydantic import BaseModel
import instructor

client = instructor.from_provider("openai/gpt-4o-mini")


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


product = client.chat.completions.create(
    response_model=Product,
    messages=[{"role": "user", "content": "iPhone 15 Pro, $999, available now"}],
)

print(product)
# Product(name='iPhone 15 Pro', price=999.0, in_stock=True)

多语言支持

Instructor 简洁的 API 提供多种语言版本：

• Python - 原版
• TypeScript - 完整 TypeScript 支持
• Ruby - Ruby 实现
• Go - Go 实现
• Elixir - Elixir 实现
• Rust - Rust 实现

了解更多

• Documentation - 全面指南
• Examples - 可复制粘贴的示例
• Blog - 教程与最佳实践
• Discord - 向社区寻求帮助

为什么选 Instructor 而不是替代方案？

对比原生 JSON 模式：Instructor 提供自动验证、重试、流式输出和嵌套对象支持。无需手写 schema。

对比 LangChain/LlamaIndex：Instructor 专注一件事——结构化抽取。更轻量、更快、更易调试。

对比自研方案：经数千名开发者实战检验，能处理你尚未想到的边界情况。

贡献

欢迎贡献！查看我们的 good first issues 开始参与。

许可证

MIT License — 详见 LICENSE。

---

由 Instructor 社区构建。特别感谢 Jason Liu 以及所有 contributors。