LightRAG 按角色配置 LLM/VLM 实战:EXTRACT、KEYWORD、QUERY、VLM 四角色的模型分治与继承规则
【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG
LightRAG 允许为抽取、关键词生成、最终回答、多模态分析四个处理阶段分别指定不同的 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 定义了一个静态角色注册表ROLES:
ROLES: 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_BINDING=openai LLM_MODEL=gpt-5-mini LLM_BINDING_HOST=https://api.openai.com/v1 LLM_BINDING_API_KEY=your_api_key # 所有 LLM 请求的默认超时 LLM_TIMEOUT=240 # 所有 LLM 调用的默认最大并发(MAX_ASYNC 仍作为弃用别名被接受) MAX_ASYNC_LLM=4常用字段:
| 变量 | 说明 |
|---|---|
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_LLM=4),并在 L1021 附近以注释形式预置了每个角色的覆盖位,可作为配置起点。
三、角色覆盖变量
每个角色可以覆盖绑定、模型、端点、API Key、并发与超时:
QUERY_LLM_BINDING=openai QUERY_LLM_MODEL=gpt-5 QUERY_LLM_BINDING_HOST=https://api.openai.com/v1 QUERY_LLM_BINDING_API_KEY=your_query_api_key QUERY_MAX_ASYNC_LLM=2 QUERY_LLM_TIMEOUT=240变量格式:
| 变量 | 说明 |
|---|---|
{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_BEDROCK(config.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_KEY";timeout未设置角色值时回落到LLM_TIMEOUT;max_async未设置角色值时在后续包装层回落到MAX_ASYNC_LLM。该函数还显式计算is_cross_provider = role_binding != args.llm_binding,作为后续 Provider 选项是否继承的判断依据。
四、Provider 选项覆盖
提供商专属选项使用如下格式:
{ROLE}_{PROVIDER_PREFIX}_{FIELD}示例:
# 仅为 QUERY 角色覆盖 OpenAI 推理强度 QUERY_OPENAI_LLM_REASONING_EFFORT=medium # 仅为 EXTRACT 角色覆盖 Bedrock 生成参数 EXTRACT_BEDROCK_LLM_TEMPERATURE=0.0 EXTRACT_BEDROCK_LLM_MAX_TOKENS=2048 # 仅为 VLM 角色覆盖 Gemini 生成参数 VLM_GEMINI_LLM_MAX_OUTPUT_TOKENS=4096 VLM_GEMINI_LLM_TEMPERATURE=0.2常见 Provider 前缀:
| Provider | 基础选项前缀 | 角色选项示例 |
|---|---|---|
openai/azure_openai | OPENAI_LLM_* | QUERY_OPENAI_LLM_REASONING_EFFORT |
ollama | OLLAMA_LLM_* | EXTRACT_OLLAMA_LLM_NUM_PREDICT |
lollms | 使用 Ollama 兼容的选项集 | QUERY_OLLAMA_LLM_TEMPERATURE |
bedrock | BEDROCK_LLM_* | EXTRACT_BEDROCK_LLM_MAX_TOKENS |
gemini | GEMINI_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_LLM; - Provider 选项先继承基础 Provider 选项,再叠加角色专属 Provider 选项。
因此,若只想在同一 Provider 内换模型,只需要设模型名:
LLM_BINDING=openai LLM_MODEL=gpt-5-mini LLM_BINDING_HOST=https://api.openai.com/v1 LLM_BINDING_API_KEY=your_api_key OPENAI_LLM_REASONING_EFFORT=minimal # QUERY 继承 host、API key、超时、并发和 OPENAI_LLM_REASONING_EFFORT QUERY_LLM_MODEL=gpt-5跨 Provider 覆盖
若角色的{ROLE}_LLM_BINDING与基础LLM_BINDING不同,即为跨 Provider 配置。当前规则是:
- 必须设置
{ROLE}_LLM_MODEL; - 非 Bedrock 提供商必须设置
{ROLE}_LLM_BINDING_API_KEY; - 若未设置
{ROLE}_LLM_BINDING_HOST,LightRAG 会尝试使用该提供商的默认 host; - Provider 选项不继承基础 Provider 选项——从空集出发,只应用角色专属选项。
示例:用 Ollama 做本地抽取,最终回答走 OpenAI:
LLM_BINDING=ollama LLM_MODEL=qwen3.5:9b LLM_BINDING_HOST=http://localhost:11434 OLLAMA_LLM_NUM_CTX=32768 QUERY_LLM_BINDING=openai QUERY_LLM_MODEL=gpt-5-mini QUERY_LLM_BINDING_HOST=https://api.openai.com/v1 QUERY_LLM_BINDING_API_KEY=your_openai_api_key QUERY_OPENAI_LLM_REASONING_EFFORT=minimal跨 Provider 配置下建议显式设置{ROLE}_LLM_BINDING_HOST,避免"默认 host"与基础 Provider 端点之间的混淆。
Bedrock 认证规则
Bedrock 不使用LLM_BINDING_API_KEY,也不支持{ROLE}_LLM_BINDING_API_KEY。可用的认证方式是:
- 全局 SigV4:
AWS_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 Token:
AWS_BEARER_TOKEN_BEDROCK。这是 AWS SDK 的进程级设置,无法按角色覆盖。
角色级 Bedrock 示例:
LLM_BINDING=openai LLM_MODEL=gpt-5-mini LLM_BINDING_HOST=https://api.openai.com/v1 LLM_BINDING_API_KEY=your_openai_api_key EXTRACT_LLM_BINDING=bedrock EXTRACT_LLM_MODEL=us.amazon.nova-lite-v1:0 EXTRACT_LLM_BINDING_HOST=DEFAULT_BEDROCK_ENDPOINT EXTRACT_AWS_REGION=us-west-2 EXTRACT_AWS_ACCESS_KEY_ID=your_extract_access_key EXTRACT_AWS_SECRET_ACCESS_KEY=your_extract_secret_key EXTRACT_AWS_SESSION_TOKEN=your_optional_session_token EXTRACT_BEDROCK_LLM_TEMPERATURE=0.0 EXTRACT_BEDROCK_LLM_MAX_TOKENS=2048从源码结构看,{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_url;DEFAULT_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_group=f"llm:{role_name}")包装每个角色的原始 LLM 函数(llm_roles.py)。也就是说{ROLE}_MAX_ASYNC_LLM和{ROLE}_LLM_TIMEOUT不是共享的全局限流参数,而是各自角色队列的容量与任务上限;EXTRACT_MAX_ASYNC_LLM=4不会挤占QUERY_MAX_ASYNC_LLM=2的额度。基础的llm_model_func本身不再单独包装——所有调用路径都经过角色包装层,并发控制因此集中在角色层。 - 支持运行时热更新。
update_llm_role_config/aupdate_llm_role_config可以在不重启的情况下更换某角色的 binding/model/host/api_key/provider_options(llm_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_BINDING=openai LLM_MODEL=gpt-5-mini LLM_BINDING_HOST=https://api.openai.com/v1 LLM_BINDING_API_KEY=your_api_key OPENAI_LLM_REASONING_EFFORT=minimal QUERY_LLM_MODEL=gpt-5 QUERY_MAX_ASYNC_LLM=2QUERY继承基础 host、API Key 与OPENAI_LLM_REASONING_EFFORT。
模式 2:同 Provider,换模型并调参
适用于基础模型用于抽取、最终回答使用更高推理强度的场景:
LLM_BINDING=openai LLM_MODEL=gpt-5-mini LLM_BINDING_HOST=https://api.openai.com/v1 LLM_BINDING_API_KEY=your_api_key OPENAI_LLM_REASONING_EFFORT=minimal OPENAI_LLM_MAX_COMPLETION_TOKENS=4096 QUERY_LLM_MODEL=gpt-5 QUERY_OPENAI_LLM_REASONING_EFFORT=medium QUERY_OPENAI_LLM_MAX_COMPLETION_TOKENS=9000 QUERY_LLM_TIMEOUT=240模式 3:同 Provider,不同端点与 API Key
适用于所有角色都用openai绑定,但部分角色访问官方 OpenAI API、其他角色访问本地 vLLM、SGLang、OpenRouter 或其他 OpenAI 兼容端点的场景。示例中:
EXTRACT使用官方 OpenAIgpt-5-mini;QUERY使用官方 OpenAIgpt-5.4,使用独立的 OpenAI Key;KEYWORD使用本地 vLLM 部署的Qwen3.5-35B-A3B。
########################################################################### # 基础 LLM 兜底。与 EXTRACT 保持一致,保证未显式配置的角色仍有有效的 OpenAI 配置 ########################################################################### LLM_BINDING=openai LLM_MODEL=gpt-5-mini LLM_BINDING_HOST=https://api.openai.com/v1 LLM_BINDING_API_KEY=your_extract_openai_api_key LLM_TIMEOUT=240 MAX_ASYNC_LLM=4 ########################################################################### # 重要: # 若有任一角色指向不支持该参数的本地 OpenAI 兼容服务器, # 不要在此设置全局 OPENAI_LLM_REASONING_EFFORT;改用角色级 OPENAI 选项。 ########################################################################### # OPENAI_LLM_REASONING_EFFORT=none ########################################################################### # EXTRACT:OpenAI 官方 API,gpt-5-mini ########################################################################### EXTRACT_LLM_BINDING=openai EXTRACT_LLM_MODEL=gpt-5-mini EXTRACT_LLM_BINDING_HOST=https://api.openai.com/v1 EXTRACT_LLM_BINDING_API_KEY=your_extract_openai_api_key EXTRACT_OPENAI_LLM_REASONING_EFFORT=low EXTRACT_OPENAI_LLM_MAX_COMPLETION_TOKENS=4096 EXTRACT_MAX_ASYNC_LLM=4 EXTRACT_LLM_TIMEOUT=180 ########################################################################### # QUERY:OpenAI 官方 API,gpt-5.4,独立 API Key ########################################################################### QUERY_LLM_BINDING=openai QUERY_LLM_MODEL=gpt-5.4 QUERY_LLM_BINDING_HOST=https://api.openai.com/v1 QUERY_LLM_BINDING_API_KEY=your_query_openai_api_key QUERY_OPENAI_LLM_REASONING_EFFORT=medium QUERY_OPENAI_LLM_MAX_COMPLETION_TOKENS=9000 QUERY_MAX_ASYNC_LLM=2 QUERY_LLM_TIMEOUT=240 ########################################################################### # KEYWORD:本地 vLLM OpenAI 兼容端点,Qwen3.5-35B-A3B ########################################################################### KEYWORD_LLM_BINDING=openai KEYWORD_LLM_MODEL=Qwen3.5-35B-A3B KEYWORD_LLM_BINDING_HOST=http://localhost:8000/v1 # 若 vLLM 以 --api-key 启动,此处填相同值; # 若 vLLM 无认证,仍需设置非空占位值,避免回落使用官方 OpenAI Key。 KEYWORD_LLM_BINDING_API_KEY=local-vllm-api-key KEYWORD_OPENAI_LLM_MAX_TOKENS=2048 # 对 vLLM 提供的 Qwen 系模型,可选,用于关闭思考 KEYWORD_OPENAI_LLM_EXTRA_BODY='{"chat_template_kwargs": {"enable_thinking": false}}' KEYWORD_MAX_ASYNC_LLM=4 KEYWORD_LLM_TIMEOUT=60该模式不算跨 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_BINDING=openai LLM_MODEL=gpt-5-mini LLM_BINDING_HOST=https://api.openai.com/v1 LLM_BINDING_API_KEY=your_openai_api_key OPENAI_LLM_REASONING_EFFORT=medium KEYWORD_LLM_BINDING=ollama KEYWORD_LLM_MODEL=qwen3.5:9b KEYWORD_LLM_BINDING_HOST=http://localhost:11434 KEYWORD_LLM_BINDING_API_KEY=ollama-local-key KEYWORD_OLLAMA_LLM_NUM_CTX=32768跨 Provider 配置下,Ollama 选项不继承 OpenAI 选项。本地 Ollama 场景中KEYWORD_LLM_BINDING_API_KEY通常可以用占位值——当前跨 Provider 校验要求非 Bedrock 角色显式提供角色级 API Key。
模式 5:为 VLM 指定专用多模态模型
适用于文本任务使用更便宜的模型、多模态分析使用视觉语言模型的场景:
VLM_PROCESS_ENABLE=true LLM_BINDING=openai LLM_MODEL=gpt-5-mini LLM_BINDING_HOST=https://api.openai.com/v1 LLM_BINDING_API_KEY=your_api_key VLM_LLM_BINDING=openai VLM_LLM_MODEL=gpt-4o VLM_OPENAI_LLM_MAX_TOKENS=4096 VLM_MAX_ASYNC_LLM=2 VLM_LLM_TIMEOUT=240若 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、anthropic;lollms因无法接受图像输入会在启动时被拒绝。这条启动期校验在 config.py 中实现:VLM_PROCESS_ENABLE=true且生效绑定命中{"lollms"}时直接SystemExit。
模式 6:Bedrock 角色级 SigV4 凭据
适用于仅有一个角色访问 Bedrock 并使用独立 IAM/STS 凭据的场景:
LLM_BINDING=openai LLM_MODEL=gpt-5-mini LLM_BINDING_HOST=https://api.openai.com/v1 LLM_BINDING_API_KEY=your_openai_api_key QUERY_LLM_BINDING=bedrock QUERY_LLM_MODEL=us.amazon.nova-lite-v1:0 QUERY_LLM_BINDING_HOST=DEFAULT_BEDROCK_ENDPOINT QUERY_AWS_REGION=us-east-1 QUERY_AWS_ACCESS_KEY_ID=your_query_access_key QUERY_AWS_SECRET_ACCESS_KEY=your_query_secret_key QUERY_AWS_SESSION_TOKEN=your_optional_session_token QUERY_BEDROCK_LLM_MAX_TOKENS=4096 QUERY_BEDROCK_LLM_TEMPERATURE=0.2不要设置QUERY_LLM_BINDING_API_KEY,Bedrock 会拒绝该配置。
九、注意事项(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_THINK=false(关键词抽取同样受影响时再加KEYWORD_OLLAMA_LLM_THINK=false)。除true/false外,该选项还接受推理级别(low/medium/high,需要 Ollama 服务器支持级别);不设置时跟随模型自身默认;空值(OLLAMA_LLM_THINK=)含义是false,而不是"未设置"。服务器启动时还会通过ensure_think_supported对每个 Ollama 角色的最终生效选项做校验,不支持的think=取值会在启动期而非首次调用时报错(lightrag_server.py)。
十、相关入口速查
| 关注点 | 位置 |
|---|---|
| 官方配置指南(本文主体文档) | docs/RoleSpecificLLMConfiguration.md |
| Provider 选项全量参考(字段、类型、取值语法) | docs/LLMProviderOptions.md |
| 角色注册表、角色运行时 Mixin | lightrag/llm_roles.py |
.env角色变量解析与启动校验 | lightrag/api/config.py |
| 角色设置运行时解析(继承链、跨 Provider 判定) | lightrag/api/lightrag_server.py |
| Provider 选项的角色级继承实现 | 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),仅供参考