> [!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 用一个简单的接口搞定这一切：**

不用 Instructor

使用 Instructor

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

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

## 几秒即可完成安装 ```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)。 ---

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