DSA DOCS

DSA 文档中心

围绕 DSA 真实使用路径：快速开始、Actions、本地、Docker，以及源项目完整文档。

GitHub Actions 部署 本地运行 Docker 部署 打开 DSA 仓库
模型与配置

LLM (大模型) 配置指南

欢迎！无论你是刚接触 AI 的新手小白，还是精通各种 API 的高玩老手，这份指南都能帮你快速把大模型（LLM）跑起来。

源文档 版本: v3.33.0-4-g7a21cd76 更新: 2026-10-17
LLM
在 GitHub 查看源文档

欢迎！无论你是刚接触 AI 的新手小白，还是精通各种 API 的高玩老手，这份指南都能帮你快速把大模型（LLM）跑起来。

本项目对外提供统一的 AI 模型接入体验，支持主流官方 API、OpenAI 兼容平台以及本地模型。底层由 LiteLLM 驱动，但大多数用户只需要理解“选服务商、填 API Key、选主模型/渠道”这条默认路径。为了照顾不同阶段的用户，我们设计了“三层优先级”配置，按需选择最适合你的方式即可。

如果你正在选择具体服务商、配置 GitHub Actions Secrets / Variables、排查 details.reason 错误或准备回滚配置，请优先查看 LLM 服务商配置指南。该文档集中维护 provider 预设、Actions 变量对照、运行时能力检测边界和常见错误处理建议。

本页的 provider/model/Base URL 说明本次未新增外部兼容语义，仅用于同步现网约定；实际兼容判断仍按当前仓库锁定依赖与运行时实现执行： - 依赖边界：litellm>=1.80.10,!=1.82.7,!=1.82.8,<1.99.0（与 requirements.txt 一致）。 - 兼容验证入口：tests/test_system_config_service.py、tests/test_system_config_api.py 以及现有前端模型配置页回归用例。 - 回退路径：优先使用 .env 配置备份 + POST /api/v1/system/config/import 恢复；也可在重启前手动回填旧 LITELLM_MODEL / LLM_* / AGENT_LITELLM_MODEL / VISION_MODEL / LLM_TEMPERATURE / LLM_USAGE_HMAC_*。
说明：本页对 provider/model/base URL 的说明同步沿用当前依赖约束与历史约定，仅做文档补充，不引入新的运行时 provider、模型或 Base URL 行为变更。

快速导航：你应该看哪一节？

  1. 【新手小白】 "我只想赶紧把系统跑起来，越简单越好！" -> 指路【方式一：极简单模型配置】
  2. 【进阶用户】 "我有好几个 Key，想配置备用模型，还要改自定义网址(Base URL)。" -> 指路【方式二：渠道(Channels)模式配置】
  3. 【高玩老手】 "我要做复杂的负载均衡、请求路由、甚至多异构平台高可用！" -> 指路【方式三：YAML 高级配置】
  4. 【本地模型】 "我想用 Ollama 本地模型！" -> 指路【示例 4：使用 Ollama 本地模型】
  5. 【视觉模型】 "我想用图片识别股票代码！" -> 指路【扩展功能：看图模型(Vision)配置】

Generation Backend（Phase 4）

Generation backend 是普通分析、大盘复盘和 generate_text() 的外层运行时选择。默认仍是 litellm，零配置路径与历史行为保持一致；codex_cli / claude_code_cli / opencode_cli 是显式 opt-in 的本地 CLI backend，当前标记为 experimental/limited。

GENERATION_BACKEND=litellm
GENERATION_FALLBACK_BACKEND=litellm
GENERATION_BACKEND_TIMEOUT_SECONDS=300
GENERATION_BACKEND_MAX_OUTPUT_BYTES=1048576
GENERATION_BACKEND_MAX_CONCURRENCY=1
LOCAL_CLI_BACKEND_MAX_CONCURRENCY=1
# 可选：留空时使用本机 OpenCode 默认模型；配置时作为 --model 覆盖值传给 OpenCode。
# OPENCODE_CLI_MODEL=provider/model
AGENT_BACKEND=auto
AGENT_GENERATION_BACKEND=auto

问股会话状态与升级

服务端统一保存主讨论对象及会话 Skill；LiteLLM single／现有 multi 与 Codex single 接口消费同一次接受快照。省略或 null Skill 沿用已保存选择（未选择时使用配置默认）；显式 [] 保存清空选择并使用内置默认，不启用配置中的非空 Skill。名称只在服务端索引唯一匹配时确认；比较不切股，模型失败／停止不撤销已接受状态。并发或会话实例冲突时，请手动刷新后重试，页面保留输入与待提交选择，不自动重发。

