第13章 Instructor 模式对比指南:核心模式与已弃用旧模式详解
第13章:模式对比指南¶
Instructor 使用跨供应商的核心模式。供应商专属模式仍然可用,但已被弃用,使用时会出现警告。模式处理逻辑现移至供应商处理器中,DSL 不再存储针对特定模式的流式处理逻辑。
核心模式¶
- TOOLS:用于结构化提取的工具或函数调用。 - JSON_SCHEMA:当供应商支持时,使用原生 Schema 支持。 - MD_JSON:从文本或代码块中提取 JSON,适用于简单场景或作为回退方案。 - PARALLEL_TOOLS:在单个响应中并行调用多个工具。 - RESPONSES_TOOLS:OpenAI Responses API 工具。
已弃用的旧模式¶
以下旧模式映射到核心模式:
- FUNCTIONS -> TOOLS - TOOLS_STRICT -> TOOLS - ANTHROPIC_TOOLS -> TOOLS - ANTHROPIC_JSON -> MD_JSON - GENAI_TOOLS -> TOOLS - GENAI_JSON -> JSON - MISTRAL_TOOLS -> TOOLS - MISTRAL_STRUCTURED_OUTPUTS -> JSON_SCHEMA - BEDROCK_TOOLS -> TOOLS - BEDROCK_JSON -> MD_JSON - FIREWORKS_TOOLS -> TOOLS - FIREWORKS_JSON -> MD_JSON - CEREBRAS_TOOLS -> TOOLS - CEREBRAS_JSON -> MD_JSON - WRITER_TOOLS -> TOOLS - WRITER_JSON -> MD_JSON - PERPLEXITY_JSON -> MD_JSON - VERTEXAI_TOOLS -> TOOLS - VERTEXAI_JSON -> MD_JSON - VERTEXAI_PARALLEL_TOOLS -> PARALLEL_TOOLS
模式选择建议¶
- 大多数结构化输出场景请使用 TOOLS。 - 当供应商支持原生 Schema 强制验证时,请使用 JSON_SCHEMA。 - 当不支持工具或输出较简单时,请使用 MD_JSON。 - 需要在单个响应中处理多个任务时,请使用 PARALLEL_TOOLS。
示例¶
TOOLS 模式(推荐)¶ import instructor from instructor import Mode
client = instructor.from_provider( "openai/gpt-4o-mini", mode=Mode.TOOLS, )
MD_JSON 模式(回退方案)¶ import instructor from instructor import Mode
client = instructor.from_provider( "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", mode=Mode.MD_JSON, )
JSON_SCHEMA 模式(原生 Schema)¶ import instructor from instructor import Mode
client = instructor.from_provider( "openai/gpt-4o-mini", mode=Mode.JSON_SCHEMA, )
更多详情请参阅《模式迁移指南》。
Google/Gemini¶
复杂结构: import instructor
client = instructor.from_provider( "google/gemini-2.5-flash", mode=instructor.Mode.TOOLS, )
包含 JSON 的结构化输出: import instructor
client = instructor.from_provider( "google/gemini-2.5-flash", mode=instructor.Mode.JSON, )
模式兼容性列表¶
旧模式仅展示以保持兼容性。新代码中优先使用核心模式。
- OpenAI:核心模式为 TOOLS;旧模式包括 TOOLS_STRICT, PARALLEL_TOOLS, FUNCTIONS, JSON, MD_JSON, JSON_O1。 - Anthropic:核心模式为 ANTHROPIC_TOOLS;旧模式包括 ANTHROPIC_PARALLEL_TOOLS, ANTHROPIC_JSON。 - Gemini:核心模式为 TOOLS;旧模式包括 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:核心模式为 TOOLS;旧模式包括 JSON。 - LiteLLM:工具类和 JSON 类模式取决于具体的提供商。
最佳实践¶
- 从你所在供应商的推荐模式开始: - OpenAI:TOOLS - Anthropic:ANTHROPIC_TOOLS(Claude 3+)或 ANTHROPIC_JSON - Gemini:TOOLS 或 JSON
- 对于简单结构或遇到兼容性问题时,尝试 JSON 模式: - JSON 模式通常适用于更简单的 Schema - 可能具有更高的 Token 效率 - 支持更多模型
- 当有供应商专属模式可用时,优先使用这些模式: - 供应商专属模式针对该供应商进行了优化 - 它们能处理特殊情况和需求
- 测试与验证: - 不同模式在你的特定用例中表现可能不同 - 务必使用实际数据和模型进行测试