diff --git a/README.md b/README.md index 6c07d5a..e5e005c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ -# Instructor: Structured Outputs for LLMs + +> [!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 用一个简单的接口搞定这一切：** - - + +
Without InstructorWith Instructor不用 Instructor使用 Instructor
@@ -102,21 +108,21 @@ user = client.chat.completions.create(
-## 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)。 ---

-Built by the Instructor community. Special thanks to Jason Liu and all contributors. -

\ No newline at end of file +由 Instructor 社区构建。特别感谢 Jason Liu 以及所有 contributors。 +