fix(backend): 修复 DeepSeek 模型列表为空 & whisper 下载不走代理 (#417)

问题1 — DeepSeek 模型下拉为空： provider 的 /models 调用失败时，get_model_list 吞掉异常返回 []， get_all_models_by_id 再对 [] 取 .data 触发 AttributeError 又被吞，最终接口返回 {"code":0,"msg":"success","data":[]}，把失败伪装成空成功，用户看不到任何原因。 - 捕获并回传真实错误，不再二次吞 - 新增 model_fallback.normalize_models 兼容 SyncPage/list/dict，绝不再 .data 崩 - 内置供应商提供已知模型兜底清单（DeepSeek→deepseek-chat/deepseek-reasoner， Qwen→qwen-plus 等），动态拿不到时回退，保证下拉非空；动态可用时仍以动态为准问题2 — whisper 模型下载不走代理（Docker 里代理没生效）： snapshot_download 既不读 UI 配的代理，HF_ENDPOINT 又固定 hf-mirror.com。 - ProxyConfigManager.apply_to_env() 把生效代理 export 到 HTTP(S)_PROXY/ALL_PROXY， huggingface_hub 即可复用；在每次下载前与启动时应用（覆盖转写按需下载） - 网络类下载报错翻译成可操作提示（配代理 / 改 HF_ENDPOINT / 检查容器外网） - .env.example 补充 HF_ENDPOINT 与代理覆盖说明新增 tests/test_model_fallback.py、tests/test_proxy_apply_env.py（14 用例） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-08-01 11:17:33 +08:00 · 2026-06-29 13:54:44 +08:00
parent 6a43043874
commit bebf2e8c61
9 changed files with 373 additions and 18 deletions
--- a/backend/app/services/model.py
+++ b/backend/app/services/model.py
@@ -83,22 +83,56 @@ class ModelService:
        return enabled_models
    @staticmethod
    def get_all_models_by_id(provider_id: str, verbose: bool = False):
+        """拉取某供应商的可选模型列表，用于设置页下拉。
+
+        历史坑（issue #417）：旧实现对 get_model_list 的返回值直接取 `.data`，但
+        get_model_list 在 /models 调用失败时会吞掉异常返回 `[]`，于是 `[].data`
+        触发 AttributeError，又被这里的 except 吞成 `[]` —— 最终接口返回
+        `{"code":0,"msg":"success","data":[]}`，把「DeepSeek /models 取不到」伪装成
+        成功的空列表，用户完全看不到原因。
+
+        现在：
+          1. 直接捕获 /models 的真实异常（不再二次吞）；
+          2. normalize_models 兼容 SyncPage / list / dict，绝不再 `.data` 崩；
+          3. 动态拿不到（失败或空）时退回内置已知清单，保证下拉非空；
+          4. 仍然为空且确有报错时，把报错带回去（前端可提示，不再假装成功）。
+        """
+        from app.services.model_fallback import (
+            builtin_fallback_models,
+            normalize_models,
+            as_model_dicts,
+        )
+
+        provider = ProviderService.get_provider_by_id(provider_id)
+        if not provider:
+            logger.warning(f"[{provider_id}] 供应商不存在")
+            return {"models": []}
+
+        models: list = []
+        error: str | None = None
        try:
-            provider = ProviderService.get_provider_by_id(provider_id)
-
-            models = ModelService.get_model_list(provider["id"], verbose=verbose)
-            print(type(models))
-            serializable_models = [m.dict() for m in models.data]
-            model_list = {
-                "models": serializable_models
-            }
-
-            logger.info(f"[{provider['name']}] 获取模型成功")
-            return model_list
+            config = ModelService._build_model_config(provider)
+            gpt = GPTFactory().from_config(config)
+            models = normalize_models(gpt.list_models())
+            if verbose:
+                print(f"[{provider['name']}] 动态模型列表: {models}")
        except Exception as e:
-            # print(f"[{provider_id}] 获取模型失败: {e}")
-            logger.error(f"[{provider_id}] 获取模型失败: {e}")
-            return []
+            error = str(e)
+            logger.warning(f"[{provider['name']}] 动态获取模型失败，尝试回退内置清单: {e}")
+
+        if not models:
+            fallback = builtin_fallback_models(provider)
+            if fallback:
+                logger.info(f"[{provider['name']}] /models 为空，回退内置清单: {fallback}")
+                models = as_model_dicts(fallback, owned_by=provider.get("name", ""))
+
+        result = {"models": models}
+        if not models and error:
+            # 既没动态结果也没兜底清单：把真实报错带回去，别再伪装成功
+            result["error"] = error
+        else:
+            logger.info(f"[{provider['name']}] 获取模型成功，共 {len(models)} 个")
+        return result
    @staticmethod
    def connect_test(id: str, model: str | None = None) -> bool:
        """连通性测试：发一条最小化 chat completion。
--- a/backend/app/services/model_fallback.py
+++ b/backend/app/services/model_fallback.py
@@ -0,0 +1,86 @@
+"""内置供应商的回退模型清单 + 模型对象归一化（issue #417）。
+
+背景：设置页的「模型下拉」依赖 provider 的 `/v1/models` 动态列表。但这个接口
+并不可靠——
+
+  - DeepSeek 的 `/models` 在部分账号/网络下取不到，下拉直接空白；
+  - 不少自建 OpenAI 兼容网关压根不实现 `/models`；
+  - key 没有 inference 权限时也可能返回异常。
+
+（`OpenAI_compatible_provider.test_connection` 的注释里已经记录过这个不可靠性。）
+
+所以对**内置供应商**额外维护一份已知可用清单兜底：动态拿不到时退回这份清单，
+保证下拉永远有内容，用户不至于卡在空列表。清单数据写在
+`app/db/builtin_providers.json` 的 `models` 字段里，单一数据源，方便维护。
+
+本模块只依赖标准库，便于单测隔离加载（不触发 app 包的重依赖导入链）。
+"""
+import json
+from pathlib import Path
+from typing import Any, List, Optional
+
+# builtin_providers.json 与本文件同属 backend/app 下：app/services/ -> app/db/
+_BUILTIN_JSON = Path(__file__).resolve().parent.parent / "db" / "builtin_providers.json"
+
+
+def _load_builtin() -> List[dict]:
+    try:
+        return json.loads(_BUILTIN_JSON.read_text(encoding="utf-8"))
+    except Exception:
+        return []
+
+
+def builtin_fallback_models(provider: Optional[dict]) -> List[str]:
+    """按 provider 的 id 或 name（忽略大小写）匹配内置清单里的 models 字段。
+
+    自定义供应商（DB 里 id 是 uuid）通常 name 也对得上内置名，所以 id / name 都试。
+    匹配不到或没配 models 返回空列表。
+    """
+    if not provider:
+        return []
+    keys = {str(provider.get("id", "")).strip().lower(), str(provider.get("name", "")).strip().lower()}
+    keys.discard("")
+    if not keys:
+        return []
+    for p in _load_builtin():
+        candidate = {str(p.get("id", "")).strip().lower(), str(p.get("name", "")).strip().lower()}
+        if keys & candidate:
+            models = p.get("models") or []
+            return [str(m) for m in models if m]
+    return []
+
+
+def normalize_models(raw: Any) -> List[dict]:
+    """把 SDK 返回值统一成 [{'id', 'object', 'owned_by', ...}] 列表。
+
+    兼容三种形态：
+      - openai SDK 的 SyncPage（取 .data）
+      - 普通 list（含旧代码失败时返回的 []，绝不能再 .data）
+      - list 里既可能是 pydantic Model 也可能是 dict
+    """
+    if raw is None:
+        return []
+    data = getattr(raw, "data", raw)  # SyncPage -> .data；list/tuple 原样
+    if not isinstance(data, (list, tuple)):
+        return []
+    out: List[dict] = []
+    for m in data:
+        if isinstance(m, dict):
+            d = m
+        elif hasattr(m, "model_dump"):
+            d = m.model_dump()
+        elif hasattr(m, "dict"):
+            d = m.dict()
+        else:
+            d = {"id": getattr(m, "id", None)}
+        if d.get("id"):
+            out.append(d)
+    return out
+
+
+def as_model_dicts(model_ids: List[str], owned_by: str = "") -> List[dict]:
+    """把模型名列表包成与 SDK Model 一致的 dict，前端下拉直接复用同一套渲染。"""
+    return [
+        {"id": mid, "object": "model", "created": None, "owned_by": owned_by}
+        for mid in model_ids
+    ]
--- a/backend/app/services/proxy_config_manager.py
+++ b/backend/app/services/proxy_config_manager.py
@@ -58,3 +58,22 @@ class ProxyConfigManager:
            if val:
                return val
        return None
+
+    def apply_to_env(self) -> Optional[str]:
+        """把当前生效的代理 URL 写进进程环境变量，返回生效的 url（无则 None）。
+
+        为什么需要（issue #417）：huggingface_hub / requests 这类库**只认**环境变量
+        HTTP_PROXY / HTTPS_PROXY / ALL_PROXY，不读我们 UI 配置文件。whisper 模型用
+        snapshot_download 从 HuggingFace 拉取，如果用户只在设置页填了代理，下载根本
+        不走代理 —— 就是用户说的「Docker 容器里代理没生效」。在下载前/启动时调用本
+        方法，把 UI 配的代理 export 到环境变量，HF 下载就能复用同一个代理。
+
+        大小写别名都写，覆盖不同库的读取习惯。
+        """
+        url = self.get_proxy_url()
+        if not url:
+            return None
+        for key in ("HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY",
+                    "http_proxy", "https_proxy", "all_proxy"):
+            os.environ[key] = url
+        return url