567-labs--instructor/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/567-labs/instructor) · [上游 README](https://github.com/567-labs/instructor/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# Instructor：面向 LLM 的结构化输出

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

```python
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 解析、错误处理或重试。只需定义一个模型，即可获得结构化数据。

[![PyPI](https://img.shields.io/pypi/v/instructor?style=flat-square)](https://pypi.org/project/instructor/)
[![Downloads](https://img.shields.io/pypi/dm/instructor?style=flat-square)](https://pypi.org/project/instructor/)
[![GitHub Stars](https://img.shields.io/github/stars/567-labs/instructor?style=flat-square)](https://github.com/567-labs/instructor)
[![Discord](https://img.shields.io/discord/1192334452110659664?style=flat-square)](https://discord.gg/bD9YE9JArw)
[![Twitter](https://img.shields.io/twitter/follow/jxnlco?style=flat-square)](https://twitter.com/jxnlco)

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

## 为什么选择 Instructor？

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

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

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

<table>
<tr>
<td><b>不用 Instructor</b></td>
<td><b>使用 Instructor</b></td>
</tr>
<tr>
<td>

```python
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
```

</td>
<td>

```python
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
```

</td>
</tr>
</table>

## 几秒即可完成安装

```bash
pip install instructor
```

或使用你的包管理器：
```bash
uv add instructor
poetry add instructor
```

## 适配所有主流提供商

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

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

## 生产就绪特性

### 自动重试

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

```python
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,
)
```

### 流式支持

在生成过程中流式输出部分对象：

```python
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)
```

### 嵌套对象

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

```python
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 创业公司。

## 快速上手

### 基础抽取

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

```python
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](https://python.useinstructor.com) - 原版
- [TypeScript](https://js.useinstructor.com) - 完整 TypeScript 支持
- [Ruby](https://ruby.useinstructor.com) - Ruby 实现  
- [Go](https://go.useinstructor.com) - Go 实现
- [Elixir](https://hex.pm/packages/instructor) - Elixir 实现
- [Rust](https://rust.useinstructor.com) - Rust 实现

### 了解更多

- [Documentation](https://python.useinstructor.com) - 全面指南
- [Examples](https://python.useinstructor.com/examples/) - 可复制粘贴的示例  
- [Blog](https://python.useinstructor.com/blog/) - 教程与最佳实践
- [Discord](https://discord.gg/bD9YE9JArw) - 向社区寻求帮助

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

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

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

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

## 贡献

欢迎贡献！查看我们的 [good first issues](https://github.com/567-labs/instructor/labels/good%20first%20issue) 开始参与。

## 许可证

MIT License — 详见 [LICENSE](https://github.com/567-labs/instructor/blob/main/LICENSE)。

---

<p align="center">
由 Instructor 社区构建。特别感谢 <a href="https://twitter.com/jxnlco">Jason Liu</a> 以及所有 <a href="https://github.com/567-labs/instructor/graphs/contributors">contributors</a>。
</p>