Skip to content

fix(transcriber): 模型下载失败时透传错误到前端并提示 (#402)#414

Closed
JefferyHcool wants to merge 1 commit into
developfrom
fix/model-download-failure-feedback
Closed

fix(transcriber): 模型下载失败时透传错误到前端并提示 (#402)#414
JefferyHcool wants to merge 1 commit into
developfrom
fix/model-download-failure-feedback

Conversation

@JefferyHcool

Copy link
Copy Markdown
Owner

背景

issue #402 的根因(large-v3-turbo 仓库 404)已由 #413 修复。但还有一个衍生问题没解决:当 whisper 模型后台下载因任何原因失败时,前端完全没有反馈。

/transcriber_models_status 此前每个模型只回传 downloading / downloaded 两个布尔,后台 _do_download_whisper 把失败状态写进 _downloading[size] = "failed" 后就被状态接口直接丢弃。于是用户看到的就是 issue 里描述的:「点了下载没反应、状态一直『未下载』、且无任何错误提示」。

本 PR 把失败态 + 失败原因一路透传到前端。

改动

后端

  • 新增轻量模块 app/transcriber/model_download_state.py:统一维护下载状态(downloading / done / failed)与失败原因,把原先散落在 config.py 多处的字符串状态赋值收敛到一处。仅依赖 logger,可被单测隔离加载(与 whisper_models.py 同款模式)。
  • config.py:下载触发与状态查询共享这份内存态;/transcriber_models_status 每个模型新增 failed 字段,失败时附带 errordownloaded=True 时一律不回传 failed/error(避免「先失败后又下好」残留旧错误)。

前端

  • 模型管理列表:新增红色「下载失败」徽标 + 错误详情文本,下载按钮在失败后变为「重试」。
  • 自定义模型项:同样展示失败图标与原因。
  • 对「本次新出现的失败」弹一次 toast(首次进页面只建立基线、不对历史失败弹窗,避免噪音)。

测试

新增 backend/tests/test_model_download_state.py(8 例)覆盖:状态流转、失败原因透传、downloaded 覆盖 failed、重新下载清除旧错误、mlx key 与 whisper 同名档位互不影响。

```
$ pytest tests/test_model_download_state.py tests/test_whisper_models.py -q
21 passed
```

前端无单测框架(仓库未配置 vitest/jest),故前端行为通过下方 Docker 实测验证;改动文件经 tsc/eslint 检查无新增报错(mlxAvailable 未使用为既有告警,非本 PR 引入,未在本 PR 内处理以保持 diff 聚焦)。

Docker 实测验证

docker compose up -d 起整套栈(nginx→backend),分别触发两种失败并轮询状态接口:

  1. 本地路径缺失(自定义模型指向不存在目录):
    {"model_size":"ci-fail-test","downloaded":false,"downloading":false,"failed":true,"error":"本地模型路径 /tmp/__bilinote_missing_model__ 下没有 model.bin,无法使用"}
  2. HF 仓库 404(复刻 issue [BUG] Whisper large-v3-turbo 模型点击下载后无进度反馈,状态始终显示未下载 #402 的 turbo 场景):
    failed:true + error401 Client Error ... Repository Not Found ...(正是 issue 日志里那段错误)。

前端构建产物也已确认包含新增的「下载失败」「重试」文案。

Refs #402

🤖 Generated with Claude Code

issue #402 衍生问题:whisper 模型后台下载失败时,/transcriber_models_status
只回传 downloading/downloaded 两个布尔,failed 态被直接丢弃,于是前端表现为
「点了下载没反应、状态一直未下载、且无任何错误提示」。

后端:新增轻量模块 model_download_state 统一维护下载状态(downloading/done/
failed)与失败原因,config.py 的下载触发与状态查询共享同一份内存态;状态接口
新增 failed 字段,失败时附带 error(仓库 404、网络中断、本地路径缺 model.bin 等)。

前端:模型管理列表新增「下载失败」红色徽标 + 错误详情,按钮在失败后变为「重试」;
自定义模型项同样展示失败图标与原因;并对「本次新出现的失败」弹一次 toast 主动提示。

测试:新增 test_model_download_state 覆盖状态流转(downloading/done/failed、
失败原因透传、downloaded 覆盖 failed、重下清错、mlx key 隔离)。

已用 docker compose 启动整套栈验证:触发本地路径缺失与 HF 仓库 404 两种失败,
/transcriber_models_status 均正确回传 failed:true + error。

Refs #402

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@JefferyHcool

Copy link
Copy Markdown
Owner Author

已通过 hotfix v2.4.3 合并进 master 与 develop(cherry-pick 自 commit 4a87c5b),故关闭此 PR。

@JefferyHcool
JefferyHcool deleted the fix/model-download-failure-feedback branch June 23, 2026 02:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant