wehub-resource-sync
377 lines
16 KiB
Markdown
377 lines
16 KiB
Markdown
# 基于角色的 LLM/VLM 配置指南
|
||
|
||
LightRAG 支持为不同处理阶段配置不同的 LLM 或 VLM。这个机制适合把低成本模型用于抽取，把更强模型用于最终回答，或为多模态分析单独指定视觉语言模型。
|
||
|
||
## 角色说明
|
||
|
||
当前支持四个角色：
|
||
|
||
| 角色 | 用途 |
|
||
| --- | --- |
|
||
| `EXTRACT` | 文件插入阶段使用的模型，主要复杂实体关系抽取和摘要总结。建议配置关闭思考模式并具备处理复杂问题的高速模型，模型参数量建议为30B或以上，上下文长度至少为32KB。 |
|
||
| `KEYWORD` | 查询阶段关键词抽取，用于检索前的 high-level / low-level keyword 生成。建议配置关闭思考模式的超高速模型，以提高查询阶段的响应速度。模型数量建议为7B或以上。 |
|
||
| `QUERY` | 查询阶段用于根据召回内容最终问答用关乎问题。建议配置开启思考模式的高质量模型。模型能力越强，回答的质量会越高。模型参数量建议为30B或以上，上下文长度至少为32KB。 |
|
||
| `VLM` | 文件插入阶段用于分析图片。需要配置具有图片识别能力的高质量模型。模型参数量建议为30B或以上。 |
|
||
|
||
如果某个角色没有专门配置，LightRAG 会使用基础 `LLM_*` 配置。
|
||
|
||
## 基础 LLM 配置
|
||
|
||
基础配置定义默认 LLM provider、模型、服务地址、认证信息和并发控制：
|
||
|
||
```env
|
||
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 provider。支持 `openai`、`ollama`、`lollms`、`azure_openai`、`bedrock`、`gemini`。 |
|
||
| `LLM_MODEL` | 基础模型名。对 Azure OpenAI 通常使用 deployment 名称。 |
|
||
| `LLM_BINDING_HOST` | 基础 provider endpoint。对于 SDK 默认 endpoint，可使用对应 sentinel，例如 `DEFAULT_GEMINI_ENDPOINT` 或 `DEFAULT_BEDROCK_ENDPOINT`。 |
|
||
| `LLM_BINDING_API_KEY` | 基础 API key。Bedrock 不使用这个字段。 |
|
||
| `LLM_TIMEOUT` | 基础 LLM timeout。角色未设置 timeout 时继承它。 |
|
||
| `MAX_ASYNC_LLM` | 基础 LLM 最大并发。角色未设置 `{ROLE}_MAX_ASYNC_LLM` 时继承它。`MAX_ASYNC` 作为兼容旧名仍可用。 |
|
||
|
||
## 角色覆盖变量
|
||
|
||
每个角色都可以覆盖 binding、模型、endpoint、API key、并发和 timeout：
|
||
|
||
```env
|
||
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` | 覆盖角色 provider。`ROLE` 可为 `EXTRACT`、`KEYWORD`、`QUERY`、`VLM`。 |
|
||
| `{ROLE}_LLM_MODEL` | 覆盖角色模型名。 |
|
||
| `{ROLE}_LLM_BINDING_HOST` | 覆盖角色 endpoint。 |
|
||
| `{ROLE}_LLM_BINDING_API_KEY` | 覆盖角色 API key。Bedrock 不支持。 |
|
||
| `{ROLE}_MAX_ASYNC_LLM` | 覆盖角色最大并发。未设置时继承 `MAX_ASYNC_LLM`。 |
|
||
| `{ROLE}_LLM_TIMEOUT` | 覆盖角色 timeout。未设置时继承 `LLM_TIMEOUT`。 |
|
||
|
||
## Provider 参数覆盖
|
||
|
||
provider 细项使用下面的格式：
|
||
|
||
```env
|
||
{ROLE}_{PROVIDER_PREFIX}_{FIELD}
|
||
```
|
||
|
||
例如：
|
||
|
||
```env
|
||
# 只覆盖 QUERY 角色的 OpenAI reasoning effort
|
||
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` |
|
||
|
||
## 继承规则
|
||
|
||
### 同一个 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 options，再叠加角色专属 provider options。
|
||
|
||
因此，同一个 provider 下只想换模型时，只需要写模型名：
|
||
|
||
```env
|
||
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、timeout、并发和 OPENAI_LLM_REASONING_EFFORT
|
||
QUERY_LLM_MODEL=gpt-5
|
||
```
|
||
|
||
### 跨 provider 覆盖
|
||
|
||
如果角色的 `{ROLE}_LLM_BINDING` 与基础 `LLM_BINDING` 不同，就是跨 provider 配置。当前规则是：
|
||
|
||
- 必须设置 `{ROLE}_LLM_MODEL`。
|
||
- 非 Bedrock provider 必须设置 `{ROLE}_LLM_BINDING_API_KEY`。
|
||
- 如果没有设置 `{ROLE}_LLM_BINDING_HOST`，LightRAG 会尝试使用该 provider 的默认 host。
|
||
- provider 参数不继承基础 provider options，而是从空配置开始，只叠加角色专属 provider options。
|
||
|
||
示例：基础使用 Ollama，本地抽取；最终回答改用 OpenAI：
|
||
|
||
```env
|
||
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 的 endpoint 混淆。
|
||
|
||
### 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 示例：
|
||
|
||
```env
|
||
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
|
||
```
|
||
|
||
## Provider 行为对照
|
||
|
||
| Provider | 角色级 host/base_url | 角色级 API key | 认证限制 |
|
||
| --- | --- | --- | --- |
|
||
| `openai` | 支持，通过 `{ROLE}_LLM_BINDING_HOST` 传给 OpenAI-compatible client。 | 支持 `{ROLE}_LLM_BINDING_API_KEY`，未设置时同 provider 继承基础 `LLM_BINDING_API_KEY`。 | 当前主要是 API key / Bearer 模式。 |
|
||
| `ollama` | 支持，通过 `{ROLE}_LLM_BINDING_HOST` 传给 Ollama client。 | 支持 `{ROLE}_LLM_BINDING_API_KEY`，未设置时同 provider 继承基础 key；底层未收到 key 时会再回退 `OLLAMA_API_KEY`。 | Bearer header。 |
|
||
| `lollms` | 支持，通过 `{ROLE}_LLM_BINDING_HOST` 作为 `base_url`。 | 支持 `{ROLE}_LLM_BINDING_API_KEY`，未设置时同 provider 继承基础 key。 | Bearer header。 |
|
||
| `azure_openai` | 支持，通过 `{ROLE}_LLM_BINDING_HOST` 作为 Azure endpoint。 | 支持 `{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 选择。 | 不支持 generic API key。 | 使用全局或角色级 SigV4。`AWS_BEARER_TOKEN_BEDROCK` 是进程级，不能按角色覆盖。 |
|
||
| `gemini` | 支持，通过 `{ROLE}_LLM_BINDING_HOST` 传给 Google GenAI client；`DEFAULT_GEMINI_ENDPOINT` 表示使用 SDK 默认 endpoint。 | AI Studio 模式支持 `{ROLE}_LLM_BINDING_API_KEY`。 | Vertex AI 由 `GOOGLE_GENAI_USE_VERTEXAI`、`GOOGLE_CLOUD_PROJECT`、`GOOGLE_CLOUD_LOCATION`、`GOOGLE_APPLICATION_CREDENTIALS` 控制，都是进程级设置。 |
|
||
|
||
## 推荐配置模式
|
||
|
||
### 1. 同 provider 只更换模型
|
||
|
||
适合用同一个 OpenAI key 和 endpoint，但让最终回答使用更强模型：
|
||
|
||
```env
|
||
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=2
|
||
```
|
||
|
||
`QUERY` 会继承基础 host、API key 和 `OPENAI_LLM_REASONING_EFFORT`。
|
||
|
||
### 2. 同 provider 更换模型并调整参数
|
||
|
||
适合基础模型用于抽取，最终回答使用更高 reasoning effort：
|
||
|
||
```env
|
||
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 使用不同 endpoint 和 API key
|
||
|
||
适合所有角色都走 `openai` binding，但其中一些角色访问 OpenAI 官方接口，另一些角色访问本地 vLLM、SGLang 或 OpenRouter 等 OpenAI-compatible endpoint。下面的例子中：
|
||
|
||
- `EXTRACT` 使用 OpenAI 官方 `gpt-5-mini`。
|
||
- `QUERY` 使用 OpenAI 官方 `gpt-5.4`，并使用单独的 OpenAI key。
|
||
- `KEYWORD` 使用本地 vLLM 部署的 `Qwen3.5-35B-A3B`。
|
||
|
||
```env
|
||
###########################################################################
|
||
# Base LLM fallback. Keep it aligned with EXTRACT so unspecified roles still
|
||
# have a valid OpenAI configuration.
|
||
###########################################################################
|
||
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
|
||
|
||
###########################################################################
|
||
# IMPORTANT:
|
||
# Do not set global OPENAI_LLM_REASONING_EFFORT here if any same-provider role
|
||
# points to a local OpenAI-compatible server that does not support it.
|
||
# Use role-specific OPENAI options instead.
|
||
###########################################################################
|
||
# OPENAI_LLM_REASONING_EFFORT=none
|
||
|
||
###########################################################################
|
||
# EXTRACT: OpenAI official 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 official API, gpt-5.4, separate 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: local vLLM OpenAI-compatible endpoint, Qwen3.5-35B-A3B
|
||
###########################################################################
|
||
KEYWORD_LLM_BINDING=openai
|
||
KEYWORD_LLM_MODEL=Qwen3.5-35B-A3B
|
||
KEYWORD_LLM_BINDING_HOST=http://localhost:8000/v1
|
||
# If vLLM was started with --api-key, use the same value here.
|
||
# If vLLM has no auth, still set a non-empty dummy value to avoid falling
|
||
# back to the official OpenAI key.
|
||
KEYWORD_LLM_BINDING_API_KEY=local-vllm-api-key
|
||
KEYWORD_OPENAI_LLM_MAX_TOKENS=2048
|
||
# Optional for Qwen-style models served by vLLM when you want to disable thinking.
|
||
KEYWORD_OPENAI_LLM_EXTRA_BODY='{"chat_template_kwargs": {"enable_thinking": false}}'
|
||
KEYWORD_MAX_ASYNC_LLM=4
|
||
KEYWORD_LLM_TIMEOUT=60
|
||
```
|
||
|
||
这个模式不是跨 provider，因为三个角色的 binding 都是 `openai`。LightRAG 会分别把每个角色的 `*_LLM_BINDING_HOST` 和 `*_LLM_BINDING_API_KEY` 传给 OpenAI-compatible client。
|
||
|
||
注意：同 provider 的 provider options 会继承基础 `OPENAI_LLM_*`。如果本地 vLLM 不支持 OpenAI 官方参数，例如 `reasoning_effort`，不要设置全局 `OPENAI_LLM_REASONING_EFFORT`；改用 `EXTRACT_OPENAI_LLM_REASONING_EFFORT`、`QUERY_OPENAI_LLM_REASONING_EFFORT` 这类角色级变量。
|
||
|
||
### 4. 某个角色跨 provider
|
||
|
||
适合基础使用 OpenAI 官方模型，只有关键词抽取使用本地 Ollama：
|
||
|
||
```env
|
||
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 参数。`KEYWORD_LLM_BINDING_API_KEY` 对本地 Ollama 通常可以使用占位值；当前跨 provider 校验会要求非 Bedrock 角色显式提供角色级 API key。
|
||
|
||
### 5. 为 VLM 单独指定多模态模型
|
||
|
||
适合文本任务使用便宜模型，多模态分析使用视觉语言模型：
|
||
|
||
```env
|
||
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` 时，pipeline 会对每个多模态 item 输出 warning 并跳过，不调用 VLM；设为 `true` 时，生效的 VLM binding（设置了 `VLM_LLM_BINDING` 时取该值，否则取 `LLM_BINDING`）必须支持图片输入。当前支持视觉输入的 provider 包括：`openai`、`azure_openai`、`gemini`、`bedrock`、`ollama`、`anthropic`。`lollms` 无法接收图片输入，会在启动时直接报错。
|
||
|
||
### 6. Bedrock 角色级 SigV4 凭证
|
||
|
||
适合只有某个角色访问 Bedrock，并使用独立 IAM/STS 凭证：
|
||
|
||
```env
|
||
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 会拒绝该配置。
|
||
|
||
## 注意事项
|
||
|
||
- 同 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。
|
||
- `LLM_BINDING_HOST` 在 Docker/Compose 中通常需要使用容器可访问地址，例如 `host.docker.internal`，角色级 host 也遵循相同原则。
|
||
- 修改 `.env` 后请重启 LightRAG Server。部分 IDE 终端会预加载 `.env`，建议打开新的终端会话确认环境变量生效。
|