agentic_huge_data_base / wiki
页面 Cognee · 6.1 大模型提供方配置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 6.1

6.1 · 大模型提供方配置（LLM Provider Configuration）

记忆管道与知识图谱构建 · 本章是 Cognee DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Cognee 章节6.1 状态全文译文 模块模型调用与提供方适配、接口与服务契约、配置治理、认证、权限与安全
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节LLM Provider Configuration 上一章6 下一章6.2
源码线索
  • .env.template
  • README.md
  • assets/cognee_benefits.png
  • cognee/api/v1/config/config.py
  • cognee/infrastructure/llm/__init__.py
  • cognee/infrastructure/llm/config.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py
  • cognee/infrastructure/llm/utils.py
  • cognee/modules/engine/operations/setup.py
模块标签
  • 模型调用与提供方适配
  • 接口与服务契约
  • 配置治理
  • 认证、权限与安全
  • 系统架构

中文译文

大模型提供方配置（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/6.1-llm-provider-configuration
翻译时间：2026-05-27T08:45:14.235Z
翻译模型：deepseek-chat
原文字符数：10443
项目：Cognee (cognee)

---

大语言模型（LLM）提供商配置

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

  • .env.template
  • README.md
  • assets/cognee_benefits.png
  • cognee/api/v1/config/config.py
  • cognee/infrastructure/llm/__init__.py
  • cognee/infrastructure/llm/config.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py
  • cognee/infrastructure/llm/utils.py
  • cognee/modules/engine/operations/setup.py
  • cognee/modules/pipelines/layers/setup_and_check_environment.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_embedding_connection_dimensions.py
  • cognee/tests/unit/infrastructure/llm/test_get_llm_client.py

本文档说明了如何在 Cognee 中配置大语言模型（LLM）提供商。系统支持多种 LLM 提供商，包括 OpenAI、Anthropic、Gemini、Mistral、Ollama、Bedrock 和 LlamaCpp，所有这些都通过 LLMConfig 类进行管理。

有关嵌入向量提供商的配置，请参阅嵌入向量服务。有关结构化输出框架，请参阅结构化输出框架。

配置系统架构

Cognee 的 LLM 配置由 LLMConfig 类管理，该类扩展了 Pydantic 的 BaseSettings，以提供类型安全、基于环境变量的配置，并包含校验功能。

graph TB
    subgraph "配置来源"
        EnvFile[".env 文件"]
        EnvVars["环境变量"]
        Defaults["默认值"]
    end

    subgraph "配置管理"
        LLMConfig["LLMConfig<br/>Pydantic BaseSettings"]
        Validator["model_validator<br/>ensure_env_vars_for_ollama"]
        PostInit["model_post_init<br/>BAML 注册表设置"]
    end

    subgraph "LLM 配置字段"
        Provider["llm_provider<br/>默认值: 'openai'"]
        Model["llm_model<br/>默认值: 'openai/gpt-5-mini'"]
        ApiKey["llm_api_key<br/>Optional[str]"]
        Endpoint["llm_endpoint<br/>可选 URL"]
        Temperature["llm_temperature<br/>默认值: 0.0"]
        MaxTokens["llm_max_completion_tokens<br/>默认值: 16384"]
        RateLimit["llm_rate_limit_*<br/>速率限制配置"]
    end

    subgraph "框架选择"
        Framework["structured_output_framework<br/>instructor | baml"]
        InstructorPath["Instructor<br/>通过 litellm"]
        BAMLPath["BAML<br/>通过 baml_py"]
    end

    subgraph "下游消费者"
        LLMCalls["LLM API 调用<br/>cognify, search"]
        StructuredOutput["结构化提取<br/>实体/图谱提取"]
    end

    EnvFile --> LLMConfig
    EnvVars --> LLMConfig
    Defaults --> LLMConfig

    LLMConfig --> Provider
    LLMConfig --> Model
    LLMConfig --> ApiKey
    LLMConfig --> Endpoint
    LLMConfig --> Temperature
    LLMConfig --> MaxTokens
    LLMConfig --> RateLimit

    LLMConfig --> Validator
    LLMConfig --> PostInit

    LLMConfig --> Framework
    Framework --> InstructorPath
    Framework --> BAMLPath

    Provider --> LLMCalls
    Model --> LLMCalls
    ApiKey --> LLMCalls
    Framework --> StructuredOutput

来源： cognee/infrastructure/llm/config.py:15-133, .env.template:1-68

核心配置参数

LLMConfig 类定义了管理 LLM 交互的主要配置参数：

参数类型默认值描述
llm_providerstr"openai"LLM 提供商标识符（参见 LLMProvider 枚举）
llm_modelstr"openai/gpt-5-mini"带提供商前缀的模型标识符
llm_api_keyOptional[str]None用于认证的 API 密钥
llm_endpointstr""自定义 API 端点 URL
llm_api_versionOptional[str]NoneAPI 版本（Azure 等）
llm_temperaturefloat0.0采样温度
llm_streamingboolFalse启用流式响应
llm_max_completion_tokensint16384最大输出 Token 数
structured_output_frameworkstr"instructor"提取框架（"instructor" 或 "baml"）
llm_argsdict[str, Any]None用于补全调用的额外关键字参数
运行时配置 API

