docs: make Chinese README the default

2026-07-13 10:45:48 +00:00
parent 97e91a83f3
commit b67ff364bc
1 changed files with 63 additions and 57 deletions
@@ -1,6 +1,12 @@
-# Instructor: Structured Outputs for LLMs
+<!-- 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 文件为准。

-Get reliable JSON from any LLM. Built on Pydantic for validation, type safety, and IDE support.
+# Instructor：面向 LLM 的结构化输出
+
+从任意 LLM 获取可靠的 JSON。基于 Pydantic 构建，提供验证、类型安全与 IDE 支持。

 ```python
 import instructor
@@ -23,7 +29,7 @@ user = client.chat.completions.create(
 print(user)  # User(name='John', age=25)
 ```

-**That's it.** No JSON parsing, no error handling, no retries. Just define a model and get structured data.
+**就这么简单。** 无需 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/)
@@ -31,24 +37,24 @@ print(user)  # User(name='John', age=25)
 [![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)

-> **Use Instructor for fast extraction, reach for PydanticAI when you need agents.** Instructor keeps schema-first flows simple and cheap. If your app needs richer agent runs, built-in observability, or shareable traces, try [PydanticAI](https://ai.pydantic.dev/). PydanticAI is the official agent runtime from the Pydantic team, adding typed tools, replayable datasets, evals, and production dashboards while using the same Pydantic models. Dive into the [PydanticAI docs](https://ai.pydantic.dev/) to see how it extends Instructor-style workflows.
+> **快速抽取用 Instructor，需要 Agent 时用 PydanticAI。** Instructor 让 schema 优先的流程保持简单、低成本。如果你的应用需要更丰富的 Agent 运行、内置可观测性（observability）或可共享的 trace，试试 [PydanticAI](https://ai.pydantic.dev/). PydanticAI 是 Pydantic 团队官方的 Agent 运行时，在沿用相同 Pydantic 模型的同时，提供类型化工具、可回放数据集、评估（evals）以及生产级仪表盘。深入阅读 [PydanticAI 文档](https://ai.pydantic.dev/) 了解它如何扩展 Instructor 风格的工作流。

-## Why Instructor?
+## 为什么选择 Instructor？

-Getting structured data from LLMs is hard. You need to:
+从 LLM 获取结构化数据很难。你需要：

-1. Write complex JSON schemas
-2. Handle validation errors  
-3. Retry failed extractions
-4. Parse unstructured responses
-5. Deal with different provider APIs
+1. 编写复杂的 JSON schema
+2. 处理验证错误  
+3. 重试失败的抽取
+4. 解析非结构化响应
+5. 应对不同提供商的 API

-**Instructor handles all of this with one simple interface:**
+**Instructor 用一个简单的接口搞定这一切：**

 <table>
 <tr>
-<td><b>Without Instructor</b></td>
-<td><b>With Instructor</b></td>
+<td><b>不用 Instructor</b></td>
+<td><b>使用 Instructor</b></td>
 </tr>
 <tr>
 <td>
@@ -102,21 +108,21 @@ user = client.chat.completions.create(
 </tr>
 </table>

-## Install in seconds
+## 几秒即可完成安装

 ```bash
 pip install instructor
 ```

-Or with your package manager:
+或使用你的包管理器：
 ```bash
 uv add instructor
 poetry add instructor
 ```

-## Works with every major provider
+## 适配所有主流提供商

-Use the same code with any LLM provider:
+同一份代码可用于任意 LLM 提供商：

 ```python
 # OpenAI
@@ -143,11 +149,11 @@ user = client.chat.completions.create(
 )
 ```

-## Production-ready features
+## 生产就绪特性

-### Automatic retries
+### 自动重试

-Failed validations are automatically retried with the error message:
+验证失败时会带上错误信息自动重试：

 ```python
 from pydantic import BaseModel, field_validator
@@ -172,9 +178,9 @@ user = client.chat.completions.create(
 )
 ```

-### Streaming support
+### 流式支持

-Stream partial objects as they're generated:
+在生成过程中流式输出部分对象：

 ```python
 from instructor import Partial
@@ -190,9 +196,9 @@ for partial_user in client.chat.completions.create(
    # User(name="John", age=25)
 ```

-### Nested objects
+### 嵌套对象

-Extract complex, nested data structures:
+抽取复杂的嵌套数据结构：

 ```python
 from typing import List
@@ -217,21 +223,21 @@ user = client.chat.completions.create(
 )
 ```

-## Used in production by
+## 生产环境在用

-Trusted by over 100,000 developers and companies building AI applications:
+受到超过 10 万名开发者和企业的信赖，他们正在构建 AI 应用：

- **3M+ monthly downloads**
- **10K+ GitHub stars**  
- **1000+ community contributors**
+- **每月 300 万+ 次下载**
+- **1 万+ GitHub star**  
+- **1000+ 社区贡献者**

-Companies using Instructor include teams at OpenAI, Google, Microsoft, AWS, and many YC startups.
+使用 Instructor 的公司包括 OpenAI、Google、Microsoft、AWS 等团队的许多 YC 创业公司。

-## Get started
+## 快速上手

-### Basic extraction
+### 基础抽取

-Extract structured data from any text:
+从任意文本中抽取结构化数据：

 ```python
 from pydantic import BaseModel
@@ -255,42 +261,42 @@ print(product)
 # Product(name='iPhone 15 Pro', price=999.0, in_stock=True)
 ```

-### Multiple languages
+### 多语言支持

-Instructor's simple API is available in many languages:
+Instructor 简洁的 API 提供多种语言版本：

- [Python](https://python.useinstructor.com) - The original
- [TypeScript](https://js.useinstructor.com) - Full TypeScript support
- [Ruby](https://ruby.useinstructor.com) - Ruby implementation  
- [Go](https://go.useinstructor.com) - Go implementation
- [Elixir](https://hex.pm/packages/instructor) - Elixir implementation
- [Rust](https://rust.useinstructor.com) - Rust implementation
+- [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 实现

-### Learn more
+### 了解更多

- [Documentation](https://python.useinstructor.com) - Comprehensive guides
- [Examples](https://python.useinstructor.com/examples/) - Copy-paste recipes  
- [Blog](https://python.useinstructor.com/blog/) - Tutorials and best practices
- [Discord](https://discord.gg/bD9YE9JArw) - Get help from the community
+- [Documentation](https://python.useinstructor.com) - 全面指南
+- [Examples](https://python.useinstructor.com/examples/) - 可复制粘贴的示例  
+- [Blog](https://python.useinstructor.com/blog/) - 教程与最佳实践
+- [Discord](https://discord.gg/bD9YE9JArw) - 向社区寻求帮助

-## Why use Instructor over alternatives?
+## 为什么选 Instructor 而不是替代方案？

-**vs Raw JSON mode**: Instructor provides automatic validation, retries, streaming, and nested object support. No manual schema writing.
+**对比原生 JSON 模式**：Instructor 提供自动验证、重试、流式输出和嵌套对象支持。无需手写 schema。

-**vs LangChain/LlamaIndex**: Instructor is focused on one thing - structured extraction. It's lighter, faster, and easier to debug.
+**对比 LangChain/LlamaIndex**：Instructor 专注一件事——结构化抽取。更轻量、更快、更易调试。

-**vs Custom solutions**: Battle-tested by thousands of developers. Handles edge cases you haven't thought of yet.
+**对比自研方案**：经数千名开发者实战检验，能处理你尚未想到的边界情况。

-## Contributing
+## 贡献

-We welcome contributions! Check out our [good first issues](https://github.com/567-labs/instructor/labels/good%20first%20issue) to get started.
+欢迎贡献！查看我们的 [good first issues](https://github.com/567-labs/instructor/labels/good%20first%20issue) 开始参与。

-## License
+## 许可证

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

 ---

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