什么是 Instructor

Instructor 是一个用于从大语言模型（LLM）获取结构化输出的 Python 库。它通过将 Pydantic 模型与 LLM API 结合，使模型输出自动经过验证和类型转换，开发者无需编写繁琐的 JSON 解析和手动验证代码。

核心价值在于简化 LLM 应用开发中的数据提取和验证流程，让开发者专注于业务逻辑而非底层实现。

资料来源：README.md:1-30

核心功能特性

多provider统一API

Instructor 支持多种主流 LLM 服务商，通过统一的接口访问不同 provider：

所有 provider 使用相同的 API 调用方式，切换时只需修改 provider 名称和模型名称。

资料来源：README.md:50-80

响应模型与自动验证

使用 response_model 参数指定 Pydantic 模型作为输出格式：

from pydantic import BaseModel

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

client = instructor.from_provider("openai/gpt-4o")
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

Instructor 自动处理 JSON 解析、类型转换和验证失败时的重试逻辑。

资料来源：README.md:35-45

自动重试机制

当验证失败时，Instructor 会自动将错误信息反馈给 LLM 并重试请求：

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

# 自动重试直到验证通过或达到最大重试次数
user = client.chat.completions.create(
    response_model=User,
    max_retries=2,
    messages=[{"role": "user", "content": "..."}],
)

资料来源：README.md:90-110

系统架构

组件结构

Instructor 的代码组织结构如下：

instructor/
├── providers/           # LLM provider 适配器
│   ├── anthropic/       # Anthropic 实现
│   ├── openai/          # OpenAI 实现
│   ├── gemini/          # Google Gemini 实现
│   ├── groq/            # Groq 实现
│   ├── vertexai/        # Vertex AI 实现
│   └── ...              # 其他 provider
└── __init__.py          # 核心导出

每个 provider 目录下包含：

• __init__.py - 模块初始化
• client.py - provider 特定的客户端工厂函数（可选）
• utils.py - provider 特定的响应处理工具（可选）

资料来源：instructor/providers/README.md:1-25

Provider 实现模式

OpenAI 作为参考实现，其工厂函数定义在 core/client.py 中，其他 provider 基于此模式扩展。

资料来源：instructor/providers/README.md:25-40

工作流程

graph TD
    A[创建 Client] --> B[调用 chat.completions.create]
    B --> C[发送请求到 LLM]
    C --> D[接收响应]
    D --> E[JSON 解析]
    E --> F[Pydantic 模型验证]
    F --> G{验证通过?}
    G -->|是| H[返回结构化对象]
    G -->|否| I[提取错误信息]
    I --> J[重试请求]
    J --> C
    J --> K[达到最大重试]
    K --> L[抛出异常]

高级功能

验证器（Validators）

Instructor 支持多种验证方式，确保 LLM 输出符合预期：

#### Pydantic 字段验证器

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

#### LLM 验证器

使用 llm_validator 对输出内容进行语义级验证：

from typing_extensions import Annotated
from pydantic import BeforeValidator

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

资料来源：examples/validators/readme.md:1-80

批处理 API

Instructor 提供统一的批处理接口，支持多个 provider：

# 使用 CLI 创建批处理任务
instructor batch create \
  --messages-file messages.jsonl \
  --model "openai/gpt-4o-mini" \
  --response-model "User"

支持的功能：

• 批量消息创建
• 批处理状态查询
• 结果文件导出
• Provider 自动检测

支持的批处理模型：

• OpenAI: gpt-4o-mini, gpt-4o, gpt-4-turbo
• Anthropic: claude-3-5-sonnet, claude-3-opus, claude-3-haiku
• Google: gemini-2.0-flash-001, gemini-pro

资料来源：examples/batch_api/README.md:1-60

钩子系统（Hooks）

Instructor 的钩子系统允许在请求生命周期中插入自定义逻辑：

graph LR
    A[请求开始] --> B[on_request 钩子]
    B --> C[LLM 调用]
    C --> D[on_response 钩子]
    D --> E{验证成功?}
    E -->|是| F[on_success 钩子]
    E -->|否| G[on_retry 钩子]
    G --> C
    F --> H[返回结果]
    E -->|最终失败| I[on_failure 钩子]
    I --> J[抛出异常]

支持的钩子事件：

资料来源：examples/hooks/README.md:1-40

模型蒸馏（Distillation）

Instructor 支持使用日志功能生成微调数据集：

# 运行脚本生成训练数据
python three_digit_mul.py

# 创建微调任务
instructor jobs create-from-file math_finetunes.jsonl

# 可选：使用验证集
instructor jobs create-from-file math_finetunes.jsonl \
  --n-epochs 4 \
  --validation-file math_finetunes_val.jsonl

此功能允许开发者用 Instructor 生成高质量的训练数据，用于微调更小、更快的模型。

资料来源：examples/distilations/readme.md:1-50

引用提取（Citations）

Instructor 支持从上下文中提取引用并标注来源：

curl -X POST 'http://localhost:8000/extract' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <OPENAI_API_KEY>' \
  -d '{
    "context": "Jason Liu 出生于中国...",
    "query": "作者在哪里出生?"
  }'

返回格式包含：

• body: 提取的事实
• spans: 原文中的位置
• citation: 引用的文本片段

资料来源：examples/citation_with_extraction/README.md:1-50

安装与配置

快速安装

pip install instructor

或使用其他包管理器：

uv add instructor
poetry add instructor

初始化客户端

# 基本用法（需设置环境变量）
client = instructor.from_provider("openai/gpt-4o")

# 直接传入 API Key
client = instructor.from_provider(
    "anthropic/claude-3-5-sonnet",
    api_key="sk-ant-..."
)

# 使用任意支持格式
client = instructor.from_provider("groq/llama-3.1-8b-instant")

资料来源：README.md:40-70

与传统方式对比

graph LR
    subgraph "传统方式"
        A1[手动定义 schema] --> A2[调用 API]
        A2 --> A3[解析 JSON]
        A3 --> A4[手动验证数据]
        A4 --> A5[处理边界情况]
    end

    subgraph "使用 Instructor"
        B1[定义 Pydantic 模型] --> B2[调用 create 方法]
        B2 --> B3[自动验证返回]
        B3 --> B4[获得类型安全对象]
    end

    A5 -.->|繁琐| B4

适用场景

Instructor 适用于以下场景：

1. 数据提取：从非结构化文本中提取结构化数据
2. 信息检索：基于上下文的问答系统
3. 内容审核：验证 LLM 输出符合规范
4. 批量处理：大规模自动化数据处理任务
5. 模型微调：生成高质量训练数据集
6. 多Provider切换：统一管理不同 LLM 服务商

技术栈

• Python: 3.9+
• Pydantic: 数据验证和类型转换
• OpenAI SDK: API 通信
• Tenacity: 重试逻辑

Instructor 设计为轻量级依赖，核心功能仅需 Pydantic 即可运行。

安装方式

Instructor 提供了多种安装方式，开发者可根据项目需求选择最适合的方法。

使用 pip 安装

最简捷的安装方式是通过 Python 包管理器 pip 安装稳定版本：

pip install instructor

使用 uv 安装

对于使用 uv 作为包管理器的项目：

uv add instructor

使用 Poetry 安装

使用 Poetry 进行依赖管理的项目：

poetry add instructor

资料来源：README.md:1-30

环境要求

Instructor 对运行环境有以下基本要求：

核心依赖

Instructor 的核心功能依赖于以下 Python 包：

# pyproject.toml 中的核心依赖
dependencies = [
    "pydantic>=2.0",
    "anyio>=4.0",
]

资料来源：pyproject.toml

LLM 提供商配置

Instructor 支持多个主流 LLM 提供商，每个提供商需要单独配置 API 密钥。

支持的提供商

初始化客户端

使用 from_provider() 方法创建客户端：

# 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 (本地)
client = instructor.from_provider("ollama/llama3.2")

直接传递 API 密钥

在某些场景下，可能需要直接传递 API 密钥而不依赖环境变量：

# OpenAI
client = instructor.from_provider("openai/gpt-4o", api_key="sk-...")

# Anthropic
client = instructor.from_provider("anthropic/claude-3-5-sonnet", api_key="sk-ant-...")

# Groq
client = instructor.from_provider("groq/llama-3.1-8b-instant", api_key="gsk_...")

资料来源：README.md:50-80

依赖安装流程

基本安装步骤

1. 创建虚拟环境（推荐）

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

1. 安装 Instructor

pip install instructor

1. 安装提供商 SDK（根据需要）

# OpenAI
pip install openai

# Anthropic
pip install anthropic

# Google Gemini
pip install google-generativeai

示例项目依赖安装

某些示例项目可能需要额外依赖：

# 示例：citation_with_extraction 项目
pip install -r requirements.txt

资料来源：examples/citation_with_extraction/README.md

高级功能依赖

批处理功能

使用批处理 API 时需要安装以下依赖：

安装命令：

uv add openai typer rich tenacity pyyaml

资料来源：scripts/README.md

微调功能

进行模型微调时需要：

1. 配置日志记录功能
2. 准备训练数据格式（JSONL）
3. 使用 Instructor CLI 提交微调任务

instructor jobs create-from-file math_finetunes.jsonl

资料来源：examples/distilations/readme.md

验证安装

安装完成后，可通过以下方式验证 Instructor 是否正确安装：

import instructor

# 验证版本
print(instructor.__version__)

# 测试基本功能
client = instructor.from_provider("openai/gpt-4o-mini")
print("Instructor 安装成功！")

安装问题排查

常见问题

验证 API 密钥

确保 API 密钥已正确配置：

# 检查环境变量（Linux/macOS）
echo $OPENAI_API_KEY

# 检查环境变量（Windows）
echo %OPENAI_API_KEY%

项目结构与模块

Instructor 采用模块化设计，主要结构如下：

instructor/
├── providers/          # LLM 提供商实现
│   ├── openai/         # OpenAI 提供商
│   ├── anthropic/     # Anthropic 提供商
│   ├── gemini/         # Google Gemini 提供商
│   └── ...
├── core/               # 核心功能模块
└── ...

