VibeVoice 仓库结构导览：四个模型、五份文档、一个 vLLM 插件

2026-08-18

第一次把 github.com/microsoft/VibeVoice 克隆下来的人，通常会在同一个地方卡住：README 的 Models 表里列了几个名字，vibevoice/ 目录下的文件名却是 modeling_vibevoice.py、modeling_vibevoice_asr.py、modeling_vibevoice_streaming.py 这一串，看不出哪个文件对应哪个模型；想 from vibevoice import ... 一个 ASR 的类，发现导不出来。

这篇就是把这张对应关系表画清楚。读完你应该能做到：拿到任意一个模型名，知道该翻哪份文档、该看哪个 .py；拿到任意一个类名，知道它在不在包的导出清单里、别人是怎么 import 它的。全文只讲仓库里白纸黑字写着的东西，不涉及运行表现。

前置条件：读代码要什么，跑代码要什么

这两件事的门槛差得很远，先分开。

只读代码：git clone 就够了，Windows 上没有任何障碍。仓库里的 .py 和 .md 都是纯文本，demo/voices/streaming_model/ 下是一批 .pt 文件，Figures/ 下是图片，读结构用不上它们。

照文档做安装与推理：pyproject.toml 写明 requires-python = ">=3.10"，依赖里带 torch、transformers>=4.51.3,<5.0.0、diffusers、librosa、gradio、fastapi、aiortc 等。另外定义了一个可选依赖组：

[project.optional-dependencies]
streamingtts = [
  "transformers==4.51.3", 
]

注意这里的落差：主依赖给的是一个区间，streamingtts 这个 extra 把 transformers 钉死在一个具体版本上。以上是仓库当前 pyproject.toml 里的约束，随版本可能变动，装之前请以仓库最新内容为准。

Windows 读者要特别看一眼：docs/vibevoice-asr.md 与 docs/vibevoice-realtime-0.5b.md 的 Installation 一节给的路径都是 NVIDIA 的 PyTorch 容器，命令形如 sudo docker run --privileged --net=host --ipc=host --gpus all --rm -it nvcr.io/nvidia/pytorch:...，docs/vibevoice-vllm-asr.md 与 docs/setup_gradio_demo.md 则是 docker run -d --gpus all ...。仓库里我们没有找到 Windows 原生安装的说明。下载附加音色的入口是 bash demo/download_experimental_voices.sh，首行是 #!/usr/bin/env bash，同样需要一个 shell 环境。

还有一个隐性依赖：vibevoice/processor/audio_utils.py 里 load_audio_use_ffmpeg() 是通过 subprocess.run 调外部 ffmpeg 可执行程序的，不是纯 Python 解码。docs/vibevoice-asr.md 在启动 Gradio demo 前专门写了一行 apt update && apt install ffmpeg -y # for demo，就是这个原因。

第一步：把四个模型和五份文档对上

README 的 Models 表列出的权重是 VibeVoice-ASR-7B、VibeVoice-ASR-BitNet（CPU）、VibeVoice-TTS-1.5B、VibeVoice-Realtime-0.5B。docs/ 下正好五份 Markdown，但它不是一一对应，其中一份讲部署：

文档	讲什么
`docs/vibevoice-asr.md`	ASR 模型本体：特性、架构图、安装、两种 demo 用法、微调入口
`docs/vibevoice-tts.md`	长音频多说话人 TTS 的介绍、架构、Tips 与 FAQ
`docs/vibevoice-realtime-0.5b.md`	实时流式 TTS：设计说明、TODO、安装与两种用法、附加音色
`docs/vibevoice-vllm-asr.md`	用 vLLM 把 ASR 起成 OpenAI 兼容 API 的部署说明
`docs/setup_gradio_demo.md`	在上面那个 vLLM 服务之上再挂 Gradio web demo 的端到端步骤

BitNet 那一路在 README 的 News 里指向另一个独立仓库与另一个 Hugging Face 权重，本仓库 docs/ 下没有对应文档。所以”四个模型五份文档”不是四加一的关系，是三份模型文档加两份部署文档，另有一个模型的入口只在 README 里。

第二步：`vibevoice/` 包里五个子目录各管什么