可以在运行时通过 cognee.config 命名空间设置配置，该命名空间会更新底层的 Pydantic 模型。例如，cognee.config.set_llm_model("gpt-4o") 会更新 LLMConfig 实例 cognee/api/v1/config/config.py:96-116。

来源： cognee/infrastructure/llm/config.py:42-84, cognee/api/v1/config/config.py:96-116

支持的 LLM 提供商

Cognee 通过 LLMProvider 枚举和相应的适配器实现支持多个提供商：

graph TB
    subgraph "LLM 提供商枚举"
        EnumOpenAI["LLMProvider.OPENAI"]
        EnumOllama["LLMProvider.OLLAMA"]
        EnumAnthropic["LLMProvider.ANTHROPIC"]
        EnumCustom["LLMProvider.CUSTOM"]
        EnumGemini["LLMProvider.GEMINI"]
        EnumMistral["LLMProvider.MISTRAL"]
        EnumAzure["LLMProvider.AZURE"]
        EnumBedrock["LLMProvider.BEDROCK"]
        EnumLlamaCpp["LLMProvider.LLAMA_CPP"]
    end

    subgraph "工厂逻辑"
        Factory["get_llm_client()"]
    end

    Factory --> EnumOpenAI
    Factory --> EnumOllama
    Factory --> EnumAnthropic
    Factory --> EnumCustom
    Factory --> EnumGemini
    Factory --> EnumMistral
    Factory --> EnumAzure
    Factory --> EnumBedrock
    Factory --> EnumLlamaCpp

来源： cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:70-92

提供商详情
提供商枚举值实现说明
OpenAIopenai默认提供商。支持 GPT-4o、GPT-5-mini cognee/modules/settings/get_settings.py:101-115。
Ollamaollama需要同时设置 LLM_MODEL、LLM_ENDPOINT 和 LLM_API_KEY cognee/infrastructure/llm/config.py:192-197。
Anthropicanthropic支持 Claude 3 系列（Opus、Sonnet、Haiku）cognee/modules/settings/get_settings.py:127-140。
Bedrockbedrock通过 BedrockAdapter 集成 AWS Bedrock。支持 API 密钥、AWS 凭证或配置文件认证 cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.py:32-42。
LlamaCppllama_cpp通过 llama_cpp_model_path 和 llama_cpp_n_ctx 配置 cognee/infrastructure/llm/config.py:73-76。
Geminigemini支持 Google 的 Gemini 模型 cognee/modules/settings/get_settings.py:141-146。

来源： cognee/infrastructure/llm/config.py:70-211, cognee/modules/settings/get_settings.py:44-180

LLM 客户端工厂（get_llm_client）

get_llm_client 函数是获取 LLM 适配器实例的核心工厂。它使用 LRU 缓存（_LLM_CLIENT_CACHE_MAXSIZE = 32）根据配置重用客户端实例 cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:20-198。

缓存键逻辑

缓存键 _LLMClientCacheKey 由所有影响适配器创建的字段的可哈希表示构建而成，包括提供商、模型、脱敏后的 API 密钥、端点和额外的 llm_args cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:46-66。

连接测试

在环境设置过程中，Cognee 通过 test_llm_connection() 执行连接测试。该测试会执行一个简单的结构化输出补全，以验证端点和 API 密钥 cognee/infrastructure/llm/utils.py:81-113。可以通过设置 COGNEE_SKIP_CONNECTION_TEST=true 来跳过此检查 cognee/modules/pipelines/layers/setup_and_check_environment.py:38-42。

来源： cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:20-198, cognee/infrastructure/llm/utils.py:81-113, cognee/modules/pipelines/layers/setup_and_check_environment.py:22-58

操作控制

速率限制

Cognee 为 LLM 和嵌入向量调用提供了内置的速率限制功能。

  • llm_rate_limit_enabled：默认值为 False。
  • llm_rate_limit_requests：每个时间间隔允许的请求数（默认 60）。
  • llm_rate_limit_interval：时间窗口（秒）（默认 60）。
  • llm_rate_limit_tokens：每个时间间隔基于 Token 的限制（0 表示禁用）。

来源： cognee/infrastructure/llm/config.py:64-71

Token 管理

get_max_chunk_tokens() 函数通过比较嵌入向量引擎的限制和 LLM 的上下文窗口（取两者中较小的值，LLM 上下文通常减半以留出提示空间），动态计算入库的最佳片段大小 cognee/infrastructure/llm/utils.py:17-44。

来源： cognee/infrastructure/llm/utils.py:17-44

Bedrock 认证

BedrockAdapter 专门支持三种 AWS 认证模式：

  1. API 密钥：通过 llm_api_key 提供。
  2. AWS 凭证：来自 S3 配置的 aws_access_key_id 和 aws_secret_access_key。
  3. AWS 配置文件：通过 aws_profile_name 使用本地 boto3 凭证链。

来源： cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.py:32-106