Instructor：为 LLM 提供结构化输出

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

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)

就是这样。 无需 JSON 解析、错误处理或重试。只需定义一个模型即可获取结构化数据。

对于快速提取，使用 Instructor；当你需要智能体时，选择 PydanticAI。 Instructor 简化了以 Schema 为先的工作流，使其简单且低成本。如果你的应用需要更丰富的智能体执行能力、内置的可观测性或可共享的跟踪记录，请尝试 PydanticAI。PydanticAI 是 Pydantic 团队官方推出的智能体运行时，支持类型化工具、可重放的数据集、评估和生产级仪表盘，同时使用相同的 Pydantic 模型。深入了解 PydanticAI 文档，了解其如何扩展 Instructor 风格的工作流。

为什么选择 Instructor？

从 LLM 获取结构化数据非常困难。你需要：

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

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"},
                    },
                },
            },
        }
    ],
)

# 解析响应
tool_call = response.choices[0].message.tool_calls[0]
user_data = json.loads(tool_call.function.arguments)

# 手动验证
if "name" not in user_data:
    # 处理错误...
    pass

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

user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

# 就是这样！user 是已验证且类型安全的

几秒钟内完成安装

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（本地）
client = instructor.from_provider("ollama/llama3.2")

# 直接使用 API 密钥（无需设置环境变量）
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_...")

# 所有提供商使用相同的 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 会自动重试
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 自动处理嵌套对象
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

生产环境中使用

受到超过 10 万名开发者和 AI 应用构建公司的信赖：

• 每月 300 万+ 次下载
• GitHub 10K+ Stars
• 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 实现

了解更多

• 文档 - 全面指南
• 示例 - 开箱即用的代码
• 博客 - 教程和最佳实践
• Discord - 寻求社区帮助

为什么选择 Instructor 而不是其他方案？

vs 原始 JSON 模式：Instructor 提供自动验证、重试、流式支持和嵌套对象支持。无需手动编写 Schema。

vs LangChain/LlamaIndex：Instructor 专注于一件事——结构化提取。它更轻量、更快，且更容易调试。

vs 自定义解决方案：经过数千名开发者的实战检验。处理了你可能尚未想到的边界情况。

贡献

欢迎贡献！从我们的 good first issues 开始。

许可证

MIT 许可证 - 详见 LICENSE。

由 Instructor 社区构建。特别感谢 Jason Liu 和所有 贡献者。