add whisper

2026-08-16 15:52:40 +08:00
parent 6e4d93cea6
commit 53cbcde543
6 changed files with 323 additions and 9 deletions
--- a/whisper/README.md
+++ b/whisper/README.md
@@ -0,0 +1,86 @@
+# Whisper 转写服务（Speaches / faster-whisper）
+
+基于 [Speaches](https://github.com/speaches-ai/speaches)（原 faster-whisper-server）的
+OpenAI 兼容语音转写服务，使用 faster-whisper（CTranslate2）推理，比原版 Whisper
+更快、显存占用更低。提供 `POST /v1/audio/transcriptions` 接口，可直接替换
+`sentence_api` 里的 MOSS 转写地址，应用代码无需改动。
+
+## 目录结构
+
+```text
+whisper/
+  docker-compose.yml           GPU 服务编排（ghcr.io/speaches-ai/speaches:latest-cuda）
+  .env.example                 配置模板（模型、端口、计算类型）
+  systemd/whisper-transcribe.service  systemd 模板
+  verify.sh                    部署验证脚本
+```
+
+## 快速部署
+
+前置条件：Ubuntu 22.04/24.04、Docker、NVIDIA 驱动（≥ 535，支持 CUDA 12.x）、
+NVIDIA Container Toolkit（安装方法见 `sentence_api/DEPLOYMENT.md` 或 NVIDIA 官方文档）。
+镜像自带 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 服务
+
+```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
+```
+
+模板假设代码位于 `/opt/whisper`，如路径不同请修改
+`WorkingDirectory`、`ExecStart`、`ExecStop` 三处。
+
+## 接入 sentence_api
+
+在 `/opt/oral-trainer/sentence_api/.env` 中：
+
+```dotenv
+MOSS_TRANSCRIBE_URL=http://127.0.0.1:9000/v1/audio/transcriptions
+MOSS_MODEL=Systran/faster-whisper-large-v3
+```
+
+然后重建 API 容器：
+
+```bash
+cd /opt/oral-trainer/sentence_api
+docker compose up -d --build
+curl http://127.0.0.1:8000/healthz   # moss_configured 应为 true
+```
+
+## 模型选择
+
+| 模型 | 显存（float16） | 特点 |
+| --- | --- | --- |
+| `Systran/faster-whisper-large-v3` | 约 6 GB | 准确率最高，默认 |
+| `Systran/faster-whisper-large-v3-turbo` | 约 3 GB | 快约 8 倍，精度略低 |
+
+L4（24 GB 显存）可同时常驻两个模型；Speaches 支持在请求的 `model` 参数里切换模型
+并自动加载。服务只监听 `127.0.0.1:9000`，请勿直接暴露公网。
+
+## 常见问题
+
+- 首次启动下载模型慢或失败：在 `docker-compose.yml` 中取消 `HF_ENDPOINT=https://hf-mirror.com`
+  注释后 `docker compose up -d`。
+- 容器报 CUDA 错误：确认宿主机驱动 ≥ 535，并已安装 NVIDIA Container Toolkit。
+- 转写结果没有说话人：Whisper 不做说话人分离，需要该功能请改用
+  `MOSS-Transcribe-Diarize`（见 `sentence_api/DEPLOYMENT.md`）。