Instructor：用于大语言模型的结构化输出

从任何大语言模型中获取可靠的 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 是 25 岁"}],
)

print(user)  # User(name='John', age=25)

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

需要快速提取时使用 Instructor，而当您需要智能体时则选择 PydanticAI。 Instructor 让以模式为中心的工作流既简单又经济。如果您的应用需要更丰富的智能体运行、内置可观性或可共享的追踪功能，请尝试 PydanticAI。PydanticAI 是 Pydantic 团队推出的官方智能体运行时，在使用相同 Pydantic 模型的基础上，增加了类型化的工具、可回放的数据集、评估以及生产级仪表盘。请参阅 PydanticAI 文档，了解它如何扩展 Instructor 式的工作流程。

为什么选择 Instructor？

从大语言模型中获取结构化数据并不容易。您通常需要：

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

兼容各大主流提供商

您可以使用相同的代码与任何大语言模型提供商合作：

# 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_...")

# 使用方式完全一致！
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

生产就绪的功能

自动重试

当验证失败时，Instructor 会自动根据错误信息进行重试：

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

已被众多企业采用

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

• 每月下载量超过 300 万次
• GitHub 星标超过 1 万个
• 社区贡献者超过 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 美元，现在有货"}],
)

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 提供自动验证、重试机制、流式处理以及嵌套对象支持。无需手动编写 Schema。

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

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

参与贡献

我们欢迎各种形式的贡献！请查看我们的 good first issue，开始你的贡献之旅。

许可证

MIT 许可证——详情请参阅 LICENSE。

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

Instructor 快速上手指南

环境准备

• Python 3.7+（推荐 3.8+）
• 无需额外依赖（instructor 会自动安装 pydantic）

安装步骤

推荐使用国内镜像加速安装（清华大学源）：

pip install instructor -i https://pypi.tuna.tsinghua.edu.cn/simple

其他安装方式：

uv add instructor
poetry add instructor

基本使用

1. 定义 Pydantic 模型
2. 创建客户端
3. 调用 API 获取结构化数据

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 解析、错误处理或重试，直接获取类型安全的结构化数据。