VibeVoice vLLM ASR 部署实战：一键拉起 OpenAI 兼容的语音转文本 API 与多 GPU 扩展

本篇围绕 vibevoice-vllm-asr.md 展开，讲解如何用官方 vLLM Docker 镜像一键部署 VibeVoice-ASR 的高性能推理服务，覆盖单卡启动、--tp/--dp 多卡扩展、OpenAI 兼容接口调用、热词与重复循环自动恢复、环境变量与常见故障排查；并结合 vllm_plugin 目录下的启动器、插件注册与音频输入映射源码，说明每个部署参数的底层作用机制。读完后你可以独立完成从 docker run 到多 GPU 负载均衡集群的完整部署，并理解每个开关在代码中的落点。

核心特性：为什么用 vLLM 部署 VibeVoice ASR

vibevoice-vllm-asr.md 将 VibeVoice-ASR 定位为一种高吞吐、OpenAI 兼容的语音转文本（speech-to-text）API 服务，核心卖点有四：

• 高吞吐推理：依托 vLLM 的 continuous batching，多请求在同一个进程内动态拼批，比逐请求推理显著更高并发；
• OpenAI 兼容 API：直接暴露标准 /v1/chat/completions 端点并支持流式（SSE）输出，现有 OpenAI SDK 代码几乎可以零改动迁移；
• 长音频支持：单次请求可处理 60 分钟以上的音频；
• 插件架构：无需修改 vLLM 源码，仅通过 Python 包的 entry point 机制注入模型（详见下文源码解析）；
• 数据并行（DP）：可在多张 GPU 上运行独立模型副本，单端口后自动负载均衡。

其中"60 分钟以上长音频"并非营销口径，源码中有明确护栏：inputs.py 中音频输入映射器定义了最大时长 _MAX_AUDIO_DURATION，默认 3660 秒（61 分钟），并可通过环境变量 VIBEVOICE_MAX_AUDIO_DURATION 调低以保护显存较小的 GPU。

插件架构：不改 vLLM 源码的注入机制

"install and run" 的实现依赖 pyproject.toml 中声明的 entry point：

[project.entry-points."vllm.general_plugins"]
vibevoice = "vllm_plugin:register_vibevoice"

vLLM 启动时会通过 vllm.general_plugins 机制自动调用 init.py 中的 register_vibevoice()，它完成四件事：

1. 把 VibeVoiceConfig 注册到 transformers 的 AutoConfig（模型架构名 vibevoice，必须与 checkpoint 的 config.json 中 architectures 列表一致）；
2. 注册 ASR 专用 tokenizer VibeVoiceASRTextTokenizerFast，把 speech_start_id/speech_pad_id/speech_end_id 分别映射到 ▁|▁ 风格的特殊 token——源码注释特别强调，这一映射"对 ASR 质量影响显著，即使请求本身能成功"；
3. 注册 Qwen2AudioProcessor 作为 AutoProcessor；
4. 向 vLLM 的 ModelRegistry 注册 VibeVoice、VibeVoiceForASRTraining、VibeVoiceForASRStreamingTraining 三个架构名，全部指向同一个模型实现 VibeVoiceForCausalLM。

模型本体在 model.py 中组装：VibeVoiceAudioEncoder（声学 + 语义双 VAE tokenizer 加 SpeechConnector 投影层，内部保持 float32 精度，输出再转成 --dtype 指定的 bfloat16）负责把 24 kHz 原始波形编码为音频 embedding，语言模型则通过 init_vllm_registered_model 以 Qwen2ForCausalLM 架构初始化。插件还会用 FFmpeg 解码器全局替换 vLLM 默认的 AudioMediaIO（见 model.py），保证 MP3、WAV、FLAC 等不同格式在 load_bytes/load_base64/load_file 三条路径上行为一致。这也是排障项"Audio decoding failed 需确认 FFmpeg 已安装"的根源。

安装与启动：官方 Docker 镜像一键部署

文档推荐直接使用官方 vLLM Docker 镜像 vllm/vllm-openai:v0.14.1 完成部署，无需本地准备 Python 环境。

