learnedmachine/whisperx-asr-service

WhisperX ASR API 服务


⚠️ Alpha版本 - 面向自托管爱好者

一个简单的ASR API服务，由WhisperX提供支持，用于带说话人分离的转录功能。专为运行https://github.com/murtaza-nasir/speakr%E6%88%96%E7%B1%BB%E4%BC%BC%E5%BA%94%E7%94%A8%E7%9A%84%E8%87%AA%E6%89%98%E7%AE%A1%E7%94%A8%E6%88%B7%E6%9E%84%E5%BB%BA%E3%80%82

功能介绍

• 使用OpenAI Whisper模型转录音频文件
• 使用Pyannote.audio识别说话人（"谁在何时说话"）
• 返回单词级时间戳
• 支持90多种语言
• 输出JSON、SRT、VTT、TSV格式
• 通过Docker在您自己的GPU硬件上运行

限制

• 非生产级：基本错误处理，无身份验证
• 需要GPU：大型模型需要14GB+ VRAM的NVIDIA GPU
• 文件大小限制：大型音频文件（>1GB）可能导致内存不足错误
• VRAM使用：内存消耗随文件大小和分离处理而增加
• Alpha软件：可能存在错误和重大更改

工作原理

音频 --> Whisper (转录) --> Wav2Vec2 (对齐) --> Pyannote (说话人ID) --> 输出

该服务支持两种服务模式：

• 简单模式（默认）：单进程uvicorn与异步GPU队列。请求通过信号量序列化，因此一次只有一个管道在GPU上运行。适用于单GPU、低流量或开发使用。
• Ray Serve模式：在Ray Serve上运行，支持跨请求批处理（@serve.batch）。可从1个GPU扩展到多GPU。提供两种管道策略：
  • 复制（默认）：每个GPU运行完整管道（Whisper + 对齐 + 分离）。4个GPU = 4个独立的管道副本，无跨GPU数据传输。
  • 拆分：每个阶段作为单独的部署运行，具有部分GPU分配。当您希望每个阶段独立扩展时非常有用。

前提条件

硬件要求

GPU内存要求因模型大小而异：

注：在RTX 3090上使用预加载模型+对齐+pyannote community-1分离测量

最低配置（小型/中型模型）：

• GPU：NVIDIA RTX 3060（12GB VRAM）或更好
• CPU：8+核心
• 内存：16GB
• 存储：50GB SSD

推荐配置（带分离功能的large-v3）：

• GPU：NVIDIA RTX 3090（24GB VRAM）或RTX 4090
• CPU：12+核心
• 内存：32GB
• 存储：100GB SSD

软件要求

• Docker 和 Docker Compose
• NVIDIA Docker运行时（用于GPU支持）
• Hugging Face账户（用于说话人分离模型）

快速开始（预构建镜像）

使用预构建的Docker镜像，通过3个步骤即可启动并运行：

1. 获取Hugging Face令牌和模型访问权限

说话人分离需要Hugging Face令牌和模型访问权限：

a) 创建Hugging Face账户：

• 访问：https://huggingface.co/join 并注册

b) 接受模型用户协议（全部必需）：

您需要接受所有三个模型的协议：

1. https://huggingface.co/pyannote/speaker-diarization-community-1 - 点击"Agree and access repository"
2. https://huggingface.co/pyannote/segmentation-3.0 - 点击"Agree and access repository"
3. https://huggingface.co/pyannote/speaker-diarization-3.1 - 点击"Agree and access repository"

c) 生成访问令牌：

• 访问：https://huggingface.co/settings/tokens
• 点击"New token"，命名（例如"whisperx-diarization"）
• 选择"Read"权限并生成
• 复制令牌（以hf_...开头）

⚠️ 重要提示： 如果不接受所有模型协议，将收到"403 Access Denied"错误。

2. 创建配置文件

创建包含Hugging Face令牌的.env文件：

bash
# 创建.env文件
cat > .env << 'EOF'
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DEVICE=cuda
COMPUTE_TYPE=float16
BATCH_SIZE=16
PRELOAD_MODEL=large-v3
MAX_FILE_SIZE_MB=1000
# 服务模式：simple（默认）或ray（带批处理的Ray Serve）
SERVE_MODE=simple
EOF

将hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx替换为您的实际令牌。

3. 使用Docker Compose运行（推荐）

下载docker-compose.yml文件并启动服务：

bash
# 下载docker-compose.yml
curl -O https://raw.githubusercontent.com/murtaza-nasir/whisperx-asr-service/main/docker-compose.yml

# 启动服务（自动拉取预构建镜像）
docker compose up -d

# 查看日志
docker compose logs -f

或使用Docker命令运行：

bash
docker run -d \
  --name whisperx-asr-api \
  --gpus all \
  -p 9000:9000 \
  -e DEVICE=cuda \
  -e COMPUTE_TYPE=float16 \
  -e BATCH_SIZE=16 \
  -e HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -e PRELOAD_MODEL=large-v3 \
  -v whisperx-cache:/.cache \
  --restart unless-stopped \
  learnedmachine/whisperx-asr-service:latest

服务将在http://localhost:9000可用

4. 测试服务

bash
# 健康检查
curl http://localhost:9000/health

# 测试转录
curl -X POST http://localhost:9000/asr \
  -F "audio_file=@your_audio.mp3" \
  -F "language=en"

---

从源代码构建（高级）

用于开发或如果您想从源代码构建：

1. 克隆仓库

bash
git clone https://github.com/murtaza-nasir/whisperx-asr-service.git
cd whisperx-asr-service

2. 设置环境

bash
# 复制示例环境文件
cp .env.example .env

# 编辑.env并添加您的Hugging Face令牌
nano .env

3. 构建和运行