旧会话只恢复明确代码，不从历史名称造新事实；“分析600519 → 改看宁德时代 → 风险呢”需要再确认，不能继续沿用600519。升级自动追加状态列，不删除消息／Skill／报告。升级或回滚前停止后端，使用 SQLite backup 或停服完整备份（不能在 WAL 活跃时只复制主文件）；保留原配置、数据库位置和数据目录，更新配套后端／Web 后重启，不手工删表／删列。回滚保留新增列，旧代码仍可写消息与 Skill；再次升级若发现回滚期间新增用户消息，先显示未确认，再由用户明确确认对象。旧／新写进程混跑不支持；分离部署升级先后端再 Web，回滚先 Web 再后端。

代码与名称混用时，比较范围包含两者；紧邻的明确代码可消除同名上市地歧义（如 688981中芯国际）。从600519改看300750／把600519换成300750 按操作词关联的目的地确认300750，不因当前已经是300750或重复发送而反向切回600519；每次接受仍保存消息并递增版本。明确切股只开放新对象的工具范围，并移除不匹配的旧报告提示；目的地含多个备选项时需澄清，不能任选最后一个或排除当前对象后猜选。

已有主对象时，看看近期走势／分析一下财务状况／分析风险 正常继续分析，保留原确认来源和时间；分析300750 或唯一匹配名称仍可确认新对象。单独的“分析／看看”加尾随文本不证明切股；明确但无法确认的“改看…”需澄清，不启动分析。旧历史沿用同一方向与动作判定，但只用有效明确代码建立事实：普通追问保留候选，无法确认的新切换使旧候选失效，后续追问不能复活它；后续明确代码可重新建立。历史名称仅作为目标变化证据，不补造确认事实；读取恢复结果不写回股票或递增版本。

否定、询问、条件或引用中的切换不作为肯定确认：不要改看300750，继续分析600519 维持600519；是否改看300750？ 保留对象并澄清，不开放300750。代码和名称按实际出现位置解释；旧历史只有目的地位置的有效代码能确认，句子另一处同码不能替历史名称造事实。首次单独输入有效代码／唯一名称仍可确认，但任意文本中的唯一提及不自动确认。

如果600519下跌，就改看300750 的相邻条件与后件即使被逗号分隔，也只保存问题并澄清，不立即切股或启动分析；旧历史恢复同样不把它当成新确认。被否定的强／弱／选择比较不贡献参与对象，例如 不要研究600519和300750的区别，继续分析600519 仍正常分析600519，工具范围只有600519。独立分句中的肯定请求不被整条消息的条件／否定屏蔽。

问股个股回测工具的汇总、明细、总数与分页共同使用 guard 已验证的市场身份；合法前缀／后缀与现有 CN 写入器的数字存储键均可读取，不重新按裸码索引选择其他市场。数字键仅由已验证 SH／SZ／BJ 对象按原写入规范生成；明细须关联同对象分析来源，来源中的明确其他市场不被认领。数字汇总须有同一回测窗口／引擎的同对象明细依据，存在冲突数字来源时不认领该汇总；缺失可证明归属的数据正常返回无数据。没有市场字段的正常旧 CN 分析沿用原裸码存储约定，不一律排除数字键。未提供严格目标的原 service／repository 入口保持 legacy 行为，不迁移或改写历史数据。此内部目标参数仅用于现有工具的汇总／明细读取，不支持日期／phase 动态聚合；显式请求不支持的组合会报错，不丢弃身份约束。

普通追问中的顺带提及不扩展工具范围。严格 Chat 的现有标的工具共用身份、scope 与适用性检查，使用本次工具调用验证好的目标读取缓存及选择数据源；日线、技术分析和实时行情保留股票／指数区分，缓存缺失不改查同码股票。执行前必要身份失效只拒绝受影响对象，其他仍可确认的 scope 成员不连带禁用；验证后同一次调用不再读取注册表重新分类。筹码、公司资料、资金流和个股回测不支持指数，明确返回不支持；原市场与 ETF 条件保留。严格自定义工具未声明适用类型时只拒绝该调用。新闻对象由已确认身份／名称决定，不采用模型猜测的另一股票名称。

同名会话的当前 Bot 与 Web 可以继续交替提问：Web 已确认对象后，Bot 普通追问使用该对象的严格工具范围，合法比较只为本轮增加比较对象；两者都保留 Web 主对象及其确认来源／时间，不递增股票状态版本。Bot 不独立持久化新主对象；明确切股或无法安全维持旧对象时，Web 状态进入待重新确认，不能继续声称旧对象可靠。真正旧代码／回滚期间的未知用户写入仍要求重新确认，不能当作当前状态感知 Bot。当前 Bot 提交校验准备快照的实例、版本和最新用户消息锚点；期间已有新接受则拒绝旧提交，不追加旧问题或自动重试模型。回复、provider trace 和摘要仍绑定该次读取的会话实例与真实消息来源，删除后重建不会接收旧实例的迟到写入。Web 的迟到初始列表可以更新列表展示，不能清空新请求／新接受实例或取消其 stream；正常的无会话恢复、切换和新建仍使用既有逻辑。