第 1 步：获取 VibeVoice 仓库

克隆 VibeVoice 仓库并进入目录（下文所有 $(pwd) 均指该目录）：

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"

关键点：

• $(pwd) 挂载为容器内 /app 并设为工作目录，这是启动器 pip install -e /app[vllm] 能生效、且 --allowed-local-media-path /app 能读取本地音频的前提；
• --ipc=host 供 PyTorch 多进程共享内存使用；
• PYTORCH_ALLOC_CONF=expandable_segments:True 让 PyTorch 分配器使用可扩展内存段，缓解长时间高并发下的显存碎片问题。

第 3 步：查看日志

docker logs -f vibevoice-vllm

文档给出的运行注意事项：-d 为后台（detached）模式；停止服务用 docker stop vibevoice-vllm；模型首次启动会下载到容器内的 HuggingFace 缓存目录 ~/.cache/huggingface。

启动器内部流程：start_server.py 做了什么

vllm_plugin/scripts/start_server.py 是"一键部署"的实际执行者，按顺序做五步：

1. 安装系统依赖（install_system_deps）：apt-get install -y ffmpeg libsndfile1；
2. 安装包（install_vibevoice）：pip install -e /app[vllm]，即本仓库可编辑安装并带上 vLLM 扩展依赖；
3. 下载模型（download_model）：默认 microsoft/VibeVoice-ASR，用 huggingface_hub.snapshot_download 落入默认缓存；
4. 生成 tokenizer 文件：python3 -m vllm_plugin.tools.generate_tokenizer_files --output <model_path>，对应 generate_tokenizer_files.py——这正是排障项"Model not found: 缺失 tokenizer 文件时先运行生成工具"的来源；
5. 启动 vLLM：根据 --dp 是否大于 1，走单进程 os.execvp("vllm", ...) 或 DP + nginx 编排两条分支。

实际拼装的 vllm serve 命令（见 _build_vllm_cmd）为：

vllm serve <model_path> \
  --served-model-name vibevoice \
  --trust-remote-code \
  --dtype bfloat16 \
  --max-num-seqs 64 \
  --max-model-len 65536 \
  --gpu-memory-utilization 0.8 \
  --no-enable-prefix-caching \
  --enable-chunked-prefill \
  --chat-template-content-format openai \
  --tensor-parallel-size <tp> \
  --data-parallel-size <dp> \
  --allowed-local-media-path /app \
  --port 8000

这些默认值都可以用启动器自身的命令行参数覆盖（见 argparse 定义）：

参数	含义	默认值
--model / -m	HuggingFace 模型 ID	microsoft/VibeVoice-ASR
--port / -p	服务端口	8000
--tp / --tensor-parallel-size	张量并行度：一个模型切到 N 张 GPU	1
--dp / --data-parallel-size	数据并行度：N 个独立副本 + 负载均衡	1
--max-num-seqs	单批最大序列数（并发上限）	64
--max-model-len	最大上下文长度	65536
--gpu-memory-utilization	显存占用比例	0.8
--skip-deps	跳过系统依赖安装	关闭
--skip-tokenizer	跳过 tokenizer 文件生成	关闭

多 GPU 部署：TP 与 DP 怎么选

启动器通过 --tp 和 --dp 支持两类 GPU 并行：

Flag	名称	作用
--tp N	Tensor Parallel	把一个模型切分到 N 张 GPU（用于单卡装不下模型的场景）
--dp N	Data Parallel	跑 N 个独立副本，每副本一张（组）GPU，单端口后自动负载均衡

数据并行（吞吐扩展的推荐方式）

指定 --dp N（N > 1）时，启动器自动拉起 N 个独立 vLLM 进程，前面架一层 nginx 反向代理（2×N 个 worker）做负载均衡。4 卡示例：

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 卡全量：

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"

张量并行

显存紧张时把一个模型切到 2 张 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 卡）：

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 暴露的设备数足够。启动器在 start_dp_server 中会用 torch.cuda.device_count() 校验，不足时直接断言报错（见 start_server.py）。

DP 编排的源码细节

从源码看，DP 模式（start_dp_server）的完整编排为：

