当前：{{ "完全离线" if ai_config.transcription_runtime.offline_only else "允许远程" }} · {{ ai_config.transcription_runtime.model_identity }} · {{ ai_config.transcription_runtime.device }}/{{ ai_config.transcription_runtime.compute_type }} · 外部费用 ¥{{ ai_config.transcription_runtime.external_cost_yuan }}
模型 {{ "已缓存" if ai_config.transcription_runtime.model_ready else "未缓存" }} · cuBLAS {{ "正常" if ai_config.transcription_runtime.cublas_ready else "缺失" }} · cuDNN {{ "正常" if ai_config.transcription_runtime.cudnn_ready else "缺失" }}。缺失时请运行 scripts/setup_local_transcription.ps1。
@@ -268,7 +297,8 @@
关键路径
任务资料根目录：{{ storage_root }}
数据库文件：{{ database_path }}（{{ "已存在" if database_exists else "尚未创建" }}）
AI 接口配置文件：项目本地 .env（{{ "已存在" if ai_config.env_exists else "尚未创建" }}）
-
1. 音频转写：{{ ai_config['values']['VOLCENGINE_ASR_API_URL'] }} · {{ ai_config['values']['VOLCENGINE_ASR_RESOURCE_ID'] }} · Key {{ "已填写" if ai_config.secret_configured['VOLCENGINE_ASR_API_KEY'] or ai_config.secret_configured['VOLCENGINE_ASR_APP_KEY'] else "未填写" }}
+
1. 音频转写：{{ ai_config.transcription_runtime.model_identity }} · {{ ai_config.transcription_runtime.device }}/{{ ai_config.transcription_runtime.compute_type }} · 模型 {{ "已缓存" if ai_config.transcription_runtime.model_ready else "待初始化" }} · GPU {{ "可用" if ai_config.transcription_runtime.gpu_ready else "待初始化" }} · 外部费用 ¥{{ ai_config.transcription_runtime.external_cost_yuan }}
+
火山回滚配置：{{ ai_config['values']['VOLCENGINE_ASR_RESOURCE_ID'] }} · Key {{ "已保留" if ai_config.secret_configured['VOLCENGINE_ASR_API_KEY'] or ai_config.secret_configured['VOLCENGINE_ASR_APP_KEY'] else "未填写" }} · {{ "完全离线锁已阻断" if ai_config.transcription_runtime.offline_only else "允许手动回滚" }}
2. 分析文字稿，生成候选切片：{{ ai_config['values']['AI_ANALYSIS_REMOTE_BASE_URL'] }} · {{ ai_config['values']['AI_ANALYSIS_REMOTE_PROTOCOL'] }} · {{ ai_config['values']['AI_ANALYSIS_REMOTE_MODEL'] }} · Key {{ "有效" if ai_config.analysis_key_valid else "异常" }}
3. 发送中心生成发布文案：{{ ai_config['values']['AI_PUBLISH_REMOTE_BASE_URL'] }} · {{ ai_config['values']['AI_PUBLISH_REMOTE_PROTOCOL'] }} · {{ ai_config['values']['AI_PUBLISH_REMOTE_MODEL'] }} · Key {{ "有效" if ai_config.publish_key_valid else "异常" }}
本地 AI：{{ ai_config['values']['AI_LOCAL_BASE_URL'] }} · {{ ai_config['values']['AI_LOCAL_MODEL'] }} · Ollama {{ "在线" if ai_config.local_ollama_online else "离线" }}
diff --git a/app/templates/task_detail.html b/app/templates/task_detail.html
index 24fc284..0938264 100644
--- a/app/templates/task_detail.html
+++ b/app/templates/task_detail.html
@@ -34,7 +34,7 @@
任务详情 · {{ task.title }}
{% endif %}
{% if not task.auto_mode %}
-
+
进入片段审核
{% endif %}
{% if not task.auto_mode and task.output_clip_count > 0 %}
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index dea9936..95f2d75 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -60,6 +60,22 @@ python -m venv .venv
pip install -r requirements.txt
```
+若要启用 Windows NVIDIA GPU 的完全离线转写，再运行一次：
+
+```powershell
+.\scripts\setup_local_transcription.ps1
+```
+
+脚本会安装固定版本 cuBLAS 12（及其固定 NVRTC 依赖），并把 `large-v3` 主模型与 `medium` CPU 兜底模型下载到 E 盘。模型大文件按 64 MiB 官方分片下载，可跨次运行续传；合并后必须同时通过固定大小和 SHA-256 校验才会启用。两套模型和运行库首次约需 5.2 GB；初始化完成后，任务运行只读取本地缓存，音频不会上传，也不会在任务过程中自动联网下载。可通过 `-AudioPath "真实音频路径"` 同时执行前 20 秒 GPU 推理冒烟。脚本默认让 PyPI 安装直连，避免本机代理拖慢 500 MB 以上的 Windows wheel；只有网络必须经代理时才增加 `-UseEnvironmentProxyForPip`。
+
+长音频验收可使用隔离基准脚本，不会写入正式数据库或任务目录：
+
+```powershell
+python .\scripts\benchmark_local_transcription.py "E:\素材\source.wav" "E:\直播间切片工作流存储\_验收\offline-asr" --seconds 600
+```
+
+要验证 checkpoint 续跑，首次增加 `--stop-after-chunks 1`；脚本会在第一个 120 秒分块安全落盘后主动停止。随后使用相同音频、相同验收目录和相同任务 ID，去掉该参数再次运行，日志应出现“已复用第 1/... 段 checkpoint”。脚本会强制 `HF_HUB_OFFLINE=1`、本地 Provider 和固定模型缓存，即使误配置远程 Key 也不会上传音频。
+
看到 `Successfully installed ...` 即为成功。
### 2.4 配置环境变量
@@ -77,7 +93,9 @@ copy .env.example .env
- `AI_CODEX_PATH`：受控 Codex CLI 命令路径（默认 `codex`）
- `AI_CODEX_MODEL`：Codex CLI 分析模型（默认 `gpt-5.6-sol`）
- `AI_ANALYSIS_REMOTE_API_KEY`：DeepSeek API Key（可选，用远程 AI 分析时需要）
-- `VOLCENGINE_ASR_API_KEY`：火山引擎转写 Key（可选，用远程转写时需要）
+- `TRANSCRIPTION_MODEL_CACHE_DIR`：离线模型缓存目录，默认 `E:\直播间切片工作流存储\_模型\faster-whisper`
+- `TRANSCRIPTION_OFFLINE_ONLY`：默认 `true`，阻断所有远程语音转写请求
+- `VOLCENGINE_ASR_API_KEY`：火山引擎回滚 Key（默认不使用，不会删除）
- `LOCAL_ADMIN_TOKEN`：管理接口鉴权 Token（可留空或设随机字符串）
### 2.5 启动服务
@@ -273,7 +291,7 @@ Windows 主机（运行 FastAPI）
| `AI_CODEX_PATH` | `codex` | 受控 Codex CLI 命令路径 |
| `AI_CODEX_MODEL` | `gpt-5.6-sol` | Codex CLI 分析模型 |
| `AI_ANALYSIS_REMOTE_API_KEY` | 空 | DeepSeek API Key |
-| `TRANSCRIPTION_PROVIDER` | `volcengine` | 转写引擎：`volcengine` 或 `faster_whisper` |
+| `TRANSCRIPTION_PROVIDER` | `local` | 转写引擎：`local` 或 `volcengine`；完全离线模式只允许 `local` |
| `AI_PROVIDER` | `codex` | AI 分析引擎：`codex`、`remote` 或 `local` |
---
diff --git a/docs/UI_REFERENCE.md b/docs/UI_REFERENCE.md
index b4d4a62..af98d9b 100644
--- a/docs/UI_REFERENCE.md
+++ b/docs/UI_REFERENCE.md
@@ -1,5 +1,20 @@
# UI 参考说明
+## 2026-09-01 更新：简体转写与 AI 安全重试
+
+- 本地 faster-whisper 的新转写统一显示简体字形；转换规则为 OpenCC `t2s`，只做繁简字形转换，因此台湾节目中的“计程车、软体”等用词仍会保留。段落、逐词时间戳和字幕复用同一份转换结果。
+- 全自动 AI 覆盖不完整时，任务会停在“AI 分析失败”，不会先显示成选片失败，也不会继续生成切片或发送中心记录。
+- “重试全自动流程”检测到可能已计费但结果不确定的 AI 单元时，先显示包含单元数量和恢复方式的确认框；只有用户再次确认才会发起 AI 调用，取消后原 Job 与证据不变。
+- transcript 未变化时，提示会说明只补跑不确定单元；transcript 已变化时，提示会说明创建全新 AI Job 且不复用旧 AI 单元。有下游切片或发布记录时，页面直接显示拒绝原因。
+- 系统状态中的 Codex 超时默认值调整为 600 秒，仍可在 10–1800 秒范围内人工配置。
+
+## 2026-08-31 更新：完全离线本地转写
+
+- 系统状态新增“完全离线转写”卡片，直接展示固定模型身份、模型缓存、GPU、cuBLAS、cuDNN 和外部转写费用 `¥0`；缺模型或 DLL 时明确提示运行初始化脚本，不在任务运行中联网下载。
+- “1. 音频转写”默认使用 `local`，固定显示 `large-v3@edaa852e / cuda / float16` 和 E 盘模型目录；火山地址与 Key 继续保留在“回滚配置”中，完全离线锁开启时不会调用。
+- 任务详情和自动流水线未显式选择 Provider 时都服从系统本地设置；失败、取消或卡住后的重试文案改为本地转写语义。显式选择火山且离线锁开启时，页面收到 409 中文提示且不会产生远程请求。
+- 转写进度、完整原文、字幕工作台和 AI 分析继续使用原有输出结构；本轮不增加说话人分离，也不改变后续文本 AI Provider。
+
## 2026-08-26 更新：全站克制动效系统
- 动效遵循“状态反馈优先、装饰最少”：使用原生 CSS/JavaScript，统一短时缓动，不引入 Motion、AutoAnimate、Animate.css、AOS、GSAP 或 View Transitions 运行时。
diff --git a/docs/agent_tasks/2026-08-31-offline-local-transcription.md b/docs/agent_tasks/2026-08-31-offline-local-transcription.md
new file mode 100644
index 0000000..4b81eb8
--- /dev/null
+++ b/docs/agent_tasks/2026-08-31-offline-local-transcription.md
@@ -0,0 +1,57 @@
+# 完全离线长音频转写实施任务
+
+## 背景
+
+火山引擎长音频转写成本过高。本机具备 RTX 4070 Ti 12GB 和 64GB 内存，项目已包含 faster-whisper、分块 checkpoint、持久化任务和时间戳输出，但默认 Provider 仍偏向远程，且 Windows GPU 运行库与固定模型缓存没有形成可验证的离线闭环。
+
+## 目标
+
+1. 默认使用固定版本 `large-v3 / cuda / float16`，正式转写不上传音频、不产生云端 ASR 费用。
+2. 首次联网初始化后只从 E 盘固定缓存加载模型，缺模型时明确失败，不在任务中静默下载。
+3. 保留 120 秒分块、5 秒重叠、SQLite checkpoint、词级时间戳及 medium CPU 本地兜底。
+4. 系统状态页和任务状态 API 提供模型、GPU、离线锁和实际版本证据。
+
+## 允许修改范围
+
+- 转写配置、Provider 解析、运行时加载、checkpoint 指纹与转写状态 API。
+- 系统状态页、相关 JavaScript、一次性初始化/诊断脚本。
+- 转写定向测试、项目进度文档和 UI 参考文档。
+- Windows GPU 可选依赖清单。
+
+## 禁止修改范围
+
+- 不删除或回显火山 Key、`.env`、历史 transcript、数据库记录和模型缓存。
+- 不增加说话人分离、降噪、人声分离或新的云端 ASR Provider。
+- 不改变下游字幕、AI 分析、切片、排期和发布数据格式。
+- 不重启正式 Web/Worker，不触发真实平台发布或远程转写。
+
+## 已确定实现要求
+
+- 主模型锁定 `Systran/faster-whisper-large-v3@edaa852ec7e145841d8ffdb056a99866b5f0a478`。
+- CPU 兜底锁定 `Systran/faster-whisper-medium@08e178d48790749d25932bbc082711ddcfdfbc4f`。
+- Windows 固定安装 `nvidia-cublas-cu12==12.9.2.10` 及其 NVRTC 依赖；继续使用 CTranslate2 自带 cuDNN 9，不再安装第二套 cuDNN。
+- 完全离线锁开启时，远程 Provider 在请求前失败；HTTP 路由返回 409。
+- 转写 checkpoint 使用完整音频 SHA-256，其他视频/封面指纹行为不变。
+- 转写 run 的 model 字段记录 `模型名@revision前8位`，旧记录保持可读。
+
+## 验收标准
+
+- 默认、普通任务、自动流水线都选择 local；离线锁下无法创建远程转写任务。
+- 模型未缓存、cuBLAS 缺失、CUDA 不可用时返回准确中文诊断。
+- 已完成分块可恢复，模型 revision 或音频内容改变时不复用旧 checkpoint。
+- 系统状态页不泄露 Secret，显示离线、模型、GPU、设备和外部费用 ¥0。
+- 20 秒真实中文音频在 GPU 上完成；代表性长音频验证另行记录，未获确认前不切换正式运行配置。
+
+## 测试命令
+
+- `.venv\\Scripts\\python.exe -m pytest tests/test_offline_transcription.py tests/test_long_live_foundation.py tests/test_transcription_checkpoint_resilience.py -q`
+- `.venv\\Scripts\\python.exe -m pytest -q`
+- `.venv\\Scripts\\python.exe -m ruff check app tests scripts`
+- `.venv\\Scripts\\python.exe -m compileall -q app scripts`
+- `node --check app/static/js/app.js`
+- `git diff --check`
+
+## 返回格式
+
+- 返回分支、提交、远端 SHA、PR、CI、测试数量与真实 GPU 冒烟证据。
+- 明确区分代码/自动化验证、模型下载、真实音频验收和正式运行时切换状态。
diff --git a/docs/agent_tasks/2026-09-01-latest-task-transcription-recovery.md b/docs/agent_tasks/2026-09-01-latest-task-transcription-recovery.md
new file mode 100644
index 0000000..9733393
--- /dev/null
+++ b/docs/agent_tasks/2026-09-01-latest-task-transcription-recovery.md
@@ -0,0 +1,67 @@
+# 最新任务失败与本地转写简体化修复任务
+
+## 背景
+
+- 最新任务 `614fb38401e0` 已完成本地转写，但 AI 分析的一个召回窗口超时，覆盖率停在 `17/18`。
+- 当前本地 faster-whisper 输出包含繁体字；用户确认今后统一转换为简体字，只转换字形并保留台湾用词。
+- 现有全自动重试入口无法正确补跑 AI 分析，也没有针对“可能已计费但结果未知”的二次确认。
+
+## 目标
+
+1. 本地转写的段落与逐词结果在写入 checkpoint 前统一执行 OpenCC `t2s` 转换。
+2. 将转换规则加入本地转写 checkpoint 身份，避免复用旧繁体分块。
+3. AI 覆盖不完整时在 AI 分析阶段失败，并保留选片阶段的防御性门禁。
+4. 全自动重试支持结构化确认、未变化输入的失败单元续跑，以及变化输入的全新 AI Job。
+5. 将 Codex 默认窗口超时调整为 600 秒，并更新页面交互、项目文档和测试。
+6. 安全恢复任务 `614fb38401e0`，不重复转写、不触发真实发布。
+
+## 允许修改范围
+
+- `app/` 中转写、AI 流水线、Job 重试、任务路由和任务详情交互相关文件。
+- `tests/` 中与本次行为对应的自动化测试。
+- `requirements.in`、`requirements.txt`、`.env.example`。
+- `DEVELOPMENT_LOG.md`、`NEXT_STEPS.md`、`docs/UI_REFERENCE.md` 和本任务文件。
+- 通过测试后，将代码提交同步到运行工作树并定向调整运行 `.env` 的超时配置。
+
+## 禁止修改范围
+
+- 主目录已有 `.codemap/*` 与 `PROJECT_REAUDIT.md`。
+- 发布 Worker、真实抖音/B站发布、排期、账号登录与平台验证。
+- PR 合并、强推、历史改写、数据库结构和既有失败 Job 证据。
+- API Key、Token、Cookie、密码及其他敏感配置内容。
+
+## 已确定实现要求
+
+- 固定依赖 `opencc==1.4.2`，使用 `t2s.json`，不使用词汇本地化转换。
+- 当前 transcript 变化后从 `AI_ANALYZING` 新建独立 Job，不继承旧 AI 单元。
+- 输入不变时，确认后只重置不确定单元并复用成功 checkpoint。
+- 未传 `confirm_uncertain_ai=true` 时返回 HTTP 409 和结构化确认信息。
+- 有下游切片或发布记录时拒绝覆盖式恢复。
+- Codex 超时默认值和运行值均设为 600 秒。
+
+## 验收标准
+
+- 段落和逐词文本均转为简体；台湾用词和非中文内容不被错误改写。
+- 旧繁体 checkpoint 不会被新规则复用。
+- AI 覆盖不完整落入 `FAILED_AI_ANALYZING`。
+- 409 确认、同输入单元续跑、变输入新 Job、下游保护均有测试覆盖。
+- 相关测试、完整 pytest、Ruff、compileall、JavaScript 语法检查、`git diff --check` 和 Windows smoke/release gate 通过。
+- 正式 transcript 有可恢复备份，转换后时间戳、行数和 Markdown 结构不变。
+- 新 AI Job 达到 100% 覆盖并进入正常后续阶段，且无发布记录。
+
+## 测试命令
+
+- `python -m pytest tests/test_offline_transcription.py tests/test_pipeline_checkpoint.py tests/test_auto_pipeline.py`
+- `python -m pytest`
+- `python -m ruff check app tests`
+- `python -m compileall app tests`
+- `node --check app/static/js/app.js`
+- `git diff --check`
+- 项目现有 Windows smoke/release gate。
+
+## 返回格式
+
+- 修改文件及核心行为。
+- 测试命令、结果与失败证据（如有）。
+- Git 分支、提交、Push、PR、CI 与未合并状态。
+- 运行服务重启验证、当前任务新 Job、AI 覆盖率和发布记录状态。
diff --git a/requirements-windows-gpu.txt b/requirements-windows-gpu.txt
new file mode 100644
index 0000000..d49710e
--- /dev/null
+++ b/requirements-windows-gpu.txt
@@ -0,0 +1,4 @@
+# Optional Windows GPU runtime for local faster-whisper transcription.
+# Install after requirements.txt with scripts/setup_local_transcription.ps1.
+nvidia-cublas-cu12==12.9.2.10
+nvidia-cuda-nvrtc-cu12==12.9.86
diff --git a/requirements.in b/requirements.in
index a50c48c..5494a2b 100644
--- a/requirements.in
+++ b/requirements.in
@@ -10,4 +10,5 @@ tzdata>=2026.1
playwright>=1.58,<1.63
aiofiles>=25.1,<26
faster-whisper>=1.2,<1.3
+opencc==1.4.2
pysubs2==1.9.0
diff --git a/requirements.txt b/requirements.txt
index 0b340de..b86e0af 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -13,4 +13,5 @@ tzdata==2026.3
playwright==1.62.0
aiofiles==25.1.0
faster-whisper==1.2.1
+opencc==1.4.2
pysubs2==1.9.0
diff --git a/scripts/benchmark_local_transcription.py b/scripts/benchmark_local_transcription.py
new file mode 100644
index 0000000..cef615a
--- /dev/null
+++ b/scripts/benchmark_local_transcription.py
@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_MODEL_CACHE_DIR = Path(r"E:\直播间切片工作流存储\_模型\faster-whisper")
+
+
+def parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(
+ description="使用隔离数据库验证本地长音频转写、分块 checkpoint 和续跑能力。",
+ )
+ parser.add_argument("audio_path", help="本地音频文件路径")
+ parser.add_argument("workspace_dir", help="隔离验收目录；续跑时必须使用同一目录")
+ parser.add_argument("--seconds", type=int, default=0, help="仅验证前 N 秒；0 表示完整音频")
+ parser.add_argument("--task-id", default="offline-local-benchmark", help="隔离数据库中的固定任务 ID")
+ parser.add_argument(
+ "--stop-after-chunks",
+ type=int,
+ default=0,
+ help="完成指定数量分块并保存 checkpoint 后主动停止；0 表示运行到结束",
+ )
+ parser.add_argument(
+ "--model-cache-dir",
+ default=str(DEFAULT_MODEL_CACHE_DIR),
+ help="固定版本 faster-whisper 模型缓存根目录",
+ )
+ return parser.parse_args()
+
+
+def configure_isolated_environment(args: argparse.Namespace, workspace_dir: Path) -> None:
+ data_dir = workspace_dir / "data"
+ storage_dir = workspace_dir / "storage"
+ environment = {
+ "DATA_DIR": str(data_dir),
+ "DATABASE_PATH": str(data_dir / "benchmark.sqlite3"),
+ "STORAGE_ROOT": str(storage_dir),
+ "TASKS_DIR": str(storage_dir),
+ "UPLOAD_TEMP_DIR": str(storage_dir / "_uploads"),
+ "TRANSCRIPTION_PROVIDER": "local",
+ "TRANSCRIPTION_FALLBACK_PROVIDER": "",
+ "TRANSCRIPTION_OFFLINE_ONLY": "true",
+ "TRANSCRIPTION_MODEL": "large-v3",
+ "TRANSCRIPTION_MODEL_REVISION": "edaa852ec7e145841d8ffdb056a99866b5f0a478",
+ "TRANSCRIPTION_MODEL_CACHE_DIR": str(Path(args.model_cache_dir).resolve()),
+ "TRANSCRIPTION_LOCAL_FILES_ONLY": "true",
+ "TRANSCRIPTION_DEVICE": "cuda",
+ "TRANSCRIPTION_COMPUTE_TYPE": "float16",
+ "HF_HUB_OFFLINE": "1",
+ "TRANSFORMERS_OFFLINE": "1",
+ }
+ os.environ.update(environment)
+
+
+def main() -> int:
+ args = parse_args()
+ audio_path = Path(args.audio_path).resolve()
+ workspace_dir = Path(args.workspace_dir).resolve()
+ if not audio_path.is_file():
+ raise SystemExit(f"音频文件不存在：{audio_path}")
+ if args.seconds < 0:
+ raise SystemExit("--seconds 不能小于 0")
+ if args.stop_after_chunks < 0:
+ raise SystemExit("--stop-after-chunks 不能小于 0")
+
+ workspace_dir.mkdir(parents=True, exist_ok=True)
+ configure_isolated_environment(args, workspace_dir)
+ if str(PROJECT_ROOT) not in sys.path:
+ sys.path.insert(0, str(PROJECT_ROOT))
+
+ from app.db.database import get_connection, init_db
+ from app.models.task import TaskCreate
+ from app.services.task_lifecycle_service import create_task_record
+ from app.services.transcript_service import (
+ TranscriptChunk,
+ _extract_audio_chunk,
+ write_transcript_markdown,
+ )
+
+ init_db()
+ with get_connection() as connection:
+ task_exists = connection.execute("SELECT 1 FROM tasks WHERE id = ?", (args.task_id,)).fetchone()
+ if not task_exists:
+ create_task_record(
+ TaskCreate(task_name="完全离线长音频验收", selection_profile="general"),
+ task_id=args.task_id,
+ task_dir_name=args.task_id,
+ )
+
+ benchmark_audio_path = audio_path
+ if args.seconds:
+ benchmark_audio_path = workspace_dir / f"source-first-{args.seconds}s.wav"
+ if not benchmark_audio_path.exists():
+ _extract_audio_chunk(
+ audio_path,
+ benchmark_audio_path,
+ TranscriptChunk(index=1, start_seconds=0, end_seconds=max(1, args.seconds)),
+ )
+
+ transcript_path = workspace_dir / "transcript.md"
+ started_at = time.perf_counter()
+ reuse_count = 0
+
+ def report_progress(progress: dict) -> None:
+ nonlocal reuse_count
+ message = str(progress.get("message") or "")
+ if "已复用第" in message and "checkpoint" in message:
+ reuse_count += 1
+ print(json.dumps(progress, ensure_ascii=False), flush=True)
+ if (
+ args.stop_after_chunks
+ and message.startswith(f"已完成第 {args.stop_after_chunks}/")
+ ):
+ raise RuntimeError(
+ f"验收脚本按计划在第 {args.stop_after_chunks} 个分块落盘后停止；"
+ "使用相同命令去掉 --stop-after-chunks 即可续跑。"
+ )
+
+ try:
+ result = write_transcript_markdown(
+ {
+ "id": args.task_id,
+ "task_name": "完全离线长音频验收",
+ "source": str(audio_path),
+ },
+ benchmark_audio_path,
+ transcript_path,
+ progress_callback=report_progress,
+ provider="local",
+ )
+ except RuntimeError as exc:
+ elapsed_seconds = round(time.perf_counter() - started_at, 2)
+ if "验收脚本按计划" in str(exc):
+ print(
+ json.dumps(
+ {
+ "status": "stopped_after_checkpoint",
+ "elapsed_seconds": elapsed_seconds,
+ "reason": str(exc),
+ },
+ ensure_ascii=False,
+ ),
+ flush=True,
+ )
+ return 75
+ raise
+
+ progress_path = transcript_path.with_name("transcript_progress.json")
+ progress = json.loads(progress_path.read_text(encoding="utf-8"))
+ elapsed_seconds = round(time.perf_counter() - started_at, 2)
+ print(
+ json.dumps(
+ {
+ "status": "completed",
+ "elapsed_seconds": elapsed_seconds,
+ "reuse_count": reuse_count,
+ "audio_path": str(benchmark_audio_path),
+ "transcript_path": str(transcript_path),
+ "provider": result.get("provider"),
+ "model": progress.get("model"),
+ "device": progress.get("device"),
+ "compute_type": progress.get("compute_type"),
+ "segment_count": result.get("segment_count"),
+ },
+ ensure_ascii=False,
+ ),
+ flush=True,
+ )
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/scripts/diagnose_transcription_environment.py b/scripts/diagnose_transcription_environment.py
index 50ff500..f351cdb 100644
--- a/scripts/diagnose_transcription_environment.py
+++ b/scripts/diagnose_transcription_environment.py
@@ -8,7 +8,8 @@
if str(PROJECT_ROOT) not in sys.path:
sys.path.insert(0, str(PROJECT_ROOT))
-from app.core.config import settings
+from app.core.config import settings # noqa: E402
+from app.services.local_transcription_runtime import get_local_transcription_runtime_status # noqa: E402
def check_command(name: str) -> tuple[bool, str]:
@@ -43,7 +44,11 @@ def main() -> None:
print("=== 当前转写配置 ===")
print(f"TRANSCRIPTION_PROVIDER={settings.transcription_provider}")
print(f"TRANSCRIPTION_FALLBACK_PROVIDER={settings.transcription_fallback_provider}")
+ print(f"TRANSCRIPTION_OFFLINE_ONLY={settings.transcription_offline_only}")
print(f"TRANSCRIPTION_MODEL={settings.transcription_model}")
+ print(f"TRANSCRIPTION_MODEL_REVISION={settings.transcription_model_revision}")
+ print(f"TRANSCRIPTION_MODEL_CACHE_DIR={settings.transcription_model_cache_dir}")
+ print(f"TRANSCRIPTION_LOCAL_FILES_ONLY={settings.transcription_local_files_only}")
print(f"TRANSCRIPTION_LANGUAGE={settings.transcription_language}")
print(f"TRANSCRIPTION_DEVICE={settings.transcription_device}")
print(f"TRANSCRIPTION_COMPUTE_TYPE={settings.transcription_compute_type}")
@@ -55,9 +60,18 @@ def main() -> None:
print(f"VOLCENGINE_ASR_API_KEY={'已填写' if settings.volcengine_asr_api_key else '未填写'}")
print(f"VOLCENGINE_ASR_AUDIO_FORMAT={settings.volcengine_asr_audio_format}")
- if settings.transcription_device.lower() == "cuda":
- print()
- print("提示：当前配置使用 CUDA。如果仍然看到 cublas64_12.dll 或 cudnn 错误，请先改用 CPU/int8 跑通。")
+ runtime = get_local_transcription_runtime_status()
+ print()
+ print("=== 本地离线转写就绪状态 ===")
+ print(f"模型固定身份：{runtime['model_identity']}")
+ print(f"模型已缓存：{'是' if runtime['model_ready'] else '否'}")
+ print(f"GPU 可用：{'是' if runtime['gpu_ready'] else '否'}")
+ print(f"CUDA 设备数：{runtime['cuda_device_count']}")
+ print(f"cuBLAS 12：{'正常' if runtime['cublas_ready'] else '缺失'}")
+ print(f"cuDNN 9：{'正常' if runtime['cudnn_ready'] else '缺失'}")
+ print(f"外部转写费用：{runtime['external_cost']}")
+ if runtime["errors"]:
+ print("待处理：" + "；".join(runtime["errors"]))
if __name__ == "__main__":
diff --git a/scripts/normalize_transcript_simplified.py b/scripts/normalize_transcript_simplified.py
new file mode 100644
index 0000000..d4b2718
--- /dev/null
+++ b/scripts/normalize_transcript_simplified.py
@@ -0,0 +1,95 @@
+"""备份并原位把 transcript.md 转为 OpenCC t2s 简体字形。"""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime
+import hashlib
+import json
+from pathlib import Path
+import re
+import shutil
+import sys
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+ sys.path.insert(0, str(PROJECT_ROOT))
+
+from app.services.chinese_text_service import simplify_chinese_text # noqa: E402
+
+
+_TIMESTAMP_PATTERN = re.compile(r"\b\d{2}:\d{2}:\d{2}\b")
+
+
+def normalize_transcript_file(transcript_path: Path, backup_dir: Path) -> dict:
+ transcript_path = transcript_path.resolve()
+ backup_dir = backup_dir.resolve()
+ if not transcript_path.is_file():
+ raise FileNotFoundError(f"未找到 transcript：{transcript_path}")
+ original_bytes = transcript_path.read_bytes()
+ original = original_bytes.decode("utf-8")
+ converted = simplify_chinese_text(original)
+ _validate_structure(original, converted)
+
+ backup_dir.mkdir(parents=True, exist_ok=True)
+ timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+ backup_path = backup_dir / f"transcript.before-t2s-{timestamp}.md"
+ if backup_path.exists():
+ raise FileExistsError(f"备份文件已存在：{backup_path}")
+ shutil.copy2(transcript_path, backup_path)
+
+ temp_path = transcript_path.with_name(f"{transcript_path.name}.t2s.tmp")
+ try:
+ temp_path.write_bytes(converted.encode("utf-8"))
+ if temp_path.read_bytes().decode("utf-8") != converted:
+ raise RuntimeError("转换后的临时文件回读校验失败")
+ temp_path.replace(transcript_path)
+ finally:
+ if temp_path.exists():
+ temp_path.unlink()
+
+ final_bytes = transcript_path.read_bytes()
+ return {
+ "status": "converted" if final_bytes != original_bytes else "unchanged",
+ "transcript_path": str(transcript_path),
+ "backup_path": str(backup_path),
+ "before_sha256": hashlib.sha256(original_bytes).hexdigest(),
+ "after_sha256": hashlib.sha256(final_bytes).hexdigest(),
+ "line_count": len(original.splitlines()),
+ "timestamp_count": len(_TIMESTAMP_PATTERN.findall(original)),
+ }
+
+
+def _validate_structure(original: str, converted: str) -> None:
+ original_lines = original.splitlines()
+ converted_lines = converted.splitlines()
+ if len(original_lines) != len(converted_lines):
+ raise RuntimeError("转换前后行数变化，已停止覆盖 transcript")
+ if _TIMESTAMP_PATTERN.findall(original) != _TIMESTAMP_PATTERN.findall(converted):
+ raise RuntimeError("转换前后时间戳变化，已停止覆盖 transcript")
+ if [line.count("|") for line in original_lines] != [line.count("|") for line in converted_lines]:
+ raise RuntimeError("转换前后 Markdown 表格结构变化，已停止覆盖 transcript")
+ if [len(line) - len(line.lstrip("#")) for line in original_lines] != [
+ len(line) - len(line.lstrip("#")) for line in converted_lines
+ ]:
+ raise RuntimeError("转换前后 Markdown 标题结构变化，已停止覆盖 transcript")
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--transcript", type=Path, required=True)
+ parser.add_argument("--backup-dir", type=Path, required=True)
+ args = parser.parse_args()
+ print(
+ json.dumps(
+ normalize_transcript_file(args.transcript, args.backup_dir),
+ ensure_ascii=False,
+ indent=2,
+ )
+ )
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/scripts/setup_local_transcription.ps1 b/scripts/setup_local_transcription.ps1
new file mode 100644
index 0000000..72eb800
--- /dev/null
+++ b/scripts/setup_local_transcription.ps1
@@ -0,0 +1,92 @@
+param(
+ [string]$PythonPath = "",
+ [string]$ModelCacheDir = "",
+ [string]$AudioPath = "",
+ [ValidateRange(1, 120)]
+ [int]$Seconds = 20,
+ [switch]$SkipDependencyInstall,
+ [switch]$UseEnvironmentProxyForPip
+)
+
+$ErrorActionPreference = "Stop"
+$projectRoot = Split-Path -Parent $PSScriptRoot
+
+function Install-VerifiedWheel {
+ param(
+ [Parameter(Mandatory = $true)]
+ [string]$Url,
+ [Parameter(Mandatory = $true)]
+ [string]$Sha256,
+ [Parameter(Mandatory = $true)]
+ [string]$Destination
+ )
+
+ if (Test-Path -LiteralPath $Destination) {
+ $existingHash = (Get-FileHash -Algorithm SHA256 -LiteralPath $Destination).Hash.ToLowerInvariant()
+ if ($existingHash -ne $Sha256) {
+ Remove-Item -LiteralPath $Destination
+ }
+ }
+ if (-not (Test-Path -LiteralPath $Destination)) {
+ & curl.exe --noproxy "*" --location --fail --retry 10 --retry-delay 2 --continue-at - --output $Destination $Url
+ if ($LASTEXITCODE -ne 0) {
+ throw "GPU 运行库 wheel 下载失败：$Destination"
+ }
+ }
+ $actualHash = (Get-FileHash -Algorithm SHA256 -LiteralPath $Destination).Hash.ToLowerInvariant()
+ if ($actualHash -ne $Sha256) {
+ throw "GPU 运行库 wheel SHA-256 校验失败：$Destination"
+ }
+}
+
+if (-not $PythonPath) {
+ $PythonPath = Join-Path $projectRoot ".venv\Scripts\python.exe"
+}
+$resolvedPython = Resolve-Path -LiteralPath $PythonPath -ErrorAction SilentlyContinue
+if (-not $resolvedPython) {
+ throw "找不到项目 Python：$PythonPath。请通过 -PythonPath 指定 NiuMa Studio 的 .venv Python。"
+}
+$pythonExe = $resolvedPython.Path
+
+if (-not $SkipDependencyInstall) {
+ if ($UseEnvironmentProxyForPip) {
+ & $pythonExe -m pip install --disable-pip-version-check --timeout 600 --retries 5 -r (Join-Path $projectRoot "requirements-windows-gpu.txt")
+ if ($LASTEXITCODE -ne 0) {
+ throw "Windows GPU 运行库安装失败，未继续下载模型。"
+ }
+ }
+ else {
+ $wheelDirectory = Join-Path ([System.IO.Path]::GetTempPath()) "niuma-offline-transcription-wheels"
+ New-Item -ItemType Directory -Force -Path $wheelDirectory | Out-Null
+ $cublasWheel = Join-Path $wheelDirectory "nvidia_cublas_cu12-12.9.2.10-py3-none-win_amd64.whl"
+ $nvrtcWheel = Join-Path $wheelDirectory "nvidia_cuda_nvrtc_cu12-12.9.86-py3-none-win_amd64.whl"
+ Install-VerifiedWheel `
+ -Url "https://files.pythonhosted.org/packages/20/e2/fc9a0e985249d873150276d5afb02e39a66817fedbf1a385724393e505ed/nvidia_cublas_cu12-12.9.2.10-py3-none-win_amd64.whl" `
+ -Sha256 "623f43027d40d44ceadf0043f002bd25cf353e8f13ce90b9a87057019f560661" `
+ -Destination $cublasWheel
+ Install-VerifiedWheel `
+ -Url "https://files.pythonhosted.org/packages/52/de/823919be3b9d0ccbf1f784035423c5f18f4267fb0123558d58b813c6ec86/nvidia_cuda_nvrtc_cu12-12.9.86-py3-none-win_amd64.whl" `
+ -Sha256 "72972ebdcf504d69462d3bcd67e7b81edd25d0fb85a2c46d3ea3517666636349" `
+ -Destination $nvrtcWheel
+ & $pythonExe -m pip install --disable-pip-version-check --no-index --no-deps $nvrtcWheel $cublasWheel
+ if ($LASTEXITCODE -ne 0) {
+ throw "Windows GPU 运行库本地 wheel 安装失败，未继续下载模型。"
+ }
+ }
+}
+
+$arguments = @(
+ "-X", "utf8",
+ (Join-Path $projectRoot "scripts\setup_local_transcription.py")
+)
+if ($ModelCacheDir) {
+ $arguments += @("--cache-dir", $ModelCacheDir)
+}
+if ($AudioPath) {
+ $arguments += @("--audio", $AudioPath, "--seconds", $Seconds)
+}
+
+& $pythonExe @arguments
+if ($LASTEXITCODE -ne 0) {
+ throw "本地离线转写初始化失败。"
+}
diff --git a/scripts/setup_local_transcription.py b/scripts/setup_local_transcription.py
new file mode 100644
index 0000000..6d3fe6f
--- /dev/null
+++ b/scripts/setup_local_transcription.py
@@ -0,0 +1,472 @@
+from __future__ import annotations
+
+import argparse
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+from tempfile import TemporaryDirectory
+import time
+from urllib.request import Request, getproxies, urlopen
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+ sys.path.insert(0, str(PROJECT_ROOT))
+
+from app.core.config import settings # noqa: E402
+from app.core.transcription_defaults import ( # noqa: E402
+ CPU_FALLBACK_TRANSCRIPTION_MODEL,
+ CPU_FALLBACK_TRANSCRIPTION_MODEL_BIN_SHA256,
+ CPU_FALLBACK_TRANSCRIPTION_MODEL_BIN_SIZE,
+ CPU_FALLBACK_TRANSCRIPTION_MODEL_REPOSITORY,
+ CPU_FALLBACK_TRANSCRIPTION_MODEL_REVISION,
+ PRIMARY_TRANSCRIPTION_MODEL,
+ PRIMARY_TRANSCRIPTION_MODEL_BIN_SHA256,
+ PRIMARY_TRANSCRIPTION_MODEL_BIN_SIZE,
+ PRIMARY_TRANSCRIPTION_MODEL_REPOSITORY,
+ PRIMARY_TRANSCRIPTION_MODEL_REVISION,
+)
+from app.services.local_transcription_runtime import ( # noqa: E402
+ MODEL_VOCABULARY_FILES,
+ OPTIONAL_MODEL_FILES,
+ REQUIRED_MODEL_FILES,
+ configure_windows_cuda_dll_directories,
+ model_cache_directory,
+ model_files_ready,
+)
+
+
+MODEL_SPECS = (
+ (
+ PRIMARY_TRANSCRIPTION_MODEL,
+ PRIMARY_TRANSCRIPTION_MODEL_REPOSITORY,
+ PRIMARY_TRANSCRIPTION_MODEL_REVISION,
+ PRIMARY_TRANSCRIPTION_MODEL_BIN_SIZE,
+ PRIMARY_TRANSCRIPTION_MODEL_BIN_SHA256,
+ "GPU 主模型",
+ ),
+ (
+ CPU_FALLBACK_TRANSCRIPTION_MODEL,
+ CPU_FALLBACK_TRANSCRIPTION_MODEL_REPOSITORY,
+ CPU_FALLBACK_TRANSCRIPTION_MODEL_REVISION,
+ CPU_FALLBACK_TRANSCRIPTION_MODEL_BIN_SIZE,
+ CPU_FALLBACK_TRANSCRIPTION_MODEL_BIN_SHA256,
+ "CPU 兜底模型",
+ ),
+)
+_MODEL_DOWNLOAD_ATTEMPTS = 20
+_CURL_DOWNLOAD_ATTEMPTS = 3
+_MODEL_BIN_PART_SIZE = 64 * 1024 * 1024
+_MODEL_BIN_DOWNLOAD_WORKERS = 8
+
+
+def parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(description="初始化 NiuMa Studio 完全离线转写模型。")
+ parser.add_argument("--cache-dir", default=str(settings.transcription_model_cache_dir))
+ parser.add_argument("--audio", default="", help="可选：真实音频路径，用于 GPU 推理冒烟。")
+ parser.add_argument("--seconds", type=int, default=20, help="真实音频冒烟截取秒数。")
+ return parser.parse_args()
+
+
+def _sha256_file(path: Path) -> str:
+ digest = hashlib.sha256()
+ with path.open("rb") as source:
+ for block in iter(lambda: source.read(4 * 1024 * 1024), b""):
+ digest.update(block)
+ return digest.hexdigest()
+
+
+def _download_model_bin_part(url: str, target: Path, start: int, end: int) -> int:
+ if shutil.which("curl"):
+ try:
+ return _download_model_bin_part_with_curl(url, target, start, end)
+ except Exception as exc:
+ print(
+ f"官方模型分片 curl 连续失败，切换 Python Range 续传：{start}-{end}；{exc}",
+ flush=True,
+ )
+ return _download_model_bin_part_with_urllib(url, target, start, end)
+
+
+def _append_download_tail(target: Path, tail: Path, expected_size: int) -> None:
+ if not tail.exists():
+ return
+ current_size = target.stat().st_size if target.exists() else 0
+ if current_size + tail.stat().st_size > expected_size:
+ tail.unlink()
+ raise RuntimeError(f"官方模型分片响应超过预期大小：{target.name}")
+ with target.open("ab" if current_size else "wb") as output, tail.open("rb") as source:
+ shutil.copyfileobj(source, output, length=1024 * 1024)
+ tail.unlink()
+
+
+def _download_model_bin_part_with_curl(url: str, target: Path, start: int, end: int) -> int:
+ expected_size = end - start + 1
+ tail = target.with_suffix(".download")
+ _append_download_tail(target, tail, expected_size)
+ proxy = getproxies().get("https") or getproxies().get("http") or ""
+ child_environment = os.environ.copy()
+ if proxy:
+ child_environment["HTTPS_PROXY"] = proxy
+ for attempt in range(1, _CURL_DOWNLOAD_ATTEMPTS + 1):
+ current_size = target.stat().st_size if target.exists() else 0
+ if current_size == expected_size:
+ return expected_size
+ if current_size > expected_size:
+ target.unlink()
+ current_size = 0
+
+ request_start = start + current_size
+ command = [
+ "curl",
+ "--location",
+ "--fail",
+ "--silent",
+ "--show-error",
+ "--connect-timeout",
+ "20",
+ "--max-time",
+ "60",
+ "--range",
+ f"{request_start}-{end}",
+ "--output",
+ str(tail),
+ ]
+ command.append(url)
+ result = subprocess.run(
+ command,
+ capture_output=True,
+ text=True,
+ check=False,
+ env=child_environment,
+ )
+ _append_download_tail(target, tail, expected_size)
+ updated_size = target.stat().st_size if target.exists() else 0
+ if updated_size == expected_size:
+ return expected_size
+ if attempt >= _CURL_DOWNLOAD_ATTEMPTS:
+ raise RuntimeError(
+ f"官方模型分片 curl 下载失败：{start}-{end}；"
+ f"exit={result.returncode}，error={result.stderr.strip()[:300]}"
+ )
+ time.sleep(min(20, attempt * 3))
+ raise RuntimeError(f"官方模型分片 curl 下载失败：{start}-{end}")
+
+
+def _download_model_bin_part_with_urllib(url: str, target: Path, start: int, end: int) -> int:
+ expected_size = end - start + 1
+ for attempt in range(1, _MODEL_DOWNLOAD_ATTEMPTS + 1):
+ current_size = target.stat().st_size if target.exists() else 0
+ if current_size == expected_size:
+ return expected_size
+ if current_size > expected_size:
+ target.unlink()
+ current_size = 0
+
+ request_start = start + current_size
+ request = Request(
+ url,
+ headers={
+ "Range": f"bytes={request_start}-{end}",
+ "User-Agent": "NiuMa-Studio-offline-transcription-setup/1.0",
+ },
+ )
+ try:
+ with urlopen(request, timeout=120) as response:
+ if getattr(response, "status", 0) != 206:
+ raise RuntimeError(f"官方模型分片接口未返回 206：{getattr(response, 'status', 0)}")
+ with target.open("ab" if current_size else "wb") as output:
+ while True:
+ block = response.read(1024 * 1024)
+ if not block:
+ break
+ output.write(block)
+ except Exception:
+ if attempt >= _MODEL_DOWNLOAD_ATTEMPTS:
+ raise
+ time.sleep(min(20, attempt * 3))
+ continue
+
+ if target.stat().st_size == expected_size:
+ return expected_size
+ raise RuntimeError(f"官方模型分片下载失败：{start}-{end}")
+
+
+def _download_verified_model_bin(
+ target_dir: Path,
+ repository: str,
+ revision: str,
+ expected_size: int,
+ expected_sha256: str,
+ label: str,
+) -> Path:
+ target = target_dir / "model.bin"
+ if target.is_file():
+ if target.stat().st_size != expected_size:
+ raise RuntimeError(f"{label} 已有 model.bin 大小异常，请人工移走后重新初始化：{target}")
+ if _sha256_file(target) != expected_sha256:
+ raise RuntimeError(f"{label} 已有 model.bin SHA-256 不一致，请人工检查：{target}")
+ print(f"[{label}] model.bin 已存在且 SHA-256 校验通过")
+ return target
+
+ part_dir = target_dir / ".model-bin-parts"
+ part_dir.mkdir(parents=True, exist_ok=True)
+ url = f"https://huggingface.co/{repository}/resolve/{revision}/model.bin?download=true"
+ ranges: list[tuple[int, int, Path]] = []
+ for index, start in enumerate(range(0, expected_size, _MODEL_BIN_PART_SIZE)):
+ end = min(expected_size - 1, start + _MODEL_BIN_PART_SIZE - 1)
+ ranges.append((start, end, part_dir / f"part-{index:04d}.bin"))
+
+ completed_bytes = sum(
+ end - start + 1
+ for start, end, part in ranges
+ if part.is_file() and part.stat().st_size == end - start + 1
+ )
+ print(
+ f"[{label}] 从 Hugging Face 官方固定 revision 下载 model.bin："
+ f"{completed_bytes}/{expected_size} 字节已缓存",
+ flush=True,
+ )
+ failures: list[Exception] = []
+ with ThreadPoolExecutor(max_workers=min(_MODEL_BIN_DOWNLOAD_WORKERS, len(ranges))) as executor:
+ future_to_range = {
+ executor.submit(_download_model_bin_part, url, part, start, end): (start, end)
+ for start, end, part in ranges
+ }
+ finished_parts = 0
+ for future in as_completed(future_to_range):
+ try:
+ future.result()
+ except Exception as exc:
+ failures.append(exc)
+ print(f"[{label}] 一个分片仍未完成，其他分片继续：{exc}", flush=True)
+ else:
+ finished_parts += 1
+ print(
+ f"[{label}] 官方 model.bin 分片完成：{finished_parts}/{len(ranges)}",
+ flush=True,
+ )
+ if failures:
+ raise RuntimeError(
+ f"{label} 仍有 {len(failures)} 个分片未完成；已保留全部分片，下次运行只补缺失字节。"
+ ) from failures[0]
+
+ temporary = target.with_suffix(".bin.tmp")
+ digest = hashlib.sha256()
+ total_size = 0
+ with temporary.open("wb") as output:
+ for _start, _end, part in ranges:
+ with part.open("rb") as source:
+ while True:
+ block = source.read(4 * 1024 * 1024)
+ if not block:
+ break
+ output.write(block)
+ digest.update(block)
+ total_size += len(block)
+ actual_sha256 = digest.hexdigest()
+ if total_size != expected_size or actual_sha256 != expected_sha256:
+ temporary.unlink(missing_ok=True)
+ raise RuntimeError(
+ f"{label} model.bin 完整性校验失败：size={total_size}/{expected_size}，"
+ f"sha256={actual_sha256}/{expected_sha256}"
+ )
+ temporary.replace(target)
+ for _start, _end, part in ranges:
+ part.unlink(missing_ok=True)
+ try:
+ part_dir.rmdir()
+ except OSError:
+ pass
+ print(f"[{label}] model.bin 官方 SHA-256 校验通过：{actual_sha256}")
+ return target
+
+
+def download_model(
+ model_name: str,
+ repository: str,
+ revision: str,
+ model_bin_size: int,
+ model_bin_sha256: str,
+ label: str,
+) -> Path:
+ from huggingface_hub import snapshot_download
+
+ target = model_cache_directory(model_name, revision)
+ target.mkdir(parents=True, exist_ok=True)
+ print(f"[{label}] 固定版本：{repository}@{revision}")
+ print(f"[{label}] 本地目录：{target}")
+ for attempt in range(1, _MODEL_DOWNLOAD_ATTEMPTS + 1):
+ try:
+ snapshot_download(
+ repo_id=repository,
+ revision=revision,
+ local_dir=target,
+ allow_patterns=[
+ name
+ for name in (*REQUIRED_MODEL_FILES, *MODEL_VOCABULARY_FILES, *OPTIONAL_MODEL_FILES)
+ if name != "model.bin"
+ ],
+ max_workers=2,
+ )
+ break
+ except Exception as exc:
+ if attempt >= _MODEL_DOWNLOAD_ATTEMPTS:
+ raise RuntimeError(
+ f"{label} 固定版本下载连续 {_MODEL_DOWNLOAD_ATTEMPTS} 次失败，"
+ "已保留本地缓存，可稍后重新运行脚本继续。"
+ ) from exc
+ delay_seconds = min(30, attempt * 5)
+ print(
+ f"[{label}] 第 {attempt}/{_MODEL_DOWNLOAD_ATTEMPTS} 次下载中断：{exc}。"
+ f"保留缓存，{delay_seconds} 秒后重试。",
+ flush=True,
+ )
+ time.sleep(delay_seconds)
+ _download_verified_model_bin(
+ target,
+ repository,
+ revision,
+ model_bin_size,
+ model_bin_sha256,
+ label,
+ )
+ if not model_files_ready(target):
+ missing = [name for name in REQUIRED_MODEL_FILES if not (target / name).is_file()]
+ if not any((target / name).is_file() for name in MODEL_VOCABULARY_FILES):
+ missing.append("vocabulary.json 或 vocabulary.txt")
+ raise RuntimeError(f"{label} 缓存不完整，缺少：{', '.join(missing)}")
+ return target
+
+
+def write_manifest(cache_dir: Path, model_paths: dict[str, Path]) -> Path:
+ payload = {
+ "schema_version": 1,
+ "created_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+ "models": [
+ {
+ "name": model_name,
+ "repository": repository,
+ "revision": revision,
+ "model_bin_size": model_bin_size,
+ "model_bin_sha256": model_bin_sha256,
+ "path": str(model_paths[model_name]),
+ }
+ for model_name, repository, revision, model_bin_size, model_bin_sha256, _label in MODEL_SPECS
+ ],
+ }
+ target = cache_dir / "offline-transcription-manifest.json"
+ temporary = target.with_suffix(".json.tmp")
+ temporary.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+ temporary.replace(target)
+ return target
+
+
+def extract_smoke_audio(source: Path, target: Path, seconds: int) -> None:
+ command = [
+ "ffmpeg",
+ "-y",
+ "-nostdin",
+ "-loglevel",
+ "error",
+ "-i",
+ str(source),
+ "-t",
+ str(max(1, seconds)),
+ "-ar",
+ "16000",
+ "-ac",
+ "1",
+ str(target),
+ ]
+ result = subprocess.run(
+ command,
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ errors="replace",
+ check=False,
+ )
+ if result.returncode != 0:
+ raise RuntimeError(result.stderr.strip() or "FFmpeg 冒烟音频截取失败")
+
+
+def verify_gpu_model(primary_path: Path, audio_path: Path | None, seconds: int) -> None:
+ dll_status = configure_windows_cuda_dll_directories()
+ if not dll_status["cublas_ready"] or not dll_status["cudnn_ready"]:
+ raise RuntimeError(
+ "Windows GPU 运行库未就绪："
+ f"cuBLAS={dll_status['cublas_ready']}，cuDNN={dll_status['cudnn_ready']}"
+ )
+
+ from faster_whisper import WhisperModel
+
+ model = WhisperModel(str(primary_path), device="cuda", compute_type="float16")
+ print("GPU 主模型加载成功：large-v3 / cuda / float16")
+ if audio_path is None:
+ print("未提供 --audio，本次只验证模型加载，未执行真实语音推理。")
+ return
+
+ if not audio_path.is_file():
+ raise RuntimeError(f"真实冒烟音频不存在：{audio_path}")
+ with TemporaryDirectory(prefix="niuma_local_asr_smoke_") as temp_dir:
+ clip_path = Path(temp_dir) / "smoke.wav"
+ extract_smoke_audio(audio_path, clip_path, seconds)
+ segments, _info = model.transcribe(
+ str(clip_path),
+ language="zh",
+ vad_filter=True,
+ beam_size=5,
+ word_timestamps=True,
+ )
+ results = list(segments)
+ if not results:
+ raise RuntimeError("真实 GPU 冒烟完成，但没有识别到语音")
+ print(f"真实 GPU 冒烟成功：识别到 {len(results)} 句")
+ for segment in results[:5]:
+ print(f"{segment.start:.1f}-{segment.end:.1f}: {segment.text.strip()}")
+
+
+def verify_cpu_fallback_model(fallback_path: Path) -> None:
+ from faster_whisper import WhisperModel
+
+ WhisperModel(str(fallback_path), device="cpu", compute_type="int8")
+ print("CPU 兜底模型加载成功：medium / cpu / int8")
+
+
+def main() -> None:
+ args = parse_args()
+ cache_dir = Path(args.cache_dir).expanduser().resolve()
+ cache_dir.mkdir(parents=True, exist_ok=True)
+ object.__setattr__(settings, "transcription_model_cache_dir", cache_dir)
+
+ model_paths: dict[str, Path] = {}
+ for model_name, repository, revision, model_bin_size, model_bin_sha256, label in MODEL_SPECS:
+ model_paths[model_name] = download_model(
+ model_name,
+ repository,
+ revision,
+ model_bin_size,
+ model_bin_sha256,
+ label,
+ )
+
+ manifest_path = write_manifest(cache_dir, model_paths)
+ verify_gpu_model(
+ model_paths[PRIMARY_TRANSCRIPTION_MODEL],
+ Path(args.audio).expanduser().resolve() if args.audio else None,
+ args.seconds,
+ )
+ verify_cpu_fallback_model(model_paths[CPU_FALLBACK_TRANSCRIPTION_MODEL])
+ print(f"离线模型清单：{manifest_path}")
+ print("初始化完成。运行时可断网加载，不会上传音频。")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/test_ai_retry.py b/tests/test_ai_retry.py
new file mode 100644
index 0000000..9269975
--- /dev/null
+++ b/tests/test_ai_retry.py
@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.db.database import get_connection
+from app.main import app
+from app.models.settings import AIConfigUpdate
+from app.models.task import TaskCreate, TaskStatus
+from app.services import job_service, task_service
+from app.services.pipeline_checkpoint_service import AUTO_PIPELINE_CHECKPOINT_KIND
+from app.services.pipeline_engine import PipelineEngine
+from app.services.storage_service import get_artifact_paths
+from app.services.task_lifecycle_service import create_task_record
+
+
+client = TestClient(app)
+
+
+@pytest.fixture(autouse=True)
+def cleanup_ai_retry_data():
+ yield
+ pattern = "test-ai-retry-%"
+ with get_connection() as connection:
+ task_ids = [
+ str(row["id"])
+ for row in connection.execute(
+ "SELECT id FROM tasks WHERE id LIKE ?",
+ (pattern,),
+ ).fetchall()
+ ]
+ connection.execute("DELETE FROM publish_jobs WHERE task_id LIKE ?", (pattern,))
+ connection.execute("DELETE FROM output_clip WHERE task_id LIKE ?", (pattern,))
+ connection.execute("DELETE FROM clip_candidates WHERE task_id LIKE ?", (pattern,))
+ connection.execute("DELETE FROM ai_analysis_windows WHERE task_id LIKE ?", (pattern,))
+ connection.execute("DELETE FROM ai_analysis_runs WHERE task_id LIKE ?", (pattern,))
+ connection.execute("DELETE FROM workflow_jobs WHERE task_id LIKE ?", (pattern,))
+ connection.execute("DELETE FROM tasks WHERE id LIKE ?", (pattern,))
+ connection.commit()
+ for task_id in task_ids:
+ shutil.rmtree(get_artifact_paths(task_id)["task_dir"], ignore_errors=True)
+
+
+def _create_task(task_id: str) -> None:
+ create_task_record(
+ TaskCreate(
+ task_name=task_id,
+ source_type="upload",
+ platform="general",
+ selection_profile="variety_comedy",
+ auto_mode=True,
+ ),
+ task_id=task_id,
+ task_dir_name=task_id,
+ )
+
+
+def _sha256(value: bytes) -> str:
+ return hashlib.sha256(value).hexdigest()
+
+
+def _failed_job(task_id: str, transcript: bytes = b"original transcript") -> dict:
+ paths = get_artifact_paths(task_id)
+ paths["transcript_path"].parent.mkdir(parents=True, exist_ok=True)
+ paths["transcript_path"].write_bytes(transcript)
+ job = job_service.create_job(
+ task_id,
+ job_service.JOB_TYPE_AUTO_PIPELINE,
+ payload={"retry": False, "start_step": None},
+ )
+ checkpoint = {
+ "kind": AUTO_PIPELINE_CHECKPOINT_KIND,
+ "task_id": task_id,
+ "run_key": "test-run-key",
+ "start_step": TaskStatus.PREPARING_SOURCE.value,
+ "current_step": TaskStatus.CLIP_SELECTING.value,
+ "completed_steps": [
+ TaskStatus.PREPARING_SOURCE.value,
+ TaskStatus.TRANSCRIBING.value,
+ TaskStatus.AI_ANALYZING.value,
+ ],
+ "steps": {
+ TaskStatus.PREPARING_SOURCE.value: {
+ "state": "succeeded",
+ "attempts": 1,
+ "outputs": {},
+ },
+ TaskStatus.TRANSCRIBING.value: {
+ "state": "succeeded",
+ "attempts": 1,
+ "outputs": {"transcript": {"sha256": _sha256(transcript)}},
+ },
+ TaskStatus.AI_ANALYZING.value: {
+ "state": "succeeded",
+ "attempts": 1,
+ "outputs": {},
+ },
+ TaskStatus.CLIP_SELECTING.value: {
+ "state": "failed",
+ "attempts": 1,
+ "outputs": {},
+ "error": "analysis incomplete",
+ },
+ },
+ "last_error": "analysis incomplete",
+ "_ai_analysis_units_v1": {
+ "namespaces": {
+ "variety_recall": {
+ "input_fingerprint": "input-v1",
+ "units": {
+ "window_001": {
+ "status": "completed",
+ "result_json": "{}",
+ "result_checksum": _sha256(b"{}"),
+ },
+ "window_004": {
+ "status": "uncertain",
+ "error": "Codex CLI timeout; billing uncertain",
+ },
+ },
+ }
+ }
+ },
+ }
+ with get_connection() as connection:
+ connection.execute(
+ """
+ UPDATE workflow_jobs
+ SET status = ?, checkpoint_json = ?, error_message = 'analysis incomplete'
+ WHERE id = ?
+ """,
+ (job_service.JOB_STATUS_FAILED, json.dumps(checkpoint), job["id"]),
+ )
+ connection.execute(
+ "UPDATE tasks SET status = ? WHERE id = ?",
+ (TaskStatus.FAILED_CLIP_SELECTING.value, task_id),
+ )
+ connection.commit()
+ return job_service.get_job(job["id"])
+
+
+def test_retry_requires_structured_confirmation() -> None:
+ assert AIConfigUpdate().ai_codex_timeout_seconds == 600
+ task_id = "test-ai-retry-confirm"
+ _create_task(task_id)
+ old_job = _failed_job(task_id)
+
+ response = client.post(f"/api/tasks/{task_id}/process/auto-retry")
+
+ assert response.status_code == 409
+ detail = response.json()["detail"]
+ assert detail["code"] == "ai_retry_confirmation_required"
+ assert detail["uncertain_unit_count"] == 1
+ assert detail["retry_mode"] == "resume_uncertain"
+ assert detail["previous_job_id"] == old_job["id"]
+
+
+def test_confirmed_same_input_retries_only_uncertain_unit() -> None:
+ task_id = "test-ai-retry-resume"
+ _create_task(task_id)
+ old_job = _failed_job(task_id)
+
+ response = client.post(
+ f"/api/tasks/{task_id}/process/auto-retry?confirm_uncertain_ai=true"
+ )
+
+ assert response.status_code == 200
+ payload = response.json()
+ assert payload["job_id"] == old_job["id"]
+ assert payload["retry_mode"] == "resume_uncertain"
+ stored = job_service.get_job(old_job["id"])
+ units = stored["checkpoint_json"]["_ai_analysis_units_v1"]["namespaces"]["variety_recall"]["units"]
+ assert units["window_001"]["status"] == "completed"
+ assert units["window_004"]["status"] == "retryable_failed"
+ assert units["window_004"]["retry_authorized_reason"] == "explicit_user_confirmation"
+ assert stored["checkpoint_json"]["completed_steps"] == [
+ TaskStatus.PREPARING_SOURCE.value,
+ TaskStatus.TRANSCRIBING.value,
+ ]
+ assert stored["checkpoint_json"]["current_step"] == TaskStatus.AI_ANALYZING.value
+ assert task_service.get_task(task_id, include_video_probe=False)["status"] == TaskStatus.FAILED_AI_ANALYZING.value
+
+
+def test_confirmed_changed_input_creates_fresh_ai_job_and_preserves_old_evidence() -> None:
+ task_id = "test-ai-retry-fresh"
+ _create_task(task_id)
+ old_job = _failed_job(task_id)
+ old_checkpoint = old_job["checkpoint_json"]
+ get_artifact_paths(task_id)["transcript_path"].write_bytes(b"simplified transcript")
+
+ response = client.post(
+ f"/api/tasks/{task_id}/process/auto-retry?confirm_uncertain_ai=true"
+ )
+
+ assert response.status_code == 200
+ payload = response.json()
+ assert payload["retry_mode"] == "fresh_ai"
+ assert payload["job_id"] != old_job["id"]
+ new_job = job_service.get_job(payload["job_id"])
+ assert new_job["payload_json"]["start_step"] == TaskStatus.AI_ANALYZING.value
+ assert new_job["checkpoint_json"] == {}
+ preserved = job_service.get_job(old_job["id"])
+ assert preserved["status"] == job_service.JOB_STATUS_FAILED
+ assert preserved["checkpoint_json"] == old_checkpoint
+ assert task_service.get_task(task_id, include_video_probe=False)["status"] == TaskStatus.FAILED_AI_ANALYZING.value
+
+
+def test_retry_refuses_existing_downstream_records() -> None:
+ task_id = "test-ai-retry-downstream"
+ _create_task(task_id)
+ _failed_job(task_id)
+ now = task_service._now_iso()
+ with get_connection() as connection:
+ connection.execute(
+ """
+ INSERT INTO output_clip (
+ id, task_id, output_file_path, output_file_name, status,
+ created_at, updated_at
+ ) VALUES ('output-existing', ?, 'clip.mp4', 'clip.mp4', 'completed', ?, ?)
+ """,
+ (task_id, now, now),
+ )
+ connection.commit()
+
+ response = client.post(f"/api/tasks/{task_id}/process/auto-retry")
+
+ assert response.status_code == 409
+ assert response.json()["detail"]["code"] == "ai_retry_downstream_conflict"
+
+
+def test_incomplete_analysis_fails_in_ai_stage(monkeypatch) -> None:
+ task_id = "test-ai-retry-incomplete-stage"
+ _create_task(task_id)
+ incomplete_meta = {
+ "analysis_incomplete": True,
+ "coverage_ratio": 0.9444,
+ "coverage_percent": 94.44,
+ }
+ monkeypatch.setattr(
+ task_service,
+ "process_task_ai_analysis",
+ lambda _task_id: {
+ "clips": [{"clip_id": "one"}],
+ "analysis_run_id": "run-one",
+ "analysis_path": "candidate_clips.json",
+ "analysis_run": {"analysis_meta": incomplete_meta},
+ },
+ )
+ monkeypatch.setattr(
+ task_service,
+ "validate_ai_analysis_meta_for_cut",
+ lambda meta, _profile: meta,
+ )
+
+ result = PipelineEngine().run(
+ task_id,
+ retry=True,
+ start_step=TaskStatus.AI_ANALYZING,
+ )
+
+ assert result["failed_step"] == TaskStatus.AI_ANALYZING.value
+ assert result["failed_status"] == TaskStatus.FAILED_AI_ANALYZING.value
+ assert task_service.get_task(task_id, include_video_probe=False)["status"] == TaskStatus.FAILED_AI_ANALYZING.value
diff --git a/tests/test_offline_transcription.py b/tests/test_offline_transcription.py
new file mode 100644
index 0000000..48e3568
--- /dev/null
+++ b/tests/test_offline_transcription.py
@@ -0,0 +1,584 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+import hashlib
+import io
+from pathlib import Path
+import sys
+from types import SimpleNamespace
+
+import pytest
+from fastapi.testclient import TestClient
+from pydantic import ValidationError
+
+from app.core.config import settings
+from app.core.transcription_defaults import (
+ CPU_FALLBACK_TRANSCRIPTION_MODEL_REVISION,
+ PRIMARY_TRANSCRIPTION_MODEL_REVISION,
+)
+from app.main import app
+from app.models.settings import AIConfigUpdate
+from app.services import local_transcription_runtime, transcript_service
+from app.services.local_transcription_runtime import (
+ MODEL_VOCABULARY_FILES,
+ REQUIRED_MODEL_FILES,
+ TranscriptionOfflinePolicyError,
+ get_local_transcription_runtime_status,
+ model_cache_directory,
+ model_files_ready,
+ model_identity,
+ resolve_local_model_source,
+)
+from app.services.transcript_service import TranscriptChunk
+from app.services.transcript_workflow_service import (
+ get_task_transcript_status,
+ validate_transcription_provider_choice,
+)
+from app.services.transcription_checkpoint_service import (
+ TranscriptionCheckpoint,
+ fingerprint_file_full,
+)
+from scripts import setup_local_transcription
+from scripts.normalize_transcript_simplified import normalize_transcript_file
+
+
+@contextmanager
+def _override_settings(**values):
+ previous = {name: getattr(settings, name) for name in values}
+ try:
+ for name, value in values.items():
+ object.__setattr__(settings, name, value)
+ yield
+ finally:
+ for name, value in previous.items():
+ object.__setattr__(settings, name, value)
+
+
+def _write_model_files(target: Path) -> None:
+ target.mkdir(parents=True, exist_ok=True)
+ for name in REQUIRED_MODEL_FILES:
+ (target / name).write_bytes(b"test")
+ (target / MODEL_VOCABULARY_FILES[0]).write_bytes(b"test")
+
+
+def test_default_transcription_configuration_is_fully_offline_local() -> None:
+ assert settings.transcription_provider == "local"
+ assert settings.transcription_fallback_provider == ""
+ assert settings.transcription_offline_only is True
+ assert settings.transcription_local_files_only is True
+ assert settings.transcription_model == "large-v3"
+ assert settings.transcription_model_revision == PRIMARY_TRANSCRIPTION_MODEL_REVISION
+ assert settings.transcription_device == "cuda"
+ assert settings.transcription_compute_type == "float16"
+ assert settings.transcription_chunk_seconds == 120
+ assert settings.transcription_chunk_overlap_seconds == 5
+
+
+def test_local_transcription_converts_segments_and_words_to_simplified(tmp_path) -> None:
+ class FakeModel:
+ def transcribe(self, *_args, **_kwargs):
+ word_items = [
+ SimpleNamespace(start=0.0, end=0.5, word="老師", probability=0.9),
+ SimpleNamespace(start=0.5, end=1.0, word="計程車", probability=0.8),
+ SimpleNamespace(start=1.0, end=1.5, word=" ABC-123 ", probability=0.7),
+ ]
+ segment = SimpleNamespace(
+ start=0.0,
+ end=1.5,
+ text="老師讓計程車載著軟體 ABC-123",
+ words=word_items,
+ avg_logprob=-0.1,
+ )
+ return [segment], SimpleNamespace()
+
+ result = transcript_service._transcribe_audio_with_model(FakeModel(), tmp_path / "audio.wav")
+
+ assert result[0].text == "老师让计程车载著软体 ABC-123"
+ assert [word.text for word in result[0].words] == ["老师", "计程车", "ABC-123"]
+ assert "计程车" in result[0].text
+ assert "软体" in result[0].text
+
+
+def test_transcript_file_conversion_backs_up_and_preserves_markdown_structure(tmp_path) -> None:
+ transcript_path = tmp_path / "transcript.md"
+ original = (
+ "# 逐句時間戳原文\r\n\r\n"
+ "| 開始 | 結束 | 文本 |\r\n"
+ "| --- | --- | --- |\r\n"
+ "| 00:00:01 | 00:00:03 | 老師搭計程車，使用軟體。 |\r\n"
+ )
+ transcript_path.write_bytes(original.encode("utf-8"))
+
+ result = normalize_transcript_file(transcript_path, tmp_path / "backups")
+
+ converted = transcript_path.read_text(encoding="utf-8")
+ assert "老师搭计程车，使用软体。" in converted
+ assert len(converted.splitlines()) == len(original.splitlines())
+ assert Path(result["backup_path"]).read_bytes() == original.encode("utf-8")
+ assert result["before_sha256"] != result["after_sha256"]
+
+
+def test_offline_config_rejects_remote_provider_and_network_model_loading() -> None:
+ with pytest.raises(ValidationError, match="转写方式必须为 local"):
+ AIConfigUpdate(transcription_provider="volcengine")
+ with pytest.raises(ValidationError, match="必须只读取本地模型文件"):
+ AIConfigUpdate(transcription_local_files_only=False)
+
+
+def test_provider_resolver_uses_local_and_blocks_explicit_remote() -> None:
+ with _override_settings(transcription_provider="local", transcription_offline_only=True):
+ assert validate_transcription_provider_choice() == "local"
+ with pytest.raises(TranscriptionOfflinePolicyError, match="完全离线"):
+ validate_transcription_provider_choice("volcengine")
+ with pytest.raises(TranscriptionOfflinePolicyError, match="完全离线"):
+ validate_transcription_provider_choice("remote")
+
+
+@pytest.mark.parametrize(
+ "endpoint",
+ (
+ "/api/tasks/not-needed/process/transcript?provider=volcengine",
+ "/api/tasks/not-needed/process/transcript-workflow?provider=volcengine",
+ ),
+)
+def test_explicit_volcengine_request_returns_409_before_job_creation(monkeypatch, endpoint) -> None:
+ called = False
+
+ def unexpected_job(*_args, **_kwargs):
+ nonlocal called
+ called = True
+ raise AssertionError("离线锁开启时不应创建远程转写 Job")
+
+ monkeypatch.setattr("app.routers.tasks.job_service.create_or_get_active_job", unexpected_job)
+ with _override_settings(transcription_provider="local", transcription_offline_only=True):
+ response = TestClient(app).post(endpoint)
+
+ assert response.status_code == 409
+ assert "完全离线" in response.json()["detail"]
+ assert called is False
+
+
+def test_remote_transcription_guard_runs_before_http(monkeypatch, tmp_path) -> None:
+ requested = False
+
+ def unexpected_urlopen(*_args, **_kwargs):
+ nonlocal requested
+ requested = True
+ raise AssertionError("离线锁开启时不应发送 HTTP 请求")
+
+ monkeypatch.setattr(transcript_service, "urlopen", unexpected_urlopen)
+ audio_path = tmp_path / "audio.mp3"
+ audio_path.write_bytes(b"audio")
+ with _override_settings(transcription_offline_only=True):
+ with pytest.raises(TranscriptionOfflinePolicyError, match="完全离线"):
+ transcript_service.transcribe_audio_with_provider(
+ audio_path,
+ tmp_path,
+ tmp_path / "progress.json",
+ "volcengine",
+ )
+
+ assert requested is False
+
+
+def test_missing_model_never_downloads_during_task(tmp_path) -> None:
+ with _override_settings(
+ transcription_model_cache_dir=tmp_path,
+ transcription_offline_only=True,
+ transcription_local_files_only=True,
+ ):
+ with pytest.raises(RuntimeError, match="不会联网下载"):
+ resolve_local_model_source("large-v3", PRIMARY_TRANSCRIPTION_MODEL_REVISION)
+
+
+def test_medium_repository_file_set_with_text_vocabulary_is_ready(tmp_path) -> None:
+ with _override_settings(transcription_model_cache_dir=tmp_path):
+ target = model_cache_directory("medium", CPU_FALLBACK_TRANSCRIPTION_MODEL_REVISION)
+ target.mkdir(parents=True, exist_ok=True)
+ for name in REQUIRED_MODEL_FILES:
+ (target / name).write_bytes(b"test")
+ (target / "vocabulary.txt").write_bytes(b"test")
+
+ assert model_files_ready(target) is True
+ assert resolve_local_model_source("medium", CPU_FALLBACK_TRANSCRIPTION_MODEL_REVISION) == str(target)
+
+
+def test_official_model_bin_range_download_resumes_partial_file(monkeypatch, tmp_path) -> None:
+ target = tmp_path / "part.bin"
+ target.write_bytes(b"abc")
+ requested_range = ""
+
+ class FakeResponse:
+ status = 206
+
+ def __init__(self):
+ self.stream = io.BytesIO(b"defghij")
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *_args):
+ return False
+
+ def read(self, size):
+ return self.stream.read(size)
+
+ def fake_urlopen(request, timeout):
+ nonlocal requested_range
+ assert timeout == 120
+ requested_range = request.get_header("Range")
+ return FakeResponse()
+
+ monkeypatch.setattr(setup_local_transcription, "urlopen", fake_urlopen)
+
+ size = setup_local_transcription._download_model_bin_part_with_urllib(
+ "https://huggingface.co/example/model.bin",
+ target,
+ 100,
+ 109,
+ )
+
+ assert size == 10
+ assert requested_range == "bytes=103-109"
+ assert target.read_bytes() == b"abcdefghij"
+
+
+def test_model_bin_part_falls_back_to_urllib_after_curl_failure(monkeypatch, tmp_path) -> None:
+ target = tmp_path / "part.bin"
+ calls: list[str] = []
+
+ monkeypatch.setattr(setup_local_transcription.shutil, "which", lambda _name: "curl.exe")
+
+ def failed_curl(*_args, **_kwargs):
+ calls.append("curl")
+ raise RuntimeError("curl failed")
+
+ def successful_urllib(*_args, **_kwargs):
+ calls.append("urllib")
+ return 10
+
+ monkeypatch.setattr(setup_local_transcription, "_download_model_bin_part_with_curl", failed_curl)
+ monkeypatch.setattr(setup_local_transcription, "_download_model_bin_part_with_urllib", successful_urllib)
+
+ assert setup_local_transcription._download_model_bin_part("https://example.test/model", target, 0, 9) == 10
+ assert calls == ["curl", "urllib"]
+
+
+def test_existing_model_bin_requires_matching_official_sha256(tmp_path) -> None:
+ payload = b"fixed official model"
+ (tmp_path / "model.bin").write_bytes(payload)
+
+ result = setup_local_transcription._download_verified_model_bin(
+ tmp_path,
+ "Systran/test-model",
+ "a" * 40,
+ len(payload),
+ hashlib.sha256(payload).hexdigest(),
+ "测试模型",
+ )
+
+ assert result == tmp_path / "model.bin"
+
+
+def test_runtime_status_reports_cached_model_and_gpu(monkeypatch, tmp_path) -> None:
+ with _override_settings(
+ transcription_provider="local",
+ transcription_model_cache_dir=tmp_path,
+ transcription_device="cuda",
+ ):
+ _write_model_files(model_cache_directory("large-v3", PRIMARY_TRANSCRIPTION_MODEL_REVISION))
+ monkeypatch.setattr(
+ local_transcription_runtime,
+ "configure_windows_cuda_dll_directories",
+ lambda: {
+ "configured": True,
+ "cublas_ready": True,
+ "cudnn_ready": True,
+ "directories": [],
+ "errors": [],
+ },
+ )
+ import ctranslate2
+
+ monkeypatch.setattr(ctranslate2, "get_cuda_device_count", lambda: 1)
+ status = get_local_transcription_runtime_status()
+
+ assert status["model_ready"] is True
+ assert status["gpu_ready"] is True
+ assert status["ready"] is True
+ assert status["model_identity"] == "large-v3@edaa852e"
+ assert status["external_cost_yuan"] == 0
+
+
+@pytest.mark.skipif(sys.platform != "win32", reason="Windows DLL 搜索路径仅在 Windows 验证")
+def test_windows_dll_directories_include_venv_cublas_and_ctranslate2(monkeypatch, tmp_path) -> None:
+ fake_prefix = tmp_path / ".venv"
+ cublas_dir = fake_prefix / "Lib" / "site-packages" / "nvidia" / "cublas" / "bin"
+ ctranslate2_dir = tmp_path / "ctranslate2"
+ cublas_dir.mkdir(parents=True)
+ ctranslate2_dir.mkdir()
+ (cublas_dir / "cublasLt64_12.dll").write_bytes(b"dll")
+ (cublas_dir / "cublas64_12.dll").write_bytes(b"dll")
+ (ctranslate2_dir / "cudnn64_9.dll").write_bytes(b"dll")
+ added: list[str] = []
+
+ monkeypatch.setattr(local_transcription_runtime.sys, "prefix", str(fake_prefix))
+ monkeypatch.setattr(
+ local_transcription_runtime,
+ "_package_directory",
+ lambda _name: ctranslate2_dir,
+ )
+ monkeypatch.setattr(
+ local_transcription_runtime.os,
+ "add_dll_directory",
+ lambda path: added.append(path) or SimpleNamespace(close=lambda: None),
+ raising=False,
+ )
+ monkeypatch.setattr(local_transcription_runtime, "_DLL_DIRECTORY_HANDLES", [])
+ monkeypatch.setattr(local_transcription_runtime, "_DLL_DIRECTORY_PATHS", set())
+ monkeypatch.setattr(local_transcription_runtime, "_DLL_LIBRARY_HANDLES", [])
+ monkeypatch.setattr(local_transcription_runtime, "_DLL_LIBRARY_PATHS", set())
+ loaded: list[str] = []
+ monkeypatch.setattr(
+ local_transcription_runtime.ctypes,
+ "WinDLL",
+ lambda path: loaded.append(path) or SimpleNamespace(),
+ raising=False,
+ )
+
+ first = local_transcription_runtime.configure_windows_cuda_dll_directories()
+ second = local_transcription_runtime.configure_windows_cuda_dll_directories()
+
+ assert first["cublas_ready"] is True
+ assert first["cudnn_ready"] is True
+ assert second["configured"] is True
+ assert added == [str(cublas_dir), str(ctranslate2_dir)]
+ assert loaded == [
+ str(cublas_dir / "cublasLt64_12.dll"),
+ str(cublas_dir / "cublas64_12.dll"),
+ str(ctranslate2_dir / "cudnn64_9.dll"),
+ ]
+
+
+def test_cuda_load_failure_selects_versioned_cpu_fallback(monkeypatch, tmp_path) -> None:
+ calls: list[tuple[str, str, str]] = []
+
+ class FakeWhisperModel:
+ def __init__(self, model_source, *, device, compute_type, **_kwargs):
+ calls.append((str(model_source), device, compute_type))
+ if device == "cuda":
+ raise RuntimeError("cublas64_12.dll could not be loaded")
+
+ fake_module = SimpleNamespace(WhisperModel=FakeWhisperModel)
+ monkeypatch.setitem(sys.modules, "faster_whisper", fake_module)
+ monkeypatch.setattr(
+ transcript_service,
+ "configure_windows_cuda_dll_directories",
+ lambda: {"configured": True},
+ )
+ monkeypatch.setattr(transcript_service, "_WHISPER_MODEL", None)
+ monkeypatch.setattr(transcript_service, "_WHISPER_MODEL_KEY", None)
+ monkeypatch.setattr(transcript_service, "_EFFECTIVE_TRANSCRIPTION_MODEL_KEY", None)
+
+ with _override_settings(
+ transcription_model_cache_dir=tmp_path,
+ transcription_model="large-v3",
+ transcription_model_revision=PRIMARY_TRANSCRIPTION_MODEL_REVISION,
+ transcription_device="cuda",
+ transcription_compute_type="float16",
+ transcription_cpu_fallback_model="medium",
+ transcription_local_files_only=True,
+ ):
+ _write_model_files(model_cache_directory("large-v3", PRIMARY_TRANSCRIPTION_MODEL_REVISION))
+ _write_model_files(model_cache_directory("medium", CPU_FALLBACK_TRANSCRIPTION_MODEL_REVISION))
+ transcript_service._set_configured_transcription_runtime("local")
+ transcript_service._prepare_local_transcription_model_for_run()
+
+ assert [call[1:] for call in calls] == [("cuda", "float16"), ("cpu", "int8")]
+ assert transcript_service._EFFECTIVE_TRANSCRIPTION_MODEL_KEY == ("medium", "cpu", "int8")
+ assert transcript_service._ACTIVE_TRANSCRIPTION_MODEL == model_identity(
+ "medium",
+ CPU_FALLBACK_TRANSCRIPTION_MODEL_REVISION,
+ )
+ assert transcript_service._transcription_model_revision_label() == CPU_FALLBACK_TRANSCRIPTION_MODEL_REVISION
+
+
+def test_cuda_inference_failure_selects_cpu_before_checkpoint(monkeypatch, tmp_path) -> None:
+ calls: list[tuple[str, str, str]] = []
+
+ class FakeWhisperModel:
+ def __init__(self, model_source, *, device, compute_type, **_kwargs):
+ self.device = device
+ calls.append((str(model_source), device, compute_type))
+
+ def transcribe(self, *_args, **_kwargs):
+ if self.device == "cuda":
+ raise RuntimeError("CUDA failed to initialize during inference")
+ return iter(()), None
+
+ fake_module = SimpleNamespace(WhisperModel=FakeWhisperModel)
+ monkeypatch.setitem(sys.modules, "faster_whisper", fake_module)
+ monkeypatch.setattr(
+ transcript_service,
+ "configure_windows_cuda_dll_directories",
+ lambda: {"configured": True},
+ )
+ monkeypatch.setattr(transcript_service, "_WHISPER_MODEL", None)
+ monkeypatch.setattr(transcript_service, "_WHISPER_MODEL_KEY", None)
+ monkeypatch.setattr(transcript_service, "_EFFECTIVE_TRANSCRIPTION_MODEL_KEY", None)
+ audio_path = tmp_path / "audio.wav"
+ audio_path.write_bytes(b"audio")
+
+ with _override_settings(
+ transcription_model_cache_dir=tmp_path,
+ transcription_model="large-v3",
+ transcription_model_revision=PRIMARY_TRANSCRIPTION_MODEL_REVISION,
+ transcription_device="cuda",
+ transcription_compute_type="float16",
+ transcription_cpu_fallback_model="medium",
+ transcription_local_files_only=True,
+ ):
+ _write_model_files(model_cache_directory("large-v3", PRIMARY_TRANSCRIPTION_MODEL_REVISION))
+ _write_model_files(model_cache_directory("medium", CPU_FALLBACK_TRANSCRIPTION_MODEL_REVISION))
+ transcript_service._set_configured_transcription_runtime("local")
+ transcript_service._prepare_local_transcription_model_for_run(audio_path)
+
+ assert [call[1:] for call in calls] == [("cuda", "float16"), ("cpu", "int8")]
+ assert transcript_service._EFFECTIVE_TRANSCRIPTION_MODEL_KEY == ("medium", "cpu", "int8")
+ assert transcript_service._ACTIVE_TRANSCRIPTION_MODEL == model_identity(
+ "medium",
+ CPU_FALLBACK_TRANSCRIPTION_MODEL_REVISION,
+ )
+
+
+def test_transcript_status_exposes_offline_runtime_fields(monkeypatch, tmp_path) -> None:
+ transcript_path = tmp_path / "transcript.md"
+ monkeypatch.setattr(
+ "app.services.task_service.get_task",
+ lambda _task_id: {
+ "status": "pending_processing",
+ "status_label": "待处理",
+ "progress": 5,
+ "error_message": "",
+ },
+ )
+ monkeypatch.setattr(
+ "app.services.transcript_workflow_service.get_artifact_paths",
+ lambda _task_id: {"transcript_path": transcript_path},
+ )
+ monkeypatch.setattr(
+ "app.services.transcript_workflow_service.get_local_transcription_runtime_status",
+ lambda: {
+ "offline_only": True,
+ "model_ready": True,
+ "gpu_ready": True,
+ "model_revision": PRIMARY_TRANSCRIPTION_MODEL_REVISION,
+ },
+ )
+
+ status = get_task_transcript_status("offline-status-test")
+
+ assert status["offline_only"] is True
+ assert status["model_ready"] is True
+ assert status["gpu_ready"] is True
+ assert status["model_revision"] == PRIMARY_TRANSCRIPTION_MODEL_REVISION
+
+
+def test_model_revision_and_full_audio_hash_invalidate_checkpoint(tmp_path) -> None:
+ from datetime import datetime, timezone
+
+ from app.db.database import get_connection
+
+ task_id = "offline-model-revision-checkpoint"
+ source = tmp_path / "same-size.wav"
+ head = b"h" * (1024 * 1024)
+ tail = b"t" * (1024 * 1024)
+ source.write_bytes(head + (b"a" * (1024 * 1024)) + tail)
+ first_hash = fingerprint_file_full(source)
+ now = datetime.now(timezone.utc).isoformat(timespec="seconds")
+ chunks = [TranscriptChunk(1, 0, 120)]
+ with get_connection() as connection:
+ connection.execute(
+ """
+ INSERT INTO tasks (
+ id, task_name, task_dir_name, source_type, platform, selection_profile,
+ status, progress, is_deleted, created_at, updated_at
+ ) VALUES (?, 'offline checkpoint', ?, 'upload', 'general', 'long_live_talk',
+ 'pending_processing', 0, 0, ?, ?)
+ """,
+ (task_id, task_id, now, now),
+ )
+ connection.commit()
+ try:
+ first = TranscriptionCheckpoint(
+ task_id=task_id,
+ source_path=source,
+ provider="local",
+ model="large-v3@edaa852e",
+ device="cuda",
+ compute_type="float16",
+ chunk_seconds=120,
+ overlap_seconds=5,
+ )
+ first.ensure_run(chunks)
+ revision_changed = TranscriptionCheckpoint(
+ task_id=task_id,
+ source_path=source,
+ provider="local",
+ model="large-v3@12345678",
+ device="cuda",
+ compute_type="float16",
+ chunk_seconds=120,
+ overlap_seconds=5,
+ )
+ revision_changed.ensure_run(chunks)
+
+ normalization_changed = TranscriptionCheckpoint(
+ task_id=task_id,
+ source_path=source,
+ provider="local",
+ model="large-v3@edaa852e|text=opencc-t2s-v1",
+ device="cuda",
+ compute_type="float16",
+ chunk_seconds=120,
+ overlap_seconds=5,
+ )
+ normalization_changed.ensure_run(chunks)
+
+ source.write_bytes(head + (b"b" * (1024 * 1024)) + tail)
+ second_hash = fingerprint_file_full(source)
+ content_changed = TranscriptionCheckpoint(
+ task_id=task_id,
+ source_path=source,
+ provider="local",
+ model="large-v3@edaa852e",
+ device="cuda",
+ compute_type="float16",
+ chunk_seconds=120,
+ overlap_seconds=5,
+ )
+ content_changed.ensure_run(chunks)
+
+ assert first_hash != second_hash
+ assert revision_changed.run_id != first.run_id
+ assert normalization_changed.run_id != first.run_id
+ assert content_changed.run_id != first.run_id
+ with get_connection() as connection:
+ models = {
+ row["model"]
+ for row in connection.execute(
+ "SELECT model FROM transcription_runs WHERE task_id = ?",
+ (task_id,),
+ ).fetchall()
+ }
+ assert {
+ "large-v3@edaa852e",
+ "large-v3@12345678",
+ "large-v3@edaa852e|text=opencc-t2s-v1",
+ } <= models
+ finally:
+ with get_connection() as connection:
+ connection.execute("DELETE FROM transcription_chunks WHERE task_id = ?", (task_id,))
+ connection.execute("DELETE FROM transcription_runs WHERE task_id = ?", (task_id,))
+ connection.execute("DELETE FROM tasks WHERE id = ?", (task_id,))
+ connection.commit()