Whisper 转写服务（Speaches / faster-whisper）

基于 Speaches（原 faster-whisper-server）的 OpenAI 兼容语音转写服务，使用 faster-whisper（CTranslate2）推理，比原版 Whisper 更快、显存占用更低。提供 POST /v1/audio/transcriptions 接口，可直接替换 sentence_api 里的 MOSS 转写地址，应用代码无需改动。

目录结构

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。

sudo mkdir -p /opt/whisper
sudo chown "$USER":"$USER" /opt/whisper
cp -a whisper/. /opt/whisper/   # 注意用 whisper/. 而不是 whisper/*，否则不会复制 .env.example 等隐藏文件
cd /opt/whisper

cp .env.example .env          # 按需修改 WHISPER_MODEL
docker compose up -d
docker compose logs -f whisper   # 首次启动下载模型（约 3 GB），看到启动完成即可

验证：

/opt/whisper/verify.sh

注册为 systemd 服务

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 中：

MOSS_TRANSCRIBE_URL=http://127.0.0.1:9000/v1/audio/transcriptions
MOSS_MODEL=Systran/faster-whisper-large-v3

然后重建 API 容器：

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，请勿直接暴露公网。

常见问题

首次启动下载模型慢或失败：默认已使用国内镜像 https://hf-mirror.com（可在 .env 的 HF_ENDPOINT 覆盖）；仍失败可改用代理，在 docker-compose.yml 的 environment 里加 HTTP_PROXY/HTTPS_PROXY 后 docker compose up -d。
容器报 CUDA 错误：确认宿主机驱动 ≥ 535，并已安装 NVIDIA Container Toolkit。
转写结果没有说话人：Whisper 不做说话人分离，需要该功能请改用 MOSS-Transcribe-Diarize（见 sentence_api/DEPLOYMENT.md）。

README.md Unescape Escape