• GPU 分配：第 rank 个副本通过 CUDA_VISIBLE_DEVICES 独占 [rank×tp, rank×tp+tp) 段 GPU，每个 worker 自身以 --data-parallel-size 1 启动；
• 端口布局：前端 nginx 监听 8000，N 个后端 vLLM 进程监听 8100, 8101, ...（frontend_port + 100 + rank）；
• 负载均衡策略：nginx 配置使用 least_conn（最少连接），worker 数为 2×N，proxy_read_timeout/proxy_send_timeout 放宽到 600 秒以容纳长音频请求，client_max_body_size 提升到 200m；
• 就绪探测：依次轮询每个后端的 /v1/models，最长等待 10 分钟；
• 故障传播：注册 SIGTERM/SIGINT 处理器，任一 worker 或 nginx 退出即整体终止，避免半残集群。

文档中"避免 vLLM 内置 DP 协调器的单进程 HTTP 瓶颈"的说法在启动器 docstring 中有对应注释：对大音频负载，N 个独立进程 + nginx 的吞吐优于单进程协调。

API 调用与测试脚本

服务就绪后，仓库提供了三个测试脚本（位于 vllm_plugin/tests）：

# 基础转写
docker exec -it vibevoice-vllm python3 vllm_plugin/tests/test_api.py /app/audio.wav

# 带热词，提升特定术语（专名、技术词、说话人姓名）的识别率
docker exec -it vibevoice-vllm python3 vllm_plugin/tests/test_api.py /app/audio.wav --hotwords "Microsoft,VibeVoice"

# 长音频防重复循环的自动恢复版本
docker exec -it vibevoice-vllm python3 vllm_plugin/tests/test_api_auto_recover.py /app/audio.wav

# 自动恢复 + 热词
docker exec -it vibevoice-vllm python3 vllm_plugin/tests/test_api_auto_recover.py /app/audio.wav --hotwords "Microsoft,VibeVoice"

注意事项（与原文档一致）：

• 音频/视频文件必须位于挂载目录内（容器里即 /app），测试前先把文件拷进 VibeVoice 文件夹；
• 热词通过提示词注入生效——从 test_api.py 源码看，--hotwords 的值会被拼进 prompt："This is a {duration} seconds audio, with extra info: {hotwords}\n\nPlease transcribe it with these keys: Start time, End time, Speaker ID, Content"；
• 测试脚本还会打印耗时与 RTF（Real-Time Factor）用于粗略评估吞吐。

请求格式与解码参数

test_api.py 实际发送的 /v1/chat/completions 负载展示了推荐的生产参数组合：

{
  "model": "vibevoice",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant that transcribes audio input into text output in JSON format."},
    {"role": "user", "content": [
      {"type": "audio_url", "audio_url": {"url": "data:audio/wav;base64,<...>"}},
      {"type": "text", "text": "This is a 12.34 seconds audio, please transcribe it with these keys: Start time, End time, Speaker ID, Content"}
    ]}
  ],
  "max_tokens": 32768,
  "temperature": 0.0,
  "stream": true,
  "top_p": 1.0
}

要点：音频以 data:<mime>;base64,<...> 的 data URL 内嵌在 audio_url 字段中（服务端因此启用了 --allowed-local-media-path /app，也支持指向 /app 下的本地文件）；model 必须为启动器注册的 vibevoice；temperature=0 贪心解码保证转写结果稳定；stream=true 走 SSE 增量输出。脚本对视频文件（mp4/mov/webm 等）会先用 FFmpeg 抽出音频再上传。

自动恢复策略：应对长音频的重复循环

test_api_auto_recover.py 面向 60 分钟级长音频的贪心解码偶发"复读"问题，其恢复策略在文件头 docstring 中写明：

1. 首次请求使用贪心解码（temperature=0, top_p=1.0）；
2. 流式输出中检测到重复循环后，依次以 temperature=0.2/0.3/0.4、top_p=0.95 重试，最多 3 次；
3. 截断到最后一个完整 JSON 片段边界（},）保证输出可解析，支持 --debug 打印恢复过程。

