mirrors / 567-labs--instructor

项目文件夹

567-labs--instructor
文件
main
T
wehub-resource-sync b67ff364bc
Test / Offline Coverage Tests (Python 3.12) (push) Has been cancelled
详情
Test / Offline Coverage Tests (Python 3.13) (push) Has been cancelled
详情
Test / Offline Coverage Tests (Python 3.9) (push) Has been cancelled
详情
Test / Full Coverage (Python 3.11) (push) Has been cancelled
详情
ty / type-check (push) Has been cancelled
详情
Ruff / Ruff (push) Has been cancelled
详情
Test / Core Tests (push) Has been cancelled
详情
Test / Offline Coverage Tests (Python 3.10) (push) Has been cancelled
详情
Test / Offline Coverage Tests (Python 3.11) (push) Has been cancelled
详情
Test / Core Provider Tests (OpenAI) (push) Has been cancelled
详情
Test / Core Provider Tests (Anthropic) (push) Has been cancelled
详情
Test / Core Provider Tests (Google) (push) Has been cancelled
详情
Test / Core Provider Tests (Other) (push) Has been cancelled
详情
Test / Anthropic Tests (push) Has been cancelled
详情
Test / Gemini Tests (push) Has been cancelled
详情
Test / Google GenAI Tests (push) Has been cancelled
详情
Test / Vertex AI Tests (push) Has been cancelled
详情
Test / OpenAI Tests (push) Has been cancelled
详情
Test / Writer Tests (push) Has been cancelled
详情
Test / Auto Client Tests (push) Has been cancelled
详情
docs: make Chinese README the default
2026-07-13 10:45:48 +00:00

303 行
8.2 KiB
Markdown
原始文件 永久链接 Blame 文件历史

此文件含有模棱两可的 Unicode 字符
此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的，可以安全地忽略该警告。 使用 Escape 按钮显示他们。
<!-- 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>
在新工单中引用 查看 Git Blame 复制永久链接