fix: 修正 LLM Model disabled 诊断 (#1208)

[massif-01]

PR Type

• fix
• feat
• refactor
• docs
• chore
• test

Background And Problem

桌面端 3.15 的 AI 模型配置中，LLM 渠道测试遇到服务商返回 Model disabled 时，会被归类为网络异常，导致用户排障方向转向 Base URL、代理或 TLS，而不是检查模型是否可用。

该问题还暴露了另一个诊断缺口：基础连接测试实际只测试模型列表首项，但失败提示没有说明本次测试的 resolved model，用户无法判断失败是否由首项模型不可用触发。

Scope Of Change

• 后端 src/services/system_config_service.py
  • 补充模型不可用/未授权/禁用类错误信号识别。
  • 将 Model disabled 等错误归入既有 model_not_found，并通过 details.reason=model_access_denied 表达具体原因。
• Web 设置页 apps/dsa-web/src/components/settings/LLMChannelEditor.tsx
  • 将 model_not_found 展示为“模型不可用”。
  • 失败 hint 展示本次测试模型和测试范围。
  • 仅在模型相关错误时提示调整模型顺序或移除不可用模型，避免误导 auth/network/quota 场景。
• 测试
  • 补充后端 LLM 渠道测试分类用例。
  • 补充前端失败提示、首项模型提示、非模型错误不显示模型调整建议的回归测试。
• 文档
  • 更新 docs/CHANGELOG.md、docs/llm-providers.md、docs/LLM_CONFIG_GUIDE.md、docs/LLM_CONFIG_GUIDE_EN.md。

Issue Link

Fixes #1208

Evidence And Compatibility Basis

• 官方来源：SiliconFlow 官方错误处理文档要求接口错误排查时记录 HTTP 错误码和 message，说明 403 表示余额不足或权限不够，其他情况参考报错 message，并建议换一个模型确认问题是否仍存在。
  • 中文：https://docs.siliconflow.cn/cn/faqs/error-code
  • 英文：https://docs.siliconflow.cn/en/faqs/error-code
• Issue 来源：Issue [Bug] AI 模型配置中 Model disabled 被误报为网络异常且测试模型不明确 #1208 的用户报告和错误日志。触发场景是桌面端 3.15 的 SiliconFlow / OpenAI Compatible 渠道测试，Base URL 为 https://api.siliconflow.cn/v1，原始错误片段为：

LLM channel test failed
litellm.APIError: APIError: OpenAIException - Model disabled.

• 线上 provider 复核记录（2026-05-06T16:21:21Z）：
  • 环境：Python 3.13.12，LiteLLM 1.82.3，项目约束 litellm>=1.80.10,!=1.82.7,!=1.82.8,<2.0.0。
  • Base URL：https://api.siliconflow.cn/v1。
  • 模型：Qwen/Qwen3-235B-A22B-Thinking-2507；LiteLLM 路由模型：openai/Qwen/Qwen3-235B-A22B-Thinking-2507。
  • 直连 SiliconFlow Chat Completions：HTTP 403，脱敏响应体 {"code":30003,"message":"Model disabled.","data":null}。
  • 同一模型走 LiteLLM completion()：抛出 APIError，脱敏 message 为 litellm.APIError: APIError: OpenAIException - Model disabled.。
• 语义边界：目前没有 SiliconFlow / OpenAI-compatible / LiteLLM 对 Model disabled 的官方错误码文档来源；该映射不声称是跨 provider 的官方语义。它是基于 Issue [Bug] AI 模型配置中 Model disabled 被误报为网络异常且测试模型不明确 #1208 已观测 provider 文案的 best-effort 归类：该返回明确包含 Model disabled，且发生在已指定测试模型的 litellm.completion() 路径中，因此比 Base URL、代理、TLS 或本地网络策略更适合引导用户先排查当前测试模型的账号可用性。
• 兼容范围：项目当前依赖约束为 litellm>=1.80.10,!=1.82.7,!=1.82.8,<2.0.0（见 requirements.txt），本地验证环境中 pip show litellm 为 1.82.3。
• 保守匹配策略：实现不会单独因为 disabled 归类为模型问题；错误文本必须同时包含 model 和明确的权限/禁用/不可用信号，才会返回既有 error_code=model_not_found 与 details.reason=model_access_denied。未覆盖或语义不同的 provider 文案会继续走既有兜底诊断。
• API 兼容性：不新增顶层错误码，不改变响应 schema；只是把已观测到的真实 provider 返回样例映射到既有模型不可用诊断路径。

Verification Commands And Results

python -m pip install -r requirements.txt
PATH=/opt/homebrew/Caskroom/miniconda/base/bin:$PATH ./scripts/ci_gate.sh
python -m pytest tests/test_system_config_service.py -q
python -m py_compile src/services/system_config_service.py

cd apps/dsa-web
npm ci
npm run test -- LLMChannelEditor.test.tsx
npm run lint
npm run build

关键输出/结论：

• PATH=/opt/homebrew/Caskroom/miniconda/base/bin:$PATH ./scripts/ci_gate.sh：通过，1721 passed, 2 deselected, 141 subtests passed。
• python -m pytest tests/test_system_config_service.py -q：通过，96 passed。
• python -m py_compile src/services/system_config_service.py：通过。
• npm ci：通过。
• npm run test -- LLMChannelEditor.test.tsx：通过，36 passed。
• npm run lint：通过。
• npm run build：通过，Vite 仅输出既有 chunk size warning。

Compatibility And Risk

• 不新增 API 字段，不修改请求/响应 schema。
• 顶层 error_code 继续使用既有 model_not_found，避免扩展前端/客户端需要识别的新枚举；具体原因通过既有 details.reason=model_access_denied 表达。
• 不改变“获取模型”的追加行为，不改模型列表保存格式，不自动改写或清理用户配置。
• 不改变基础连接测试只发起一次 LLM 请求的行为，只让本次测试模型和测试范围在 UI 中可见。
• 风险：错误文本匹配可能覆盖不到所有服务商变体，或其它 provider 复用类似文案但语义不同。当前实现要求文本同时包含 model 和明确权限/禁用/不可用信号，以降低误判；未命中的变体、以及语义不同但未命中保守规则的 provider 文案，仍会走既有兜底诊断。

Rollback Plan

• 最小回滚方式：revert this PR。
• 无配置迁移、无数据写入语义变化，回滚后不需要额外的数据或配置回滚。

EXTRACT_PROMPT Change (if applicable)

未修改 src/services/image_stock_extractor.py 中的 EXTRACT_PROMPT。

展开 / Expand: Full EXTRACT_PROMPT

N/A

Checklist

• 本 PR 有明确动机和业务价值 / This PR has a clear motivation and value
• 已提供可复现的验证命令与结果 / Reproducible verification commands and results are included
• 已评估兼容性与风险 / Compatibility and risk have been assessed
• 已提供回滚方案 / A rollback plan is provided
• 若涉及用户可见变更，已同步更新相关文档与 docs/CHANGELOG.md；README.md 仅在首页级信息变化时更新，细节优先写入 docs/*.md / If user-visible changes are included, relevant docs and docs/CHANGELOG.md are updated; README.md is updated only for homepage-level changes, with details kept in docs/*.md

[github-actions]

🤖 自动审查报告

项目	结果
📊 变更文件	8 个
➕ 新增行数	151 行
➖ 删除行数	9 行
🔍 静态检查	✅ 通过
🧠 AI 审查	✅ 已完成

📁 修改的文件

• 📝 apps/dsa-web/src/components/settings/LLMChannelEditor.tsx (+30/-4)
• 📝 apps/dsa-web/src/components/settings/__tests__/LLMChannelEditor.test.tsx (+77/-0)
• 📝 docs/CHANGELOG.md (+1/-0)
• 📝 docs/LLM_CONFIG_GUIDE.md (+1/-1)
• 📝 docs/LLM_CONFIG_GUIDE_EN.md (+1/-1)
• 📝 docs/llm-providers.md (+9/-1)
• 📝 src/services/system_config_service.py (+26/-2)
• 📝 tests/test_system_config_service.py (+6/-0)

---

🧠 AI 代码审查意见

结论

Ready to Merge

结构化审查结果

• 必要性：通过。PR 描述详细阐述了桌面端 AI 模型配置中 LLM 渠道测试将 Model disabled 误分类为网络异常的问题，导致用户排障方向错误。同时指出了基础连接测试提示缺乏对实际测试模型的说明。问题明确，具有较高的业务价值。
• 关联性：通过。PR 明确关联到 Fixes #1208，并且描述中引用了 Issue [Bug] AI 模型配置中 Model disabled 被误报为网络异常且测试模型不明确 #1208 的用户报告和错误日志作为可核验来源。
• 类型判定：PR 描述中标记为 fix, docs, test。实际改动内容（修复诊断逻辑、更新文档、添加测试）与此完全匹配。建议类型：fix, docs, test。
• 描述完整性：完整。PR 描述包含了背景、变更范围、验证命令与结果、兼容性风险、回滚方案等所有必需信息。特别值得注意的是，PR 描述明确说明了 ci_gate.sh 已执行并通过，这弥补了该脚本未集成到自动化 CI 中的不足。
• 风险级别：低。
  • 关键风险：PR 描述中提到了“错误文本匹配可能覆盖不到所有服务商变体，或其它 provider 复用类似文案但语义不同”。但实现中采用了保守匹配策略（要求错误文本同时包含 model 和明确的权限/禁用/不可用信号），大大降低了误判风险。此变更不新增 API 字段，不改变响应 schema，仅使用现有 error_code (model_not_found) 和 details.reason (model_access_denied) 来表达具体原因，进一步降低了兼容性风险。前端测试也充分覆盖了正常、模型问题、网络问题等多种场景，确保提示的正确性，避免误导用户。
• 必改项：无。
• 建议项：无。

---

审查细节

1. 代码（前端）：
   • apps/dsa-web/src/components/settings/LLMChannelEditor.tsx 中的改动符合 PR 描述。增加了对基础连接测试首项模型的提示，将 model_not_found 的展示文本改为“模型不可用”，并对 model_access_denied 提供了更具体、更具指导性的提示。
   • buildLlmTestHint 函数的引入和逻辑 shouldSuggestModelListChange 确保了“调整模型顺序或移除不可用模型”的建议仅在模型相关错误时显示，避免了在鉴权或网络问题时误导用户。
2. 代码（后端）：
   • src/services/system_config_service.py 的具体 diff 未在 PR 描述中完全展示（被截断）。但 PR 描述中详细说明了后端逻辑：“补充模型不可用/未授权/禁用类错误信号识别”，“将 Model disabled 等错误归入既有 model_not_found，并通过 details.reason=model_access_denied 表达具体原因”，以及“保守匹配策略”。考虑到 PR 描述中提供的后端测试命令 (pytest tests/test_system_config_service.py) 已通过，且在 CI 状态中所有 Python 静态检查均通过，可以合理推断后端实现符合其描述。
3. 文档：
   • docs/CHANGELOG.md 已同步更新，记录了本次修复。
   • docs/LLM_CONFIG_GUIDE.md 和 docs/LLM_CONFIG_GUIDE_EN.md 对“测试连接”的描述进行了更新，明确了只测试模型列表首项，并增加了对 details.reason=model_access_denied 的解释和排障指导，与代码变更和问题背景完全对应。
   • docs/llm-providers.md 更新了 model_access_denied 的解释和建议，并额外增加了对其作为 best-effort 分类依据的详细说明，提供了良好的背景信息和透明度。
4. 测试：
   • apps/dsa-web/src/components/settings/__tests__/LLMChannelEditor.test.tsx 中新增的测试用例充分覆盖了模型禁用场景下的提示显示（包括实际测试模型、模型调整建议、以及非模型错误不显示模型调整建议等），验证了前端逻辑的正确性。
   • 后端测试 (tests/test_system_config_service.py) 描述为“补充后端 LLM 渠道测试分类用例”，且 PR 描述中已给出测试通过结果。
5. CI 检查状态：所有自动化静态检查（py_compile, flake8 严重错误）均已通过。PR 描述中也明确指出了 ./scripts/ci_gate.sh 已在本地执行并通过。

综上，本次 PR 经过了充分的考虑、详尽的描述和全面的验证，代码质量高，文档同步到位，且风险控制良好，具备合入条件。

---

💡 提示: 请确保代码已通过本地测试，并遵循项目代码规范。

[massif-01]

已按最新 Process blocker 补齐外部 LLM/API 兼容证据，并把证据写入入库文档。

新增 commit：4f8fb5b docs: add SiliconFlow model disabled evidence (#1208)

补充内容：

• docs/llm-providers.md 现已列出 SiliconFlow 官方错误处理文档作为 provider 侧依据：
  • 中文：https://docs.siliconflow.cn/cn/faqs/error-code
  • 英文：https://docs.siliconflow.cn/en/faqs/error-code
  • 同一段文档补充线上复核记录（2026-05-06T16:21:21Z）：Python 3.13.12、LiteLLM 1.82.3、Base URL https://api.siliconflow.cn/v1、模型 Qwen/Qwen3-235B-A22B-Thinking-2507。
  • 直连 SiliconFlow Chat Completions 返回 HTTP 403，脱敏响应体：{"code":30003,"message":"Model disabled.","data":null}。
  • 同一模型通过 LiteLLM completion(model="openai/Qwen/Qwen3-235B-A22B-Thinking-2507") 返回 APIError: OpenAIException - Model disabled.。
  • PR 描述的 Evidence And Compatibility Basis 也同步加入官方来源和线上复核记录。

本次本地验证：

• git diff --check
• python -m py_compile src/services/system_config_service.py
• python -m pytest tests/test_system_config_service.py -q -> 96 passed

[ZhuLinsen]

评审结论

• 必要性：通过；修正 Model disabled 被误归类为网络异常的问题，能直接改善 LLM 渠道测试的用户排障方向。
• 是否有对应 issue：有，Fixes #1208。
• PR 类型：fix/docs/test；包含后端错误分类修复、前端提示调整、回归测试和 LLM 配置文档更新。
• description 完整性：完整；已覆盖背景、改动范围、官方/线上 provider 证据、兼容性边界、验证结果和最小回滚方案，且符合 AGENTS.md 对用户可见变更同步 docs/CHANGELOG.md 与专题文档的要求。
• 是否可直接合入：可；当前 CI 全部通过，diff 未引入配置迁移或静默清理行为，mergeable_state=blocked 仅反映受保护分支策略，不构成代码层阻断。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[ZhuLinsen]

跟进结论

• 结论：接受 + 已补齐 provider 官方排查依据、线上复核记录，并把 Model disabled 明确收敛为基于已观测文案的 best-effort 模型可用性诊断，之前“外部语义依据不足”的阻断可以关闭。
• 是否仍有阻断：无 + 当前 CI 全部通过，改动未新增 schema/顶层错误码/配置迁移，mergeable_state=blocked 在本仓库保护规则下不单独构成合入阻断。

说明

1. docs/llm-providers.md 已说明 model_access_denied 不是跨 provider 官方错误码映射，并补充 SiliconFlow 官方错误处理文档、Issue #1208 脱敏样例和 LiteLLM 在线复核记录；这已覆盖此前要求的外部/API 兼容证据缺口。
2. src/services/system_config_service.py 的方向是继续复用既有 model_not_found，用 details.reason=model_access_denied 表达细分原因，且匹配条件要求同时出现 model 和权限/禁用/不可用信号，风险已收敛。
3. tests/test_system_config_service.py、apps/dsa-web/src/components/settings/__tests__/LLMChannelEditor.test.tsx 覆盖了 Model disabled 分类、非模型错误不提示调整模型顺序、前端展示本次测试模型和首项模型范围，回归证据充分。
4. docs/LLM_CONFIG_GUIDE.md 与英文版已同步说明测试连接只测模型列表首项、resolved_model 展示和 best-effort 边界；当前 diff 没有实际静默清空或迁移用户运行时配置的代码改动。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[zenghui01]

我试了下这个分支，还是报错

[ZhuLinsen]

跟进结论

• 结论：部分接受 + “仍然报错”这个现象成立，但当前 PR 修的是诊断归类和提示，不是让服务商已禁用/未开通的模型连接成功。
• 是否仍有阻断：无 + 当前代码、测试和 CI 已覆盖 Model disabled 归入模型不可用诊断；除非实际界面仍显示为网络异常或缺少本次测试模型提示，否则不能据“仍报错”判定修复失败。

说明

1. src/services/system_config_service.py：本 PR 的行为是把包含 Model disabled 的错误归到既有 model_not_found，并通过 details.reason=model_access_denied 表达账号/模型可用性问题；该场景仍应返回失败，不会把禁用模型变成可用。
2. apps/dsa-web/src/components/settings/LLMChannelEditor.tsx：前端已把 model_not_found 展示为“模型不可用”，并提示“本次测试模型”和“基础连接测试默认只测试模型列表中的第一个模型”；如果首项模型仍是禁用模型，继续失败是预期结果。
3. tests/test_system_config_service.py 与 LLMChannelEditor.test.tsx：已补充 Model disabled 后端归类、前端模型可用性提示，以及 auth/network/quota 不误提示模型顺序调整的回归覆盖。
4. 最新回复需要进一步区分“仍失败”和“仍误诊断”：如果截图中的错误标题已经是“模型不可用”，这是 PR 预期行为；如果仍显示“网络异常”或继续引导检查 Base URL/代理/TLS，则需要补充后端响应 JSON 或浏览器控制台/API 返回内容后再重开阻断。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[ZhuLinsen]

我试了下这个分支，还是报错

@massif-01 佬帮忙看下？

[ZhuLinsen]

跟进结论

• 结论：部分接受 + “仍然报错”成立，但这不等于本 PR 修复失败；当前改动目标是把 Model disabled 从网络异常改为模型不可用诊断，并提示本次测试模型。
• 是否仍有阻断：无 + 当前代码、测试与 CI 均显示诊断归类和前端提示已覆盖，mergeable_state=blocked 不单独构成阻断。

说明

1. src/services/system_config_service.py：已将包含 Model disabled 且匹配模型/权限/禁用语义的错误归入既有 model_not_found，并设置 details.reason=model_access_denied；不会让服务商已禁用或账号未开通的模型连接成功。
2. apps/dsa-web/src/components/settings/LLMChannelEditor.tsx：失败提示会展示“本次测试模型”和“基础连接测试默认只测试模型列表首项”，并仅在模型相关错误时建议调整模型顺序或移除不可用模型。
3. tests/test_system_config_service.py 与 LLMChannelEditor.test.tsx：已覆盖 Model disabled、模型不可用提示、首项模型提示，以及 auth/network/quota 场景不展示模型调整建议。
4. 如果实际截图里仍显示为“网络异常”、仍引导检查 Base URL/代理/TLS，或没有展示本次测试模型，那才是本 PR 的剩余问题；仅服务商继续返回 Model disabled 不构成阻断。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[massif-01]

我试了下这个分支，还是报错

@massif-01 佬帮忙看下？

looking

[massif-01]

我试了下这个分支，还是报错

@massif-01 佬帮忙看下？

又暴露了一个新的诊断缺口。

核心链路是：

1. 当前分支的新提示已经生效了：它明确显示基础测试只测首项 gpt-5.5，实际测试模型是 openai/gpt-5.5。
2. 服务端/LiteLLM 返回的原始错误不是 Model disabled，而是：
   OpenAIException - Your request was blocked.
3. 现在后端没有专门识别 request was blocked 这类错误，所以会掉到默认兜底：
   system_config_service.py 返回 network_error / unknown_error。
4. 前端把 network_error 显示成“网络异常”，并给出 Base URL、代理、TLS、网关这类排障提示：
   LLMChannelEditor.tsx

所以，“还是报错”本身是正常的：被服务商或中转网关拦截的请求不会因为这个分支变成功。真正不对的是诊断标签仍然显示成“网络异常”。

我建议把它判断为一个相邻的新问题：Your request was blocked 应该分类为“请求被服务商/网关拦截”之类，而不是网络异常。修法可以很窄：后端新增 blocked 信号识别，返回一个明确 reason；前端针对该 reason 显示“请求被拦截/服务商拒绝请求”的文案，并提示检查账号风控、地域、模型开通、网关策略或内容策略。

当前截图不能证明 #1208 的 Model disabled 修复失败，但证明 LLM 测试诊断还有一个未覆盖错误类型。

[ZhuLinsen]

跟进结论

• 结论：部分接受 + 最新反馈中“服务商仍返回错误”成立，但这符合本 PR 的修复边界：本次修的是诊断归类与提示，不是让已禁用/未开通模型连接成功。
• 是否仍有阻断：无 + 当前 CI 成功，代码与测试已覆盖 Model disabled 归入模型不可用诊断，未看到新的代码行为风险或文档错误。

说明

1. src/services/system_config_service.py：当前实现将包含模型与禁用/权限/不可用信号的错误归入既有 model_not_found，并用 details.reason=model_access_denied 表达具体原因；这不会改变服务商实际拒绝请求的事实。
2. apps/dsa-web/src/components/settings/LLMChannelEditor.tsx：前端已把 model_not_found 展示为“模型不可用”，并在失败 hint 中展示本次测试模型、模型列表首项和调整模型顺序/移除不可用模型的建议；这比原先误导到 Base URL、代理、TLS 更贴合当前错误。
3. tests/test_system_config_service.py 与 LLMChannelEditor.test.tsx：已覆盖 Model disabled 分类、resolved_model 展示、模型错误提示，以及网络/鉴权/配额错误不显示模型列表调整建议。
4. docs/llm-providers.md 与双语 LLM 配置指南已收窄说明：model_access_denied 是基于已观测 provider 文案的 best-effort 诊断，不是跨 provider 官方错误码映射。当前无需继续维持“外部语义依据不足”的阻断。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[massif-01]

我试了下这个分支，还是报错

测完了，结论比较明确：

OpenAI 官方 /v1/models 可以访问，Key 是有效的。
gpt-5.5 在模型列表里可见。
但实际发 Chat Completions 时，OpenAI 官方返回的是 429 insufficient_quota：
You exceeded your current quota...
走项目的 test_llm_channel() 测同一个官方 Key、同一个模型、同一个 Base URL，也返回了：
error_code=quota，details.reason=insufficient_balance，resolved_model=openai/gpt-5.5
所以这次官方 API 对照说明两点：

测试连接功能本身不是完全坏的。它确实发出了请求，并且能把 OpenAI 官方的 quota 类错误归到 quota，没有误报成“网络异常”。
这个 Key 当前不能用来验证成功路径，因为账号/项目没有可用额度或 billing quota。要验证“直连成功且项目也成功”，需要一个当前有额度、可正常完成 Chat Completions 的 Key。
这也反过来支持前面的判断：用户截图里的 Your request was blocked. 不是 OpenAI 官方 API 这次返回的错误，而更像是他使用的中转网关/服务商/风控策略拦截；当前分支的问题是这类 blocked 错误还会兜底成 network_error，文案不准确。

[ZhuLinsen]

跟进结论

• 结论：部分接受 + “仍然报错”这个现象成立，但它说明当前服务商/账号下测试模型仍不可用，不等于本 PR 的诊断归类修复失败。
• 是否仍有阻断：无 + 当前 CI 全部成功，代码和测试已覆盖 Model disabled 归入模型不可用诊断，未看到新的行为风险或文档错误。

说明

1. src/services/system_config_service.py：当前修复点是识别包含 model 与禁用/权限/不可用信号的异常，将其归入既有 model_not_found，并通过 details.reason=model_access_denied 表达；这不会让已禁用或未开通的模型连接成功。
2. apps/dsa-web/src/components/settings/LLMChannelEditor.tsx：失败提示会展示本次测试模型，并说明基础连接测试默认只测模型列表首项；因此用户仍需根据提示调整模型顺序、移除不可用模型或在服务商控制台确认模型权限。
3. tests/test_system_config_service.py 与 apps/dsa-web/src/components/settings/__tests__/LLMChannelEditor.test.tsx：已覆盖 Model disabled 分类、非网络错误提示、非模型错误不展示模型调整建议等回归场景。
4. docs/llm-providers.md 与中英文 LLM 配置指南：已把该语义收敛为基于已观测 provider 文案的 best-effort 诊断，并说明不是跨 provider 官方错误码映射；外部兼容性说明目前足够支撑本 PR 范围。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。