agentic_huge_data_base / wiki
页面 LightRAG · 6.5 配置与绑定选项·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 6.5

6.5 · 配置与绑定选项（Configuration and Binding Options）

轻量图谱增强检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目LightRAG 章节6.5 状态全文译文 模块模型调用与提供方适配、配置治理、文档对象与元数据、接口与服务契约
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节Configuration and Binding Options 上一章6.4 下一章6.6
源码线索
  • env.example
  • lightrag/api/config.py
  • lightrag/api/lightrag_server.py
  • lightrag/api/routers/document_routes.py
  • lightrag/api/utils_api.py
  • lightrag/constants.py
  • lightrag/kg/shared_storage.py
  • lightrag/llm/binding_options.py
  • pyproject.toml
  • requirements-offline-llm.txt
模块标签
  • 模型调用与提供方适配
  • 配置治理
  • 文档对象与元数据
  • 接口与服务契约
  • 存储与持久化

章节正文

配置与绑定选项

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/6.5-configuration-and-binding-options
此页面内容来自 DeepWiki 重组后的对应页面（来源：3-3.zh.md）

按角色配置大语言模型（LLM）

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • docs/RoleSpecificLLMConfiguration-zh.md
  • docs/RoleSpecificLLMConfiguration.md
  • env.example
  • lightrag/api/config.py
  • lightrag/api/lightrag_server.py
  • lightrag/api/utils_api.py
  • lightrag/constants.py
  • lightrag/kg/factory.py
  • lightrag/llm_roles.py
  • lightrag/storage_migrations.py
  • tests/test_api_config_role_max_async.py
  • tests/test_bedrock_llm.py
  • tests/test_doc_status_chunk_preservation.py
  • tests/test_llm_role_runtime.py

LightRAG 支持为检索增强生成（RAG）管线的不同阶段分配不同的大语言模型（LLM）或视觉语言模型（VLM）。这样可以优化成本、延迟和性能——例如，使用高吞吐量、低成本的模型进行实体提取，同时保留强大的推理模型用于最终查询回答。

角色概览

系统定义了四个不同的角色，每个角色对应引擎内的一组特定操作 docs/RoleSpecificLLMConfiguration.md:7-14：

角色用途
EXTRACT从文本片段中提取实体和关系，并在合并过程中进行描述摘要 docs/RoleSpecificLLMConfiguration.md:11-11。
KEYWORD生成用于多向量检索的高层和低层关键词 docs/RoleSpecificLLMConfiguration.md:12-12。
QUERY最终响应生成、查询扩展以及兼容 Ollama 的 API 补全 docs/RoleSpecificLLMConfiguration.md:13-13。
VLM通过视觉语言模型分析多模态内容（图像、表格、公式）docs/RoleSpecificLLMConfiguration.md:14-14。

数据流与类架构

配置通过 RoleLLMConfig 对象进行管理，这些对象被传递给 LightRAG 类。在内部，引擎使用 create_role_llm_func 将提供者绑定包装成角色感知的执行单元。

配置层级图

下图展示了环境变量和代码实体如何映射到内部的 RoleLLMConfig 状态。

LightRAG · 配置层级图 · 图 1
LightRAG · 配置层级图 · 图 1

来源：lightrag/llm_roles.py:1-40、lightrag/lightrag.py:100-150、docs/RoleSpecificLLMConfiguration.md:46-76

实现细节

角色定义与规范

角色被定义为包含角色名称和文档的 RoleSpec 对象。全局 ROLES 列表作为所有有效管线阶段的注册表 lightrag/llm_roles.py:34-40。

配置容器：RoleLLMConfig

RoleLLMConfig 类是一个数据容器，用于存储特定角色的覆盖配置 lightrag/llm_roles.py:13-31：

  • model：该角色的具体模型名称。
  • binding：提供者绑定（例如 openai、ollama）。
  • host：端点 URL。
  • max_async：该特定角色的并发限制。
  • kwargs：提供者特定选项的字典（例如 temperature、top_p）。
运行时角色切换

LightRAG 类初始化一个字典 _role_llm_states 来跟踪每个角色的状态 lightrag/lightrag.py:180-200。当管线组件需要调用大语言模型（LLM）时，它会使用该角色的有效配置。

执行流程：create_role_llm_func

系统使用工厂模式将配置转换为可执行函数。

LightRAG · 执行流程： create_role_llm_func · 图 2
LightRAG · 执行流程： create_role_llm_func · 图 2

来源：lightrag/lightrag.py:250-300、lightrag/llm/binding_options.py:10-50

继承规则

系统遵循严格的继承层级，以最小化配置冗余 docs/RoleSpecificLLMConfiguration.md:103-137：

  1. 提供者内继承：如果 {ROLE}_LLM_BINDING 与基础 LLM_BINDING 匹配，则该角色继承基础的主机、API 密钥和超时设置。它仅覆盖 model 或 max_async 等特定字段 docs/RoleSpecificLLMConfiguration.md:105-127。
  2. 跨提供者配置：如果绑定不同，则必须完整指定角色特定配置（模型、API 密钥和端点）。它不会从基础 LLM 继承提供者特定选项 docs/RoleSpecificLLMConfiguration.md:129-153。
  3. 并发（MAX_ASYNC）：如果未设置 {ROLE}_MAX_ASYNC_LLM，则默认使用全局 MAX_ASYNC 值 lightrag/api/config.py:30-36。

提供者行为矩阵

提供者主机覆盖API 密钥覆盖认证来源
openaiQUERY_LLM_BINDING_HOSTQUERY_LLM_BINDING_API_KEYBearer 令牌
bedrockEXTRACT_LLM_BINDING_HOST不支持角色级 SigV4 docs/RoleSpecificLLMConfiguration.md:155-180
geminiVLM_LLM_BINDING_HOSTVLM_LLM_BINDING_API_KEYAPI 密钥或 Vertex AI docs/RoleSpecificLLMConfiguration.md:191-191
ollamaEXTRACT_LLM_BINDING_HOSTEXTRACT_LLM_BINDING_API_KEY可选的 Bearer

来源：docs/RoleSpecificLLMConfiguration.md:183-191、lightrag/api/config.py:71-86

服务端配置

在 lightrag-server 中，配置通过 parse_args 从环境变量解析 lightrag/api/config.py:5-20。服务器使用 LLMConfigCache 预计算不同提供者的选项字典，确保角色特定的覆盖配置正确合并到提供者特定的 Options 类（例如 OpenAILLMOptions）中 lightrag/api/lightrag_server.py:131-150。

来源：lightrag/api/lightrag_server.py、lightrag/api/config.py、lightrag/llm_roles.py、docs/RoleSpecificLLMConfiguration.md。