vibevoice/modular/：配置类与建模代码。配置分两个文件——configuration_vibevoice.py 里有 VibeVoiceAcousticTokenizerConfig、VibeVoiceSemanticTokenizerConfig、VibeVoiceDiffusionHeadConfig、VibeVoiceConfig、VibeVoiceASRConfig；configuration_vibevoice_streaming.py 里是 VibeVoiceStreamingConfig。建模按模型分文件：modeling_vibevoice.py、modeling_vibevoice_asr.py、modeling_vibevoice_streaming.py 与 modeling_vibevoice_streaming_inference.py。此外 modular_vibevoice_tokenizer.py 是声学/语义 tokenizer 的网络实现，modular_vibevoice_text_tokenizer.py 是三个文本 tokenizer 类，modular_vibevoice_diffusion_head.py 里对外的主类是 VibeVoiceDiffusionHead（同文件里还有若干内部层类），streamer.py 里被上层导出的是 AudioStreamer 与 AsyncAudioStreamer。
vibevoice/processor/：把音频与文本变成模型输入的那一层，四个 processor 分文件放（vibevoice_processor.py 里的 VibeVoiceProcessor、vibevoice_asr_processor.py 里的 VibeVoiceASRProcessor、vibevoice_streaming_processor.py 里的 VibeVoiceStreamingProcessor、vibevoice_tokenizer_processor.py 里的 VibeVoiceTokenizerProcessor），加上 audio_utils.py 的解码工具与 AudioNormalizer。
vibevoice/schedule/：dpm_solver.py（DPMSolverMultistepScheduler，文件头保留了 Apache-2.0 的版权声明）与 timestep_sampler.py（UniformSampler、LogitNormalSampler）。注意 schedule/__init__.py 是空文件，所以这里的类只能按完整模块路径 import。
vibevoice/scripts/：目录下只有一个空的 __init__.py，没有别的文件。
vibevoice/configs/：两份 JSON，qwen2.5_1.5b_64k.json 与 qwen2.5_7b_32k.json，两份的顶层键结构一致，都包含 acoustic_vae_dim、acoustic_tokenizer_config、decoder_config、diffusion_head_config、semantic_tokenizer_config、semantic_vae_dim，以及 model_type 与 torch_dtype。

这里有两处值得并排看一眼。其一，这两份 JSON 的 model_type 写的是 vibepod，其中声学 tokenizer 子配置写的是 vibepod_acoustic_tokenizer；而 configuration_vibevoice.py 里 VibeVoiceConfig.model_type = "vibevoice"，代码在处理 dict 形式的子配置时会把 model_type 覆写成 "vibevoice_acoustic_tokenizer"。其二，我们在仓库的 .py 与 .md 文件里没有 grep 到对 vibevoice/configs/ 这两个文件的引用。两件事摆在这里，具体怎么用、是否为历史遗留，仓库里没有找到相关说明。

第三步：三层 `init.py` 到底导出了什么

这是最容易踩的一处。包里有三个非空的 __init__.py，导出范围一层比一层窄。

vibevoice/__init__.py 的 __all__ 只有四个符号：VibeVoiceStreamingForConditionalGenerationInference、VibeVoiceStreamingConfig、VibeVoiceStreamingProcessor、VibeVoiceTokenizerProcessor。

vibevoice/modular/__init__.py 的 __all__ 是 Streaming 一系的六个：上面那个推理类，加 VibeVoiceStreamingConfig、VibeVoiceStreamingModel、VibeVoiceStreamingPreTrainedModel、AudioStreamer、AsyncAudioStreamer。

vibevoice/processor/__init__.py 的 __all__ 是 VibeVoiceProcessor、VibeVoiceStreamingProcessor、VibeVoiceTokenizerProcessor、AudioNormalizer。

把这三份清单和目录里实际存在的类对一下，结论很直接：ASR 一系的类一个都不在任何 __all__ 里。VibeVoiceASRForConditionalGeneration、VibeVoiceASRProcessor、VibeVoiceASRConfig、VibeVoiceASRTextTokenizerFast 都得走完整模块路径。仓库自己的代码就是这么写的，demo/vibevoice_asr_inference_from_file.py 里是：

from vibevoice.modular.modeling_vibevoice_asr import VibeVoiceASRForConditionalGeneration
from vibevoice.processor.vibevoice_asr_processor import VibeVoiceASRProcessor
from vibevoice.processor.audio_utils import COMMON_AUDIO_EXTS

finetuning-asr/lora_finetune.py、finetuning-asr/inference_lora.py、vllm_plugin/__init__.py 用的也是同一种完整路径写法。VibeVoiceProcessor 是个例外——它在 processor 的 __all__ 里，但没有出现在顶层包的 __all__ 里。

顺带一个配置层面的细节，能帮你记住三个模型形态的差别：VibeVoiceConfig.sub_configs 有四项（声学 tokenizer、语义 tokenizer、decoder、diffusion head），VibeVoiceASRConfig.sub_configs 少了 diffusion head 只剩三项，VibeVoiceStreamingConfig.sub_configs 少了语义 tokenizer 也是三项。docs/vibevoice-realtime-0.5b.md 正文对后者有对应表述，写明流式模型移除了语义 tokenizer、只依赖工作在 7.5 Hz 超低帧率的声学 tokenizer。