每个提供商都有独立的子模块，包含初始化工厂函数和响应处理工具：

providers/
├── provider_name/
│   ├── __init__.py
│   ├── client.py      # 提供商特定客户端
│   └── utils.py       # 响应处理工具

资料来源：instructor/providers/README.md

快速开始工作流

以下流程图展示了从安装到首次使用的完整过程：

graph TD
    A[开始] --> B[安装 Instructor]
    B --> C{选择提供商}
    C -->|OpenAI| D[设置 OPENAI_API_KEY]
    C -->|Anthropic| E[设置 ANTHROPIC_API_KEY]
    C -->|Google| F[设置 GOOGLE_API_KEY]
    C -->|Ollama| G[配置本地 Ollama]
    D --> H[创建客户端]
    E --> H
    F --> H
    G --> H
    H --> I[定义响应模型]
    I --> J[调用 API]
    J --> K[获取结构化输出]

许可证

Instructor 采用 MIT 许可证开源发布，可自由使用、修改和分发。

资料来源：README.md

什么是 Instructor

Instructor 是 567 Labs 开发的一个开源库，它通过与 Pydantic 的深度集成，将 LLM 的非结构化输出转换为结构化的 Python 对象。与传统的工具调用方式相比，Instructor 提供了更简洁的 API 和自动验证机制。

传统的 LLM 调用需要手动解析 tool_call 中的 arguments，手动进行 JSON 解析和验证，而使用 Instructor 只需要定义 Pydantic 模型并调用 client.create() 即可获得完整的类型安全验证结果。

安装 Instructor

Instructor 支持多种安装方式，开发者可以根据项目需求选择合适的方式。

使用 pip 安装

pip install instructor

使用包管理器安装

Instructor 也支持其他主流 Python 包管理器：

# 使用 uv
uv add instructor

# 使用 poetry
poetry add instructor

资料来源：README.md

基本概念

核心组件

Instructor 的核心架构包含以下几个关键组件：

支持的 LLM 提供商

Instructor 与多个主流 LLM 提供商兼容，包括 OpenAI、Anthropic、Google、Ollama 等。

资料来源：README.md

创建客户端

在使用 Instructor 之前，需要先创建客户端实例。Instructor 提供了 from_provider() 工厂函数来简化这一过程。

基本用法

import instructor
from pydantic import BaseModel

# 从 OpenAI 创建客户端
client = instructor.from_provider("openai/gpt-4o-mini")

支持的提供商示例

# 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 (本地)
client = instructor.from_provider("ollama/llama3.2")

# 直接传入 API Key
client = instructor.from_provider("openai/gpt-4o", api_key="sk-...")

资料来源：README.md

第一个提取示例

本节通过一个简单的用户信息提取示例，帮助开发者快速上手 Instructor。

定义数据模型

首先，使用 Pydantic 定义要提取的数据结构：

from pydantic import BaseModel


class User(BaseModel):
    name: str
    age: int
    email: str
    address: str = None  # 可选字段

资料来源：examples/simple-extraction/user.py

执行提取

定义好模型后，即可使用 Instructor 进行结构化数据提取：

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

# 定义提取模型
class User(BaseModel):
    name: str
    age: int
    email: str
    address: str = None


# 提取数据
user = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=User,
    messages=[
        {
            "role": "user",
            "content": "张三, 30岁, 邮箱是 [email protected]"
        }
    ],
)

print(user)
# User(name='张三', age=30, email='[email protected]', address=None)

资料来源：docs/getting-started.md

工作流程

Instructor 的数据提取流程如下：

graph TD
    A[定义 Pydantic 模型] --> B[创建 Instructor 客户端]
    B --> C[调用 client.chat.completions.create]
    C --> D[发送请求到 LLM]
    D --> E[接收 LLM 响应]
    E --> F[Pydantic 模型验证]
    F --> G{验证是否通过}
    G -->|通过| H[返回结构化对象]
    G -->|失败| I[自动重试并返回错误]
    I --> C

流程说明

1. 定义模型：开发者定义 Pydantic 模型来描述期望的输出结构
2. 创建客户端：使用 from_provider() 创建与指定 LLM 提供商的连接
3. 调用 API：使用 client.chat.completions.create() 发送请求
4. 自动验证：Instructor 自动对 LLM 输出进行 Pydantic 验证
5. 自动重试：如果验证失败，Instructor 会自动重试并将错误信息反馈给 LLM

资料来源：docs/learning/getting_started/first_extraction.md

自动重试机制

Instructor 内置了强大的自动重试机制。当 Pydantic 验证失败时，系统会自动重试并向 LLM 传递错误信息。

添加自定义验证

可以使用 Pydantic 的 field_validator 装饰器添加自定义验证逻辑：

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('年龄必须为正数')
        return v


# 当年龄为负数时，Instructor 会自动重试
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "用户年龄为-5岁"}],
)

资料来源：README.md

LLM 验证器

除了传统的字段验证器，Instructor 还支持使用 llm_validator 进行基于 LLM 的文本验证：

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


class QuestionAnswerNoEvil(BaseModel):
    question: str
    answer: Annotated[
        str,
        BeforeValidator(
            llm_validator("不要说不恰当的话", allow_override=True)
        ),
    ]

资料来源：examples/validators/readme.md

嵌套对象处理

Instructor 支持自动处理嵌套对象的提取，无需额外配置。

from pydantic import BaseModel
from typing import Optional


class Address(BaseModel):
    street: str
    city: str
    country: str


class User(BaseModel):
    name: str
    email: str
    address: Optional[Address] = None


user = client.chat.completions.create(
    response_model=User,
    messages=[
        {
            "role": "user",
            "content": "李四, 邮箱是 [email protected], 住在北京市朝阳区建国路88号"
        }
    ],
)

print(user.address)
# Address(street='建国路88号', city='北京市', country='中国')

资料来源：README.md

完整示例代码

以下是使用 Instructor 进行用户信息提取的完整示例：

from pydantic import BaseModel
import instructor

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


class User(BaseModel):
    name: str
    age: int
    email: str
    address: str = None


# 提取结构化数据
user = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=User,
    messages=[
        {
            "role": "user",
            "content": "张三, 30岁, 邮箱是 [email protected]"
        }
    ],
)

# user 已经是完全验证的 User 对象
print(f"姓名: {user.name}")
print(f"年龄: {user.age}")
print(f"邮箱: {user.email}")

资料来源：examples/simple-extraction/user.py

下一步

完成快速入门后，建议继续学习以下内容：

概述

Instructor 是一个用于从大语言模型（LLM）获取结构化输出的 Python 库。它通过统一 API 连接多种 LLM 提供商，并使用 Pydantic 模型进行响应验证和类型转换。该库的核心设计理念是简化 LLM 函数调用与结构化数据提取的复杂性，使开发者能够以声明式方式定义期望的输出格式，同时自动处理验证、重试和错误恢复。

Instructor 的架构采用分层设计，核心层负责客户端管理、响应处理和验证逻辑，而 providers 层则负责与不同 LLM 提供商的适配。这种分层设计确保了代码的可维护性和可扩展性，同时保持了统一的接口体验。资料来源：README.md:1-15

核心架构组件

分层架构概览

Instructor 的系统架构可分为三个主要层次：应用接口层、核心处理层和提供商适配层。

graph TD
    A[应用层 - 用户代码] --> B[核心层 - Instructor Client]
    B --> C[处理层 - Response/FunctionCall]
    C --> D[验证层 - Validators]
    D --> E[提供商适配层 - Providers]
    
    E --> F[OpenAI]
    E --> G[Anthropic]
    E --> H[Google Gemini]
    E --> I[Ollama]
    E --> J[Groq]
    
    style A fill:#e1f5fe
    style B fill:#b3e5fc
    style C fill:#81d4fa
    style D fill:#4fc3f7
    style E fill:#29b6f6

核心层（Core Layer）

核心层是 Instructor 的心脏，负责创建客户端实例、管理 API 调用和协调处理流程。该层的核心组件位于 instructor/core/client.py 文件中，提供了统一的客户端工厂函数 from_provider()。资料来源：instructor/core/client.py:1-50

核心层的主要职责包括：

• 客户端工厂：通过 from_provider() 函数根据提供商名称创建适配的客户端实例
• 请求调度：将用户的结构化请求转换为特定提供商的 API 格式
• 响应路由：将提供商的原始响应分发到相应的处理模块

处理层（Processing Layer）

处理层负责将 LLM 的原始输出转换为 Pydantic 模型实例。该层包含三个关键模块：

#### 响应处理模块

response.py 模块负责解析 LLM 返回的文本响应，并将其映射到预定义的 Pydantic 模型。当 LLM 直接返回文本而非函数调用时，此模块执行必要的数据提取和转换。资料来源：instructor/processing/response.py:1-30

#### 函数调用处理模块

function_calls.py 模块处理 LLM 的函数调用输出。当模型选择调用特定函数时，此模块负责：

• 解析函数名称和参数
• 验证参数类型和格式
• 提取结构化数据填充到 Pydantic 模型

资料来源：instructor/processing/function_calls.py:1-40

#### 验证器模块

validators.py 模块实现了一套完整的验证机制，确保 LLM 输出符合预定义的约束条件。验证器包括：

资料来源：instructor/processing/validators.py:1-50

提供商适配层（Providers Layer）

Provider 层为不同的 LLM 服务提供商提供统一的适配接口。每个提供商都有独立的子目录，采用标准化的目录结构。资料来源：instructor/providers/README.md:1-20

提供商架构

提供商组织结构

Instructor 支持多种 LLM 提供商，采用统一的目录结构和适配模式：

providers/
├── provider_name/
│   ├── __init__.py
│   ├── client.py      # 提供商特定客户端工厂
│   └── utils.py       # 提供商特定工具函数

提供商分类

根据实现复杂度，Provider 可分为以下几类：

资料来源：instructor/providers/README.md:8-15

提供商工厂模式

