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 让以模式为先的流程保持简单和低成本。如果你的应用需要更丰富的智能体运行、内置可观测性或可共享的追踪记录，请尝试 PydanticAI。PydanticAI 是 Pydantic 团队官方的智能体运行时，它在使用相同 Pydantic 模型的同时，增加了类型化工具、可重放的数据集、评估和生产仪表板等功能。请查阅 PydanticAI 文档，了解它如何扩展 Instructor 风格的工作流。

为什么选择 Instructor？

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

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

Instructor 通过一个简单的接口处理所有这些问题：

response = openai.chat.completions.create(
    model="gpt-4",
    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-4")

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('年龄必须为正数')
        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": "..."}],
)

生产环境用户

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

• 月下载量超过 300 万次
• GitHub 星标超过 10,000 个
• 社区贡献者超过 1,000 名

使用 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 而非其他方案？

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

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

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

贡献

我们欢迎贡献！查看我们的新手友好任务开始吧。

许可证

MIT 许可证 - 详见 LICENSE。

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