这不改变模型路由、Phase 2 或 Codex 工具权限。Gate 0B 的受影响真实 Codex 路径仍为 BLOCKED；受控执行端的状态验证不能证明真实运行层或所有平台升级通过。

Codex 本地 Agent（Phase 6 实验原型）

AGENT_BACKEND 只决定现有问股 Chat 的运行方式，不影响普通报告、定时分析、大盘复盘、普通 Agent 分析 pipeline、LiteLLM Multi Agent 或 Deep Research：

# auto（推荐）不会自动启用实验性的 Codex；auto 与 litellm 均保持原有默认模型路径。
AGENT_BACKEND=auto
# 显式启用时：
# AGENT_BACKEND=codex_app_server
# AGENT_ARCH=single

Web 启用步骤：打开「设置 → Agent 设置 → 问股生成方式」，选择「Codex 本地 Agent（实验）」，确认架构为「单 Agent」，并将 Agent 整体时限设置为大于 0 后保存。设置页只检查当前配置、本机 Codex 命令和所需 App Server 协议是否允许尝试，不登录、不调用模型，也不读取股票数据。保存后可直接回到问股页提问；第一次问题就是第一次真实执行。要恢复原有行为，选择「自动（推荐）」并保存。

Local CLI 本地 backend 隐私与边界

方式一：极简单模型配置（适合新手）

目标： 只要记得填入 API Key 和对应的模型名就能立刻用。不需要折腾复杂概念。

如果你只打算用一种模型，这是最快捷的办法。打开项目根目录下的 .env 文件（如果没有，复制一份 .env.example 并重命名为 .env）。

Modelflare 使用标准 Channels 配置，见下方 Modelflare 示例。本节保留单模型 legacy 配置，现有配置无需迁移。

示例 1：使用通用第三方平台（兼容 OpenAI 格式，推荐）

现在市面上绝大多数第三方聚合平台（例如硅基流动、AIHubmix、阿里百炼、智谱等）都兼容 OpenAI 的接口格式。只要平台提供了 API Key 和 Base URL，你都可以按照以下格式无脑配置：

# 填入平台提供给你的 API Key
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
# 填入平台的接口地址 (非常重要：结尾通常必须带有 /v1)
OPENAI_BASE_URL=https://api.siliconflow.cn/v1
# 填入该平台上具体的模型名称（非常重要：注意前面必须加上 openai/ 前缀帮系统识别）
LITELLM_MODEL=openai/deepseek-ai/DeepSeek-V3

示例 2：使用 DeepSeek 官方接口

# 填入你在 DeepSeek 官方平台申请的 API Key
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx

*兼容提示：仅填这一行时，系统仍会默认使用 deepseek/deepseek-chat 并在日志提示迁移。* deepseek-chat / deepseek-reasoner 仍可用于兼容旧配置，但 DeepSeek 官方已标记为 2026/07/24 后废弃；新配置建议通过 Web 快速渠道或显式 LITELLM_MODEL=deepseek/deepseek-v4-flash 迁移到 deepseek-v4-flash / deepseek-v4-pro。

示例 3：使用 Gemini 免费 API

# 填入你获取的 Google Gemini Key
GEMINI_API_KEY=AIzac...

示例 4：使用 Ollama 本地模型

# Ollama 无需 API Key，本地运行 ollama serve 后即可使用
OLLAMA_API_BASE=http://localhost:11434
LITELLM_MODEL=ollama/qwen3:8b
重要：Ollama 必须使用 OLLAMA_API_BASE 配置，不要使用 OPENAI_BASE_URL，否则系统会错误拼接 URL（如 404、api/generate/api/show）。远程 Ollama 时，将 OLLAMA_API_BASE 设为实际地址（如 http://192.168.1.100:11434）。当前依赖约束为 litellm>=1.80.10,!=1.82.7,!=1.82.8,<1.99.0（与 requirements.txt 一致）。

Anspire Open legacy 兼容示例

现有 Anspire 搜索与 LLM 共用 Key 的兼容路径继续保留。以下为配置示例，模型与网关可用性以账号权限和 Anspire 控制台为准；可在 Web 设置页点击“测试连接”确认。