Instructor 使用统一的工厂模式创建客户端实例：

# 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 (本地)
client = instructor.from_provider("ollama/llama3.2")

所有客户端使用相同的 API 调用方式，底层的提供商差异被完全抽象：

user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

资料来源：README.md:45-65

请求处理流程

完整请求生命周期

Instructor 的请求处理遵循标准化的生命周期流程：

graph TD
    A[创建客户端 from_provider] --> B[调用 create 方法]
    B --> C[构建 API 请求]
    C --> D{提供商类型检测}
    D -->|OpenAI| E[使用标准工具调用格式]
    D -->|Anthropic| F[使用 Beta Messages API]
    D -->|其他| G[使用提供商特定格式]
    E --> H[发送请求到 LLM]
    F --> H
    G --> H
    H --> I{解析响应}
    I -->|函数调用| J[调用 function_calls 处理]
    I -->|文本响应| K[调用 response 处理]
    J --> L{运行验证器}
    K --> L
    L -->|验证失败| M[重试并提供错误信息]
    L -->|验证成功| N[返回 Pydantic 模型]
    M --> H

Hooks 系统架构

Instructor 提供了强大的钩子系统，允许开发者在请求处理的不同阶段插入自定义逻辑。钩子系统支持拦截请求发送前和响应处理后的流程。资料来源：examples/hooks/README.md:1-30

Hook 事件类型包括：

验证与重试机制

自动重试机制

Instructor 的核心特性之一是自动重试机制。当 Pydantic 验证失败时，系统会自动重试并携带错误信息，让 LLM 有机会修正输出。资料来源：README.md:80-95

graph LR
    A[首次请求] --> B{验证通过?}
    B -->|是| C[返回结果]
    B -->|否| D[提取验证错误]
    D --> E[携带错误信息重试]
    E --> A
    C --> F[最多重试 max_retries 次]
    F -->|失败| G[抛出异常]

验证器链

验证器可以链式使用，形成多层次的验证策略：

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

这种设计允许组合使用 Pydantic 原生验证和 LLM 驱动的语义验证。资料来源：examples/validators/readme.md:30-50

批处理架构

BatchProcessor 组件

Instructor 提供了统一的批处理 API，支持多个提供商：

from instructor import BatchProcessor

processor = BatchProcessor()
batch_id = processor.create_batch(
    model="openai/gpt-4o-mini",
    messages=messages,
    response_model=User,
)

资料来源：examples/batch_api/README.md:1-40

支持的提供商

扩展机制

插件式架构

Instructor 的架构设计支持插件扩展，主要扩展点包括：

1. 自定义 Provider：通过实现 provider 适配接口添加新提供商
2. 自定义 Validator：通过扩展 validators 模块添加新的验证策略
3. Hook 钩子：通过注册事件处理器扩展处理流程

添加新 Provider 的标准流程

1. 在 providers/ 下创建新的提供商子目录
2. 添加 __init__.py 文件（可为空或包含导入）
3. 如需自定义处理逻辑，添加 utils.py 文件
4. 如需自定义客户端工厂，添加 client.py 文件
5. 更新提供商注册表

资料来源：instructor/providers/README.md:18-25

关键设计模式

统一接口模式

Instructor 采用统一接口模式，隐藏底层提供商差异：

• 客户端统一：所有提供商客户端实现相同的 chat.completions.create 接口
• 响应统一：无论来源如何，所有响应都转换为 Pydantic 模型实例
• 错误统一：验证错误和 API 错误采用一致的异常格式

声明式配置模式

开发者通过声明式方式定义期望的输出结构：

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

user = client.chat.completions.create(
    response_model=User,
    messages=[...],
)

这种模式将验证逻辑与业务逻辑分离，提高了代码的可读性和可维护性。

工厂模式

from_provider() 工厂函数是整个系统的入口点，根据提供商标识符动态创建适当的客户端实例。这种模式简化了客户端管理，同时支持运行时提供商切换。

总结

Instructor 的系统架构围绕三个核心目标设计：简化 LLM 结构化输出、保证输出质量、支持多提供商。其分层架构确保了关注点分离，而统一的接口模式提供了无缝的跨提供商体验。验证和重试机制的深度集成使得系统能够在 LLM 输出不符合预期时自动恢复，极大地提高了生产环境的稳定性。资料来源：docs/architecture.md:1-30

概述

Instructor 的提供商集成（Provider Integration）模块为开发者提供了统一的接口，用于对接多种大型语言模型（LLM）提供商。通过 instructor.from_provider() 工厂方法，开发者可以使用相同的代码结构访问 OpenAI、Anthropic、Google、Ollama 等不同提供商的模型，无需关心底层 API 的差异。

该模块位于 instructor/providers/ 目录下，每个提供商都有独立的子目录和实现文件，采用一致的目录结构但根据提供商复杂度灵活配置。

核心架构

目录结构

instructor/providers/
├── __init__.py
├── provider_name/
│   ├── __init__.py
│   ├── client.py      # 提供商特定的客户端工厂（可选）
│   └── utils.py       # 提供商特定的工具函数（可选）

资料来源：instructor/providers/README.md

提供商分类

Instructor 根据实现复杂度将提供商分为三类：

资料来源：instructor/providers/README.md

工作流程图

graph TD
    A[用户调用 from_provider] --> B{提供商类型判断}
    B -->|OpenAI| C[core/client.py 处理]
    B -->|Anthropic| D[anthropic/client.py]
    B -->|Gemini| E[gemini/client.py]
    B -->|其他| F[对应 provider/client.py]
    
    D --> G[provider/utils.py 响应处理]
    E --> G
    C --> H[统一响应格式化]
    F --> G
    G --> H

快速开始

基础用法

使用 from_provider() 方法创建客户端：

import instructor

# 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 (本地部署)
client = instructor.from_provider("ollama/llama3.2")

资料来源：README.md

使用 API Key

所有提供商使用统一的 API：

from pydantic import BaseModel

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

# 直接传递 API Key
client = instructor.from_provider("openai/gpt-4o", api_key="sk-...")
client = instructor.from_provider("anthropic/claude-3-5-sonnet", api_key="sk-ant-...")

# 使用统一接口
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
)

支持的提供商

OpenAI

OpenAI 是 Instructor 的参考实现，from_openai() 函数定义在 core/client.py 中。其他提供商的实现都基于此模式。

支持模型：

Anthropic

Anthropic 提供商位于 instructor/providers/anthropic/，包含完整的 client.py 和 utils.py 实现。

支持模型：

Google Gemini

Google Gemini 提供商位于 instructor/providers/gemini/，使用 gemini-pro 等模型。

支持模型：

其他提供商

Instructor 还支持以下提供商，采用简化实现：

批量处理集成

每个提供商都支持批量 API 调用，通过 BatchProcessor 类实现统一的批量处理接口。

批量处理工作流

graph LR
    A[准备消息列表] --> B[BatchProcessor]
    B --> C{提供商检测}
    C -->|OpenAI| D[生成 batch JSON]
    C -->|Anthropic| E[使用 beta API]
    C -->|Google| F[模拟模式/GCS]
    D --> G[提交批量任务]
    E --> G
    F --> G
    G --> H[返回 Batch ID]

支持的批量操作

# 创建批量任务
instructor batch create \
  --messages-file messages.jsonl \
  --model "openai/gpt-4o-mini" \
  --response-model "User"

# 从文件提交批量任务
instructor batch create-from-file \
  --file-path batch_requests.jsonl \
  --model "openai/gpt-4o-mini"

资料来源：examples/batch_api/README.md

新增提供商

添加步骤

当需要添加新的提供商时，按照以下流程操作：

1. 在 instructor/providers/ 下创建新的子目录
2. 添加 __init__.py 文件（可为空）
3. 根据复杂度添加 client.py 和/或 utils.py

graph TD
    A[创建 providers/newprovider/] --> B[添加 __init__.py]
    B --> C{需要自定义处理?}
    C -->|是| D[创建 client.py 和 utils.py]
    C -->|否| E[仅创建 client.py]
    D --> F[实现 from_newprovider 工厂函数]
    E --> F
    F --> G[导出到 providers/__init__.py]

实现要求

资料来源：instructor/providers/README.md

配置与认证

环境变量

初始化参数

from_provider() 方法支持以下参数：

与旧版 API 的兼容性

Instructor 提供了模式转换脚本，用于将旧版 API 调用迁移到新版本：

API 模式变更

审计工具

使用 audit_patterns.py 脚本检查文档中的旧模式：

# 详细报告
python scripts/audit_patterns.py

# 仅摘要
python scripts/audit_patterns.py --summary

# 检查单个文件
python scripts/audit_patterns.py --file docs/index.md

资料来源：scripts/README.md

最佳实践

提供商选择指南

graph TD
    A[选择提供商] --> B{场景类型}
    B -->|生产环境| C{预算考虑}
    C -->|充足| D[OpenAI GPT-4]
    C -->|有限| E[OpenAI GPT-4o-mini 或 Groq]
    B -->|本地部署| F[Ollama]
    B -->|高精度| G[Anthropic Claude Opus]
    B -->|多模态| H[Google Gemini Pro Vision]

错误处理

总结

Instructor 的提供商集成模块通过统一的抽象层，简化了多提供商 LLM 的使用流程。开发者只需掌握 from_provider() 工厂方法，即可无缝切换不同的模型提供商，同时保持代码的一致性和可维护性。

概述

在传统的 LLM API 调用中，返回的响应是原始文本或 JSON 字符串，需要开发者手动解析和验证。这种方式不仅繁琐，还容易引入错误。响应模型通过将 Pydantic 模型作为 response_model 参数传递，让 Instructor 自动完成以下工作：

资料来源：README.md:1-30

基本用法

安装与初始化

pip install instructor

# 从 OpenAI 初始化客户端
client = instructor.from_provider("openai/gpt-4o")

资料来源：README.md:45-50

定义响应模型

响应模型基于 Pydantic 的 BaseModel 构建：

from pydantic import BaseModel

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