使用docker-compose.dev.yml（带实时代码挂载）：

bash
# 构建并启动
docker compose -f docker-compose.dev.yml up -d --build

# 查看日志
docker compose -f docker-compose.dev.yml logs -f

或手动构建：

bash
# 构建镜像
docker build -t whisperx-asr-service .

# 运行容器
docker run -d \
  --name whisperx-asr-api \
  --gpus all \
  -p 9000:9000 \
  --env-file .env \
  -v whisperx-cache:/.cache \
  whisperx-asr-service

注意： docker-compose.dev.yml文件挂载./app目录，以便无需重建即可进行实时代码更改。

---

API文档

运行后，访问http://localhost:9000/docs获取交互式API文档。

主要端点：POST /asr

参数：

示例请求（JSON输出）：

bash
curl -X POST http://localhost:9000/asr \
  -F "audio_file=@meeting.mp3" \
  -F "language=en" \
  -F "model=large-v3" \
  -F "output_format=json" \
  -F "diarize=true" \
  -F "min_speakers=2" \
  -F "max_speakers=5"

示例请求（SRT字幕）：

bash
curl -X POST http://localhost:9000/asr \
  -F "audio_file=@video.mp4" \
  -F "language=en" \
  -F "output_format=srt" \
  -F "diarize=false"

示例响应（JSON）：

json
{
  "text": [
    {
      "start": 0.5,
      "end": 2.3,
      "text": " 你好，欢迎参加会议。",
      "speaker": "SPEAKER_00",
      "words": [
        {"word": "你好", "start": 0.5, "end": 0.8, "score": 0.95},
        {"word": "欢迎", "start": 0.9, "end": 1.2, "score": 0.93}
      ]
    }
  ],
  "language": "en",
  "segments": [...],
  "word_segments": [...]
}

高级说话人分离功能

确切说话人数

当您知道确切的说话人数时，使用num_speakers可以获得更准确的分离结果：

bash
curl -X POST http://localhost:9000/asr \
  -F "audio_file=@interview.mp3" \
  -F "num_speakers=2" \
  -F "diarize=true"

这会覆盖min_speakers和max_speakers，并且通常比基于范围的检测提供更好的准确性。

独占说话人分离

当pyannote community-1模型可用时，此服务自动使用独占说话人分离。此功能简化了细粒度说话人分离时间戳和转录时间戳之间的协调，非常适合像https://github.com/murtaza-nasir/speakr%E8%BF%99%E6%A0%B7%E9%9C%80%E8%A6%81%E5%B0%86%E8%BD%AC%E5%BD%95%E4%B8%8E%E8%AF%B4%E8%AF%9D%E4%BA%BA%E7%89%87%E6%AE%B5%E5%AF%B9%E9%BD%90%E7%9A%84%E5%BA%94%E7%94%A8%E3%80%82

优点：

• 说话人和单词之间的时间戳对齐更准确
• 更好地处理说话人转换
• 简化多说话人转录的后处理

自定义词汇（热词）

Whisper经常拼错品牌名称、首字母缩写词和特定领域术语。您可以使用hotwords和initial_prompt提高准确性：

• hotwords在解码过程中偏向模型的束搜索以支持特定单词
• initial_prompt提供上下文句子，引导模型预期某些拼写

示例： 转录包含"我们使用CTranslate2在Kubernetes集群上部署了Speakr进行推理。PyAnnote处理分离。"的音频

bash
# 基准（无提示）
curl -X POST "http://localhost:9000/asr?language=en" \
  -F "audio_file=@meeting.mp3"
# 结果："我们部署了Speaker...使用ctranslate2...PnNote处理分离。"

# 使用热词
curl -X POST "http://localhost:9000/asr?language=en&hotwords=Speakr,CTranslate2,PyAnnote" \
  -F "audio_file=@meeting.mp3"
# 结果："我们部署了Speaker...使用CTranslate2...PyAnnote处理分离。"

# 使用热词+初始提示（最佳结果）
curl -X POST "http://localhost:9000/asr?language=en&hotwords=Speakr,CTranslate2,PyAnnote&initial_prompt=Speakr是一个转录应用。" \
  -F "audio_file=@meeting.mp3"
# 结果："我们部署了Speakr...使用CTranslate2...PyAnnote处理分离。"

单独使用hotwords可以修复大多数拼写问题。与常见英语单词发音相同的单词（如"Speakr"与"Speaker"）可能还需要initial_prompt来提供足够的上下文，使模型覆盖其默认值。

OpenAI兼容端点（/v1/audio/transcriptions）也支持hotwords表单字段。如果只提供prompt，它将用作热词。

包含一个测试脚本，用于验证您自己音频的热词：

bash
./tests/test_hotwords.sh testfiles/your_audio.flac

# 自定义热词
HOTWORDS="MyBrand,TechTerm" INITIAL_PROMPT="MyBrand是一个产品。" \
  ./tests/test_hotwords.sh testfiles/your_audio.flac

与Speakr集成

要将此服务与https://github.com/murtaza-nasir/speakr%E4%B8%80%E8%B5%B7%E4%BD%BF%E7%94%A8%EF%BC%8C%E8%80%8C%E4%B8%8D%E6%98%AF%E9%BB%98%E8%AE%A4%E7%9A%84ASR%E7%AB%AF%E7%82%B9%EF%BC%9A

如果在同一台机器上运行

更新Speakr的.env文件：

bash
# 启用ASR端点
USE_ASR_ENDPOINT=true

# 指向WhisperX服务
ASR_BASE_URL=http://whisperx-asr-api:9000

如果Speakr和WhisperX在同一个Docker Compose堆栈中，使用容器名称。否则，使用http://localhost:9000。

如果在不同的GPU机器上运行

1. 在GPU机器上： 部署此服务

bash
#