instructor

用途

Instructor 用于从大语言模型（LLM）的响应中可靠地提取结构化数据。当你需要把 LLM 的自由文本输出转换为有类型、可校验、可编程处理的对象时，可以使用它。典型需求包括：可靠地从 LLM 响应中抽取结构化数据、用 Pydantic schema 自动校验输出、在校验失败时自动重试并处理错误、以类型安全方式解析复杂 JSON、流式输出部分结果用于实时处理，以及用一致的 API 支持多个 LLM 提供商。

主要能力

• 响应模型（Pydantic）：用 Pydantic 的 BaseModel 定义 LLM 输出的结构与校验规则，支持字段描述、嵌套模型、可选字段、默认值、枚举约束等。
• 自动校验：Pydantic 自动校验 LLM 输出，支持内置校验（如 min_length、ge、le、EmailStr、HttpUrl）、自定义字段校验器（field_validator）和模型级校验器（model_validator）。
• 自动重试：校验失败时，Instructor 会把错误信息反馈给 LLM 并重试，默认最多重试 3 次（可通过 max_retries 配置）。
• 流式输出：支持流式返回部分对象（create_partial）和流式返回可迭代列表项（create_iterable），用于实时处理。
• 多提供商支持：提供 Anthropic Claude、OpenAI、本地模型（如 Ollama）等提供商的统一接入方式。
• 高级特性：支持 Union 类型、运行时动态创建模型（create_model）、自定义模式（如 Mode.JSON、Mode.ANTHROPIC_TOOLS、Mode.TOOLS）、上下文管理（with 语句）以及错误处理。

使用方式

安装：

# 基础安装
pip install instructor

# 按提供商安装
pip install "instructor[anthropic]"  # Anthropic Claude
pip install "instructor[openai]"     # OpenAI
pip install "instructor[all]"        # 所有提供商

基本用法（以 Anthropic 为例）：先定义 Pydantic 输出结构，再用 instructor.from_anthropic 创建客户端，调用 client.messages.create 并传入 response_model。OpenAI 则用 instructor.from_openai 创建客户端，调用 client.chat.completions.create 并传入 response_model。本地模型（Ollama）通过 OpenAI 兼容接口指向本地服务地址，并设置 mode=instructor.Mode.JSON。

自动重试：在调用时传入 max_retries（默认 3）。流程为：LLM 生成输出 → Pydantic 校验 → 若无效则把错误信息发回 LLM → LLM 带错误反馈重试 → 重复直到达到 max_retries。

流式：使用 create_partial 获取部分对象更新，或使用 create_iterable 逐项处理生成的列表。

适用场景

• 从文本中抽取数据（如公司信息、人物信息）
• 文本分类（配合枚举约束类别）
• 多实体抽取（人物、组织、地点等）
• 结构化分析（如情感分析，输出正面/负面方面、建议、评分）
• 批量处理（对多条文本循环调用抽取函数）

限制与说明

资料中未提供具体的收费、价格信息。资料中未提供性能基准或效果保证。资料中未提供除 Anthropic、OpenAI、Ollama 之外其他提供商的具体配置细节。资料中未提供完整的错误码或异常类型清单。资料中未提供版本兼容性说明。资料中未提供部署、并发或速率限制方面的说明。