LightRAG 按角色配置 LLM/VLM 实战EXTRACT、KEYWORD、QUERY、VLM 四角色的模型分治与继承规则【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAGLightRAG 允许为抽取、关键词生成、最终回答、多模态分析四个处理阶段分别指定不同的 LLM/VLM 绑定实现低成本模型做抽取、强模型做回答、专用视觉模型分析图片的成本与质量平衡。本文完整继承 docs/RoleSpecificLLMConfiguration.md 的变量体系、继承规则与六类推荐配置并结合 角色注册表、API 配置解析与Provider 选项继承实现讲清每一条配置在运行时的落地机制。读完后你可以直接复制可运行的.env配置并能定位配置未生效时的源码检查点。一、四个角色及其职责LightRAG 当前支持四个可独立配置 LLM/VLM 的角色角色用途EXTRACT文件入库阶段使用的模型主要用于实体/关系抽取与摘要。推荐关闭思考模式、能处理复杂问题的快速模型建议参数规模 30B 以上、上下文长度至少 32KB。KEYWORD查询阶段的关键词抽取检索前的高层/低层关键词生成。推荐关闭思考模式的超快速模型以提升查询响应速度建议参数规模 7B 以上。QUERY查询阶段基于召回内容生成最终回答的模型。推荐开启思考模式的高质量模型建议参数规模 30B 以上、上下文长度至少 32KB。VLM文件入库阶段分析图片使用的模型。必须支持图像识别建议参数规模 30B 以上。如果某个角色没有专门配置LightRAG 会使用基础LLM_*配置。这一角色划分不是散落的魔法字符串。从源码结构看lightrag/llm_roles.py 定义了一个静态角色注册表ROLESROLES: tuple[RoleSpec, ...] ( RoleSpec(extract, EXTRACT, extract LLM func), RoleSpec(keyword, KEYWORD, keyword LLM func), RoleSpec(query, QUERY, query LLM func), RoleSpec(vlm, VLM, vlm LLM func), )每个RoleSpec携带小写角色名用于role_llm_configs字典与日志、大写环境变量前缀如EXTRACT对应EXTRACT_LLM_BINDING、以及队列显示名。API 层的.env解析循环、队列可观测性、角色配置热更新流程都遍历这个注册表而不是硬编码角色名——这也意味着新增角色只需在注册表追加一行。二、基础 LLM 配置基础配置定义默认 LLM 提供商、模型、服务端点、认证信息以及并发控制LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key # 所有 LLM 请求的默认超时 LLM_TIMEOUT240 # 所有 LLM 调用的默认最大并发MAX_ASYNC 仍作为弃用别名被接受 MAX_ASYNC_LLM4常用字段变量说明LLM_BINDING基础 LLM 提供商。支持openai、ollama、lollms、azure_openai、bedrock、gemini。LLM_MODEL基础模型名。Azure OpenAI 场景下通常是部署名。LLM_BINDING_HOST基础提供商端点。SDK 默认端点使用对应哨兵值如DEFAULT_GEMINI_ENDPOINT或DEFAULT_BEDROCK_ENDPOINT。LLM_BINDING_API_KEY基础 API Key。Bedrock 不使用该字段。LLM_TIMEOUT基础 LLM 超时。未设置角色超时时角色继承它。MAX_ASYNC_LLM基础 LLM 最大并发。未设置{ROLE}_MAX_ASYNC_LLM时角色继承它MAX_ASYNC仍作为弃用别名被接受。仓库的 env.example 中给出了同样的基础默认值MAX_ASYNC_LLM4并在 L1021 附近以注释形式预置了每个角色的覆盖位可作为配置起点。三、角色覆盖变量每个角色可以覆盖绑定、模型、端点、API Key、并发与超时QUERY_LLM_BINDINGopenai QUERY_LLM_MODELgpt-5 QUERY_LLM_BINDING_HOSThttps://api.openai.com/v1 QUERY_LLM_BINDING_API_KEYyour_query_api_key QUERY_MAX_ASYNC_LLM2 QUERY_LLM_TIMEOUT240变量格式变量说明{ROLE}_LLM_BINDING覆盖角色提供商。ROLE可为EXTRACT、KEYWORD、QUERY、VLM。{ROLE}_LLM_MODEL覆盖角色模型名。{ROLE}_LLM_BINDING_HOST覆盖角色端点。{ROLE}_LLM_BINDING_API_KEY覆盖角色 API Key。Bedrock 不支持。{ROLE}_MAX_ASYNC_LLM覆盖角色最大并发。未设置时继承MAX_ASYNC_LLM。{ROLE}_LLM_TIMEOUT覆盖角色超时。未设置时继承LLM_TIMEOUT。源码中的解析链路这些变量的读取并非逐个手写而是由 lightrag/api/config.py 中的循环按ROLES注册表统一处理for spec in ROLES: prefix spec.env_prefix binding_key f{prefix}_LLM_BINDING model_key f{prefix}_LLM_MODEL host_key f{prefix}_LLM_BINDING_HOST apikey_key f{prefix}_LLM_BINDING_API_KEY max_async_key f{prefix}_MAX_ASYNC_LLM timeout_key f{prefix}_LLM_TIMEOUT ...同一循环中还内置了两条启动期校验把配置错误挡在启动阶段而不是第一次调用时Bedrock 角色拒绝通用 API Key若role_binding bedrock且设置了{ROLE}_LLM_BINDING_API_KEY直接SystemExit并提示改用角色级 SigV4AWS_*变量或进程级AWS_BEARER_TOKEN_BEDROCKconfig.py。跨提供商必填校验若角色绑定与基础LLM_BINDING不同则必须设置{ROLE}_LLM_MODEL非 Bedrock 角色还必须设置{ROLE}_LLM_BINDING_API_KEY否则启动即失败并列出缺失变量config.py。若{ROLE}_LLM_BINDING_HOST未设置代码会用该提供商的默认端点回填。运行时继承则发生在 lightrag/api/lightrag_server.py 的resolve_role_llm_settings中binding/model/host 依次取角色运行时覆盖 → 角色环境变量 → 基础值API Key 在非 Bedrock 角色上取角色 Key 或基础LLM_BINDING_API_KEYtimeout未设置角色值时回落到LLM_TIMEOUTmax_async未设置角色值时在后续包装层回落到MAX_ASYNC_LLM。该函数还显式计算is_cross_provider role_binding ! args.llm_binding作为后续 Provider 选项是否继承的判断依据。四、Provider 选项覆盖提供商专属选项使用如下格式{ROLE}_{PROVIDER_PREFIX}_{FIELD}示例# 仅为 QUERY 角色覆盖 OpenAI 推理强度 QUERY_OPENAI_LLM_REASONING_EFFORTmedium # 仅为 EXTRACT 角色覆盖 Bedrock 生成参数 EXTRACT_BEDROCK_LLM_TEMPERATURE0.0 EXTRACT_BEDROCK_LLM_MAX_TOKENS2048 # 仅为 VLM 角色覆盖 Gemini 生成参数 VLM_GEMINI_LLM_MAX_OUTPUT_TOKENS4096 VLM_GEMINI_LLM_TEMPERATURE0.2常见 Provider 前缀Provider基础选项前缀角色选项示例openai/azure_openaiOPENAI_LLM_*QUERY_OPENAI_LLM_REASONING_EFFORTollamaOLLAMA_LLM_*EXTRACT_OLLAMA_LLM_NUM_PREDICTlollms使用 Ollama 兼容的选项集QUERY_OLLAMA_LLM_TEMPERATUREbedrockBEDROCK_LLM_*EXTRACT_BEDROCK_LLM_MAX_TOKENSgeminiGEMINI_LLM_*VLM_GEMINI_LLM_THINKING_CONFIG这篇指南覆盖角色前缀与继承规则关于{FIELD}这一半——每个前缀接受哪些选项、类型、取值语法以及 Provider 驱动如何消费它们——参见 LLM and Embedding Provider Options Reference。options_dict_for_role 的继承实现上述同 Provider 继承、跨 Provider 从空开始的规则由 lightrag/llm/binding_options.py 的options_dict_for_role实现if is_cross_provider: base: dict[str, Any] {} # 跨 Provider从空选项集出发 else: base cls.options_dict(args) # 同 Provider先继承基础 Provider 选项 role_upper role.upper() env_prefix cls._binding_name.upper() _ for arg_item in cls.args_env_name_type_value(): original_env arg_item[env_name] role_env f{role_upper}_{original_env} # 如 EXTRACT_OPENAI_LLM_TEMPERATURE env_raw os.getenv(role_env) if env_raw is None: continue ... base[field_name] ... # 按声明类型解析后叠加到 base 上可以看到角色选项是在基础选项字典上按声明的类型做解析叠加bool、int、float 按类型转换list/dict 走 JSON 解析解析失败时保留原始字符串并留待请求期报错——布尔字面量选项如 think 级别则被提前严格校验。lollms在 lightrag_server.py 中与ollama共用OllamaLLMOptions解析路径因此QUERY_OLLAMA_LLM_TEMPERATURE这类变量对 lollms 角色同样生效。五、继承规则同一 Provider 内的覆盖若角色未设置{ROLE}_LLM_BINDING或设置成与基础LLM_BINDING相同的值则角色继承基础配置未设置{ROLE}_LLM_MODEL时继承LLM_MODEL未设置{ROLE}_LLM_BINDING_HOST时继承LLM_BINDING_HOST未设置{ROLE}_LLM_BINDING_API_KEY时继承LLM_BINDING_API_KEY未设置{ROLE}_LLM_TIMEOUT时继承LLM_TIMEOUT未设置{ROLE}_MAX_ASYNC_LLM时继承MAX_ASYNC_LLMProvider 选项先继承基础 Provider 选项再叠加角色专属 Provider 选项。因此若只想在同一 Provider 内换模型只需要设模型名LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key OPENAI_LLM_REASONING_EFFORTminimal # QUERY 继承 host、API key、超时、并发和 OPENAI_LLM_REASONING_EFFORT QUERY_LLM_MODELgpt-5跨 Provider 覆盖若角色的{ROLE}_LLM_BINDING与基础LLM_BINDING不同即为跨 Provider 配置。当前规则是必须设置{ROLE}_LLM_MODEL非 Bedrock 提供商必须设置{ROLE}_LLM_BINDING_API_KEY若未设置{ROLE}_LLM_BINDING_HOSTLightRAG 会尝试使用该提供商的默认 hostProvider 选项不继承基础 Provider 选项——从空集出发只应用角色专属选项。示例用 Ollama 做本地抽取最终回答走 OpenAILLM_BINDINGollama LLM_MODELqwen3.5:9b LLM_BINDING_HOSThttp://localhost:11434 OLLAMA_LLM_NUM_CTX32768 QUERY_LLM_BINDINGopenai QUERY_LLM_MODELgpt-5-mini QUERY_LLM_BINDING_HOSThttps://api.openai.com/v1 QUERY_LLM_BINDING_API_KEYyour_openai_api_key QUERY_OPENAI_LLM_REASONING_EFFORTminimal跨 Provider 配置下建议显式设置{ROLE}_LLM_BINDING_HOST避免默认 host与基础 Provider 端点之间的混淆。Bedrock 认证规则Bedrock 不使用LLM_BINDING_API_KEY也不支持{ROLE}_LLM_BINDING_API_KEY。可用的认证方式是全局 SigV4AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN、AWS_REGION角色级 SigV4{ROLE}_AWS_ACCESS_KEY_ID、{ROLE}_AWS_SECRET_ACCESS_KEY、{ROLE}_AWS_SESSION_TOKEN、{ROLE}_AWS_REGION进程级 Bearer TokenAWS_BEARER_TOKEN_BEDROCK。这是 AWS SDK 的进程级设置无法按角色覆盖。角色级 Bedrock 示例LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_openai_api_key EXTRACT_LLM_BINDINGbedrock EXTRACT_LLM_MODELus.amazon.nova-lite-v1:0 EXTRACT_LLM_BINDING_HOSTDEFAULT_BEDROCK_ENDPOINT EXTRACT_AWS_REGIONus-west-2 EXTRACT_AWS_ACCESS_KEY_IDyour_extract_access_key EXTRACT_AWS_SECRET_ACCESS_KEYyour_extract_secret_key EXTRACT_AWS_SESSION_TOKENyour_optional_session_token EXTRACT_BEDROCK_LLM_TEMPERATURE0.0 EXTRACT_BEDROCK_LLM_MAX_TOKENS2048从源码结构看{ROLE}_AWS_*四个变量同样由 config.py 的角色循环统一读取config.py运行时在resolve_role_llm_settings中按角色级 → 全局的顺序合并lightrag_server.py所以单个角色可以用独立 IAM/STS 凭据其余角色继续走全局凭据。六、Provider 行为矩阵Provider角色级 host/base_url角色级 API Key认证限制openai支持通过{ROLE}_LLM_BINDING_HOST传入 OpenAI 兼容客户端。支持{ROLE}_LLM_BINDING_API_KEY同 Provider 内未设置时继承基础LLM_BINDING_API_KEY。当前主要是 API Key / Bearer 模式。ollama支持通过{ROLE}_LLM_BINDING_HOST传入 Ollama 客户端。支持{ROLE}_LLM_BINDING_API_KEY同 Provider 内未设置时继承基础 Key。若没有 Key 到达下层回落到OLLAMA_API_KEY。Bearer 头。lollms支持{ROLE}_LLM_BINDING_HOST作为base_url使用。支持{ROLE}_LLM_BINDING_API_KEY同 Provider 内未设置时继承基础 Key。Bearer 头。azure_openai支持{ROLE}_LLM_BINDING_HOST作为 Azure 端点。支持{ROLE}_LLM_BINDING_API_KEY同 Provider 内未设置时继承基础 Key并可能回落到AZURE_OPENAI_API_KEY。AZURE_OPENAI_API_VERSION是全局环境变量不支持角色级覆盖。bedrock支持{ROLE}_LLM_BINDING_HOST作为endpoint_urlDEFAULT_BEDROCK_ENDPOINT表示交给 AWS SDK 选择。不支持通用 API Key。使用全局或角色级 SigV4。AWS_BEARER_TOKEN_BEDROCK是进程级的不能按角色覆盖。gemini支持通过{ROLE}_LLM_BINDING_HOST传给 Google GenAI 客户端DEFAULT_GEMINI_ENDPOINT表示使用 SDK 默认端点。AI Studio 模式支持{ROLE}_LLM_BINDING_API_KEY。Vertex AI 由GOOGLE_GENAI_USE_VERTEXAI、GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION、GOOGLE_APPLICATION_CREDENTIALS控制均为进程级设置。七、运行时机制角色独立队列、热更新与可观测性环境变量只是配置入口真正让角色分治成立的是 lightrag/llm_roles.py 中的_RoleLLMMixin。结合源码可以看三点每个角色拥有独立并发队列。_wrap_llm_role_func用priority_limit_async_func_call(max_async, llm_timeout..., concurrency_groupfllm:{role_name})包装每个角色的原始 LLM 函数llm_roles.py。也就是说{ROLE}_MAX_ASYNC_LLM和{ROLE}_LLM_TIMEOUT不是共享的全局限流参数而是各自角色队列的容量与任务上限EXTRACT_MAX_ASYNC_LLM4不会挤占QUERY_MAX_ASYNC_LLM2的额度。基础的llm_model_func本身不再单独包装——所有调用路径都经过角色包装层并发控制因此集中在角色层。支持运行时热更新。update_llm_role_config/aupdate_llm_role_config可以在不重启的情况下更换某角色的 binding/model/host/api_key/provider_optionsllm_roles.py更新采用先快照、失败即回滚的策略异步版本还会等待旧队列排空后才返回其排空上限为llm_timeout * 2 15秒。可观测输出对凭据脱敏。get_llm_role_config用于/health与 WebUI 展示会彻底剥离而非打码metadata 中的api_key、secret、token等敏感字段只保留 binding/model/host/max_async/timeout 等安全信息llm_roles.py。每角色的队列状态也可通过get_llm_queue_status查询多 worker 场景下会聚合各 gunicorn worker 的快照。对排障的含义当你怀疑某角色配置未生效时可以先看服务日志中的 Role LLM Configuration 行与/health的角色配置视图确认生效的 binding/model/host/max_async/timeout再回查对应环境变量。相关实现行为有测试用例覆盖如 tests/llm/test_llm_role_runtime.py 与 tests/api/config/test_api_config_ollama_role_think.py。八、推荐配置模式模式 1同 Provider仅换模型适用于使用同一 OpenAI Key 与端点但希望最终回答用更强模型的场景LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key OPENAI_LLM_REASONING_EFFORTminimal QUERY_LLM_MODELgpt-5 QUERY_MAX_ASYNC_LLM2QUERY继承基础 host、API Key 与OPENAI_LLM_REASONING_EFFORT。模式 2同 Provider换模型并调参适用于基础模型用于抽取、最终回答使用更高推理强度的场景LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key OPENAI_LLM_REASONING_EFFORTminimal OPENAI_LLM_MAX_COMPLETION_TOKENS4096 QUERY_LLM_MODELgpt-5 QUERY_OPENAI_LLM_REASONING_EFFORTmedium QUERY_OPENAI_LLM_MAX_COMPLETION_TOKENS9000 QUERY_LLM_TIMEOUT240模式 3同 Provider不同端点与 API Key适用于所有角色都用openai绑定但部分角色访问官方 OpenAI API、其他角色访问本地 vLLM、SGLang、OpenRouter 或其他 OpenAI 兼容端点的场景。示例中EXTRACT使用官方 OpenAIgpt-5-miniQUERY使用官方 OpenAIgpt-5.4使用独立的 OpenAI KeyKEYWORD使用本地 vLLM 部署的Qwen3.5-35B-A3B。########################################################################### # 基础 LLM 兜底。与 EXTRACT 保持一致保证未显式配置的角色仍有有效的 OpenAI 配置 ########################################################################### LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_extract_openai_api_key LLM_TIMEOUT240 MAX_ASYNC_LLM4 ########################################################################### # 重要 # 若有任一角色指向不支持该参数的本地 OpenAI 兼容服务器 # 不要在此设置全局 OPENAI_LLM_REASONING_EFFORT改用角色级 OPENAI 选项。 ########################################################################### # OPENAI_LLM_REASONING_EFFORTnone ########################################################################### # EXTRACTOpenAI 官方 APIgpt-5-mini ########################################################################### EXTRACT_LLM_BINDINGopenai EXTRACT_LLM_MODELgpt-5-mini EXTRACT_LLM_BINDING_HOSThttps://api.openai.com/v1 EXTRACT_LLM_BINDING_API_KEYyour_extract_openai_api_key EXTRACT_OPENAI_LLM_REASONING_EFFORTlow EXTRACT_OPENAI_LLM_MAX_COMPLETION_TOKENS4096 EXTRACT_MAX_ASYNC_LLM4 EXTRACT_LLM_TIMEOUT180 ########################################################################### # QUERYOpenAI 官方 APIgpt-5.4独立 API Key ########################################################################### QUERY_LLM_BINDINGopenai QUERY_LLM_MODELgpt-5.4 QUERY_LLM_BINDING_HOSThttps://api.openai.com/v1 QUERY_LLM_BINDING_API_KEYyour_query_openai_api_key QUERY_OPENAI_LLM_REASONING_EFFORTmedium QUERY_OPENAI_LLM_MAX_COMPLETION_TOKENS9000 QUERY_MAX_ASYNC_LLM2 QUERY_LLM_TIMEOUT240 ########################################################################### # KEYWORD本地 vLLM OpenAI 兼容端点Qwen3.5-35B-A3B ########################################################################### KEYWORD_LLM_BINDINGopenai KEYWORD_LLM_MODELQwen3.5-35B-A3B KEYWORD_LLM_BINDING_HOSThttp://localhost:8000/v1 # 若 vLLM 以 --api-key 启动此处填相同值 # 若 vLLM 无认证仍需设置非空占位值避免回落使用官方 OpenAI Key。 KEYWORD_LLM_BINDING_API_KEYlocal-vllm-api-key KEYWORD_OPENAI_LLM_MAX_TOKENS2048 # 对 vLLM 提供的 Qwen 系模型可选用于关闭思考 KEYWORD_OPENAI_LLM_EXTRA_BODY{chat_template_kwargs: {enable_thinking: false}} KEYWORD_MAX_ASYNC_LLM4 KEYWORD_LLM_TIMEOUT60该模式不算跨 Provider因为三个角色都用openai绑定。LightRAG 会把每个角色的*_LLM_BINDING_HOST与*_LLM_BINDING_API_KEY分别传给 OpenAI 兼容客户端。注意同 Provider 内Provider 选项会继承基础OPENAI_LLM_*。若本地 vLLM 服务器不支持reasoning_effort这类官方 OpenAI 参数不要设置全局OPENAI_LLM_REASONING_EFFORT应改用EXTRACT_OPENAI_LLM_REASONING_EFFORT、QUERY_OPENAI_LLM_REASONING_EFFORT等角色级变量。模式 4单角色跨 Provider适用于基础使用官方 OpenAI 模型、仅关键词抽取使用本地 Ollama 的场景LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_openai_api_key OPENAI_LLM_REASONING_EFFORTmedium KEYWORD_LLM_BINDINGollama KEYWORD_LLM_MODELqwen3.5:9b KEYWORD_LLM_BINDING_HOSThttp://localhost:11434 KEYWORD_LLM_BINDING_API_KEYollama-local-key KEYWORD_OLLAMA_LLM_NUM_CTX32768跨 Provider 配置下Ollama 选项不继承 OpenAI 选项。本地 Ollama 场景中KEYWORD_LLM_BINDING_API_KEY通常可以用占位值——当前跨 Provider 校验要求非 Bedrock 角色显式提供角色级 API Key。模式 5为 VLM 指定专用多模态模型适用于文本任务使用更便宜的模型、多模态分析使用视觉语言模型的场景VLM_PROCESS_ENABLEtrue LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key VLM_LLM_BINDINGopenai VLM_LLM_MODELgpt-4o VLM_OPENAI_LLM_MAX_TOKENS4096 VLM_MAX_ASYNC_LLM2 VLM_LLM_TIMEOUT240若 VLM 使用与基础相同的 Provider 和 Key可以省略VLM_LLM_BINDING_HOST与VLM_LLM_BINDING_API_KEY。VLM_PROCESS_ENABLE是多模态分析的总开关。为false时管线会发警告并跳过所有多模态条目而不调用 VLM为true时实际生效的 VLM 绑定设置了VLM_LLM_BINDING就用它否则用LLM_BINDING必须支持图像输入。具备视觉能力的 Provider 有openai、azure_openai、gemini、bedrock、ollama、anthropiclollms因无法接受图像输入会在启动时被拒绝。这条启动期校验在 config.py 中实现VLM_PROCESS_ENABLEtrue且生效绑定命中{lollms}时直接SystemExit。模式 6Bedrock 角色级 SigV4 凭据适用于仅有一个角色访问 Bedrock 并使用独立 IAM/STS 凭据的场景LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_openai_api_key QUERY_LLM_BINDINGbedrock QUERY_LLM_MODELus.amazon.nova-lite-v1:0 QUERY_LLM_BINDING_HOSTDEFAULT_BEDROCK_ENDPOINT QUERY_AWS_REGIONus-east-1 QUERY_AWS_ACCESS_KEY_IDyour_query_access_key QUERY_AWS_SECRET_ACCESS_KEYyour_query_secret_key QUERY_AWS_SESSION_TOKENyour_optional_session_token QUERY_BEDROCK_LLM_MAX_TOKENS4096 QUERY_BEDROCK_LLM_TEMPERATURE0.2不要设置QUERY_LLM_BINDING_API_KEYBedrock 会拒绝该配置。九、注意事项Caveats同 Provider 内OPENAI_LLM_REASONING_EFFORT、OPENAI_LLM_MAX_TOKENS、OLLAMA_LLM_NUM_CTX、GEMINI_LLM_THINKING_CONFIG等 Provider 选项会自动继承。目前没有干净的角色级取消继承某个 Provider 选项的语义。若同 Provider 角色的模型不支持某个基础选项要么显式为该角色覆盖成该模型支持的取值要么把角色配置为跨 Provider 并只设置它支持的角色级 Provider 选项。azure_openai的AZURE_OPENAI_DEPLOYMENT与AZURE_OPENAI_API_VERSION是全局环境变量。若设置了AZURE_OPENAI_DEPLOYMENT它可能优先于角色模型名。Gemini 的 Vertex AI 模式由进程级 Google 环境变量控制。同一个 LightRAG 进程内不能一部分角色用 Vertex AI、另一部分角色用 AI Studio API Key。在 Docker/Compose 中LLM_BINDING_HOST通常需要使用容器可达地址如host.docker.internal角色级 host 遵循同样原则。修改.env后要重启 LightRAG Server。部分 IDE 终端会预加载.env建议打开新的终端会话确认环境变量已生效。支持思考的 Ollama 模型在抽取阶段可能静默返回空实体/关系——当整个生成预算都花在输出前的隐藏推理上时issue #3597。若出现该情况设置EXTRACT_OLLAMA_LLM_THINKfalse关键词抽取同样受影响时再加KEYWORD_OLLAMA_LLM_THINKfalse。除true/false外该选项还接受推理级别low/medium/high需要 Ollama 服务器支持级别不设置时跟随模型自身默认空值OLLAMA_LLM_THINK含义是false而不是未设置。服务器启动时还会通过ensure_think_supported对每个 Ollama 角色的最终生效选项做校验不支持的think取值会在启动期而非首次调用时报错lightrag_server.py。十、相关入口速查关注点位置官方配置指南本文主体文档docs/RoleSpecificLLMConfiguration.mdProvider 选项全量参考字段、类型、取值语法docs/LLMProviderOptions.md角色注册表、角色运行时 Mixinlightrag/llm_roles.py.env角色变量解析与启动校验lightrag/api/config.py角色设置运行时解析继承链、跨 Provider 判定lightrag/api/lightrag_server.pyProvider 选项的角色级继承实现lightrag/llm/binding_options.py预置的角色变量注释模板env.example约 L1021–L1057 的角色配置段角色运行时行为测试tests/llm/test_llm_role_runtime.py、tests/api/config/test_api_config_ollama_role_think.py综合来看LightRAG 的角色化 LLM 配置是一套注册表驱动 启动期强校验 运行时独立队列的机制配置面由ROLES注册表统一生成错误配置Bedrock 配 API Key、跨 Provider 缺必填项、VLM_PROCESS_ENABLE绑定不支持图像在启动期就会失败退出运行面则让每个角色拥有独立的并发配额、超时与 Provider 选项集互不挤占。按本文的六类模式选用模板、再对照第九节注意事项排查即可在成本与回答质量之间取得可控的平衡。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LightRAG 按角色配置 LLM/VLM 实战：EXTRACT、KEYWORD、QUERY、VLM 四角色的模型分治与继承规则
LightRAG 按角色配置 LLM/VLM 实战EXTRACT、KEYWORD、QUERY、VLM 四角色的模型分治与继承规则【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAGLightRAG 允许为抽取、关键词生成、最终回答、多模态分析四个处理阶段分别指定不同的 LLM/VLM 绑定实现低成本模型做抽取、强模型做回答、专用视觉模型分析图片的成本与质量平衡。本文完整继承 docs/RoleSpecificLLMConfiguration.md 的变量体系、继承规则与六类推荐配置并结合 角色注册表、API 配置解析与Provider 选项继承实现讲清每一条配置在运行时的落地机制。读完后你可以直接复制可运行的.env配置并能定位配置未生效时的源码检查点。一、四个角色及其职责LightRAG 当前支持四个可独立配置 LLM/VLM 的角色角色用途EXTRACT文件入库阶段使用的模型主要用于实体/关系抽取与摘要。推荐关闭思考模式、能处理复杂问题的快速模型建议参数规模 30B 以上、上下文长度至少 32KB。KEYWORD查询阶段的关键词抽取检索前的高层/低层关键词生成。推荐关闭思考模式的超快速模型以提升查询响应速度建议参数规模 7B 以上。QUERY查询阶段基于召回内容生成最终回答的模型。推荐开启思考模式的高质量模型建议参数规模 30B 以上、上下文长度至少 32KB。VLM文件入库阶段分析图片使用的模型。必须支持图像识别建议参数规模 30B 以上。如果某个角色没有专门配置LightRAG 会使用基础LLM_*配置。这一角色划分不是散落的魔法字符串。从源码结构看lightrag/llm_roles.py 定义了一个静态角色注册表ROLESROLES: tuple[RoleSpec, ...] ( RoleSpec(extract, EXTRACT, extract LLM func), RoleSpec(keyword, KEYWORD, keyword LLM func), RoleSpec(query, QUERY, query LLM func), RoleSpec(vlm, VLM, vlm LLM func), )每个RoleSpec携带小写角色名用于role_llm_configs字典与日志、大写环境变量前缀如EXTRACT对应EXTRACT_LLM_BINDING、以及队列显示名。API 层的.env解析循环、队列可观测性、角色配置热更新流程都遍历这个注册表而不是硬编码角色名——这也意味着新增角色只需在注册表追加一行。二、基础 LLM 配置基础配置定义默认 LLM 提供商、模型、服务端点、认证信息以及并发控制LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key # 所有 LLM 请求的默认超时 LLM_TIMEOUT240 # 所有 LLM 调用的默认最大并发MAX_ASYNC 仍作为弃用别名被接受 MAX_ASYNC_LLM4常用字段变量说明LLM_BINDING基础 LLM 提供商。支持openai、ollama、lollms、azure_openai、bedrock、gemini。LLM_MODEL基础模型名。Azure OpenAI 场景下通常是部署名。LLM_BINDING_HOST基础提供商端点。SDK 默认端点使用对应哨兵值如DEFAULT_GEMINI_ENDPOINT或DEFAULT_BEDROCK_ENDPOINT。LLM_BINDING_API_KEY基础 API Key。Bedrock 不使用该字段。LLM_TIMEOUT基础 LLM 超时。未设置角色超时时角色继承它。MAX_ASYNC_LLM基础 LLM 最大并发。未设置{ROLE}_MAX_ASYNC_LLM时角色继承它MAX_ASYNC仍作为弃用别名被接受。仓库的 env.example 中给出了同样的基础默认值MAX_ASYNC_LLM4并在 L1021 附近以注释形式预置了每个角色的覆盖位可作为配置起点。三、角色覆盖变量每个角色可以覆盖绑定、模型、端点、API Key、并发与超时QUERY_LLM_BINDINGopenai QUERY_LLM_MODELgpt-5 QUERY_LLM_BINDING_HOSThttps://api.openai.com/v1 QUERY_LLM_BINDING_API_KEYyour_query_api_key QUERY_MAX_ASYNC_LLM2 QUERY_LLM_TIMEOUT240变量格式变量说明{ROLE}_LLM_BINDING覆盖角色提供商。ROLE可为EXTRACT、KEYWORD、QUERY、VLM。{ROLE}_LLM_MODEL覆盖角色模型名。{ROLE}_LLM_BINDING_HOST覆盖角色端点。{ROLE}_LLM_BINDING_API_KEY覆盖角色 API Key。Bedrock 不支持。{ROLE}_MAX_ASYNC_LLM覆盖角色最大并发。未设置时继承MAX_ASYNC_LLM。{ROLE}_LLM_TIMEOUT覆盖角色超时。未设置时继承LLM_TIMEOUT。源码中的解析链路这些变量的读取并非逐个手写而是由 lightrag/api/config.py 中的循环按ROLES注册表统一处理for spec in ROLES: prefix spec.env_prefix binding_key f{prefix}_LLM_BINDING model_key f{prefix}_LLM_MODEL host_key f{prefix}_LLM_BINDING_HOST apikey_key f{prefix}_LLM_BINDING_API_KEY max_async_key f{prefix}_MAX_ASYNC_LLM timeout_key f{prefix}_LLM_TIMEOUT ...同一循环中还内置了两条启动期校验把配置错误挡在启动阶段而不是第一次调用时Bedrock 角色拒绝通用 API Key若role_binding bedrock且设置了{ROLE}_LLM_BINDING_API_KEY直接SystemExit并提示改用角色级 SigV4AWS_*变量或进程级AWS_BEARER_TOKEN_BEDROCKconfig.py。跨提供商必填校验若角色绑定与基础LLM_BINDING不同则必须设置{ROLE}_LLM_MODEL非 Bedrock 角色还必须设置{ROLE}_LLM_BINDING_API_KEY否则启动即失败并列出缺失变量config.py。若{ROLE}_LLM_BINDING_HOST未设置代码会用该提供商的默认端点回填。运行时继承则发生在 lightrag/api/lightrag_server.py 的resolve_role_llm_settings中binding/model/host 依次取角色运行时覆盖 → 角色环境变量 → 基础值API Key 在非 Bedrock 角色上取角色 Key 或基础LLM_BINDING_API_KEYtimeout未设置角色值时回落到LLM_TIMEOUTmax_async未设置角色值时在后续包装层回落到MAX_ASYNC_LLM。该函数还显式计算is_cross_provider role_binding ! args.llm_binding作为后续 Provider 选项是否继承的判断依据。四、Provider 选项覆盖提供商专属选项使用如下格式{ROLE}_{PROVIDER_PREFIX}_{FIELD}示例# 仅为 QUERY 角色覆盖 OpenAI 推理强度 QUERY_OPENAI_LLM_REASONING_EFFORTmedium # 仅为 EXTRACT 角色覆盖 Bedrock 生成参数 EXTRACT_BEDROCK_LLM_TEMPERATURE0.0 EXTRACT_BEDROCK_LLM_MAX_TOKENS2048 # 仅为 VLM 角色覆盖 Gemini 生成参数 VLM_GEMINI_LLM_MAX_OUTPUT_TOKENS4096 VLM_GEMINI_LLM_TEMPERATURE0.2常见 Provider 前缀Provider基础选项前缀角色选项示例openai/azure_openaiOPENAI_LLM_*QUERY_OPENAI_LLM_REASONING_EFFORTollamaOLLAMA_LLM_*EXTRACT_OLLAMA_LLM_NUM_PREDICTlollms使用 Ollama 兼容的选项集QUERY_OLLAMA_LLM_TEMPERATUREbedrockBEDROCK_LLM_*EXTRACT_BEDROCK_LLM_MAX_TOKENSgeminiGEMINI_LLM_*VLM_GEMINI_LLM_THINKING_CONFIG这篇指南覆盖角色前缀与继承规则关于{FIELD}这一半——每个前缀接受哪些选项、类型、取值语法以及 Provider 驱动如何消费它们——参见 LLM and Embedding Provider Options Reference。options_dict_for_role 的继承实现上述同 Provider 继承、跨 Provider 从空开始的规则由 lightrag/llm/binding_options.py 的options_dict_for_role实现if is_cross_provider: base: dict[str, Any] {} # 跨 Provider从空选项集出发 else: base cls.options_dict(args) # 同 Provider先继承基础 Provider 选项 role_upper role.upper() env_prefix cls._binding_name.upper() _ for arg_item in cls.args_env_name_type_value(): original_env arg_item[env_name] role_env f{role_upper}_{original_env} # 如 EXTRACT_OPENAI_LLM_TEMPERATURE env_raw os.getenv(role_env) if env_raw is None: continue ... base[field_name] ... # 按声明类型解析后叠加到 base 上可以看到角色选项是在基础选项字典上按声明的类型做解析叠加bool、int、float 按类型转换list/dict 走 JSON 解析解析失败时保留原始字符串并留待请求期报错——布尔字面量选项如 think 级别则被提前严格校验。lollms在 lightrag_server.py 中与ollama共用OllamaLLMOptions解析路径因此QUERY_OLLAMA_LLM_TEMPERATURE这类变量对 lollms 角色同样生效。五、继承规则同一 Provider 内的覆盖若角色未设置{ROLE}_LLM_BINDING或设置成与基础LLM_BINDING相同的值则角色继承基础配置未设置{ROLE}_LLM_MODEL时继承LLM_MODEL未设置{ROLE}_LLM_BINDING_HOST时继承LLM_BINDING_HOST未设置{ROLE}_LLM_BINDING_API_KEY时继承LLM_BINDING_API_KEY未设置{ROLE}_LLM_TIMEOUT时继承LLM_TIMEOUT未设置{ROLE}_MAX_ASYNC_LLM时继承MAX_ASYNC_LLMProvider 选项先继承基础 Provider 选项再叠加角色专属 Provider 选项。因此若只想在同一 Provider 内换模型只需要设模型名LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key OPENAI_LLM_REASONING_EFFORTminimal # QUERY 继承 host、API key、超时、并发和 OPENAI_LLM_REASONING_EFFORT QUERY_LLM_MODELgpt-5跨 Provider 覆盖若角色的{ROLE}_LLM_BINDING与基础LLM_BINDING不同即为跨 Provider 配置。当前规则是必须设置{ROLE}_LLM_MODEL非 Bedrock 提供商必须设置{ROLE}_LLM_BINDING_API_KEY若未设置{ROLE}_LLM_BINDING_HOSTLightRAG 会尝试使用该提供商的默认 hostProvider 选项不继承基础 Provider 选项——从空集出发只应用角色专属选项。示例用 Ollama 做本地抽取最终回答走 OpenAILLM_BINDINGollama LLM_MODELqwen3.5:9b LLM_BINDING_HOSThttp://localhost:11434 OLLAMA_LLM_NUM_CTX32768 QUERY_LLM_BINDINGopenai QUERY_LLM_MODELgpt-5-mini QUERY_LLM_BINDING_HOSThttps://api.openai.com/v1 QUERY_LLM_BINDING_API_KEYyour_openai_api_key QUERY_OPENAI_LLM_REASONING_EFFORTminimal跨 Provider 配置下建议显式设置{ROLE}_LLM_BINDING_HOST避免默认 host与基础 Provider 端点之间的混淆。Bedrock 认证规则Bedrock 不使用LLM_BINDING_API_KEY也不支持{ROLE}_LLM_BINDING_API_KEY。可用的认证方式是全局 SigV4AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN、AWS_REGION角色级 SigV4{ROLE}_AWS_ACCESS_KEY_ID、{ROLE}_AWS_SECRET_ACCESS_KEY、{ROLE}_AWS_SESSION_TOKEN、{ROLE}_AWS_REGION进程级 Bearer TokenAWS_BEARER_TOKEN_BEDROCK。这是 AWS SDK 的进程级设置无法按角色覆盖。角色级 Bedrock 示例LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_openai_api_key EXTRACT_LLM_BINDINGbedrock EXTRACT_LLM_MODELus.amazon.nova-lite-v1:0 EXTRACT_LLM_BINDING_HOSTDEFAULT_BEDROCK_ENDPOINT EXTRACT_AWS_REGIONus-west-2 EXTRACT_AWS_ACCESS_KEY_IDyour_extract_access_key EXTRACT_AWS_SECRET_ACCESS_KEYyour_extract_secret_key EXTRACT_AWS_SESSION_TOKENyour_optional_session_token EXTRACT_BEDROCK_LLM_TEMPERATURE0.0 EXTRACT_BEDROCK_LLM_MAX_TOKENS2048从源码结构看{ROLE}_AWS_*四个变量同样由 config.py 的角色循环统一读取config.py运行时在resolve_role_llm_settings中按角色级 → 全局的顺序合并lightrag_server.py所以单个角色可以用独立 IAM/STS 凭据其余角色继续走全局凭据。六、Provider 行为矩阵Provider角色级 host/base_url角色级 API Key认证限制openai支持通过{ROLE}_LLM_BINDING_HOST传入 OpenAI 兼容客户端。支持{ROLE}_LLM_BINDING_API_KEY同 Provider 内未设置时继承基础LLM_BINDING_API_KEY。当前主要是 API Key / Bearer 模式。ollama支持通过{ROLE}_LLM_BINDING_HOST传入 Ollama 客户端。支持{ROLE}_LLM_BINDING_API_KEY同 Provider 内未设置时继承基础 Key。若没有 Key 到达下层回落到OLLAMA_API_KEY。Bearer 头。lollms支持{ROLE}_LLM_BINDING_HOST作为base_url使用。支持{ROLE}_LLM_BINDING_API_KEY同 Provider 内未设置时继承基础 Key。Bearer 头。azure_openai支持{ROLE}_LLM_BINDING_HOST作为 Azure 端点。支持{ROLE}_LLM_BINDING_API_KEY同 Provider 内未设置时继承基础 Key并可能回落到AZURE_OPENAI_API_KEY。AZURE_OPENAI_API_VERSION是全局环境变量不支持角色级覆盖。bedrock支持{ROLE}_LLM_BINDING_HOST作为endpoint_urlDEFAULT_BEDROCK_ENDPOINT表示交给 AWS SDK 选择。不支持通用 API Key。使用全局或角色级 SigV4。AWS_BEARER_TOKEN_BEDROCK是进程级的不能按角色覆盖。gemini支持通过{ROLE}_LLM_BINDING_HOST传给 Google GenAI 客户端DEFAULT_GEMINI_ENDPOINT表示使用 SDK 默认端点。AI Studio 模式支持{ROLE}_LLM_BINDING_API_KEY。Vertex AI 由GOOGLE_GENAI_USE_VERTEXAI、GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION、GOOGLE_APPLICATION_CREDENTIALS控制均为进程级设置。七、运行时机制角色独立队列、热更新与可观测性环境变量只是配置入口真正让角色分治成立的是 lightrag/llm_roles.py 中的_RoleLLMMixin。结合源码可以看三点每个角色拥有独立并发队列。_wrap_llm_role_func用priority_limit_async_func_call(max_async, llm_timeout..., concurrency_groupfllm:{role_name})包装每个角色的原始 LLM 函数llm_roles.py。也就是说{ROLE}_MAX_ASYNC_LLM和{ROLE}_LLM_TIMEOUT不是共享的全局限流参数而是各自角色队列的容量与任务上限EXTRACT_MAX_ASYNC_LLM4不会挤占QUERY_MAX_ASYNC_LLM2的额度。基础的llm_model_func本身不再单独包装——所有调用路径都经过角色包装层并发控制因此集中在角色层。支持运行时热更新。update_llm_role_config/aupdate_llm_role_config可以在不重启的情况下更换某角色的 binding/model/host/api_key/provider_optionsllm_roles.py更新采用先快照、失败即回滚的策略异步版本还会等待旧队列排空后才返回其排空上限为llm_timeout * 2 15秒。可观测输出对凭据脱敏。get_llm_role_config用于/health与 WebUI 展示会彻底剥离而非打码metadata 中的api_key、secret、token等敏感字段只保留 binding/model/host/max_async/timeout 等安全信息llm_roles.py。每角色的队列状态也可通过get_llm_queue_status查询多 worker 场景下会聚合各 gunicorn worker 的快照。对排障的含义当你怀疑某角色配置未生效时可以先看服务日志中的 Role LLM Configuration 行与/health的角色配置视图确认生效的 binding/model/host/max_async/timeout再回查对应环境变量。相关实现行为有测试用例覆盖如 tests/llm/test_llm_role_runtime.py 与 tests/api/config/test_api_config_ollama_role_think.py。八、推荐配置模式模式 1同 Provider仅换模型适用于使用同一 OpenAI Key 与端点但希望最终回答用更强模型的场景LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key OPENAI_LLM_REASONING_EFFORTminimal QUERY_LLM_MODELgpt-5 QUERY_MAX_ASYNC_LLM2QUERY继承基础 host、API Key 与OPENAI_LLM_REASONING_EFFORT。模式 2同 Provider换模型并调参适用于基础模型用于抽取、最终回答使用更高推理强度的场景LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key OPENAI_LLM_REASONING_EFFORTminimal OPENAI_LLM_MAX_COMPLETION_TOKENS4096 QUERY_LLM_MODELgpt-5 QUERY_OPENAI_LLM_REASONING_EFFORTmedium QUERY_OPENAI_LLM_MAX_COMPLETION_TOKENS9000 QUERY_LLM_TIMEOUT240模式 3同 Provider不同端点与 API Key适用于所有角色都用openai绑定但部分角色访问官方 OpenAI API、其他角色访问本地 vLLM、SGLang、OpenRouter 或其他 OpenAI 兼容端点的场景。示例中EXTRACT使用官方 OpenAIgpt-5-miniQUERY使用官方 OpenAIgpt-5.4使用独立的 OpenAI KeyKEYWORD使用本地 vLLM 部署的Qwen3.5-35B-A3B。########################################################################### # 基础 LLM 兜底。与 EXTRACT 保持一致保证未显式配置的角色仍有有效的 OpenAI 配置 ########################################################################### LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_extract_openai_api_key LLM_TIMEOUT240 MAX_ASYNC_LLM4 ########################################################################### # 重要 # 若有任一角色指向不支持该参数的本地 OpenAI 兼容服务器 # 不要在此设置全局 OPENAI_LLM_REASONING_EFFORT改用角色级 OPENAI 选项。 ########################################################################### # OPENAI_LLM_REASONING_EFFORTnone ########################################################################### # EXTRACTOpenAI 官方 APIgpt-5-mini ########################################################################### EXTRACT_LLM_BINDINGopenai EXTRACT_LLM_MODELgpt-5-mini EXTRACT_LLM_BINDING_HOSThttps://api.openai.com/v1 EXTRACT_LLM_BINDING_API_KEYyour_extract_openai_api_key EXTRACT_OPENAI_LLM_REASONING_EFFORTlow EXTRACT_OPENAI_LLM_MAX_COMPLETION_TOKENS4096 EXTRACT_MAX_ASYNC_LLM4 EXTRACT_LLM_TIMEOUT180 ########################################################################### # QUERYOpenAI 官方 APIgpt-5.4独立 API Key ########################################################################### QUERY_LLM_BINDINGopenai QUERY_LLM_MODELgpt-5.4 QUERY_LLM_BINDING_HOSThttps://api.openai.com/v1 QUERY_LLM_BINDING_API_KEYyour_query_openai_api_key QUERY_OPENAI_LLM_REASONING_EFFORTmedium QUERY_OPENAI_LLM_MAX_COMPLETION_TOKENS9000 QUERY_MAX_ASYNC_LLM2 QUERY_LLM_TIMEOUT240 ########################################################################### # KEYWORD本地 vLLM OpenAI 兼容端点Qwen3.5-35B-A3B ########################################################################### KEYWORD_LLM_BINDINGopenai KEYWORD_LLM_MODELQwen3.5-35B-A3B KEYWORD_LLM_BINDING_HOSThttp://localhost:8000/v1 # 若 vLLM 以 --api-key 启动此处填相同值 # 若 vLLM 无认证仍需设置非空占位值避免回落使用官方 OpenAI Key。 KEYWORD_LLM_BINDING_API_KEYlocal-vllm-api-key KEYWORD_OPENAI_LLM_MAX_TOKENS2048 # 对 vLLM 提供的 Qwen 系模型可选用于关闭思考 KEYWORD_OPENAI_LLM_EXTRA_BODY{chat_template_kwargs: {enable_thinking: false}} KEYWORD_MAX_ASYNC_LLM4 KEYWORD_LLM_TIMEOUT60该模式不算跨 Provider因为三个角色都用openai绑定。LightRAG 会把每个角色的*_LLM_BINDING_HOST与*_LLM_BINDING_API_KEY分别传给 OpenAI 兼容客户端。注意同 Provider 内Provider 选项会继承基础OPENAI_LLM_*。若本地 vLLM 服务器不支持reasoning_effort这类官方 OpenAI 参数不要设置全局OPENAI_LLM_REASONING_EFFORT应改用EXTRACT_OPENAI_LLM_REASONING_EFFORT、QUERY_OPENAI_LLM_REASONING_EFFORT等角色级变量。模式 4单角色跨 Provider适用于基础使用官方 OpenAI 模型、仅关键词抽取使用本地 Ollama 的场景LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_openai_api_key OPENAI_LLM_REASONING_EFFORTmedium KEYWORD_LLM_BINDINGollama KEYWORD_LLM_MODELqwen3.5:9b KEYWORD_LLM_BINDING_HOSThttp://localhost:11434 KEYWORD_LLM_BINDING_API_KEYollama-local-key KEYWORD_OLLAMA_LLM_NUM_CTX32768跨 Provider 配置下Ollama 选项不继承 OpenAI 选项。本地 Ollama 场景中KEYWORD_LLM_BINDING_API_KEY通常可以用占位值——当前跨 Provider 校验要求非 Bedrock 角色显式提供角色级 API Key。模式 5为 VLM 指定专用多模态模型适用于文本任务使用更便宜的模型、多模态分析使用视觉语言模型的场景VLM_PROCESS_ENABLEtrue LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key VLM_LLM_BINDINGopenai VLM_LLM_MODELgpt-4o VLM_OPENAI_LLM_MAX_TOKENS4096 VLM_MAX_ASYNC_LLM2 VLM_LLM_TIMEOUT240若 VLM 使用与基础相同的 Provider 和 Key可以省略VLM_LLM_BINDING_HOST与VLM_LLM_BINDING_API_KEY。VLM_PROCESS_ENABLE是多模态分析的总开关。为false时管线会发警告并跳过所有多模态条目而不调用 VLM为true时实际生效的 VLM 绑定设置了VLM_LLM_BINDING就用它否则用LLM_BINDING必须支持图像输入。具备视觉能力的 Provider 有openai、azure_openai、gemini、bedrock、ollama、anthropiclollms因无法接受图像输入会在启动时被拒绝。这条启动期校验在 config.py 中实现VLM_PROCESS_ENABLEtrue且生效绑定命中{lollms}时直接SystemExit。模式 6Bedrock 角色级 SigV4 凭据适用于仅有一个角色访问 Bedrock 并使用独立 IAM/STS 凭据的场景LLM_BINDINGopenai LLM_MODELgpt-5-mini LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_openai_api_key QUERY_LLM_BINDINGbedrock QUERY_LLM_MODELus.amazon.nova-lite-v1:0 QUERY_LLM_BINDING_HOSTDEFAULT_BEDROCK_ENDPOINT QUERY_AWS_REGIONus-east-1 QUERY_AWS_ACCESS_KEY_IDyour_query_access_key QUERY_AWS_SECRET_ACCESS_KEYyour_query_secret_key QUERY_AWS_SESSION_TOKENyour_optional_session_token QUERY_BEDROCK_LLM_MAX_TOKENS4096 QUERY_BEDROCK_LLM_TEMPERATURE0.2不要设置QUERY_LLM_BINDING_API_KEYBedrock 会拒绝该配置。九、注意事项Caveats同 Provider 内OPENAI_LLM_REASONING_EFFORT、OPENAI_LLM_MAX_TOKENS、OLLAMA_LLM_NUM_CTX、GEMINI_LLM_THINKING_CONFIG等 Provider 选项会自动继承。目前没有干净的角色级取消继承某个 Provider 选项的语义。若同 Provider 角色的模型不支持某个基础选项要么显式为该角色覆盖成该模型支持的取值要么把角色配置为跨 Provider 并只设置它支持的角色级 Provider 选项。azure_openai的AZURE_OPENAI_DEPLOYMENT与AZURE_OPENAI_API_VERSION是全局环境变量。若设置了AZURE_OPENAI_DEPLOYMENT它可能优先于角色模型名。Gemini 的 Vertex AI 模式由进程级 Google 环境变量控制。同一个 LightRAG 进程内不能一部分角色用 Vertex AI、另一部分角色用 AI Studio API Key。在 Docker/Compose 中LLM_BINDING_HOST通常需要使用容器可达地址如host.docker.internal角色级 host 遵循同样原则。修改.env后要重启 LightRAG Server。部分 IDE 终端会预加载.env建议打开新的终端会话确认环境变量已生效。支持思考的 Ollama 模型在抽取阶段可能静默返回空实体/关系——当整个生成预算都花在输出前的隐藏推理上时issue #3597。若出现该情况设置EXTRACT_OLLAMA_LLM_THINKfalse关键词抽取同样受影响时再加KEYWORD_OLLAMA_LLM_THINKfalse。除true/false外该选项还接受推理级别low/medium/high需要 Ollama 服务器支持级别不设置时跟随模型自身默认空值OLLAMA_LLM_THINK含义是false而不是未设置。服务器启动时还会通过ensure_think_supported对每个 Ollama 角色的最终生效选项做校验不支持的think取值会在启动期而非首次调用时报错lightrag_server.py。十、相关入口速查关注点位置官方配置指南本文主体文档docs/RoleSpecificLLMConfiguration.mdProvider 选项全量参考字段、类型、取值语法docs/LLMProviderOptions.md角色注册表、角色运行时 Mixinlightrag/llm_roles.py.env角色变量解析与启动校验lightrag/api/config.py角色设置运行时解析继承链、跨 Provider 判定lightrag/api/lightrag_server.pyProvider 选项的角色级继承实现lightrag/llm/binding_options.py预置的角色变量注释模板env.example约 L1021–L1057 的角色配置段角色运行时行为测试tests/llm/test_llm_role_runtime.py、tests/api/config/test_api_config_ollama_role_think.py综合来看LightRAG 的角色化 LLM 配置是一套注册表驱动 启动期强校验 运行时独立队列的机制配置面由ROLES注册表统一生成错误配置Bedrock 配 API Key、跨 Provider 缺必填项、VLM_PROCESS_ENABLE绑定不支持图像在启动期就会失败退出运行面则让每个角色拥有独立的并发配额、超时与 Provider 选项集互不挤占。按本文的六类模式选用模板、再对照第九节注意事项排查即可在成本与回答质量之间取得可控的平衡。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考