LLM 服务商配置指南

本文面向首次配置用户，说明如何选择 LLM 配置方式、如何把 Web 设置页「AI 模型配置」预设映射到 .env / GitHub Actions，以及如何处理常见检测错误。

实际可用模型、额度、区域限制和价格以各服务商控制台为准；如果模型列表拉取失败，可在 Web 中手动填写模型名。Web 设置页展示的 provider 能力标签、官方来源链接和配置注意事项来自静态 provider template，仅用于配置参考，不代表运行时能力已验证通过。

先选配置方式

优先级保持不变：LITELLM_CONFIG / LITELLM_CONFIG_YAML > LLM_CHANNELS > legacy provider keys。P4 只补文档，不迁移、不清空、不静默改写旧配置。

Web 设置页路径

推荐优先使用 Web 设置页完成 Channels 配置：

1. 打开设置页的「AI 模型配置」。
2. 在「快速添加渠道」选择服务商预设。
3. 填入 API Key，必要时点击「获取模型」。
4. 选择主模型、Agent 主模型、备选模型和 Vision 模型后保存。
5. 点击「测试连接」确认鉴权、模型名、额度和响应格式正常。
6. 如需确认 JSON / tools / stream / vision 能力，手动勾选「运行时能力检测」后再触发；该检测会产生真实 LLM 请求，结果只代表当前账号、模型和 endpoint 的一次 best-effort 检测，不会写回 .env，也不会阻止保存。

Channels 示例

DeepSeek 官方渠道

LLM_CHANNELS=deepseek
LLM_DEEPSEEK_PROTOCOL=deepseek
LLM_DEEPSEEK_BASE_URL=https://api.deepseek.com
LLM_DEEPSEEK_API_KEY=sk-xxx
LLM_DEEPSEEK_MODELS=deepseek-v4-flash,deepseek-v4-pro
LITELLM_MODEL=deepseek/deepseek-v4-flash

OpenAI-compatible 聚合或自定义网关

LLM_CHANNELS=my_proxy
LLM_MY_PROXY_PROTOCOL=openai
LLM_MY_PROXY_BASE_URL=https://your-proxy.example.com/v1
LLM_MY_PROXY_API_KEY=sk-xxx
LLM_MY_PROXY_MODELS=gpt-5.5,claude-sonnet-4-6

OpenAI-compatible Base URL 只填到服务商兼容入口，不额外拼接 /chat/completions。本地 .env、Docker 和自托管脚本可以直接使用自定义 channel；GitHub Actions 需要 workflow 显式透传同名 LLM_MY_PROXY_* 变量。

常用服务商预设

官方来源与兼容性

本页预设只保证配置形状与当前依赖的 OpenAI-compatible 路由规则一致；实际连通性仍取决于服务商账号权限、地域、额度和模型开通状态。当前 LiteLLM 版本约束以 requirements.txt 为准。

OpenAI-compatible 与 LiteLLM 规则

• OpenAI-compatible provider 的 channel protocol 通常是 openai。
• 运行时模型名通常写成 openai/<model>；例如自定义网关里的 gpt-5.5 可以作为 openai/gpt-5.5 被 LiteLLM 路由。
• Qwen/...、deepseek-ai/... 这类是服务商或模型仓库组织名前缀，不等同于 LiteLLM provider prefix；不要因为它们包含斜杠就误判为 provider/model 路由。
• Base URL 只填官方或网关给出的兼容入口，通常到 /v1、/api/v3 或厂商文档指定路径；不要手动追加 /chat/completions。
• 如果使用 YAML 模式，按 LiteLLM model_list / litellm_params 的原生语义配置；YAML 有效时优先级高于 Channels。

GitHub Actions 配置

仓库自带 .github/workflows/daily_analysis.yml 只会透传 workflow 中显式列出的环境变量。使用渠道模式时，先在 Repository Variables 或 Secrets 中设置 LLM_CHANNELS，再按渠道名补齐对应 LLM_<CHANNEL>_*。

默认 workflow 已显式映射 primary、secondary、aihubmix、anspire、deepseek、dashscope、zhipu、moonshot、minimax、volcengine、siliconflow、openrouter、gemini、anthropic、openai、ollama。如果使用自定义渠道名（如 my_proxy），仅在 Repository Secrets / Variables 中新增 LLM_MY_PROXY_* 不会自动生效，需要同步扩展 workflow 的 env: 映射；本地 .env、Docker 和自托管脚本不受这个限制。

Ollama 默认 Base URL http://127.0.0.1:11434 主要面向本地、Docker 或能访问该服务的 self-hosted runner。GitHub-hosted runner 通常没有本地 Ollama 服务，直接配置 LLM_CHANNELS=ollama 大概率会连接失败。

常见错误与处理建议

完整分类逻辑以 src/services/system_config_service.py 中的错误分类实现为准。

运行时能力检测边界

• JSON / tools / stream / vision smoke 必须在 Web 中显式触发。
• 检测会产生真实 LLM 请求，可能带来 token / 图像输入费用、RPM/TPM 限流、余额不足或超时。
• 检测结果只代表当前账号、模型和 endpoint 的一次 best-effort 运行时结果。
• 检测结果不会写回 .env，也不会阻止保存配置。
• 能力检测失败不等于 provider 全局不支持；失败可能来自账号权限、模型未开通、endpoint 区域、余额、服务商兼容层或 LiteLLM 转换路径。

回滚方式

• Web 设置页：删除或禁用对应 channel，重新选择旧的主模型 / Agent 模型 / fallback。
• .env：恢复备份中的 LLM_*、LITELLM_MODEL、AGENT_LITELLM_MODEL、VISION_MODEL、LITELLM_FALLBACK_MODELS。
• 从 Channels 回到 legacy：删除或清空 LLM_CHANNELS，保留 legacy provider key 和 LITELLM_MODEL。
• 从 YAML 回到 Channels / legacy：移除 LITELLM_CONFIG / LITELLM_CONFIG_YAML，重启后下层配置重新生效。
• 桌面端：使用导出的配置备份恢复。
• PR 回滚：revert 对应 docs PR；P4 不涉及配置、数据或代码迁移。