进阶 python.useinstructor.com 2026-11-15 16:34:58 · 26 阅读

第1章 Instructor 简介与快速入门

Instructor:用于 LLM 结构化输出的顶级多语言库

Instructor 让你从任意 LLM 中提取结构化数据,提供类型安全、校验和自动重试功能。目前支持 Python、TypeScript、Go、Ruby、Elixir 和 Rust。对于提取任务用 Instructor,对于智能体(Agent)应用用 PydanticAI。当你需要快速、基于 Schema 的提取且无需额外智能体时,Instructor 是最佳选择。如果你的项目需要质量关卡、可共享的运行记录或内置的可观测性,请尝试 PydanticAI。PydanticAI 是 Pydantic 团队官方推出的智能体运行时框架:它在保留现有 Instructor 模型的基础上,增加了类型化工具、数据集回放和生产环境仪表盘等功能。阅读 PydanticAI 文档可以了解如何将这些功能集成到你的技术栈中。

Instructor 是什么?

Instructor 是目前最流行的用于从大语言模型(LLM)中提取结构化数据的 Python 库。月下载量超过 300 万次,GitHub 星数超过 1.1 万,拥有 100 多位贡献者,它是那些需要 AI 模型输出可靠且经过校验的数据的开发者们的首选方案。Instructor 基于 Pydantic 构建,提供了类型安全的数据提取,并支持自动校验、重试和流式处理。无论你是使用 OpenAI 的 GPT 模型、Anthropic 的 Claude、Google 的 Gemini,还是通过 Ollama、DeepSeek 或其他 15+ 支持提供商运行的开源模型,Instructor 都能确保 LLM 的输出始终结构化且经过校验。

LLM 数据提取的核心特性

结构化输出:定义 Pydantic 模型以精确指定你希望从 LLM 获取的数据格式。 自动重试:内置重试逻辑,当校验失败时自动重试,无需手动处理错误。 数据校验:利用 Pydantic 强大的校验功能确保响应质量。 流式支持:支持实时处理部分响应和列表。 多提供商兼容:支持 OpenAI、Anthropic、Google、Mistral、Cohere、Ollama、DeepSeek 以及 15+ LLM 提供商。 类型安全:提供完整的 IDE 支持,包括正确的类型推断和自动补全。 开源模型支持:通过 Ollama、llama-cpp-python 或 vLLM 在本地运行任何开源模型。

快速开始

安装 Instructor 并几分钟内开始提取结构化数据:

pip install instructor uv add instructor poetry add instructor

提取结构化数据

Instructor 的 from_provider 函数提供了统一接口,方便与任何 LLM 提供商交互。使用相同的代码即可在 OpenAI、Anthropic、Google、Ollama、DeepSeek 等 15+ 提供商之间切换:

import instructor from pydantic import BaseModel

class Person(BaseModel): name: str age: int occupation: str

# 适用于任何提供商 - 界面保持一致 client = instructor.from_provider("openai/gpt-5-nano") # 或者: instructor.from_provider("anthropic/claude-3") # 或者: instructor.from_provider("google/gemini-pro") # 或者: instructor.from_provider("ollama/llama3.2") # 本地

# 从自然语言中提取结构化数据 person = client.create( response_model=Person, messages=[ {"role": "user", "content": "提取: John is a 30-year-old software engineer"} ], ) print(person) # Person(name='John', age=30, occupation='software engineer')

from_provider API 支持同步和异步用法(async_client=True),并自动处理提供商特定的配置。查看所有支持的提供商 →

复杂模式与校验

Instructor 擅长提取带有自定义校验规则的复杂嵌套数据结构。这是一个简明的示例:

import instructor from pydantic import BaseModel, Field, field_validator from typing import List, Optional from enum import Enum

class Priority(str, Enum): LOW = "low" MEDIUM = "medium" HIGH = "high" CRITICAL = "critical"

class Ticket(BaseModel): title: str = Field(..., min_length=5, max_length=100) priority: Priority estimated_hours: Optional[float] = Field(None, gt=0, le=100)

@field_validator('estimated_hours') @classmethod def validate_hours(cls, v): if v is not None and v % 0.5 != 0: raise ValueError('Hours must be in 0.5 increments') return v

class CustomerSupport(BaseModel): customer_name: str tickets: List[Ticket] = Field(..., min_items=1)