# Anspire Open API Keys（支持多个，逗号分隔）
# 获取: https://open.anspire.cn/dsa?share_code=QFBC0FYC
# 满足默认优先级条件时，系统会复用该 Key 处理搜索与 LLM（仅限示例兜底路径）。
# 示例模型：Doubao-Seed-2.0-lite；示例网关：https://open-gateway.anspire.cn/v6
ANSPIRE_API_KEYS=sk-xxxxxxxxxxxxxxxx
# 可选：按控制台可用性切换模型或网关
# ANSPIRE_LLM_MODEL=Doubao-Seed-2.0-pro
# ANSPIRE_LLM_BASE_URL=https://open-gateway.anspire.ai/v6
恭喜！小白读到这里就可以去运行程序了！ 想测测看通没通？在主目录打开命令行输入：python scripts/check_env.py --llm

方式二：渠道(Channels)模式配置（适合进阶/多模型）

目标： 我有多个不同平台的 Key 想要混着用，如果主模型卡了/网络挂了，我希望它能自动切换到备用模型。

网页端可以直接配： 你可以启动程序后，在 Web UI 的“系统设置 -> AI 模型 -> AI 模型接入” 中非常直观地进行可视化配置！

新版编辑体验补充：对于 DeepSeek、阿里百炼（DashScope）以及其他兼容 OpenAI /v1/models 的渠道，设置页现在支持直接点击“获取模型”，从 {base_url}/models 拉取可用模型并多选；底层仍会保存为原来的 LLM_{CHANNEL}_MODELS=model1,model2 逗号格式。若渠道不支持该接口、鉴权失败或暂时不可达，仍可继续手动填写模型列表，不影响保存。

首次启动配置状态

后端提供只读状态接口 GET /api/v1/system/config/setup/status，用于判断首次启动闭环中最基础的几类配置是否已经就绪：LLM 主渠道、Agent 渠道、自选股、通知渠道和本地存储。这个接口只读取已保存的 .env 与当前进程环境变量，不会重载运行时配置、写入 .env、测试真实模型或创建数据库文件；前端向导和后续 smoke run 可以基于该接口逐步接入。

Web 渠道编辑器的兼容性 / 迁移 / 回退规则

