vLLM 插件注册不上：VibeVoice 的 vllm_plugin 入口在哪

按 VibeVoice 仓库 docs/vibevoice-vllm-asr.md 的说法，它的 vLLM 部署方式是插件式的：文档里那句「No vLLM source code modification required - just install and run」写得很清楚，不需要动 vLLM 的源码。好处是升级 vLLM 不用重打补丁，代价是——出问题的时候，你要排的不是「代码写错了」，而是「注册这一步到底有没有发生」。

这篇就沿着仓库里的注册链路走一遍，把注册机制、模型与输入处理器的挂载点、以及几处版本耦合的位置标出来。涉及的路径与字段以仓库最新内容为准，该项目持续更新。

现象

最典型的现象是服务起不来，或者起来了但请求进不去模型。仓库文档 docs/vibevoice-vllm-asr.md 的 Troubleshooting 一节把它单列成一条，标题就叫 "Plugin not loaded"，给的两条动作是：

pip show vibevoice
pip show -f vibevoice | grep entry

以上为仓库文档中的原文命令。它把排查方向指得很明确：先确认包装上了，再确认入口点在。

怎么确认是这个问题

注册的入口声明只有一处，在仓库根目录的 pyproject.toml：

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

这一行说明了三件事：分组名是 vllm.general_plugins，插件名叫 vibevoice，被调用的是 vllm_plugin 包顶层的 register_vibevoice 函数。vllm_plugin/__init__.py 的模块文档字符串里也自述了同一件事——插件由 vLLM 通过 pyproject.toml 里定义的 vllm.general_plugins 入口自动加载；文件末尾还有一行注释自述，这种方式能确保它在所有 vLLM 进程里都跑到。

所以第一个判定动作，是拿 pip show -f 的输出去核对这个入口是否真的被写进了已安装的包元数据。这条命令是 POSIX shell 写法，grep 在 Windows 原生的 PowerShell / CMD 里并不存在；仓库文档没有给 Windows 版命令，你可以只跑 pip show -f vibevoice 然后自己翻输出里的入口点条目——这属于通用做法，不是该项目的官方内容。

第二个判定动作，是确认 vllm_plugin 这个包本身有没有被装进去。pyproject.toml 里的打包范围写得很具体：

[tool.setuptools.packages.find]
where = ["."]
include = ["vibevoice*", "vllm_plugin*"]

vibevoice* 和 vllm_plugin* 是两个并列的顶层包。如果你不是从仓库根目录整体安装的，入口点指向的模块可能根本不在环境里，而入口声明本身是写在包元数据里的——这两处分开，恰好构成一种「看起来装了、其实导不进来」的状态。

第三个判定动作，是打开模型权重目录的 config.json 看 architectures 字段。vllm_plugin/__init__.py 在 ModelRegistry.register_model 那一行上方有一句注释，明说这个名字必须和 config.json 里的 architectures 列表匹配。

注册函数到底做了什么

register_vibevoice() 的函数体不长，做的是四件事：

步骤	调用	注册的东西
1	AutoConfig.register("vibevoice", VibeVoiceConfig)	配置类，绑定到 model_type 为 vibevoice
2	AutoTokenizer.register(...)	slow 用 Qwen2Tokenizer，fast 用 VibeVoiceASRTextTokenizerFast
3	AutoProcessor.register(VibeVoiceConfig, processor_class=Qwen2AudioProcessor)	processor
4	ModelRegistry.register_model(...)	架构名 "VibeVoice" 与 "VibeVoiceForASRTraining" 两个，都指向 VibeVoiceForCausalLM

前两件事挂在 transformers 的注册表上，第四件挂在 vLLM 的 ModelRegistry 上。

这里有个排查时必须知道的细节：第 2 步和第 3 步都被 try/except Exception: pass 包住了，except 分支的注释写的是 May already be registered。换句话说，tokenizer 与 processor 的注册失败不会以异常形式冒出来。你在日志里找不到它们出错的痕迹，不代表它们成功了。第 1 步和第 4 步没有包 try，这两处才是会直接报出来的。

模型与输入处理器挂在哪

vllm_plugin/__init__.py 顶部有一句 from .model import VibeVoiceForCausalLM。这句 import 本身就是挂载动作的一部分——因为 vllm_plugin/model.py 里，多模态那一整套是靠类装饰器注册的：