client = instructor.from_provider("openai/gpt-4o")

support_case = client.create( response_model=CustomerSupport, messages=[{"role": "user", "content": "Extract support case details..."}], max_retries=3, )

关键特性包括: - 支持深层嵌套模型和列表 - 使用 Pydantic 验证器进行自定义校验 - 校验失败时自动重试 - 具备完整 IDE 支持的类型安全提取

了解关于校验和复杂模式的更多信息 →

支持的 LLM 提供商

Instructor 无缝兼容 15+ 主流 LLM 提供商,让你在保持结构化输出处理一致性的同时,灵活使用任何模型。从 OpenAI 的 GPT 模型到通过 Ollama、DeepSeek 模型和本地推理使用的开源替代品,你可以在任何地方获取经过校验的数据提取功能。Instructor 以其简洁性、透明性和以用户为中心的设计脱颖而出,它建立在 Pydantic 之上,帮助你管理校验上下文、通过 Tenacity 实现重试,以及处理流式列表和部分响应。

Star the Repo Cookbooks Prompting Guide

如果你遇到问题,随时可以运行 instructor docs 命令在浏览器中打开文档。它甚至支持搜索特定主题。instructor docs [QUERY]

提供商示例

所有提供商使用相同的简单接口。以下是主要提供商的快速示例:

OpenAI import instructor from pydantic import BaseModel

class ExtractUser(BaseModel): name: str age: int

client = instructor.from_provider("openai/gpt-5-nano") res = client.create( response_model=ExtractUser, messages=[{"role": "user", "content": "John Doe is 30 years old."}], )

完整 OpenAI 文档 →

Anthropic import instructor from pydantic import BaseModel

class ExtractUser(BaseModel): name: str age: int

client = instructor.from_provider("anthropic/claude-3-5-sonnet-20240620") resp = client.create( response_model=ExtractUser, messages=[{"role": "user", "content": "Extract Jason is 25 years old."}], )

完整 Anthropic 文档 →

Google Gemini import instructor from pydantic import BaseModel

class ExtractUser(BaseModel): name: str age: int

client = instructor.from_provider("google/gemini-2.5-flash") resp = client.create( response_model=ExtractUser, messages=[{"role": "user", "content": "Extract Jason is 25 years old."}], )

完整 Google 文档 →

Ollama (本地) import instructor from pydantic import BaseModel

class ExtractUser(BaseModel): name: str age: int

client = instructor.from_provider("ollama/llama3.2") resp = client.create( response_model=ExtractUser, messages=[{"role": "user", "content": "Extract Jason is 25 years old."}], )

完整 Ollama 文档 →

查看所有 15+ 提供商 →

引用

如果你在研究或项目中使用了 Instructor,请引用:

@software{liu2024instructor, author = {Jason Liu and Contributors}, title = {Instructor: A library for structured outputs from large language models}, url = {https://github.com/instructor-ai/instructor}, year = {2024}, month = {3} }

为什么要用 Instructor?

简单 API 与完整的提示词控制:Instructor 提供了一个直观的 API,让你完全掌控提示词。这允许对 LLM 交互进行精细的定制和优化。 探索概念

多语言支持:通过类型提示和校验简化 LLM 的结构化数据提取。支持 Python、TypeScript、Ruby、Go、Elixir、Rust。

重新提问与校验:当校验失败时自动重新询问模型,确保输出高质量。利用 Pydantic 的校验功能进行稳健的错误处理。 了解重新提问功能

流式支持:轻松流式处理部分结果和可迭代对象,实现实时处理并提高应用响应速度。 了解流式处理

基于类型提示:利用 Pydantic 进行模式校验、提示词控制、减少代码量并集成 IDE。 了解更多

简化的 LLM 交互:支持 OpenAI、Anthropic、Google、Vertex AI、Mistral/Mixtral、Ollama、llama-cpp-python、Cohere、LiteLLM。 查看集成中心

使用 Hooks

Instructor 的 hooks 系统允许你在 LLM 交互过程中拦截和处理事件。使用 hooks 进行日志记录、监控或自定义错误处理:

import instructor from pydantic import BaseModel

class UserInfo(BaseModel): name: str age: int

client = instructor.from_provider("openai/gpt-4o-mini")

# 附加 hooks 用于日志和错误处理 client.on("completion:kwargs", lambda kw: print("Called with:", kw)) client.on("completion:error", lambda e: print(f"Error: {e}"))

user_info = client.create( response_model=UserInfo, messages=[{"role": "user", "content": "Extract: John is 20 years old"}], )

了解关于 hooks 的更多信息 →

类型推断与高级方法

Instructor 提供完整的类型推断以增强 IDE 支持和类型安全。client 包含针对不同用例的专业方法:

基本提取: import instructor from pydantic import BaseModel

class User(BaseModel): name: str age: int

client = instructor.from_provider("openai/gpt-4o-mini") user = client.create(response_model=User, messages=[...]) # 类型: User

异步支持: client = instructor.from_provider("openai/gpt-4o-mini", async_client=True) user = await client.create(...) # 类型: User

访问原始完成结果: user, completion = client.create_with_completion(...) # 返回元组

流式处理部分对象: for partial in client.create_partial(...): # 类型: Generator[User, None] print(partial)

流式处理多个对象: for user in client.create_iterable(...): # 类型: Generator[User, None] print(user)

所有方法都提供完整的类型推断,以优化 IDE 自动补全和类型检查。

常见问题解答

Instructor 是什么? Instructor 是一个从大语言模型(LLMs)中提取结构化、经过校验数据的 Python 库。它使用 Pydantic 模型定义输出模式,并自动处理校验、重试和错误处理。

Instructor 支持哪些 LLM 提供商? Instructor 支持 15+ 提供商,包括 OpenAI、Anthropic、Google Gemini、Mistral、Cohere、Ollama、DeepSeek 等。查看我们的集成页面了解完整列表。

使用 Instructor 需要懂 Pydantic 吗? 基础的 Pydantic 知识会有帮助,但你可以通过简单的模型入门。Instructor 适用于任何 Pydantic BaseModel,你可以按需学习高级功能。

Instructor 与其他库相比如何? Instructor 专门聚焦于带有自动校验和重试的结构化输出。与更大的框架不同,Instructor 只做一件事并做得很好:从 LLMs 中获取可靠、经过校验的数据。

我可以将 Instructor 用于开源模型吗? 可以!Instructor 支持 Ollama、llama-cpp-python 和其他本地模型。查看我们的 Ollama 集成指南以开始使用。

Instructor 支持异步代码吗? 是的,Instructor 完全支持 async/await。创建 client 时使用 async_client=True,然后使用 await client.create()。

查看所有常见问题 →

模板

Instructor 支持使用 Jinja 进行模板化,让你可以创建动态提示词。这在你想用数据填充提示词部分时非常有用。这是一个简单的示例:

import instructor from pydantic import BaseModel

client = instructor.from_provider("openai/gpt-4o-mini")

class User(BaseModel): name: str age: int

# 在消息内容中使用 Jinja 模板创建完成 response = client.create( messages=[ { "role": "user", "content": """Extract the information from the following text: {{ data }}`""", }, ], response_model=User, context={"data": "John Doe is thirty years old"}, )

print(response) #> User(name='John Doe', age=30)

了解关于模板的更多信息:

校验

你还可以使用 Pydantic 校验输出,并在失败时让 LLM 重试。查看我们关于重试和校验上下文的文档。

import instructor from pydantic import BaseModel, ValidationError, BeforeValidator from typing_extensions import Annotated from instructor import llm_validator

# 创建 instructor client client = instructor.from_provider("openai/gpt-4o-mini")

class QuestionAnswer(BaseModel): question: str answer: Annotated[ str, BeforeValidator(llm_validator("don't say objectionable things", client=client)), ]

try: qa = QuestionAnswer( question="What is the meaning of life?", answer="The meaning of life is to be evil and steal", ) except ValidationError as e: print(e) """ 1 validation error for QuestionAnswer answer Assertion failed, The statement promotes objectionable behavior by encouraging evil and stealing. [type=assertion_error, input_value='The meaning of life is to be evil and steal', input_type=str] """

贡献

如果你愿意帮忙,请查看标记为 good-first-issue 或 help-wanted 的问题。可以在这里找到。内容可能包括代码改进、客座博文或新的食谱(Cookbook)。

许可

本项目基于 MIT 许可发布。

评论 (0)