跳到内容

Instructor 模式对比指南

Instructor 支持针对不同 LLM 提供商的多种“模式”。本指南帮助您了解何时使用每种模式及其权衡。

可用模式概览

Instructor 的模式决定了如何从 LLM 响应中请求和提取结构化数据。选择合适的模式取决于您的提供商、模型和具体需求。

以下是快速对比

模式 描述 最佳适用场景 提供商
TOOLS 使用函数/工具调用 API 大多数 OpenAI 用例 OpenAI、Azure、LiteLLM 等
JSON 请求直接输出 JSON 不支持工具调用的模型 大多数提供商
FUNCTIONS (旧版) 旧版 OpenAI 函数调用 向后兼容性 OpenAI、Azure
PARALLEL_TOOLS 并行运行多个工具 复杂、多步骤的任务 仅限 OpenAI
MD_JSON Markdown 代码块中的 JSON 更清晰的提示 大多数提供商
TOOLS_STRICT 更严格的 TOOLS 版本 生产系统 OpenAI、Azure
JSON_O1 使用 JSON 进行一次性补全 简单提取 OpenAI、Azure
ANTHROPIC_TOOLS Anthropic 的工具调用 Claude 模型 Anthropic
ANTHROPIC_JSON 直接输出 Claude 的 JSON Claude 模型 Anthropic
GEMINI_TOOLS Google 的函数调用 Gemini 模型 Google
GEMINI_JSON 直接输出 Gemini 的 JSON Gemini 模型 Google
VERTEXAI_TOOLS Vertex AI 函数调用 Vertex AI 模型 Vertex AI
VERTEXAI_JSON 直接输出 Vertex AI 的 JSON Vertex AI 模型 Vertex AI
COHERE_TOOLS Cohere 的工具调用 Cohere 模型 Cohere

模式详细解释

兼容 OpenAI 的模式

TOOLS 模式

client = instructor.from_openai(
    OpenAI(),
    mode=instructor.Mode.TOOLS
)

这是 OpenAI 模型的推荐模式。它使用 OpenAI 的工具调用 API 来

  • 为模型提供清晰的 schema
  • 确保格式正确
  • 启用验证和重试

最佳适用场景：大多数 OpenAI 用例，特别是 GPT-3.5 和 GPT-4 模型。

优点： - 最可靠 - 最适合复杂结构 - 适用于所有当前的 OpenAI 模型

JSON 模式

client = instructor.from_openai(
    OpenAI(),
    mode=instructor.Mode.JSON
)

此模式指示模型直接输出 JSON。它： - 几乎适用于任何模型 - 可靠性略低于 TOOLS - 可能更适合非常简单的结构

最佳适用场景：不支持工具调用的模型或简单的提取任务。

优点： - 适用于更多模型 - 可能更节省 token - 提示更简单

MD_JSON 模式

client = instructor.from_openai(
    OpenAI(),
    mode=instructor.Mode.MD_JSON
)

此模式指示模型在 Markdown 代码块内输出 JSON。它： - 适用于大多数模型 - 可以使提示更易读 - 可能产生更清晰的输出

最佳适用场景：需要更清晰输出的简单结构。

Anthropic 模式

ANTHROPIC_TOOLS 模式

client = instructor.from_anthropic(
    Anthropic(),
    mode=instructor.Mode.ANTHROPIC_TOOLS
)

此模式使用 Anthropic 的工具调用 API，适用于 Claude 3+ 模型。它： - 提供结构化的工具定义 - 确保响应格式正确 - 适用于复杂结构

最佳适用场景：使用 Claude 3+ 模型进行复杂结构化输出。

ANTHROPIC_JSON 模式

client = instructor.from_anthropic(
    Anthropic(),
    mode=instructor.Mode.ANTHROPIC_JSON
)

此模式请求 Anthropic 模型直接输出 JSON。它： - 适用于所有 Claude 模型 - 结构化程度低于工具调用 - 对于简单用例可能更灵活

最佳适用场景：简单结构或旧版 Claude 模型。

Google/Gemini 模式

GEMINI_TOOLS 模式

client = instructor.from_gemini(
    genai.GenerativeModel("gemini-1.5-pro"),
    mode=instructor.Mode.GEMINI_TOOLS
)