外部 provider 示例模型说明：cohere/*、google/*、xai/* 等 provider 前缀值仅用于说明当前保存清理语义，不代表该依赖约束内的逐型号可用性保证。文档或测试中的具体模型名都是配置保留行为样例，不是生产推荐；实际可用性请以对应官方模型文档为准，并结合仓库依赖约束 litellm>=1.80.10,!=1.82.7,!=1.82.8,<1.99.0 复核。

回退与兼容性证据

常用官方文档来源（用于核对预设 provider / Base URL / 模型命名）

如果不方便用网页版，在 .env 文件中配置也非常丝滑，它能让你同时管理多个第三方平台。规则如下：

  1. 先声明你有几个渠道：LLM_CHANNELS=渠道名称1,渠道名称2
  2. 给每个渠道分别填写配置（注意全大写）：LLM_{渠道名}_XXX

示例：Modelflare

注册 Modelflare，在控制台创建 API Key 后配置：

MODELFLARE_KEY=sk-xxx

只需填写 MODELFLARE_KEY，后端自动启用 Modelflare，默认地址为 https://modelflare.dev/v1、模型为 openai/gpt-6.1-sol，无需填写渠道名、地址或模型。显式 YAML 或 LLM_CHANNELS 优先，Modelflare 显式渠道 Key 优先于此简写；清空 Key 或禁用渠道即可停用。推导不改写已保存配置。

只声明 modelflare 一个渠道且未填渠道模型列表时，未配置主模型时默认使用 openai/gpt-6.1-sol；配置主模型后，后端复用 LITELLM_MODEL 和带 openai/ 前缀的备用模型；主模型使用 openai/<模型名>。显式 LLM_MODELFLARE_MODELS 优先，多渠道仍需分别声明模型。推导不改写已保存配置或模型选择。

渠道名为 modelflare 时，未填写或留空的接入地址自动使用 https://modelflare.dev/v1；显式 LLM_MODELFLARE_BASE_URL 优先。该地址默认识别为 openai 协议，接口默认为 chat_completions；未设置 LITELLM_MODEL 时使用首个渠道模型。默认模型仍需账号有访问权限，不自动补充 API Key。

gpt-6.1-sol 是本项目的 Modelflare 默认模型。请按账号权限选择实际可用模型，并通过 Web「获取模型」和「测试连接」确认；Base URL 不要附加 /chat/completions。Modelflare 是新建渠道的首选模板，已保存的渠道和主模型不会因模板顺序调整而改变。Anspire Search 仍通过 ANSPIRE_API_KEYS 独立配置。

客户端快速添加按钮及渠道说明中的「Modelflare 专属注册」都使用 app UTM，README 使用 github UTM。新建渠道尚未填写 Key，或主模型/备用模型不属于当前启用渠道时，状态预览会提示「配置需要调整」并列出具体字段；补填 Key、选择可用模型或清空无效的备用模型后重试，预览不会自动改写已保存配置。

兼容示例：Anspire Responses API（GPT-5.6 名称为观测样本）

LLM_CHANNELS=anspire
LLM_ANSPIRE_PROTOCOL=openai
LLM_ANSPIRE_API_SURFACE=responses
LLM_ANSPIRE_BASE_URL=https://open-gateway.anspire.cn/v6
LLM_ANSPIRE_API_KEY=sk-xxx
LLM_ANSPIRE_MODELS=gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna
LITELLM_MODEL=openai/gpt-5.6-sol
LITELLM_FALLBACK_MODELS=openai/gpt-5.6-terra,openai/gpt-5.6-luna

Anspire 官方接入页公开了 https://open-gateway.anspire.cn/v6/responses 调用方式：<https://open.anspire.cn/model?link=sample&tab=models>。Responses 路由不按模型名写死；上面的 GPT-5.6 名称只是当前网关观测样本，不作为长期模型清单承诺。模型、Surface 与账号权限请以渠道实时 /models 返回、服务商说明和连接测试为准。

示例：同时配置 DeepSeek 和某中转平台，并设置备用切换

# 1. 开启渠道模式，声明这里有两个渠道：deepseek 和 aihubmix
LLM_CHANNELS=deepseek,aihubmix

# 2. 渠道一：配置 DeepSeek 官方
LLM_DEEPSEEK_BASE_URL=https://api.deepseek.com
LLM_DEEPSEEK_API_KEY=sk-1111111111111
LLM_DEEPSEEK_MODELS=deepseek-v4-flash,deepseek-v4-pro

# 3. 渠道二：配置一个常用的聚合中转 API
LLM_AIHUBMIX_BASE_URL=https://api.aihubmix.com/v1
LLM_AIHUBMIX_API_KEY=sk-2222222222222
LLM_AIHUBMIX_MODELS=gpt-5.5,claude-sonnet-4-6

# 4. 【关键】指定主模型和备用模型列表
# 平时首选用 deepseek 这款模型：
LITELLM_MODEL=deepseek/deepseek-v4-flash
# 可选：Agent 问股单独指定主模型（留空则继承主模型）
AGENT_LITELLM_MODEL=deepseek/deepseek-v4-pro
# 主模型崩了立刻挨个尝试下面这俩备用模型：
LITELLM_FALLBACK_MODELS=openai/gpt-5.4-mini,anthropic/claude-sonnet-4-6

示例：Ollama 渠道模式（本地模型，无需 API Key）

# 1. 开启渠道模式，声明 ollama 渠道
LLM_CHANNELS=ollama

# 2. 配置 Ollama 地址（本地默认 11434 端口）
LLM_OLLAMA_BASE_URL=http://localhost:11434
LLM_OLLAMA_MODELS=qwen3:8b,llama3.2

# 3. 指定主模型
LITELLM_MODEL=ollama/qwen3:8b

示例：Hermes 本地 HTTP Generation（Phase 3）

LLM_CHANNELS=hermes
LLM_HERMES_PROTOCOL=openai
LLM_HERMES_BASE_URL=http://127.0.0.1:8642/v1
LLM_HERMES_API_KEY=sk-local-hermes
LLM_HERMES_MODELS=hermes-agent
LITELLM_MODEL=openai/hermes-agent

Hermes 是保留渠道名，只支持本机 loopback /v1 OpenAI-compatible generation。Phase 3 只验证普通分析与 JSON 输出；不支持 Stream/SSE、Tools、Vision、Agent tools、远程 Hermes 或进程生命周期管理。Hermes API Key 只能使用单个 LLM_HERMES_API_KEY，不要配置 LLM_HERMES_API_KEYS 或 LLM_HERMES_EXTRA_HEADERS。如果 Hermes 配置非法，系统会阻止 legacy provider silent fallback，避免错误地改用外部模型。Web 设置页保存 reserved Hermes 渠道时，会显式清空旧的 LLM_HERMES_API_KEYS / LLM_HERMES_EXTRA_HEADERS 并返回 warning；如需恢复旧值，请从 .env 备份、Git 历史或桌面端导出备份手动还原，但 Phase 3 仍会拒绝非空的多 Key / Extra Headers 配置。

MiniMax 渠道模型填写说明

默认模型问股 / LiteLLM 配置兼容说明

问股可见对话上下文压缩

默认情况下，问股仍按历史行为只注入最近 20 条可见对话。以下 LLM 压缩只适用于「默认模型」问股：Codex Agent 始终使用最近 20 条用户可见对话，不会调用 AGENT_LITELLM_MODEL 生成历史摘要。切换到 Codex 不会清空已保存的压缩配置，切回「默认模型」后会继续生效。需要为默认模型长会话省 token 时，可开启：

AGENT_CONTEXT_COMPRESSION_ENABLED=true
AGENT_CONTEXT_COMPRESSION_PROFILE=balanced
# 留空则跟随 profile preset
AGENT_CONTEXT_COMPRESSION_TRIGGER_TOKENS=
AGENT_CONTEXT_PROTECTED_TURNS=

压缩只处理 session_id 下用户可见的 user / assistant 文本历史，不处理 provider trace、thinking blocks、tool calls 或 tool results，也不会改变同轮工具调用透传。三档 preset 分别是 cost（6000 tokens / 保护 2 轮）、balanced（12000 / 4）和 long_context_raw_first（24000 / 6）；trigger / protected 留空时跟随当前 profile，显式填写时覆盖 profile。

问股 single-agent 路径会额外维护一条 provider-aware trace 分轨，用于 DeepSeek V4 thinking + tool-call 的跨轮协议回放：只有同一轮同时出现 tool_calls 与 reasoning_content 时才会按当前 session_id + provider + model 保存最近 3 条最小协议材料，并在下一轮按原始时序插回对应可见 assistant 回复之前。该 trace 只能原样保留或整段丢弃，不参与摘要、不写入 Web 会话消息、不新增 .env 配置；model/provider 不匹配、锚点已被 summary 覆盖或预算不足时会整段跳过。Claude extended thinking 本轮只覆盖 adapter/storage 级 opaque thinking / redacted_thinking / signature blocks plumbing 与离线 fixture，不声明生产端到端支持；multi-agent trace 注入仍是 follow-up。外部协议依据包括 DeepSeek thinking mode 文档（<https://api-docs.deepseek.com/guides/thinking_mode>）和 Anthropic Claude extended thinking 文档（<https://platform.claude.com/docs/en/docs/build-with-claude/extended-thinking>），LiteLLM 兼容窗口仍以 requirements.txt 的 litellm>=1.80.10,!=1.82.7,!=1.82.8,<1.99.0 为准。

严格 temperature 模型兼容说明

兼容依据与回退审计说明（本次 PR 适配说明）

LLM usage HMAC 遥测

P0a usage telemetry 会为实际发送的 message 生成 HMAC-SHA256 指纹，用于后续判断相同 prompt/message 前缀是否稳定。该能力只写入本地 llm_usage 记录，不改变 prompt、provider 参数、cache hint、模型输出或 fallback 顺序。

Usage 来源按三层读取：

Cache token 归一化只做 allowlisted best-effort normalization。外部字段依据和运行时边界如下，避免把官方稳定契约、LiteLLM 当前归一化行为和本仓库兼容 allowlist 混为一谈：

Provider / 来源读取字段依据与边界覆盖情况
OpenAIusage.prompt_tokens_details.cached_tokens官方 Prompt Caching 文档说明 1024 tokens 以下也会返回 cached_tokens=0：unit/mock 覆盖；本 PR 未做 OpenAI live smoke
Anthropiccache_creation_input_tokens / cache_read_input_tokens / input_tokens官方 Prompt Caching 文档定义 total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens：unit/mock 覆盖；本 PR 未做 Anthropic live smoke
Gemini / Vertex AI官方字段为 UsageMetadata.cachedContentTokenCount；运行时消费 LiteLLM 暴露的 snake_case / normalized 字段，如 cached_content_token_count、cache_read_input_tokens 或 prompt_tokens_details.cached_tokensGemini UsageMetadata 官方字段见 ；本仓库不新增 native camelCase runtime fallback，运行时边界以 litellm>=1.80.10,!=1.82.7,!=1.82.8,<1.99.0 为准unit/mock 覆盖；本 PR 未做 Gemini / Vertex live smoke
DeepSeekprompt_cache_hit_tokens / prompt_cache_miss_tokensDeepSeek Chat Completion 文档说明 prompt_tokens = prompt_cache_hit_tokens + prompt_cache_miss_tokens：unit/mock 覆盖；本 PR 只做一次脱敏 DeepSeek smoke，不保存完整响应
GLM / OpenAI-compatible / StepFun 等兼容平台已建模 token/cache count allowlist 中能映射到统一字段的值不声明官方稳定 cache telemetry contract；仅表示在当前 LiteLLM / OpenAI-compatible shape 下做 best-effort normalization，未建模 metadata 不持久化unit/fixture/mock 覆盖；本 PR 未做这些 provider 的 live smoke
LiteLLM public response shapeusage / usage_metadata按当前依赖窗口 litellm>=1.80.10,!=1.82.7,!=1.82.8,<1.99.0 的 response / Usage object shape 消费；不作为 LiteLLM 2.x 兼容承诺Analyzer / Agent / usage tests 覆盖
LiteLLM private fallback_hidden_params["usage"]private/internal best-effort fallback，不是 LiteLLM 稳定公共契约；仅在 public usage zero-only/no-signal 等窄场景补足 streaming usage，不改变 provider 请求参数unit/mock 覆盖；缺失时只影响 telemetry 完整性，不代表模型请求失败
 
LLM_USAGE_HMAC_SECRET=
LLM_USAGE_HMAC_KEY_VERSION=local-v1

Provider prompt cache 配置（/ .5）

Prompt cache 配置只控制本项目是否记录 cache usage / diagnostics，以及主分析路径是否主动发送已验证的 provider-specific hint；它不控制 OpenAI、Gemini、DeepSeek 等 provider 的 implicit / provider-managed cache。

LLM_PROMPT_CACHE_TELEMETRY_ENABLED=true
LLM_PROMPT_CACHE_HINTS_ENABLED=false
LLM_PROMPT_CACHE_DIAGNOSTICS_LEVEL=off

Legacy message stability audit（.5a）

.5a 在普通个股分析路径为 legacy [system, user] message 追加内部稳定性审计字段，继续写入本地 llm_usage。它复用上面的 message HMAC，不修改 prompt 内容、message 顺序、provider 请求参数、cache hint、模型输出、fallback 顺序，也不扩展公开 Usage API 或 Web 页面。

新增字段只用于维护者诊断：

.5a 不引入 PromptBlock IR、block_id、stability_class、static_prefix_hash 或 dynamic_context_hash。Agent、research 与 market review 路径暂不接入该审计。

方式三：YAML 高级配置（适合老手自定义）

目标： 我不在乎学习门槛，我要最高控制权，我要用原生规则做企业级高可用！

这一层会直接映射到底层 LiteLLM 路由能力，支持高并发、自动重试、按 RPM/TPM 负载均衡等操作。

本地运行 / Docker 部署模式配置说明

  1. 在 .env 中只保留一行指向声明：
   LITELLM_CONFIG=./litellm_config.yaml
  1. 在项目根目录创建一个 litellm_config.yaml（可以参考自带的 docs/examples/litellm_config.example.yaml）。

示例 litellm_config.yaml：

model_list:
  - model_name: my-smart-model
    litellm_params:
      model: deepseek/deepseek-v4-flash
      api_base: https://api.deepseek.com
      api_key: "os.environ/MY_CUSTOM_SECRET_KEY"  # 从环境变量读取 Key，安全防泄漏

  # Ollama 本地模型（无需 api_key）
  - model_name: ollama/qwen3:8b
    litellm_params:
      model: ollama/qwen3:8b
      api_base: http://localhost:11434

GitHub Actions配置说明

  1. Settings → Secrets and variables → Actions。非敏感配置（如模型名、开关、Base URL）可以放在 Secret 或 Variables；凡是 _API_KEY / _API_KEYS 以及 LLM__API_KEY / LLM__API_KEYS 这类密钥字段，请统一放在 Secret 标签页的 New repository secret
  1. 按下表配置，只有全部必填配置正确配置，YAML 高级配置模式才可以生效，YAML配置文件的写法，可以参考自带的 docs/examples/litellm_config.example.yaml
Secret 名称说明必填
LITELLM_CONFIG高级模型路由配置文件路径，通常配置 ./litellm_config.yaml必填
LITELLM_MODEL默认主模型名称或路由别名必填
LITELLM_CONFIG_YAML存放 YAML 配置文件内容，可不在仓库中提交实体文件可选
LITELLM_API_KEY用于存储API Key，可在配置文件中引用（环境变量引用方式）。由于GitHub Actions必须要指定导入的环境变量，因此你不能像本地运行模式那样自由命名环境变量可选，必须配置到repository secret中
ANTHROPIC_API_KEY如果要多个API Key，这个变量名称也能拿来用可选，必须配置到repository secret中
OPENAI_API_KEY同上，可以用来存储API Key可选，必须配置到repository secret中

渠道模式无需上传 YAML 文件。仓库自带 00-daily-analysis.yml 已显式透传以下常用字段：

例如在 GitHub Actions 中配置 LLM_CHANNELS=primary,deepseek 时，需同步配置 LLM_PRIMARY_* / LLM_DEEPSEEK_*。其中 LLM_<NAME>_API_KEY / LLM_<NAME>_API_KEYS 当前也仅从 repository secrets 导入；如果你把这些值放在 Variables，运行时不会生效。若使用自定义渠道名（如 my_proxy），GitHub Actions 还必须在 workflow env: 中显式新增对应的 LLM_MY_PROXY_* 映射；本地 .env 和 Docker 不受这个限制。

三层配置互斥准则：YAML 优先级最高！只要配置了 YAML，渠道模式 和 新手极简模式 统统被忽略。系统优先级为：YAML配置 > 渠道模式 > 极简单模型。

扩展功能：看图模型 (Vision) 配置

系统中有些特定功能（比如上传股票软件截图，让 AI 提取出截图里的股票代码并放入自选股池）必须用到具备“视觉能力”的模型。你需在 .env 单独给它指派一个懂图片的模型。

# 指定你看图专用的模型名
VISION_MODEL=openai/gpt-5.5
# 别忘了填写它对应提供商的 API KEY，如果是 OpenAI 兼容渠道就提供 OPENAI_API_KEY：
# OPENAI_API_KEY=xxx

备用看图机制： 为了防止偶尔罢工，系统内置了切换策略。如果主视觉模型调用失败，它会按照下方的顺位尝试寻找是否有其他看图模型的 Key：

# 默认的备用顺序：
VISION_PROVIDER_PRIORITY=gemini,anthropic,openai

检测与排错 (Troubleshooting)

配好了之后心惊胆战不知道对不对？在命令行（Terminal）里敲入下面代码帮你挂号问诊：

常见踩坑答疑台

遇到了什么诡异报错？罪魁祸首可能是啥？该怎么收拾它？
界面提示主模型未配置系统不知道你到底想用哪家的哪个模型在 .env 中写上一句明白话：LITELLM_MODEL=provider/你的模型名。比如 openai/gpt-5.5
我写了好几家的Key，为什么死活只有一个生效？修改还没用？你把 极简模式 和 渠道模式 混着写了！想好一条路走到黑——只要简单就删掉 LLM_CHANNELS 开头的；想要丰富备用切换就要全部转投到 LLM_CHANNELS 下的编制里。
错误码报 400 或 401 或 Invalid API KeyAPI Key 填错、少复制了一截、账号充值没到账、或者模型名字敲错（极度常见）。1. 检查复制的 Key 前后是否有误填空格。 2. 检查 Base URL 最后是不是少了一个 /v1。 3. 检查模型名是否少写了 openai/ 之类的前缀！
Kimi K2.6 报 invalid temperature（可能提示只允许 1.0 或 0.6）该模型按 thinking / non-thinking 模式要求不同固定 temperature；旧配置或调用入口可能还在传 0.7。升级后系统会对 kimi-k2.6 默认 / thinking 请求自动使用 temperature=1.0；如果你在 LiteLLM YAML 路由里显式关闭 thinking，则自动改用 0.6。模型名建议写成 openai/kimi-k2.6 并配合 Moonshot / 聚合平台的 OpenAI 兼容 Base URL 与 API Key。非 Kimi fallback 仍会继续使用你配置的 LLM_TEMPERATURE。
GPT-5 / o 系列报 temperature 不支持或只允许默认值这类模型只接受服务端默认采样参数，但旧调用入口会显式传 0.7。升级后请求层会省略 temperature，让服务端使用默认值；.env / Web 设置中的 LLM_TEMPERATURE 不会被改写，切回普通模型后仍按原值发送。
转圈转不停，最后报 Timeout / ConnectionRefused 等1. 在国内使用国外原版（像 Google、OpenAI），没开代理被墙了。2. 你买的云服务器压根不能出境。非常推荐使用国内官方（如DeepSeek、阿里）或者各种兼容 OpenAI 的聚合中转接口。因为中转站把网络问题帮你解决好了。
Ollama 报 404、Could not get model info 或 api/generate/api/show误用 OPENAI_BASE_URL 配置 Ollama，系统会错误拼接 URL改用 OLLAMA_API_BASE=http://localhost:11434 或渠道模式（LLM_CHANNELS=ollama + LLM_OLLAMA_BASE_URL）

*进阶老手的叮嘱：如果你开启了 Agent (深度思考网络搜索问股) 模式，这里有个经验之谈，推荐选用如 deepseek-v4-pro 这种逻辑推导能力更强的大模型。如果为了省钱用小微模型跑 Agent，它逻辑能力大概率跟不上，不仅达不到预期，还会白跑一堆空流程。*