第四步：包外面那三个目录

vllm_plugin/ 是一个插件包，靠 pyproject.toml 里的入口点接进 vLLM：

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

vllm_plugin/__init__.py 里的 register_vibevoice() 做四件注册：AutoConfig.register("vibevoice", VibeVoiceConfig)、把 VibeVoiceASRTextTokenizerFast 注册给 AutoTokenizer、把 Qwen2AudioProcessor 注册给 AutoProcessor、用 ModelRegistry.register_model 把 VibeVoiceForCausalLM 挂到 "VibeVoice" 和 "VibeVoiceForASRTraining" 两个架构名下。文件注释还专门标注了 tokenizer 注册的映射关系会影响 ASR 结果。目录下另有 inputs.py、model.py、scripts/、tests/、tools/generate_tokenizer_files.py。

finetuning-asr/ 是 ASR 的 LoRA 微调脚本与一个玩具数据集，README 明确写了 toy_dataset/ 是用 VibeVoice TTS 合成的演示数据、不是完整的微调数据集，另外需要额外 pip install peft。demo/ 下按模型分成两路：vibevoice_asr_*.py 是 ASR 的，vibevoice_realtime_demo.py、realtime_model_inference_from_file.py、web/app.py 是流式 TTS 的。

边界：哪些东西在仓库里但用不了

TTS 那一路的状态必须说清楚。 README 的 News 记载，2025-09-05 微软因发现有与既定意图不符的使用方式、基于负责任 AI 原则从该仓库移除了 VibeVoice-TTS 代码。与之一致的是三处痕迹：docs/vibevoice-tts.md 的 “Installation and Usage” 一节正文只有一句 Disabled due to widespread misuse.；README 的 Models 表里 VibeVoice-TTS-1.5B 的 Quick Try 列写的是 Disabled；vibevoice/modular/modeling_vibevoice.py 首行注释标明该文件是从社区 fork github.com/vibevoice-community/VibeVoice 复制过来的，且这个文件里的类不在任何 __all__ 中。所以你在目录里看得到 modeling_vibevoice.py，不等于这条路是官方支持的用法。

Realtime 一路有明确的能力边界。 docs/vibevoice-realtime-0.5b.md 写明该实时变体只支持单说话人，模型当前面向英文，其它语言可能产生不可预期的结果；额外提供的多语种音色在文档里被称为 experimental、并注明未经充分测试；风险与限制一节还列出不支持读代码、公式与生僻符号，输入文本极短时稳定性会下降。同一份文档的 TODO 里，“流式文本输入”与”合入官方 transformers 仓库”两项是未打勾的——而文档标题与首段都写着 streaming text input，这两处怎么理解需要以仓库最新内容为准，我们只把它们并排指出来。

文档与代码的默认值不完全一致。 docs/vibevoice-vllm-asr.md 的环境变量表把 VIBEVOICE_FFMPEG_MAX_CONCURRENCY 的 Default 写成 64，而 vibevoice/processor/audio_utils.py 里 _get_ffmpeg_max_concurrency() 在环境变量为空时返回 0，注释写的是 0 或负数表示不做显式限制；文档里的 64 出现在 docker run 命令的 -e 参数里。这些都是仓库当前代码与文档里的值，随版本可能变动。

怎么验证你读对了

装好包之后，最省事的核对方式是直接把导出清单打出来：

import vibevoice, vibevoice.modular, vibevoice.processor

print(vibevoice.__all__)
print(vibevoice.modular.__all__)
print(vibevoice.processor.__all__)

以上为按仓库代码中的接口语义组合的示例，未经实测，以仓库最新代码为准。如果第一行打出来的不是那四个 Streaming 相关符号，说明你装到的版本已经和本文描述的结构不一样了，请直接以仓库最新内容为准。

想确认 vLLM 插件的入口点是否真的注册上了，docs/vibevoice-vllm-asr.md 的 Troubleshooting 一节给了现成的两条：pip show vibevoice 和 pip show -f vibevoice | grep entry。Windows 的 PowerShell 里没有 grep，仓库里也没有给 Windows 侧的等价写法，你需要自行换用本机可用的筛选方式——这属于通用做法，不是该项目官方内容。

最后一句：这个项目持续更新，上面所有目录、类名、导出清单与配置字段都请以仓库最新内容为准。

本文依据 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 生成内容时主动披露。