此模式使用 Google 的函数调用功能，适用于 Gemini 模型。它： - 提供结构化的工具定义 - 工作原理类似于 OpenAI 的工具调用 - 具有一些 Google 特定的适配

最佳适用场景：使用 Gemini 模型进行复杂结构化输出。

注意：不能与多模态输入一起使用。

GEMINI_JSON 模式

client = instructor.from_gemini(
    genai.GenerativeModel("gemini-1.5-pro"),
    mode=instructor.Mode.GEMINI_JSON
)

此模式请求 Gemini 模型直接输出 JSON。它： - 适用于所有 Gemini 模型 - 适用于多模态输入（图像、音频） - 对于复杂结构可能可靠性较低

最佳适用场景：简单结构或使用多模态输入时。

模式选择指南

何时使用基于工具的模式

  • 对于复杂、嵌套的数据结构
  • 当可靠性至关重要时
  • 使用支持工具调用的现代模型时
  • 在需要验证的生产系统中

何时使用基于 JSON 的模式

  • 对于简单的数据结构
  • 使用不支持工具调用的模型时
  • 当 token 效率重要时
  • 使用多模态输入时（对于不支持带多模态的工具的提供商）

特定提供商的建议

OpenAI

# Best for most OpenAI use cases
client = instructor.from_openai(OpenAI(), mode=instructor.Mode.TOOLS)

# For very simple extractions
client = instructor.from_openai(OpenAI(), mode=instructor.Mode.JSON)

# For complex, multi-step processes
client = instructor.from_openai(OpenAI(), mode=instructor.Mode.PARALLEL_TOOLS)

Anthropic

# For Claude 3+ with complex structures
client = instructor.from_anthropic(Anthropic(), mode=instructor.Mode.ANTHROPIC_TOOLS)

# For simpler extractions or older Claude models
client = instructor.from_anthropic(Anthropic(), mode=instructor.Mode.ANTHROPIC_JSON)

Google/Gemini

# For complex structures (non-multi-modal)
client = instructor.from_gemini(
    genai.GenerativeModel("gemini-1.5-pro"),
    mode=instructor.Mode.GEMINI_TOOLS
)

# For multi-modal inputs or simple structures
client = instructor.from_gemini(
    genai.GenerativeModel("gemini-1.5-pro"),
    mode=instructor.Mode.GEMINI_JSON
)

模式兼容性表格

提供商 基于工具的模式 基于 JSON 的模式
OpenAI TOOLS, TOOLS_STRICT, PARALLEL_TOOLS, FUNCTIONS JSON, MD_JSON, JSON_O1
Anthropic ANTHROPIC_TOOLS ANTHROPIC_JSON
Gemini GEMINI_TOOLS GEMINI_JSON
Vertex AI VERTEXAI_TOOLS VERTEXAI_JSON
Cohere COHERE_TOOLS JSON, MD_JSON
Mistral MISTRAL_TOOLS MISTRAL_STRUCTURED_OUTPUTS
Anyscale - JSON, MD_JSON, JSON_SCHEMA
Databricks TOOLS JSON, MD_JSON
Together - JSON, MD_JSON
Fireworks FIREWORKS_TOOLS FIREWORKS_JSON
Cerebras - CEREBRAS_JSON
Writer WRITER_TOOLS JSON
Perplexity - PERPLEXITY_JSON
GenAI GENAI_TOOLS GENAI_STRUCTURED_OUTPUTS
LiteLLM (取决于提供商) (取决于提供商)

最佳实践

  1. 从您的提供商推荐的模式开始
  2. 对于 OpenAI: TOOLS
  3. 对于 Anthropic: ANTHROPIC_TOOLS (Claude 3+) 或 ANTHROPIC_JSON

  4. 对于 Gemini: GEMINI_TOOLS 或用于多模态的 GEMINI_JSON

  5. 对于简单结构或遇到问题时，尝试 JSON 模式

  6. JSON 模式通常适用于更简单的 schema
  7. 它们可能更节省 token

  8. 它们适用于更多模型

  9. 在可用时使用特定于提供商的模式

  10. 特定于提供商的模式针对该提供商进行了优化

  11. 它们处理特殊情况和要求

  12. 测试和验证

  13. 不同的模式在您的特定用例中可能有不同的表现
  14. 始终使用您的实际数据和模型进行测试