6.3 · 结构化输出框架

结构化输出框架

结构化输出框架

相关源文件

本章引用的主要源码文件：

• .env.template
• README.md
• assets/cognee_benefits.png
• cognee/api/v1/config/config.py
• cognee/infrastructure/llm/config.py
• cognee/infrastructure/llm/structured_output_framework/baml/baml_src/extraction/acreate_structured_output.py
• cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/anthropic/adapter.py
• cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/azure_openai/adapter.py
• cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.py
• cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/gemini/adapter.py
• cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/generic_llm_api/adapter.py
• cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py
• cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/llama_cpp/adapter.py
• cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/mistral/adapter.py
• cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/ollama/adapter.py
• cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/openai/adapter.py
• cognee/modules/settings/__init__.py
• cognee/modules/settings/get_settings.py
• cognee/modules/settings/save_llm_config.py
• cognee/modules/settings/save_vector_db_config.py
• cognee/tests/unit/infrastructure/llm/test_get_llm_client.py

目的与范围

本文档解释了 Cognee 的结构化输出框架，该框架用于强制大语言模型（LLM）调用产生类型安全且经过校验的输出。Cognee 利用 Instructor 和 BAML 来确保在实体提取、关系检测和知识图谱构建过程中，大语言模型的响应符合预定义的 Pydantic 模式。

有关大语言模型提供商的配置详情，请参阅大语言模型提供商配置。有关嵌入向量服务，请参阅嵌入向量服务。

概述

结构化输出框架位于 Cognee 的处理管线与大语言模型提供商之间，将自由形式的大语言模型响应转换为经过校验的 Python 对象。这对于需要数据一致性和类型安全的实体提取、知识图谱构建和语义分析任务至关重要。

关键组件：

• Instructor 集成：基于 LiteLLM 构建，为 OpenAI、Anthropic 和 Ollama 等提供商提供统一的结构化提取接口。
• Instructor 模式：支持多种交互模式，包括 json_schema_mode、json_mode 以及提供商特定的工具模式（例如 mistral_tools、anthropic_tools）。
• Pydantic 响应模型：定义大语言模型输出预期结构的主要机制。
• BAML 支持：一个替代框架，使用专门的领域特定语言（DSL）处理复杂的提取任务和动态类型构建。

来源：cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:69-93、cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/llm_interface.py:8-19、cognee/infrastructure/llm/config.py:42-48

框架架构

下图将用户输入和系统提示的自然语言空间与 Pydantic 模型和大语言模型适配器的代码实体空间连接起来。

标题：结构化输出的自然语言到代码实体映射

来源：cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:69-117、cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/openai/adapter.py:37-56、cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/llm_interface.py:8-19

Instructor 框架

Instructor 是 Cognee 中的默认框架。它封装了大语言模型客户端，并强制其返回符合 Pydantic 模型的数据。

Instructor 模式与适配器

Cognee 实现了提供商特定的适配器，以处理不同大语言模型支持结构化输出（例如通过函数调用、工具使用或 JSON 模式）的细微差别。

数据流：acreate_structured_output

acreate_structured_output 方法是生成经过校验数据的主要入口点。

1. 输入：接收 text_input、system_prompt 和一个 response_model（Pydantic 类）。cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/llm_interface.py:17-19
2. 速率限制：将调用包装在 llm_rate_limiter_context_manager 中。cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/openai/adapter.py:144-145
3. 大语言模型调用：通过修补后的 aclient 执行请求。
4. 重试逻辑：使用 tenacity 在临时故障时进行重试（认证错误或 404 错误除外）。cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/openai/adapter.py:109-117
5. 回退：如果配置了 fallback_model 和 fallback_api_key，在遇到内容策略违规或 Instructor 重试后，Cognee 会使用回退模型再次尝试请求。cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/openai/adapter.py:164-190

来源：cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/openai/adapter.py:118-190、cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/generic_llm_api/adapter.py:127-175

BAML 框架支持

BAML 作为替代框架得到支持，特别适用于需要专用领域特定语言（DSL）以更好地控制提示和响应映射的复杂提取任务。通过在环境中设置 STRUCTURED_OUTPUT_FRAMEWORK="baml" 来启用它。cognee/infrastructure/llm/config.py:42-48

动态类型构建

Cognee 使用 TypeBuilder 将 BAML 的内部类型与 Python Pydantic 模型连接起来。

标题：BAML 结构化输出数据流

来源：cognee/infrastructure/llm/structured_output_framework/baml/baml_src/extraction/acreate_structured_output.py:36-76、cognee/infrastructure/llm/config.py:135-152

BAML 关键组件：

• TypeBuilder：在运行时从 Pydantic 模型动态构建 BAML 类型。cognee/infrastructure/llm/structured_output_framework/baml/baml_src/extraction/acreate_structured_output.py:62-63
• baml_registry：一个 ClientRegistry 实例，用于存储 BAML 运行时的大语言模型提供商配置（模型、API 密钥、端点）。cognee/infrastructure/llm/config.py:135-152
• b.AcreateStructuredOutput：生成的 BAML 函数，用于执行实际的大语言模型调用。cognee/infrastructure/llm/structured_output_framework/baml/baml_src/extraction/acreate_structured_output.py:66-70

大语言模型适配器实现

GenericAPIAdapter 作为大多数基于 Instructor 的提供商的基类，实现了 LLMInterface。

GenericAPIAdapter 属性

• self.aclient：使用 litellm.acompletion 的经过 Instructor 修补的客户端。cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/generic_llm_api/adapter.py:113-115
• self.instructor_mode：默认为 json_mode，但可以通过配置进行覆盖。cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/generic_llm_api/adapter.py:72-104
• self.llm_args：传递给完成调用的附加参数字典。cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/generic_llm_api/adapter.py:101-102

可观测性集成

适配器使用 @observe 装饰器来追踪生成和转录。如果通过 _enrich_llm_span 工具启用了追踪，它们还会使用 COGNEE_LLM_MODEL 和 COGNEE_LLM_PROVIDER 属性来丰富 OpenTelemetry 跨度。cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/generic_llm_api/adapter.py:38-55

来源：cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/generic_llm_api/adapter.py:58-115、cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/llm_interface.py:8-19

汇总表：框架特性

来源：cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:69-117、cognee/infrastructure/llm/structured_output_framework/baml/baml_src/extraction/acreate_structured_output.py:30-76、cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/generic_llm_api/adapter.py:38-55