另外，插件侧还有配套的长音频工程处理：model.py 中 VibeVoiceAudioEncoder.forward 对超过 streaming_segment_duration（默认 60 秒）的音频按段编码并跨段缓存，避免一次性 VAE 编码超长波形的显存峰值。

环境变量

变量	说明	默认
VIBEVOICE_FFMPEG_MAX_CONCURRENCY	FFmpeg 音频解码并发进程上限	64
PYTORCH_ALLOC_CONF	PyTorch 内存分配器配置	expandable_segments:True

从源码看，VIBEVOICE_FFMPEG_MAX_CONCURRENCY 的落点在 audio_utils.py：进程启动时读取该变量构造一个全局 threading.Semaphore，所有 ffmpeg 子进程调用都先获取信号量——在高并发请求下防止 FFmpeg 进程爆炸打满 CPU/IO 导致超时；未设置（或为 0/负数）表示不限制。DP 模式下，启动器还会对每个 worker 自动取 max(64, 该变量值) 并下发，同时把 VLLM_MEDIA_LOADING_THREAD_COUNT 取 max(8, ...) 作为每 worker 的媒体加载线程数（见 start_server.py）。

此外还有两个源码级可调项（文档未单列，部署显存受限时可参考）：

• VIBEVOICE_MAX_AUDIO_DURATION：单请求最大音频秒数，默认 3660（61 分钟），见 inputs.py；
• VIBEVOICE_USE_MEAN：置 1 时声学 token 用均值而非采样，输出更确定（见 model.py）。

性能调优

原文档给出三条调优建议，结合启动器默认值可细化为：

1. 显存利用率：独占 GPU 时可把 --gpu-memory-utilization 提到 0.9（默认 0.8），换取更大的 KV cache 与吞吐；
2. 并发批量：提高 --max-num-seqs（默认 64）可提升并发，代价是更高显存占用；
3. FFmpeg 并发：按 CPU 核数调整 VIBEVOICE_FFMPEG_MAX_CONCURRENCY，解码是 CPU 密集步骤，核数很少时设小一点反而更稳。

常见问题排查

症状	处理
CUDA out of memory	降低 --gpu-memory-utilization；降低 --max-num-seqs；调小 --max-model-len（默认 65536，可按最大音频时长裁剪）
Audio decoding failed	确认容器内有 FFmpeg（ffmpeg -version）；确认音频格式受支持（解码统一走 FFmpeg，见 model.py）
Model not found	确认模型目录内含 config.json 与权重；缺失 tokenizer 文件时先运行 generate_tokenizer_files.py
Plugin not loaded	pip show vibevoice 确认已安装；`pip show -f vibevoice

关键文件索引

文件	作用
docs/vibevoice-vllm-asr.md	本篇对应的部署文档
vllm_plugin/scripts/start_server.py	一键启动器：依赖安装、模型下载、tokenizer 生成、TP/DP 编排与 nginx 配置
vllm_plugin/init.py	插件注册入口（entry point 指向 register_vibevoice）
vllm_plugin/model.py	VibeVoiceForCausalLM 多模态实现：音频编码器、prompt 占位符展开、权重前缀映射
vllm_plugin/inputs.py	音频输入映射：24 kHz 重采样、时长护栏（61 分钟默认上限）
vibevoice/processor/audio_utils.py	FFmpeg 解码与全局并发信号量
vllm_plugin/tests/test_api.py	基础/热词转写测试客户端
vllm_plugin/tests/test_api_auto_recover.py	重复循环自动恢复客户端
vllm_plugin/tools/generate_tokenizer_files.py	为模型目录生成 tokenizer 文件
pyproject.toml	vllm.general_plugins entry point 声明

以上即 VibeVoice-ASR 经由 vLLM 插件化部署的完整链路：Docker 镜像提供运行时，启动器完成"装依赖 → 下模型 → 生成 tokenizer → vllm serve"的确定性编排，OpenAI 兼容接口与长音频护栏则由 vllm_plugin 包内的注册、处理与映射代码实现。若还需逐块音频实时转写的流式方案，可继续参考仓库内的 vibevoice-vllm-asr-streaming.md。