@MULTIMODAL_REGISTRY.register_processor(
    VibeVoiceMultiModalProcessor,
    info=VibeVoiceProcessingInfo,
    dummy_inputs=VibeVoiceDummyInputsBuilder,
)
class VibeVoiceForCausalLM(nn.Module, SupportsMultiModal, SupportsPP):

装饰器在模块被 import 的那一刻执行。所以「插件没加载」和「多模态 processor 没注册」在这个仓库里是同一件事的两面：只要 from .model import ... 没走到，MULTIMODAL_REGISTRY 里就不会有这一项，而 ModelRegistry.register_model 在它后面，同样不会执行。

音频输入这一侧，链路是这样的：VibeVoiceForCausalLM.get_placeholder_str 对 audio 开头的模态返回 "<|AUDIO|>"；VibeVoiceMultiModalProcessor._call_hf_processor 的注释自述，它刻意不跑会预先展开 <|AUDIO|> 的 HF processor，而是把 prompt 原样 tokenize、把原始音频张量存下来，交给 _get_prompt_updates 去展开；_hf_processor_applies_updates 因此直接返回 False。另外 _get_data_parser 里写死了 target_sr = 24000，注释标明 VibeVoice 需要 24kHz 而不是 Whisper 默认的 16kHz。

vllm_plugin/inputs.py 里的 vibevoice_audio_input_mapper 负责把外部传进来的音频转成 MultiModalInputs，接受路径字符串、字节、numpy 数组，以及字符串列表（列表只取第一个，注释里写明了）。它还有一道时长闸门：

_MAX_AUDIO_DURATION = float(os.environ.get("VIBEVOICE_MAX_AUDIO_DURATION", "3660"))

3660 是仓库当前代码里的默认值，随版本可能变动；代码注释说明这个值对应模型设计上的容量，并可以通过环境变量下调。超过就抛 ValueError，报错文案里直接把环境变量名写给你了。

版本耦合在哪

这是这个插件最容易被 vLLM 升级咬到的地方，而且全部集中在 vllm_plugin/model.py 的 import 段：

• AudioMediaIO 有两个候选导入路径，代码里用 try/except ImportError 分别对应新旧位置（vllm.multimodal.media.audio 与 vllm.multimodal.audio），拿到之后派生出 _PatchedAudioMediaIO，用 FFmpeg 接管 load_bytes / load_base64 / load_file，再把它写回模块属性；随后还试着去 patch vllm.multimodal.utils 里同名的引用，这一处的 except 注释写的是新版本可能已经不在 utils 里 import 它了。
• BaseDummyInputsBuilder 与 ProcessorInputs 有三层 fallback：先 vllm.multimodal.processing，再 vllm.multimodal.profiling，最后退到 vllm.multimodal.processing.dummy_inputs / .inputs 单独导。

这两段跑在 register_vibevoice() 之前——因为它们在 model.py 的模块级，而 model.py 是被 __init__.py 顶部 import 拉进来的。也就是说，vLLM 内部模块一旦搬到这三层 fallback 都盖不住的位置，失败会发生在 import 期，而不是注册期。

文档给的 Docker 命令把 vLLM 镜像 tag 写定了，start_server.py 也是在这个镜像里跑的：

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"

以上为仓库文档中的原文命令，镜像 tag 是文档当前写定的值，随仓库更新变动。-v $(pwd):/app 是 POSIX shell 的当前目录展开写法，Windows 上要按你自己 shell 的语法替换，仓库里没有给 Windows 版本的对应命令。

还有一处源与源对不上，值得记一笔：vllm_plugin/scripts/start_server.py 的 install_vibevoice() 执行的是 pip install -e /app[vllm]，而 pyproject.toml 的 [project.optional-dependencies] 里只声明了 streamingtts 一个 extra，没有 vllm。两处摆在一起就是这样，具体怎么处理请以仓库最新内容为准。

处置后怎么验证

start_server.py 的 _build_vllm_cmd 里 --served-model-name 写死为 vibevoice，所以请求里的模型名用它。文档给的验证动作是看日志与跑自带测试脚本：

docker logs -f vibevoice-vllm
docker exec -it vibevoice-vllm python3 vllm_plugin/tests/test_api.py /app/audio.wav