调用 API

使用 response_model 参数指定期望的响应模型：

user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "Extract: Jason, 28 years old"}],
)

# user 已经是验证通过的 User 实例
print(user.name)  # Jason
print(user.age)   # 28

资料来源：README.md:35-45

工作原理

Instructor 的响应模型处理流程如下：

graph TD
    A[用户请求] --> B[创建 API 调用]
    B --> C{传入 response_model}
    C -->|是| D[发送请求到 LLM]
    C -->|否| E[返回原始响应]
    D --> F[解析 LLM 输出为 JSON]
    F --> G[Pydantic 验证]
    G --> H{验证通过?}
    H -->|是| I[返回模型实例]
    H -->|否| J[生成错误信息]
    J --> K{重试次数 < max_retries?}
    K -->|是| D
    K -->|否| L[抛出 ValidationError]

自动重试机制

当 Pydantic 验证失败时，Instructor 会自动将错误信息反馈给 LLM 并重试请求：

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('年龄必须为正数')
        return v

# Instructor 自动处理重试
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
    max_retries=3,  # 默认值，可自定义
)

资料来源：README.md:75-95

重试流程图

graph LR
    A[验证失败] --> B[提取错误信息]
    B --> C[构造修正提示]
    C --> D[重新发送请求]
    D --> E{再次验证}
    E -->|通过| F[返回结果]
    E -->|失败| G{重试次数剩余?}
    G -->|是| A
    G -->|否| H[抛出异常]

高级用法

使用 BeforeValidator 进行自定义验证

使用 llm_validator 实现基于 LLM 的文本验证：

from typing_extensions import Annotated
from pydantic import BeforeValidator

class QuestionAnswer(BaseModel):
    question: str
    answer: Annotated[
        str,
        BeforeValidator(
            llm_validator("不要发表不当言论", allow_override=True)
        ),
    ]

资料来源：examples/validators/readme.md:50-60

处理验证异常

try:
    qa = client.chat.completions.create(
        response_model=QuestionAnswerNoEvil,
        messages=[{"role": "user", "content": "..."}],
    )
except Exception as e:
    print(f"验证失败: {e}")

资料来源：examples/validators/readme.md:80-90

设置最大重试次数

qa = client.chat.completions.create(
    model="gpt-3.5-turbo",
    response_model=QuestionAnswerNoEvil,
    max_retries=2,  # 允许最多 2 次重试
    messages=[{"role": "user", "content": "..."}],
)

资料来源：examples/validators/readme.md:100-110

配置参数

与传统方式的对比

资料来源：README.md:1-20

完整示例

from pydantic import BaseModel, field_validator
import instructor

# 初始化客户端
client = instructor.from_provider("openai/gpt-4o")

# 定义响应模型
class User(BaseModel):
    name: str
    age: int
    email: str | None = None

    @field_validator('age')
    @classmethod
    def validate_age(cls, v):
        if v < 0:
            raise ValueError('年龄必须为正数')
        return v

# 使用响应模型
user = client.chat.completions.create(
    model="gpt-4o",
    response_model=User,
    messages=[
        {"role": "system", "content": "你是一个数据提取助手"},
        {"role": "user", "content": "从以下文本提取用户信息：张三，35岁，邮箱 [email protected]"}
    ],
)

print(f"姓名: {user.name}")
print(f"年龄: {user.age}")
print(f"邮箱: {user.email}")

支持的模型类型

响应模型支持所有 Pydantic v2 的特性：

• 基本类型：str、int、float、bool
• 可选类型：Optional[T] 或 T | None
• 列表类型：List[T]
• 嵌套模型：嵌套的 BaseModel
• 联合类型：Union[A, B] 或 A | B
• 枚举类型：Enum
• 验证器：@field_validator、@model_validator

最佳实践

1. 始终定义类型注解：让 Pydantic 正确推断类型
2. 使用验证器：在模型中定义业务规则验证
3. 设置合理的 max_retries：默认为 3，根据复杂程度调整
4. 使用 Optional 处理可选字段：避免验证失败
5. 保持模型简洁：复杂逻辑使用嵌套模型分离

下一步

• 验证器使用指南
• 钩子系统
• 批量处理

概述

Instructor 的验证机制是确保 LLM（大语言模型）输出结构化数据正确性的核心系统。该机制构建在 Pydantic 框架之上，提供自动验证、错误处理、重试逻辑和 LLM 级语义验证能力。

Instructor 的验证流程采用多层架构设计：

graph TD
    A[LLM 响应] --> B[响应解析]
    B --> C[Pydantic 模型验证]
    C --> D{验证通过?}
    D -->|是| E[返回结构化数据]
    D -->|否| F[收集验证错误]
    F --> G{重试次数 < max_retries?}
    G -->|是| H[提取错误信息]
    H --> I[构建重试提示]
    I --> J[重新发送给 LLM]
    J --> A
    G -->|否| K[抛出异常]

资料来源：docs/concepts/reask_validation.md:1-20

核心验证流程

Pydantic BaseModel 集成

Instructor 使用 Pydantic 的 BaseModel 作为响应模型的基础。当定义响应模型时，Instructor 自动将模型转换为 LLM 可理解的 JSON Schema，并在验证失败时生成精确的错误提示。

资料来源：README.md:1-30

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('年龄必须为正数')
        return v

资料来源：README.md:60-75

字段验证器（Field Validators）

字段验证器允许在字段级别添加自定义验证逻辑。通过 Pydantic 的 @field_validator 装饰器，可以对单个字段进行类型检查、范围验证和格式校验。

资料来源：examples/validators/field_validator.py:1-50

LLM 级语义验证

llm_validator 机制

llm_validator 是 Instructor 提供的特殊验证器，用于执行 LLM 级别的语义验证。它允许开发者定义自然语言约束条件，由 LLM 判断输出是否符合预期语义。

资料来源：instructor/validation/llm_validators.py:1-30

from typing_extensions import Annotated
from pydantic import BeforeValidator
from instructor import llm_validator

class QuestionAnswerNoEvil(BaseModel):
    question: str
    answer: Annotated[
        str,
        BeforeValidator(
            llm_validator("不要说出不当言论", allow_override=True)
        ),
    ]

资料来源：examples/validators/readme.md:1-50

llm_validator 参数说明

资料来源：instructor/validation/llm_validators.py:30-60

自动重试机制

重试工作流程

当验证失败时，Instructor 自动将错误信息提取并附加到下一轮对话中，引导 LLM 修正错误。这一过程无需手动干预。

sequenceDiagram
    participant U as 用户
    participant I as Instructor
    participant LLM as LLM API
    participant V as 验证器
    
    U->>I: 调用 create(response_model=User)
    I->>LLM: 发送初始请求
    LLM-->>I: 返回响应
    I->>V: 执行 Pydantic 验证
    V-->>I: 验证失败: age < 0
    I->>I: 生成重试提示
    I->>LLM: 发送修正请求 + 错误信息
    LLM-->>I: 返回修正响应
    I->>V: 再次验证
    V-->>I: 验证通过
    I-->>U: 返回 User 对象

资料来源：instructor/core/retry.py:1-80

重试配置

通过 max_retries 参数控制重试次数，默认行为由 Instructor 内部配置决定。

user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
    max_retries=3,  # 最多重试3次
)

资料来源：README.md:75-85

重试策略

Instructor 采用指数退避策略处理重试，避免在瞬时错误时过度调用 API。每次重试之间会有适当延迟。

资料来源：instructor/core/retry.py:80-120

错误处理

验证错误捕获

验证失败时会抛出 ValidationError 异常，可通过标准的 Python 异常处理机制捕获。

try:
    qa = client.chat.completions.create(
        response_model=QuestionAnswerNoEvil,
        messages=[{"role": "user", "content": "..."}],
    )
except Exception as e:
    print(f"验证失败: {e}")

资料来源：examples/validators/readme.md:100-120

错误响应格式

验证错误包含详细的字段级错误信息：

1 validation error for QuestionAnswerNoEvil
answer
    Assertion failed, 陈述包含不当言论

资料来源：examples/validators/readme.md:70-75

流式验证

Partial 模型支持

Instructor 支持流式输出验证，使用 Partial[T] 类型在生成过程中逐步验证和返回部分结果。

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="张三", age=None)
    # User(name="张三", age=25)

资料来源：README.md:90-105

流式验证流程

graph LR
    A[开始生成] --> B[解析部分响应]
    B --> C[执行部分验证]
    C --> D[返回部分对象]
    D --> E{生成完成?}
    E -->|否| B
    E -->|是| F[最终验证]
    F --> G[返回完整对象]

嵌套对象验证

复杂数据结构

Instructor 自动处理嵌套的 Pydantic 模型，支持多层级的结构化数据验证。

from typing import List

class Address(BaseModel):
    street: str
    city: str
    country: str

class User(BaseModel):
    name: str
    age: int
    addresses: List[Address]

资料来源：README.md:110-125

嵌套验证特性

自定义验证器

创建自定义验证器

可通过继承和组合的方式创建领域特定的验证器。

from pydantic import BeforeValidator
from typing import Any

def custom_validator(value: Any) -> Any:
    # 自定义验证逻辑
    if isinstance(value, str) and len(value) > 100:
        raise ValueError("字符串长度不能超过100")
    return value

class MyModel(BaseModel):
    content: Annotated[str, BeforeValidator(custom_validator)]

资料来源：instructor/dsl/validators.py:1-40

验证器组合

多个验证器可以组合使用，形成链式验证：

class ValidatedString(BaseModel):
    value: Annotated[
        str,
        BeforeValidator(validator1),
        BeforeValidator(validator2),
        BeforeValidator(validator3),
    ]

资料来源：instructor/dsl/validators.py:40-60

最佳实践

验证设计原则

1. 渐进式验证：从简单类型验证开始，逐步增加复杂规则
2. 错误消息清晰：自定义错误消息应明确指出问题所在
3. 合理设置重试次数：根据场景调整 max_retries 值
4. 使用 LLM 验证器：对于语义相关的验证，优先使用 llm_validator

