add whisper

sentence_api/DEPLOYMENT.md

@@ -3,7 +3,9 @@
 本文部署以下两个进程：
 
 - `oral-trainer-api`：视频上传、管理后台、边界查询、Range 视频播放和朗读评分。
-- `MOSS-Transcribe-Diarize`：GPU 转写服务，只在服务器内网监听。
+- GPU 转写服务（二选一，只在服务器内网监听）：
+  - `whisper/`：faster-whisper（Speaches），推荐，部署最简单，见第 2A 节。
+  - `MOSS-Transcribe-Diarize`：带说话人分离，见第 2 节。
 
 推荐 Ubuntu 22.04/24.04、Python 3.12、FFmpeg、NVIDIA GPU 和已安装的 NVIDIA 驱动。MOSS 0.9B 的实际显存占用受推理框架、并发和音频长度影响，生产环境建议从 16 GB 以上显存开始验证。
 
@@ -26,10 +28,56 @@
 | 服务 | 监听地址 | 用途 |
 | --- | --- | --- |
 | MOSS | `127.0.0.1:8001` | 内部语音转写 |
+| Whisper | `127.0.0.1:9000` | 内部语音转写（Whisper 方案，见第 2A 节） |
 | FastAPI | `127.0.0.1:8000` | 内部应用服务 |
 | Nginx | `0.0.0.0:443` | 对外 HTTPS |
 
-不要把 MOSS 的 `8001` 端口直接暴露到公网。
+不要把 MOSS/Whisper 的转写端口直接暴露到公网。
+
+## 2A. 部署 Whisper（推荐）
+
+基于 faster-whisper（Speaches）的 OpenAI 兼容转写服务，接口与 MOSS 相同
+（`POST /v1/audio/transcriptions`，支持 `verbose_json`），因此接入 `sentence_api`
+时应用代码无需改动。部署文件在仓库的 [`whisper/`](../whisper/) 目录。
+
+前置条件：Docker、NVIDIA 驱动（≥ 535，支持 CUDA 12.x）和 NVIDIA Container Toolkit。
+镜像自带 CUDA 12.6 运行时，宿主机不需要再装 CUDA。
+
+```bash
+sudo mkdir -p /opt/whisper
+sudo chown "$USER":"$USER" /opt/whisper
+cp -r whisper/* /opt/whisper/
+cd /opt/whisper
+
+cp .env.example .env          # 按需修改 WHISPER_MODEL
+docker compose up -d
+docker compose logs -f whisper   # 首次启动下载模型（约 3 GB）
+```
+
+验证：
+
+```bash
+/opt/whisper/verify.sh
+```
+
+注册为 systemd 服务（可选，模板位于 `whisper/systemd/`）：
+
+```bash
+sudo cp whisper/systemd/whisper-transcribe.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now whisper-transcribe
+sudo journalctl -u whisper-transcribe -f
+```
+
+接入 API 时，把 `.env` 改为：
+
+```dotenv
+MOSS_TRANSCRIBE_URL=http://127.0.0.1:9000/v1/audio/transcriptions
+MOSS_MODEL=Systran/faster-whisper-large-v3
+```
+
+变量名沿用 `MOSS_*` 前缀，实际指向 Whisper 即可。模型选型与常见问题见
+[`whisper/README.md`](../whisper/README.md)。
 
 ## 2. 部署 MOSS
 
@@ -119,6 +167,10 @@ PUBLIC_BASE_URL=https://video_service.d1kt.cn
 MOSS_TRANSCRIBE_URL=http://127.0.0.1:8001/v1/audio/transcriptions
 ```
 
+若使用 Whisper 方案（第 2A 节），把 `MOSS_TRANSCRIBE_URL` 改为
+`http://127.0.0.1:9000/v1/audio/transcriptions`，并把 `MOSS_MODEL` 设为
+`Systran/faster-whisper-large-v3`。
+
 启动：
 
 ```bash
@@ -126,10 +178,10 @@ docker compose up -d --build
 docker compose logs -f oral-trainer-api
 ```
 
-Compose 配置使用 Linux 的 host network，使容器可以访问只监听
-`127.0.0.1:8001` 的 MOSS，同时 API 也只监听 `127.0.0.1:8000`。如果在
+Compose 配置使用 Linux 的 host network，使容器可以访问只监听本机的
+转写服务（MOSS `127.0.0.1:8001` 或 Whisper `127.0.0.1:9000`），同时 API 也只监听 `127.0.0.1:8000`。如果在
 Docker Desktop 上做本地测试，可移除 `network_mode: host`，恢复端口映射，并把
-MOSS 地址改为 `host.docker.internal`。
+转写服务地址改为 `host.docker.internal`。
 
 检查：
 
@@ -233,8 +285,8 @@ https://video_service.d1kt.cn/admin
 1. 管理后台通过 raw body 流式写入临时文件并同步计算 SHA-256，不会先在系统临时目录保留完整副本。兼容的 multipart 接口仍以 4 MB 分块复制。
 2. 保存到 `data/v/{sha256}.{extension}`。
 3. 使用 FFmpeg 提取 16 kHz 单声道 WAV。
-4. 请求 MOSS 的 `verbose_json` 转写接口。
-5. 以 MOSS 时间戳生成句子边界，并计算每句原音有效语音时长。
+4. 请求转写服务（MOSS 或 Whisper）的 `verbose_json` 接口。
+5. 以转写时间戳生成句子边界，并计算每句原音有效语音时长。
 6. 把视频和句子写入 SQLite，状态变为 `ready`。
 
 查询处理状态：
@@ -244,7 +296,7 @@ curl https://video_service.d1kt.cn/api/v1/videos
 curl https://video_service.d1kt.cn/api/v1/videos/{sha256}
 ```
 
-如果 MOSS 未配置，上传仍会使用原来的静音检测生成边界，但句子文本为空，无法开始测验。配置好 MOSS 后可在后台点击“重新处理”。
+如果转写服务未配置，上传仍会使用原来的静音检测生成边界，但句子文本为空，无法开始测验。配置好转写服务后可在后台点击“重新处理”。
 
 ## 6. 视频随机播放
 
@@ -291,7 +343,7 @@ curl -X POST \
 
 总分不低于 `ASSESSMENT_PASS_SCORE`（默认 70）即通过。`pronunciation_score` 和 `prosody_score` 目前返回 `null`，避免把 ASR 内容匹配误报为音素发音质量。
 
-服务只向 MOSS 发送语言提示，不发送标准句子作为 prompt 或热词，避免标准答案诱导识别结果。
+服务只向转写服务发送语言提示，不发送标准句子作为 prompt 或热词，避免标准答案诱导识别结果。
 
 ## 8. 运维与备份