以上为仓库文档中的原文命令。文档同时提醒，音频或视频文件必须放在挂载进容器的目录里（示例中是 /app）。

tokenizer 文件这一步也别跳。start_server.py 里 generate_tokenizer() 调的是 python -m vllm_plugin.tools.generate_tokenizer_files --output <模型目录>，并有 --skip-tokenizer 开关可以跳过它。这个工具会把 <|AUDIO|>、<|audio_bos|>、<|audio_eos|> 三个音频 token 写进 tokenizer_config.json、added_tokens.json 与 special_tokens_map.json。把它和 model.py 里的 VibeVoiceProcessingInfo.get_audio_token_info() 放在一起看就明白了：后者是从 tokenizer.get_vocab() 里 vocab.get("<|AUDIO|>") 取 id 的，词表里没有就是 None。

什么情况说明不是这个原因

最后这一步不能省，否则容易朝错方向修：

• 报的是 "CUDA out of memory" —— 文档 Troubleshooting 第 1 条给的是调 --gpu-memory-utilization、--max-num-seqs、--max-model-len，与注册无关。
• 报的是音频时长超限（错误文本里带 VIBEVOICE_MAX_AUDIO_DURATION）—— 那是 inputs.py 的时长闸门，说明输入已经走到 mapper 了，注册显然是成功的。
• 报的是 "Audio decoding failed" —— 文档给的是先确认 FFmpeg 装了（ffmpeg -version）、再看格式，属于解码侧。
• 报的是 "Model not found" —— 文档指向模型目录里的 config.json 与权重是否齐全、tokenizer 文件是否需要生成。
• 服务能起、请求也能返回，但转写结果不对劲 —— 这种情况最不像注册问题，但恰恰要回头看注册。vllm_plugin/__init__.py 在 AutoTokenizer.register 上方有一段以 IMPORTANT (ASR) 开头的注释，说明 VibeVoiceASRTextTokenizerFast 把 speech_start_id 映射到 <|object_ref_start|>、speech_pad_id 映射到 <|box_start|>、speech_end_id 映射到 <|object_ref_end|>，并明确写道：即使请求成功，这一点也会显著影响 ASR 质量。而这一步的注册正好被 try/except Exception: pass 包着。日志里安安静静，不等于它按预期生效了。

另外提一句模型家族的对应关系，避免走弯路：register_vibevoice() 往 ModelRegistry 里放的架构名只有 "VibeVoice" 和 "VibeVoiceForASRTraining"，AutoConfig.register 绑定的 model_type 只有 "vibevoice"。VibeVoice 在 Hugging Face 上有多个不同模型，它们 config 里的 architectures 与 model_type 并不都落在这两个名字上——比如 Realtime 那个走的是 vibevoice_streaming，ASR 还有一份以 vibevoice_asr 为 model_type 的变体。这个插件对应的是仓库 docs/vibevoice-vllm-asr.md 里那条 ASR 部署路线，写哪个就读哪个文档，不要拿别的权重目录来套。

---

本文依据 github.com/microsoft/VibeVoice 仓库与 Hugging Face 模型卡于 2026-08-18 的公开内容整理， 事实来自仓库内的文档与源码。我们没有下载权重、没有跑过推理、也没有做过训练， 因此不涉及显存占用、推理速度、识别准确率与音质的任何描述，也不与其它模型做比较或排名。 该项目持续更新，文中涉及的模块路径、配置字段与接口写法随版本变动，请以仓库最新内容为准。

需要说明的是：仓库 README 记载，2025-09-05 微软因发现有与既定意图不符的使用方式， 基于负责任 AI 原则从该仓库移除了 VibeVoice-TTS 代码； 当前 vibevoice/modular/modeling_vibevoice.py 首行注释标明其来自社区 fork， 且该模块未被 vibevoice/modular/__init__.py 的 __all__ 导出。 本文只讲代码与架构，不构成 TTS 推理的可用性保证。

仓库 README 的风险与限制一节写明：该模型仅供研究与开发用途， 未经进一步测试与开发不建议用于商业或真实场景，并特别提示了合成语音被用于伪造与虚假信息的风险。 使用合成语音时应遵守所在司法辖区的法律法规，并在分享 AI 生成内容时主动披露。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。