性能考虑

相关资源

• Pydantic 官方文档：https://docs.pydantic.dev/
• Instructor 验证概念文档：docs/concepts/validation.md
• 重试机制文档：docs/concepts/reask_validation.md

概述

流式输出（Streaming）是 Instructor 库中用于处理大型语言模型（LLM）响应的核心功能之一。当模型生成较长文本或复杂结构化数据时，流式输出允许开发者逐步获取模型的生成结果，而无需等待完整响应生成完毕。这种方式显著改善了用户体验，特别是在需要实时反馈的应用场景中，如聊天机器人、长文本生成工具和交互式数据分析系统。

Instructor 提供了两种主要的流式输出模式：第一种是部分模式（Partial），用于接收正在构建中的结构化数据；第二种是可迭代模式（Iterable），用于处理需要逐步验证的长序列数据。这两种模式都基于 Pydantic 模型进行类型安全保证，确保流式输出的数据始终符合预期的数据结构。

流式输出的核心优势在于其能够将模型的增量生成与验证逻辑紧密结合。当模型逐 token 生成内容时，Instructor 能够实时解析这些部分内容并填充到 Pydantic 模型字段中，开发者可以在每个增量更新时访问当前已验证的部分数据。这种实时解析和验证的能力使得 Instructor 的流式输出不仅提供了流畅的用户体验，还确保了数据结构的完整性和类型安全。

架构设计

核心组件关系

Instructor 的流式输出系统由多个关键组件协同工作，这些组件共同实现了从模型生成到结构化数据解析的完整流程。理解这些组件之间的关系对于正确使用流式输出功能至关重要。

graph TD
    A[LLM 模型] --> B[流式响应]
    B --> C[响应处理器]
    C --> D[Partial 模式]
    C --> E[Iterable 模式]
    D --> F[Pydantic BaseModel]
    E --> G[迭代器接口]
    F --> H[实时验证]
    G --> I[延迟验证]
    H --> J[增量更新回调]
    I --> J

从架构层面来看，Instructor 的流式输出系统采用了分层设计模式。最底层是模型提供者（Provider）无关的通用接口，中间层是针对不同输出模式的处理逻辑，顶层则是面向开发者的简洁 API。这种分层设计确保了代码的可维护性和扩展性，同时也为支持新的 LLM 提供者提供了便利。

数据流处理

流式输出的数据处理流程可以分为几个关键阶段，每个阶段都有明确的职责和接口定义。在数据生成的初始阶段，模型以流式方式返回 token 序列，这些 token 会被实时拼接成部分完成的文本或 JSON 结构。Instructor 的响应处理器负责识别当前接收到的内容是否构成完整的语义单元，并将这些内容路由到相应的处理模块。

sequenceDiagram
    participant LLM as LLM 模型
    participant Handler as 响应处理器
    participant Parser as 部分解析器
    participant Validator as 验证器
    participant App as 应用程序
    
    LLM->>Handler: 发送增量 token
    Handler->>Parser: 解析部分内容
    Parser->>Validator: 验证当前数据
    Validator-->>Parser: 验证结果
    Parser-->>Handler: 更新状态
    Handler-->>App: 推送部分更新
    App-->>LLM: 请求下一批 token

Partial 模式

功能说明

Partial 模式是 Instructor 流式输出体系中的核心组件，专门设计用于处理结构化数据的增量生成。在传统的非流式调用中，开发者必须等待模型完整生成所有内容后才能获得最终的结构化数据。然而，在许多应用场景中，用户希望能够实时看到正在生成的数据，例如在表单填充、实时分析或交互式问答系统中。

Partial 模式通过维护一个持续更新的 Pydantic 模型实例来实现这一功能。每当模型生成新的 token 并被解析后，对应的模型字段会立即更新，开发者可以访问这些部分填充的字段内容。这种设计确保了数据的即时可用性，同时保持了 Pydantic 模型提供的类型安全和验证功能。

Partial 模式的核心实现位于 instructor/dsl/partial.py 文件中，该文件定义了处理部分响应的基础架构和工具函数。这些实现支持多种 LLM 提供者，并提供了灵活的配置选项以适应不同的使用场景。

使用示例

使用 Partial 模式需要从 Instructor 导入必要的组件，并定义一个继承自 BaseModel 的响应模型。以下是一个典型的工作流程示例，展示了如何配置和使用流式输出来实时获取结构化数据：

from instructor import from_provider
from pydantic import BaseModel

# 初始化 Instructor 客户端
client = from_provider("openai/gpt-4o")

# 定义响应模型
class UserProfile(BaseModel):
    name: str
    bio: str
    skills: list[str]

# 使用 create_partial 方法进行流式输出
response = client.chat.completions.create_partial(
    model="gpt-4o",
    response_model=UserProfile,
    messages=[
        {"role": "user", "content": "生成一个用户画像，包含姓名、简介和技能列表"}
    ]
)

# 迭代处理部分响应
for partial in response:
    print(f"当前进度 - 姓名: {partial.name}")
    if partial.bio:
        print(f"简介: {partial.bio}")
    if partial.skills:
        print(f"技能: {partial.skills}")

上述示例演示了 Partial 模式的基本用法。在实际应用中，开发者可以根据需求添加更复杂的验证逻辑、错误处理机制或用户界面更新代码。关键在于 create_partial 方法返回一个可迭代对象，每次迭代都会产生当前已验证的部分数据。

API 签名

create_partial 方法是 Instructor 流式输出 API 的核心入口，其参数设计兼顾了灵活性和易用性。该方法的签名与标准聊天补全 API 保持高度一致，同时添加了专门用于控制流式行为的参数。

方法的返回值是一个生成器对象，每次迭代产生当前已填充的响应模型实例。当模型生成新内容并通过验证时，该实例会更新相应字段的值。

Iterable 模式

功能说明

Iterable 模式是 Instructor 提供的另一种流式输出实现，专门针对需要生成多个结构化对象的场景。与 Partial 模式不同，Iterable 模式允许模型生成一个序列中的多个项目，每个项目独立验证并在生成后立即可用。这种模式特别适合处理列表生成、批量提取、连续问答等任务。

在 Iterable 模式的工作流程中，模型可以逐步输出多个对象，每个对象都是完整的 Pydantic 模型实例。当第一个对象完成生成并通过验证后，它会被立即返回给调用者，同时模型继续生成后续对象。这种方式的优势在于解耦了对象的生成顺序和可用性，允许应用程序在等待完整列表生成的同时处理已生成的项目。

Iterable 模式的核心实现位于 instructor/dsl/iterable.py 文件中，该实现处理了迭代器协议的所有复杂性，包括状态管理、错误恢复和生成终止条件的判断。开发者无需关心这些底层细节，只需专注于处理生成的对象。

使用示例

以下示例展示了如何使用 Iterable 模式从文本中提取多个实体信息：

from instructor import from_provider
from pydantic import BaseModel
from typing import List

# 初始化 Instructor 客户端
client = from_provider("openai/gpt-4o")

# 定义单个实体的数据模型
class ExtractedEntity(BaseModel):
    name: str
    entity_type: str
    confidence: float

# 使用 create_iterable 方法处理多实体提取
response = client.chat.completions.create_iterable(
    model="gpt-4o",
    response_model=ExtractedEntity,
    messages=[
        {"role": "user", "content": "从以下文本中提取所有提到的组织和人员：..."}
    ]
)

# 处理每个提取的实体
for entity in response:
    print(f"提取实体: {entity.name}")
    print(f"类型: {entity.entity_type}")
    print(f"置信度: {entity.confidence}")

这个示例演示了 Iterable 模式在信息提取任务中的应用。在实际部署中，开发者可以实现更复杂的处理逻辑，如将提取的实体存储到数据库、实时更新用户界面或进行后续的关联分析。

与 Partial 模式的对比

Partial 和 Iterable 模式虽然都是流式输出功能，但它们的设计目标和适用场景有显著差异。理解这些差异有助于开发者选择最适合特定应用需求的模式。

实现原理

部分模型（Partial Model）

Instructor 的流式输出系统建立在 Pydantic 的部分模型（Partial Model）概念之上。部分模型是 Pydantic BaseModel 的一个特殊变体，它允许模型字段在完全填充之前就存在实例。这种设计支持增量数据填充场景，与传统的需要完整数据才能实例化的模型形成对比。

部分模型的实现利用了 Python 的类型注解和描述符协议。当模型实例被创建但某些字段尚未赋值时，这些字段保持为特殊的占位状态。Instructor 的响应处理器会追踪哪些字段已被填充，哪些仍在等待数据，并在每次新的数据到达时更新实例状态。

这种实现方式的一个关键优势是它与 Pydantic 的验证系统完全兼容。即使只有部分字段被填充，Instructor 仍然会对已填充的字段执行验证逻辑，确保数据的有效性和一致性。如果某个字段的验证失败，系统会触发相应的错误处理流程，可能是重试当前字段或跳过该字段继续处理其他内容。

验证与重试机制

流式输出中的验证机制面临着独特的挑战，因为部分数据可能不符合完整的验证规则，但这些数据在最终完成时将是有效的。为了处理这种情况，Instructor 实现了智能化的验证策略，在严格性和灵活性之间取得平衡。

graph TD
    A[接收增量数据] --> B{字段完整？}
    B -->|是| C[执行完整验证]
    B -->|否| D[检查必填字段]
    C --> E{验证通过？}
    E -->|是| F[更新模型实例]
    E -->|否| G{重试次数<限制？}
    G -->|是| H[发送修正请求]
    G -->|否| I[抛出验证异常]
    D --> F
    H --> A

验证过程首先检查已填充的字段是否满足其约束条件。对于可选字段，即使没有数据也会通过验证；对于必填字段，系统会等待足够的数据到达后才进行验证。一旦所有必填字段都被填充且通过验证，部分模型就可以被安全地传递给应用程序。

重试机制是流式输出可靠性的重要保障。当验证失败且错误表明是暂时性问题（如格式不完整或内容不符合约束）时，Instructor 会自动重试请求，并在重试时附带错误信息作为上下文，帮助模型修正之前的错误输出。

高级用法

与钩子（Hooks）集成

Instructor 的钩子系统与流式输出功能深度集成，提供了在处理流程的各个阶段插入自定义逻辑的能力。钩子允许开发者在响应处理、数据验证、错误处理等关键时刻执行自定义代码，实现日志记录、性能监控、内容过滤等辅助功能。

流式输出场景下的钩子使用方式与非流式场景基本一致，但钩子接收的参数可能因部分数据的性质而有所不同。例如，一个用于记录进度的钩子可能在每次部分更新时被调用，并接收当前已更新的字段列表作为参数。以下是一个集成钩子的示例：

from instructor import from_provider, Hooks

def on_partial_update(partial_data):
    print(f"部分更新接收 - 已填充字段: {list(partial_data.model_dump(exclude_none=True).keys())}")

# 定义钩子配置
hooks = Hooks(on_partial_update=on_partial_update)

# 在流式调用中使用钩子
response = client.chat.completions.create_partial(
    model="gpt-4o",
    response_model=UserProfile,
    messages=[...],
    hooks=hooks
)

错误处理策略

流式输出中的错误处理需要考虑实时性和上下文相关性特点。与批处理模式不同，流式场景下的错误通常需要在数据仍在生成时被捕获和处理，否则可能导致用户体验的中断或数据丢失。Instructor 提供了多层次的错误处理机制，以适应不同的故障场景。

在验证错误的情况下，如果设置了 max_retries 参数，Instructor 会自动尝试修复问题并继续生成过程。这种自动修复能力依赖于底层模型的上下文理解能力，当错误信息被作为上下文反馈给模型时，模型通常能够理解问题所在并生成更符合要求的输出。如果重试次数耗尽仍未通过验证，系统会抛出异常，应用程序应准备好捕获并优雅地处理这些异常。

对于网络错误或服务不可用等外部问题，Instructor 利用 tenacity 库实现的重试逻辑来处理。这些错误通常是暂时性的，通过指数退避策略进行重试可以有效提高请求成功率。开发者在配置重试策略时应考虑应用场景的实时性要求，在可靠性和响应速度之间做出权衡。

最佳实践

性能优化建议

在使用 Instructor 流式输出功能时，遵循一定的性能优化实践可以显著提升应用的响应速度和资源利用效率。首先，应该根据实际需求选择合适的流式模式：对于需要实时看到部分结果的场景使用 Partial 模式，对于可以等待完整对象生成后再处理的场景使用 Iterable 模式。

模型选择对性能有直接影响。较大的模型通常能生成更准确的结果，但响应速度和成本也相应增加。在需要高吞吐量的场景中，可以考虑使用较小但足够准确的模型，或者先使用小模型进行快速验证，再在必要时切换到大模型进行精调。

网络连接质量对流式输出的用户体验至关重要。建议使用可靠的连接并进行适当的超时配置。对于需要处理不稳定网络环境的应用，可以实现连接重试逻辑和断点续传机制，确保在网络中断后能够快速恢复处理。

常见陷阱与规避

流式输出实现中的常见陷阱之一是在处理部分数据时过早地假设数据完整性。开发者应该始终检查字段是否为 None 或使用 Pydantic 的 model_dump(exclude_none=True) 方法来获取已填充的数据。忽略这些检查可能导致应用程序在使用未完成的字段值时出现错误。

另一个常见问题是未能正确处理验证失败的情况。在流式场景中，模型可能在首次尝试时生成不符合验证规则的内容，这并不一定表示系统故障。通过设置合理的 max_retries 值并实现适当的回退逻辑，可以有效处理这些情况，同时保持良好的用户体验。

资源管理也是需要关注的问题。长时间运行的流式请求会占用网络连接和内存资源，如果应用程序同时处理大量并发请求，可能会导致资源耗尽。建议实现适当的请求限制机制，并确保在使用完毕后正确关闭流式连接。

参考资料

本页面内容基于 Instructor 项目的源码和文档生成，以下是主要参考资料：

• 部分模式实现源码：instructor/dsl/partial.py 资料来源：instructor/dsl/partial.py
• 可迭代模式实现源码：instructor/dsl/iterable.py 资料来源：instructor/dsl/iterable.py
• 部分模式文档：docs/concepts/partial.md 资料来源：docs/concepts/partial.md
• 可迭代模式文档：docs/concepts/iterable.md 资料来源：docs/concepts/iterable.md
• 流式输出示例代码：examples/partial_streaming/run.py 资料来源：examples/partial_streaming/run.py
• 钩子系统文档：examples/hooks/README.md 资料来源：examples/hooks/README.md

概述

批处理（Batching）是 Instructor 库提供的一项高级功能，允许用户将多个 LLM 请求批量提交到各大模型提供商，从而显著提升大规模数据处理的效率。与实时交互式 API 调用不同，批处理作业会在后台异步执行，适用于需要对大量数据进行结构化提取、转换或分类的场景。Instructor 通过统一的 BatchProcessor 接口抽象了不同提供商（OpenAI、Anthropic、Google）的批处理实现，开发者无需关心底层细节即可完成跨平台批处理任务。资料来源：examples/batch_api/README.md

核心架构

组件结构

Instructor 的批处理系统由以下核心组件构成：

工作流程

graph TD
    A[用户创建批处理请求] --> B[BatchProcessor 接收请求]
    B --> C{Provider 检测}
    C -->|OpenAI| D[OpenAI Batch Provider]
    C -->|Anthropic| E[Anthropic Batch Provider]
    C -->|Google| F[Google Batch Provider]
    D --> G[生成 Provider 特定格式]
    E --> G
    F --> G
    G --> H[提交批处理作业]
    H --> I[保存 Batch ID]
    I --> J[返回控制权给用户]
    J --> K[用户轮询状态]
    K --> L[获取结果]

BatchProcessor 核心功能

主要特性

BatchProcessor 提供了以下核心能力：

• 统一 API 设计：通过 instructor.from_provider() 自动检测提供商类型
• 异步执行：批处理作业在后台异步运行，不阻塞主线程
• Provider 检测：自动识别 provider/model-name 格式中的提供商
• 批量文件生成：根据不同 Provider 生成符合其规范的 JSONL 格式文件
• 任务状态管理：保存批处理 ID 供后续状态查询使用

使用示例

from instructor.batch import BatchProcessor
from openai import OpenAI

# 初始化客户端和批处理器
client = instructor.from_provider("openai/gpt-4o-mini")
batch_processor = BatchProcessor(client=client)

# 创建批处理作业
batch_job = batch_processor.create(
    model="openai/gpt-4o-mini",
    messages=test_messages,
    response_model=User
)

# 保存 Batch ID
with open("openai_batch_id.txt", "w") as f:
    f.write(batch_job.id)

支持的模型提供商

OpenAI

Anthropic

Google

Provider 特定实现

OpenAI Batch Provider

OpenAI 的批处理采用 client.beta.batch 端点，生成符合 OpenAI 规范的批处理文件格式。处理流程包括：

1. 接收消息列表和响应模型
2. 将每个消息转换为 OpenAI Batch API 的 JSONL 格式
3. 提交批处理作业到 OpenAI 端点
4. 返回包含批处理 ID 的响应对象

资料来源：instructor/batch/providers/openai.py

Anthropic Batch Provider

Anthropic 的批处理使用 client.beta.messages.batches 端点，属于 Beta API 范畴。需要特别注意：

• 必须拥有 Anthropic API 访问权限
• 可能存在地区可用性限制
• 批处理速率限制与常规 API 分离

资料来源：instructor/batch/providers/anthropic.py

Google Batch Provider

Google Gemini 的批处理目前默认为模拟模式运行。完整实现需要：

• 配置 Google Cloud Storage (GCS)
• 设置适当的 GCS 认证
• 创建实际的 GCS 存储桶用于输入/输出

资料来源：examples/batch_api/README.md

命令行接口

Instructor CLI 提供了便捷的批处理操作命令：

# 创建批处理作业
instructor batch create \
  --messages-file messages.jsonl \
  --model "openai/gpt-4o-mini" \
  --response-model "examples.User" \
  --output-file batch_requests.jsonl

# 从文件提交批处理
instructor batch create-from-file \
  --file-path batch_requests.jsonl \
  --model "openai/gpt-4o-mini"

资料来源：examples/batch_api/README.md

环境配置

API 密钥要求

直接传递密钥

除了环境变量方式，Instructor 也支持在代码中直接传递 API 密钥：

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_...")

常见错误处理

Provider 格式错误

❌ Error: Model must be in format 'provider/model-name'

解决方案：使用 provider/model-name 格式，例如 openai/gpt-4o-mini

不支持的 Provider

❌ Unsupported provider: xyz

解决方案：当前仅支持 openai、anthropic 和 google 作为 Provider

密钥未设置

❌ OPENAI_API_KEY is not set

解决方案：设置相应的环境变量或通过参数传递 API 密钥

测试与验证

测试脚本

examples/batch_api/run_batch_test.py 提供完整的批处理功能测试：

# 测试 OpenAI
export OPENAI_API_KEY="your-openai-api-key"
python run_batch_test.py create --model "openai/gpt-4o-mini"

# 测试 Anthropic
export ANTHROPIC_API_KEY="your-anthropic-api-key"
python run_batch_test.py create --model "anthropic/claude-3-5-sonnet-20241022"

# 测试 Google (模拟模式)
python run_batch_test.py create --model "google/gemini-2.0-flash-001"

查看支持模型

python run_batch_test.py list-models

与其他功能的集成

与 Retries 的结合

批处理支持 Instructor 的自动重试机制，当验证失败时会自动重试：

batch_job = batch_processor.create(
    model="openai/gpt-4o-mini",
    messages=test_messages,
    response_model=User,
    max_retries=3  # 启用自动重试
)

与 Validators 的结合

批处理可以配合 Pydantic 验证器使用，确保输出符合预期结构：

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

