# 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 -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），看到启动完成即可
```

验证：

```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`）。