VibeVoice vLLM ASR 部署¶

使用 vLLM 将 VibeVoice ASR 模型部署为高性能 API 服务。该插件提供兼容 OpenAI 的 API 端点，支持流式语音转文本转录。

🔥 Key Features¶

• 🚀 高性能服务：通过 vLLM 的连续批处理优化高吞吐量的 ASR 推理
• 📡 OpenAI 兼容 API：标准的 /v1/chat/completions 端点，支持流式输出
• 🎵 长音频支持：单个请求可处理长达 60+ 分钟的音频
• 🔌 插件架构：无需修改 vLLM 源代码 — 安装即可运行
• ⚡ Data Parallel (DP)：在多个 GPU 上运行独立的模型副本，并在单个端口后自动负载均衡

🛠️ 安装¶

使用官方 vLLM Docker 镜像（推荐）

1. 克隆仓库

   git clone https://github.com/microsoft/VibeVoice.git
   cd VibeVoice
   

2. 启动服务器（后台模式）

   docker run -d --gpus all --name vibevoice-vllm \
     --ipc=host \
     -p 8000:8000 \
     -e VIBEVOICE_FFMPEG_MAX_CONCURRENCY=64 \
     -e PYTORCH_ALLOC_CONF=expandable_segments:True \
     -v $(pwd):/app \
     -w /app \
     --entrypoint bash \
     vllm/vllm-openai:v0.14.1 \
     -c "python3 /app/vllm_plugin/scripts/start_server.py"
   

⚡ 多 GPU 部署¶

启动器通过 --tp 和 --dp 标志支持两种 GPU 并行方式：

Data Parallel（推荐用于扩展吞吐量）¶

在 N 个 GPU 上运行 N 个独立副本，并在单个端口后自动负载均衡。 当指定 --dp N（N > 1）时，启动器会自动启动 N 个独立的 vLLM 进程，并置于 nginx 反向代理（2×N 个 worker）之后，以获得最佳吞吐量：

docker run -d --gpus '"device=0,1,2,3"' --name vibevoice-vllm \
  --ipc=host \
  -p 8000:8000 \
  -e VIBEVOICE_FFMPEG_MAX_CONCURRENCY=64 \
  -e PYTORCH_ALLOC_CONF=expandable_segments:True \
  -v $(pwd):/app \
  -w /app \
  --entrypoint bash \
  vllm/vllm-openai:v0.14.1 \
  -c "python3 /app/vllm_plugin/scripts/start_server.py --dp 4"

在全部 8 个 GPU 上运行：

docker run -d --gpus all --name vibevoice-vllm \
  --ipc=host \
  -p 8000:8000 \
  -e VIBEVOICE_FFMPEG_MAX_CONCURRENCY=64 \
  -e PYTORCH_ALLOC_CONF=expandable_segments:True \
  -v $(pwd):/app \
  -w /app \
  --entrypoint bash \
  vllm/vllm-openai:v0.14.1 \
  -c "python3 /app/vllm_plugin/scripts/start_server.py --dp 8"

Tensor Parallel¶

将单个模型拆分到 2 个 GPU 上（适用于 GPU 内存有限的情况）：

docker run -d --gpus '"device=0,1"' --name vibevoice-vllm \
  --ipc=host \
  -p 8000:8000 \
  -e VIBEVOICE_FFMPEG_MAX_CONCURRENCY=64 \
  -e PYTORCH_ALLOC_CONF=expandable_segments:True \
  -v $(pwd):/app \
  -w /app \
  --entrypoint bash \
  vllm/vllm-openai:v0.14.1 \
  -c "python3 /app/vllm_plugin/scripts/start_server.py --tp 2"

混合（DP × TP）¶

结合两者 —— 例如，2 个副本，每个副本拆分到 2 个 GPU 上（共 4 个 GPU）：

docker run -d --gpus '"device=0,1,2,3"' --name vibevoice-vllm \
  --ipc=host \
  -p 8000:8000 \
  -v $(pwd):/app \
  -w /app \
  --entrypoint bash \
  vllm/vllm-openai:v0.14.1 \
  -c "python3 /app/vllm_plugin/scripts/start_server.py --dp 2 --tp 2"

注意：所需 GPU 总数 = dp × tp。请确保在 Docker 的 --gpus 标志中暴露足够的 GPU 设备。

1. 查看日志

   docker logs -f vibevoice-vllm
   

注意： - -d 标志以后台模式（分离模式）运行容器 - 使用 docker stop vibevoice-vllm 停止服务 - 模型将下载到容器内的 HuggingFace 缓存（~/.cache/huggingface）

🚀 用法¶

测试 API¶

vLLM 服务器运行后，使用提供的脚本进行测试：

# Basic transcription
docker exec -it vibevoice-vllm python3 vllm_plugin/tests/test_api.py /app/audio.wav

# With hotwords for better recognition of specific terms
docker exec -it vibevoice-vllm python3 vllm_plugin/tests/test_api.py /app/audio.wav --hotwords "Microsoft,VibeVoice"

# With auto-recovery from repetition loops (for long audio)
docker exec -it vibevoice-vllm python3 vllm_plugin/tests/test_api_auto_recover.py /app/audio.wav

# Auto-recover with hotwords
docker exec -it vibevoice-vllm python3 vllm_plugin/tests/test_api_auto_recover.py /app/audio.wav --hotwords "Microsoft,VibeVoice"

注意： - 音频/视频文件必须位于挂载目录内（容器中的 /app）。测试前请将文件复制到 VibeVoice 文件夹中。 - 热词（hotwords）有助于提高对专有名词、技术术语和说话人姓名等特定领域术语的识别准确率。

环境变量¶

📊 性能提示¶

1. GPU 内存：如果有专用 GPU，请使用 --gpu-memory-utilization 0.9 以获得最大吞吐量
2. 批处理大小：增大 --max-num-seqs 以提高并发度（需要更多 GPU 内存）
3. FFmpeg 并发度：根据 CPU 核心数调整 VIBEVOICE_FFMPEG_MAX_CONCURRENCY

🚨 故障排除¶

常见问题¶

1. "CUDA out of memory"
2. 降低 --gpu-memory-utilization
3. 降低 --max-num-seqs

4. 使用更小的 --max-model-len

5. "Audio decoding failed"

6. 确保已安装 FFmpeg：ffmpeg -version

7. 检查音频文件格式是否受支持

8. “模型未找到”

9. 确保模型路径包含 config.json 和模型权重

10. 如果缺失，请生成 tokenizer 文件

11. “插件未加载”

12. 验证安装：pip show vibevoice
13. 检查入口点：pip show -f vibevoice | grep entry