batch_job = batch_processor.create(
    model="openai/gpt-4o-mini",
    messages=test_messages,
    response_model=User
)

最佳实践

1. 批量大小控制：根据 Provider 的速率限制调整批处理大小
2. 响应模型设计：使用清晰的 Pydantic 模型定义期望的输出结构
3. 错误处理：实现健壮的错误捕获和重试逻辑
4. 状态监控：定期轮询批处理状态以获取最新结果
5. 成本优化：选择合适的模型（如 gpt-4o-mini）以平衡成本和性能

概述

Instructor 的钩子系统是一个强大的事件监听与回调机制，允许开发者在 LLM 请求的完整生命周期中插入自定义逻辑。通过钩子，开发者可以监控请求状态、记录日志、统计 token 使用量、处理解析错误、捕获完成错误以及跟踪重试尝试。

钩子系统的主要作用包括：

• 请求监控：在请求发送前获取完整的请求详情
• 使用量统计：追踪输入/输出 token 数量和成本
• 错误处理：捕获并处理解析错误和完成错误
• 重试跟踪：记录自动重试的次数和状态变化
• 自定义扩展：在任意生命周期节点插入业务逻辑

资料来源：examples/hooks/README.md

架构设计

钩子类型体系

Instructor 的钩子系统采用分层架构设计，主要包含以下钩子类型：

graph TD
    A[Hook 基类] --> B[HookStatistics]
    A --> C[HookBase]
    B --> D[TokenUsageHook]
    B --> E[RetryHook]
    C --> F[ParseErrorHook]
    C --> G[CompletionErrorHook]
    C --> H[RequestHook]

资料来源：instructor/core/hooks.py

请求生命周期钩子流程

sequenceDiagram
    participant Client as 客户端
    participant Hooks as 钩子系统
    participant LLM as LLM API
    participant Validator as 验证器
    
    Client->>Hooks: 1. 触发 on_request 钩子
    Hooks->>Hooks: 记录请求详情和模型信息
    Client->>LLM: 2. 发送请求
    LLM-->>Client: 返回响应
    Client->>Hooks: 3. 触发 on_new_token 钩子
    Hooks->>Hooks: 记录 token 使用量
    Client->>Validator: 4. 验证响应
    alt 验证成功
        Client->>Hooks: 5. 触发 on_success 钩子
    else 验证失败
        Client->>Hooks: 5a. 触发 on_retry 钩子
        Client->>LLM: 6. 重试请求
        loop 直到成功或达到最大重试次数
            LLM-->>Client: 返回新响应
            Client->>Validator: 重新验证
        end
        alt 最终成功
            Client->>Hooks: 触发 on_success
        else 最终失败
            Client->>Hooks: 触发 on_parse_error 或 on_completion_error
        end
    end

资料来源：instructor/hooks.py

核心钩子类型详解

1. 请求钩子 (RequestHook)

请求钩子允许在每次 API 调用时执行自定义逻辑，可用于日志记录、请求追踪等场景。

事件触发时机：在请求发送到 LLM API 之前触发。

from instructor.hooks import RequestHook

def my_request_hook(
    completion: Any,
    prompt: Union[str, List[Dict]],
    model: str,
    **kwargs: Any,
) -> None:
    """自定义请求钩子"""
    print(f"请求发送至模型: {model}")
    print(f"提示词长度: {len(str(prompt))} 字符")

资料来源：instructor/hooks.py

2. Token 使用量钩子 (TokenUsageHook)

Token 使用量钩子用于统计和记录 API 调用消耗的 token 数量及预估成本。

事件触发时机：在收到响应后、解析完成前触发。

from instructor.hooks import TokenUsageHook

class MyTokenTracker(TokenUsageHook):
    def __init__(self):
        self.total_input_tokens = 0
        self.total_output_tokens = 0
        self.cost_per_1k_input = 0.0015  # GPT-4o 价格
        self.cost_per_1k_output = 0.002

    def __call__(
        self,
        completion: Any,
        prompt_tokens: int,
        completion_tokens: int,
        total_tokens: int,
        **kwargs: Any,
    ) -> None:
        self.total_input_tokens += prompt_tokens
        self.total_output_tokens += completion_tokens
        estimated_cost = (
            prompt_tokens * self.cost_per_1k_input / 1000 +
            completion_tokens * self.cost_per_1k_output / 1000
        )
        print(f"预估成本: ${estimated_cost:.4f}")

资料来源：instructor/core/hooks.py

3. 解析错误钩子 (ParseErrorHook)

解析错误钩子在响应无法被解析为目标 Pydantic 模型时触发。

事件触发时机：当模型验证失败或响应格式不符合预期时触发。

from instructor.hooks import ParseErrorHook

def handle_parse_error(
    completion: Any,
    response_model: Type[BaseModel],
    error: ValidationError,
    attempt: int,
    **kwargs: Any,
) -> None:
    """处理解析错误"""
    print(f"解析错误 (尝试 {attempt}/{max_retries})")
    print(f"错误详情: {error}")
    # 可选: 记录到监控系统

资料来源：instructor/hooks.py

4. 完成错误钩子 (CompletionErrorHook)

完成错误钩子在 LLM API 调用本身失败时触发，如网络错误、超时、API 限流等。

事件触发时机：当 API 调用抛出异常时触发。

from instructor.hooks import CompletionErrorHook

def handle_completion_error(
    completion: Optional[Any],
    error: Exception,
    attempt: int,
    **kwargs: Any,
) -> None:
    """处理 API 完成错误"""
    print(f"API 错误 (尝试 {attempt}/{max_retries})")
    print(f"错误类型: {type(error).__name__}")
    print(f"错误信息: {str(error)}")

资料来源：instructor/hooks.py

5. 重试钩子 (RetryHook)

重试钩子在触发自动重试时调用，可用于追踪重试行为和性能监控。

事件触发时机：在每次重试开始前触发。

from instructor.hooks import RetryHook

def track_retry(
    attempt: int,
    exception: Exception,
    **kwargs: Any,
) -> None:
    """追踪重试行为"""
    print(f"触发重试 #{attempt}")
    print(f"原因: {type(exception).__name__}: {exception}")

资料来源：instructor/core/hooks.py

使用指南

基础使用方式

#### 方式一：使用装饰器注册钩子

from instructor import from_openai
from instructor.hooks import Hooks, hook

client = from_openai(OpenAI())

@hook
def my_hooks(
    on_request: bool = True,
    on_success: bool = True,
    on_retry: bool = True,
    on_error: bool = True,
    **kwargs,
) -> Hooks:
    # 每次请求时打印统计信息
    print(f"Request sent to {kwargs.get('model', 'unknown')}")
    return Hooks(
        on_new_token=lambda token, **kw: print(f"Token: {token}"),
        on_success=lambda response, **kw: print("Success!"),
    )

user = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}],
    response_model=User,
    hooks=my_hooks,  # 传入钩子函数
)

资料来源：examples/hooks/run.py

#### 方式二：创建 Hooks 实例

from instructor import Instructor
from instructor.hooks import Hooks

def request_handler(completion, **kwargs):
    print(f"📏 近似输入 Token 数量: {kwargs.get('estimated_tokens', 0)}")

def success_handler(response, **kwargs):
    print("✅ 成功响应")
    print(f"响应类型: {type(response)}")

hooks = Hooks(
    on_request=request_handler,
    on_success=success_handler,
)

client = Instructor(
    model="gpt-4o-mini",
    hooks=hooks,
)

资料来源：examples/hooks/run.py

客户端级钩子配置

在创建客户端时配置全局钩子：

from instructor import from_openai

# 全局钩子实例
global_hooks = Hooks(
    on_request=lambda **kw: log_request(**kw),
    on_new_token=lambda token, **kw: track_token(token, **kw),
    on_success=lambda response, **kw: log_success(**kw),
    on_retry=lambda attempt, **kw: log_retry(attempt, **kw),
    on_parse_error=lambda error, **kw: alert_parse_error(error, **kw),
    on_completion_error=lambda error, **kw: alert_completion_error(error, **kw),
)

client = from_openai(
    OpenAI(),
    hooks=global_hooks,
)

资料来源：docs/concepts/hooks.md

请求级钩子覆盖

单个请求可以覆盖客户端级钩子：

from instructor.hooks import Hooks

request_hooks = Hooks(
    on_request=lambda **kw: print(f"此请求使用模型: {kw.get('model')}"),
)

user = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Extract user info"}],
    response_model=User,
    hooks=request_hooks,  # 仅此请求使用
)

资料来源：instructor/core/hooks.py

高级用法

多钩子组合

from instructor.hooks import Hooks

class StatisticsCollector:
    """统计收集器"""
    def __init__(self):
        self.request_count = 0
        self.success_count = 0
        self.error_count = 0
        self.total_retries = 0

    def on_request(self, **kwargs):
        self.request_count += 1
        print(f"📊 请求 #{self.request_count}")

    def on_success(self, **kwargs):
        self.success_count += 1
        print(f"✅ 成功 #{self.success_count}")

    def on_retry(self, attempt, **kwargs):
        self.total_retries += 1
        print(f"🔄 重试 #{attempt} (总计: {self.total_retries})")

    def on_parse_error(self, error, **kwargs):
        self.error_count += 1
        print(f"⚠️ 解析错误 #{self.error_count}: {error}")

# 创建收集器实例
stats = StatisticsCollector()

hooks = Hooks(
    on_request=stats.on_request,
    on_success=stats.on_success,
    on_retry=stats.on_retry,
    on_parse_error=stats.on_parse_error,
)

# 使用钩子
client = from_openai(OpenAI(), hooks=hooks)

资料来源：examples/hooks/run.py

钩子与重试机制集成

钩子系统与 Instructor 的自动重试机制深度集成：

graph LR
    A[请求发送] --> B{验证成功?}
    B -->|是| C[触发 on_success]
    B -->|否| D{还有重试次数?}
    D -->|是| E[触发 on_retry]
    E --> F[重新发送请求]
    F --> A
    D -->|否| G{错误类型}
    G -->|解析错误| H[触发 on_parse_error]
    G -->|API错误| I[触发 on_completion_error]

from instructor.hooks import Hooks

def retry_logger(attempt, exception, **kwargs):
    """记录重试详情"""
    print(f"🔄 重试 #{attempt}")
    print(f"   异常类型: {type(exception).__name__}")
    print(f"   异常信息: {str(exception)[:100]}")

hooks = Hooks(
    on_retry=retry_logger,
)

# Instructor 会自动使用钩子在重试时通知
user = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "..."}],
    response_model=User,
    max_retries=3,  # 启用自动重试
    hooks=hooks,
)

资料来源：instructor/core/hooks.py

条件性钩子执行

from instructor.hooks import Hooks
from functools import partial

def log_if_error(error, **kwargs):
    """仅在错误发生时记录"""
    print(f"⚠️ 错误: {error}")

def log_every_request(model, **kwargs):
    """记录所有请求"""
    print(f"📤 请求: {model}")

def conditional_hooks_factory(condition: bool):
    """根据条件返回不同的钩子"""
    if condition:
        return Hooks(
            on_request=log_every_request,
            on_error=log_if_error,
        )
    return Hooks()

# 根据业务逻辑选择钩子
hooks = conditional_hooks_factory(debug_mode=True)

资料来源：instructor/hooks.py

Hooks 类 API 参考

构造函数参数

on_request 钩子参数

on_success 钩子参数

on_retry 钩子参数

资料来源：instructor/core/hooks.py

最佳实践

1. 钩子函数应保持轻量

# ✅ 推荐：轻量级钩子
def quick_log(**kwargs):
    logger.info(f"Model: {kwargs.get('model')}")

# ❌ 避免：重量级操作在钩子中
def heavy_hook(**kwargs):
    # 不要在钩子中进行复杂计算或网络请求
    result = some_external_api_call()  # 这会影响性能

资料来源：examples/hooks/run.py

2. 使用类封装状态

class HookManager:
    """钩子管理器 - 封装状态和逻辑"""
    
    def __init__(self, output_path: str):
        self.output_path = output_path
        self.metrics = []
    
    def create_hooks(self) -> Hooks:
        return Hooks(
            on_request=self._handle_request,
            on_success=self._handle_success,
            on_error=self._handle_error,
        )
    
    def _handle_request(self, **kwargs):
        self.metrics.append({"type": "request", **kwargs})
    
    def _handle_success(self, response, **kwargs):
        self.metrics.append({"type": "success"})
    
    def _handle_error(self, error, **kwargs):
        self.metrics.append({"type": "error", "error": str(error)})

资料来源：instructor/hooks.py

3. 分离关注点

# 不同的关注点使用不同的钩子处理器
class RequestLogger:
    def __call__(self, **kwargs):
        logging.info(f"Request: {kwargs}")

class MetricsCollector:
    def __call__(self, **kwargs):
        prometheus.counter("instructor_requests").inc()

class AlertManager:
    def __call__(self, error, **kwargs):
        sentry.capture_exception(error)

# 组合使用
hooks = Hooks(
    on_request=RequestLogger(),
    on_success=MetricsCollector(),
    on_error=AlertManager(),
)

资料来源：docs/concepts/hooks.md

4. 异常安全

def safe_hook(func):
    """包装钩子以确保异常安全"""
    def wrapper(*args, **kwargs):
        try:
            func(*args, **kwargs)
        except Exception as e:
            # 记录错误但不阻止流程
            logging.error(f"Hook error: {e}")
    return wrapper

hooks = Hooks(
    on_request=safe_hook(my_request_hook),
    on_success=safe_hook(my_success_hook),
)

常见应用场景

场景一：API 使用量监控

from instructor.hooks import Hooks

class UsageMonitor:
    def __init__(self):
        self.total_tokens = {"prompt": 0, "completion": 0}
    
    def __call__(self, **kwargs):
        self.total_tokens["prompt"] += kwargs.get("prompt_tokens", 0)
        self.total_tokens["completion"] += kwargs.get("completion_tokens", 0)
        print(f"累计: 输入={self.total_tokens['prompt']}, 输出={self.total_tokens['completion']}")

hooks = Hooks(
    on_new_token=UsageMonitor(),
)

场景二：调试响应内容

def debug_hook(response, completion, **kwargs):
    """调试钩子：打印响应详情"""
    print("=" * 50)
    print(f"响应类型: {type(response)}")
    print(f"原始响应: {completion}")
    print("=" * 50)

hooks = Hooks(
    on_success=debug_hook,
)

场景三：性能追踪

import time

class PerformanceTracker:
    def __init__(self):
        self.start_time = None
    
    def on_request(self, **kwargs):
        self.start_time = time.time()
    
    def on_success(self, response, **kwargs):
        elapsed = time.time() - self.start_time
        print(f"⏱️ 响应时间: {elapsed:.2f}秒")
    
    def on_retry(self, attempt, **kwargs):
        print(f"🔄 第 {attempt} 次重试...")

hooks = Hooks(
    on_request=PerformanceTracker().on_request,
    on_success=PerformanceTracker().on_success,
    on_retry=PerformanceTracker().on_retry,
)

资料来源：examples/hooks/run.py

总结

Instructor 的钩子系统提供了一套完整的事件监听机制，覆盖了 LLM 请求的完整生命周期。通过合理使用钩子，开发者可以实现：

• 可观测性：监控请求、响应、错误和性能指标
• 可追溯性：记录详细的操作日志用于审计
• 自愈能力：结合重试机制自动处理临时性故障
• 业务扩展：在任意生命周期节点插入自定义逻辑

钩子系统设计简洁、API 清晰，与 Instructor 的核心功能深度集成，是构建生产级 LLM 应用不可或缺的组件。

资料来源：docs/concepts/hooks.md

Pitfall Log / 踩坑日志

项目：567-labs/instructor

摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Documentation (at least Google-related) is an outdated mess.。

1. 安装坑 · 来源证据：Documentation (at least Google-related) is an outdated mess.

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Documentation (at least Google-related) is an outdated mess.
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b87b003416cd4308bc863f0cd66a68fd | https://github.com/567-labs/instructor/issues/2289 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：v1.13.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.13.0
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f3c1e8416a744b51b5691317c10bc5bf | https://github.com/567-labs/instructor/releases/tag/v1.13.0 | 来源类型 github_release 暴露的待验证使用条件。

3. 配置坑 · 来源证据：v1.12.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.12.0
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9b8236f58f8641c586777618a838409f | https://github.com/567-labs/instructor/releases/tag/v1.12.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：v1.14.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_053ef3382ace48778d05ef006d87cead | https://github.com/567-labs/instructor/releases/tag/v1.14.0 | 来源类型 github_release 暴露的待验证使用条件。

5. 配置坑 · 来源证据：v1.14.3

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.3
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d18c003929614c7097d16742ec94cc8c | https://github.com/567-labs/instructor/releases/tag/v1.14.3 | 来源类型 github_release 暴露的待验证使用条件。

6. 配置坑 · 来源证据：v1.14.4

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.14.4
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_76987134f9a747d685958a5e98f3b51a | https://github.com/567-labs/instructor/releases/tag/v1.14.4 | 来源类型 github_release 暴露的待验证使用条件。

7. 配置坑 · 来源证据：v1.15.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.15.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_430369db61e440e5a4b575e2b3618464 | https://github.com/567-labs/instructor/releases/tag/v1.15.0 | 来源类型 github_release 暴露的待验证使用条件。

8. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:653589102 | https://github.com/567-labs/instructor | README/documentation is current enough for a first validation pass.

9. 运行坑 · 来源证据：v1.14.2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.14.2
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_fd561faf78f147518bcda7a0370a9a4f | https://github.com/567-labs/instructor/releases/tag/v1.14.2 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

10. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | last_activity_observed missing

11. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium

12. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:653589102 | https://github.com/567-labs/instructor | no_demo; severity=medium

13. 安全/权限坑 · 来源证据：Catching IncompleteOutputException : not possible as presently documented / tested.

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Catching IncompleteOutputException : not possible as presently documented / tested.
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_dc0f4256859740f8a4cacd1731514783 | https://github.com/567-labs/instructor/issues/2273 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

14. 安全/权限坑 · 来源证据：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RESPONSES_TOOLS streaming drops reasoning summary events (summary: auto)
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b982358c78a346bfaa26b428e00968bb | https://github.com/567-labs/instructor/issues/2291 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

15. 安全/权限坑 · 来源证据：bump lightllm upper bound for recent vulnerabililties

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bump lightllm upper bound for recent vulnerabililties
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2ae9c53479204c778e56a8b4b3feb404 | https://github.com/567-labs/instructor/issues/2290 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：logger.debug in response.py leaks api_key verbatim via new_kwargs

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：logger.debug in response.py leaks api_key verbatim via new_kwargs
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2076a35fb27a4c119141e9f57acdf9bc | https://github.com/567-labs/instructor/issues/2265 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

17. 安全/权限坑 · 来源证据：reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUseBlock.caller=None serialized as null in retry m…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：reask_anthropic_tools retry fails with HTTP 400 on AWS Bedrock — ToolUseBlock.caller=None serialized as null in retry message
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0ab343e8383b4d89bbe8eeea25cc69d8 | https://github.com/567-labs/instructor/issues/2277 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

18. 安全/权限坑 · 来源证据：v1.14.5

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.14.5
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e73ef57918504fe88cf0af969c414ca1 | https://github.com/567-labs/instructor/releases/tag/v1.14.5 | 来源类型 github_release 暴露的待验证使用条件。

19. 安全/权限坑 · 来源证据：v1.15.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.15.1
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ef102fc17ae84e319f80cfd4cc306eaa | https://github.com/567-labs/instructor/releases/tag/v1.15.1 | 来源类型 github_release 暴露的待验证使用条件。

20. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | issue_or_pr_quality=unknown

21. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:653589102 | https://github.com/567-labs/instructor | release_recency=unknown