想跑 VibeVoice-TTS 却发现状态特殊：仓库到底还剩什么

2026-08-18

现象：教程里的导入语句和仓库对不上

一个很典型的场景：你搜到一篇讲 VibeVoice 做长音频合成的文章，照着写下 from vibevoice import VibeVoiceForConditionalGeneration，或者去 demo/ 目录里找那个跑 TTS 的推理脚本，结果都对不上。再翻 docs/vibevoice-tts.md，模型介绍写得很完整，可到了「Installation and Usage」那一节，正文只有一句 Disabled due to widespread misuse.。

这时候第一反应通常是「我装错版本了」或者「我 clone 的分支不对」。但在改环境之前，先花五分钟把仓库当前的状态确认一遍——这一类对不上，很可能压根不是环境问题。

怎么确认是这个问题：五个可执行的判定动作

下面五步都只需要读文件，不需要下载权重。仓库根目录记作 <你的项目目录>。

第一步，读 README 的 News 节。 里面有一条日期为 2025-09-05 的记录，原文写明：VibeVoice 是一个旨在推动语音合成社区协作的开源研究框架，发布后他们发现了与既定意图不符的使用方式，由于负责任地使用 AI 是微软的指导原则之一，因此从该仓库移除了 VibeVoice-TTS 代码。这条是判定的起点。

Linux/macOS：

grep -n "2025-09-05" README.md

Windows PowerShell：

Select-String -Path README.md -Pattern "2025-09-05"

第二步，看包的导出边界。 打开 vibevoice/__init__.py，它的 __all__ 里是 VibeVoiceStreamingForConditionalGenerationInference、VibeVoiceStreamingConfig、VibeVoiceStreamingProcessor、VibeVoiceTokenizerProcessor。再打开 vibevoice/modular/__init__.py，它的 __all__ 是 Streaming 系列的六个符号：VibeVoiceStreamingForConditionalGenerationInference、VibeVoiceStreamingConfig、VibeVoiceStreamingModel、VibeVoiceStreamingPreTrainedModel、AudioStreamer、AsyncAudioStreamer。

两处 __all__ 里都没有 TTS 的模型类。 所以那句 from vibevoice import VibeVoiceForConditionalGeneration 对不上，不是拼错了名字，是这个名字本来就不在包的顶层命名空间里。

第三步，读 vibevoice/modular/modeling_vibevoice.py 的第一行。 这个文件确实还在仓库里，但它的首行是一句注释，标明该文件复制自社区 fork github.com/vibevoice-community/VibeVoice 的同名路径。也就是说，现在你在官方仓库里读到的这份 TTS 建模代码，其来源在文件头部被显式注明了。

head -n 1 vibevoice/modular/modeling_vibevoice.py

Windows PowerShell 下取首行：

Get-Content vibevoice/modular/modeling_vibevoice.py -TotalCount 1

第四步，看 docs/vibevoice-tts.md 的安装用法节。 前面提到的那句 Disabled due to widespread misuse. 就在这里。同一篇文档的模型表格里，VibeVoice-Large 那一行的 Weight 列写的是 Disabled 而不是链接。

第五步，对一下 Hugging Face 侧。 README 顶部的模型表格里，VibeVoice-TTS-1.5B 这一行的 Quick Try 列写的是 Disabled；而 VibeVoice-1.5B 的 Hugging Face 模型卡在其模型表里，把 VibeVoice-Large 的权重同样标成了 Disabled。仓库侧与模型卡侧是一致的。

五步都对上，基本可以停止折腾环境了。

仓库里现在到底还剩什么

确认状态之后，更有用的问题是：留下来的这部分能读到什么。 逐个说。

配置层是完整的。 vibevoice/modular/configuration_vibevoice.py 的 __all__ 导出五个配置类：VibeVoiceAcousticTokenizerConfig、VibeVoiceSemanticTokenizerConfig、VibeVoiceDiffusionHeadConfig、VibeVoiceConfig、VibeVoiceASRConfig。前三个的 model_type 分别是 vibevoice_acoustic_tokenizer、vibevoice_semantic_tokenizer、vibevoice_diffusion_head。这里有个容易踩的地方：VibeVoiceConfig 与 VibeVoiceASRConfig 的 model_type 都写成了 vibevoice。这是同一个文件里白纸黑字的两处，仓库里我们没有找到关于这一点的进一步说明，只把它摆在这儿，不做推测。

建模层的类还在，但只在模块自己的 __all__ 里。 modeling_vibevoice.py 定义了 VibeVoiceCausalLMOutputWithPast、VibeVoiceGenerationOutput、SpeechConnector、VibeVoicePreTrainedModel、VibeVoiceModel、VibeVoiceForConditionalGeneration，文件末尾的 __all__ 里也列了其中五个，并调用了 AutoModel.register(VibeVoiceConfig, VibeVoiceModel) 与 AutoModelForCausalLM.register(VibeVoiceConfig, VibeVoiceForConditionalGeneration)。注意这两句是模块被导入时才执行的注册，注册进 Auto 类和「官方支持你拿它做 TTS 推理」是两回事——README 的移除记录与文档里那句 Disabled 才是仓库对可用性的表态。

这个文件在仓库内部还有引用。 vibevoice/modular/modeling_vibevoice_asr.py 从 .modeling_vibevoice 导入了 VibeVoiceCausalLMOutputWithPast 和 SpeechConnector。这是代码里写着的引用关系，能看到的就这么多；至于它为什么留在仓库里，仓库没写，我们不替作者解释。

processor 层的口子比 modular 层开。 vibevoice/processor/__init__.py 的 __all__ 里有 VibeVoiceProcessor、VibeVoiceStreamingProcessor、VibeVoiceTokenizerProcessor、AudioNormalizer——TTS 侧的 VibeVoiceProcessor 是导出的，虽然顶层 vibevoice/__init__.py 没有把它再往上抬一层。这个类里能读到相当具体的东西：构造函数签名是 __init__(self, tokenizer=None, audio_processor=None, speech_tok_compress_ratio=3200, db_normalize=True, **kwargs)，其中 speech_tok_compress_ratio 与 db_normalize 的这两个取值是仓库当前代码里的默认值，随版本可能变动；它还在 __init__ 里写死了一段 system_prompt 字符串，内容是让模型把各说话人提供的文本转成语音、并使用各自不同的音色。

再往下，_parse_script 用的正则是 ^Speaker\s+(\d+)\s*:\s*(.*)$（带 re.IGNORECASE），并且在所有 speaker id 都大于 0 时会整体减一归一化到从 0 开始。这就是那套 Speaker 0: / Speaker 1: 剧本格式在代码里的落点。想弄明白多说话人剧本是怎么被切开的，读这个函数比读任何二手教程都直接。

还有两处细节值得一提。 一是 vibevoice/configs/ 下的两个 JSON，文件名分别是 qwen2.5_1.5b_64k.json 与 qwen2.5_7b_32k.json。以前者为例，它的顶层键包含 acoustic_vae_dim、semantic_vae_dim、acoustic_tokenizer_config、semantic_tokenizer_config、diffusion_head_config、decoder_config——正好对应前面那几个配置类的结构。有意思的是它的 model_type 写的是 vibepod，和 configuration_vibevoice.py 里 VibeVoiceConfig 声明的 vibevoice 不是一个值；而这两个 JSON 的路径，我们在仓库的 Python 与 Markdown 文件里没有找到任何引用。两件事摆在一起就到此为止，不往下推。二是 demo/text_examples/1p_vibevoice.txt，里面是一段介绍 VibeVoice 框架本身的英文说明文本。这个文件不是无人认领的遗留物：demo/realtime_model_inference_from_file.py 把它写成了 --txt_path 这个参数的默认值，docs/vibevoice-realtime-0.5b.md 的示例命令里也显式传了它。也就是说它服务的是 Realtime 那条线，看到 text_examples/ 目录别顺手把它当成 TTS 的遗产。

缺的是「把流程走完所需要的那一半」。 demo/ 目录下有 ASR 与 Realtime 的推理脚本、Gradio 与 Web 演示，demo/web/app.py 导入的是 VibeVoiceStreamingForConditionalGenerationInference 与 VibeVoiceStreamingProcessor；demo/voices/ 下只有 streaming_model/ 一个子目录。TTS 那条线对应的推理入口脚本与音色素材，我们在当前仓库里没有找到。

处置后怎么复核

复核只做一件事：确认你面对的是「仓库当前的导出边界」，而不是自己写错了。

import vibevoice
print(vibevoice.__all__)

from vibevoice.processor import VibeVoiceProcessor

按 vibevoice/__init__.py 与 vibevoice/processor/__init__.py 里写着的内容，第一行打印出来的应当是前面列过的那四个 Streaming 侧符号，VibeVoiceProcessor 则可以从 vibevoice.processor 取到。以上为按仓库代码中的接口语义组合的示例，未经实测，以仓库最新代码为准。

如果你的目标只是「要有一条能走的语音合成路线」，README 的 News 节里 2025-12-03 那条记录了 VibeVoice-Realtime-0.5B 的开源，文档在 docs/vibevoice-realtime-0.5b.md，代码路径就是上面那批 Streaming 符号。要注意 2025-12-16 那条新闻自述新增的多语种与英语风格音色是**实验性（experimental）**的，仓库把它归在「供探索」的位置上，不要当成稳定能力来规划。

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

这一步不能省，否则很容易把所有导入失败都归到「代码被移除」上：

报 ModuleNotFoundError: No module named 'vibevoice'：这是包没装上，跟移除没关系。pyproject.toml 里 name 是 vibevoice，并用 requires-python 声明了最低 Python 版本，具体数值以仓库最新内容为准。
失败的是 Streaming 系列的名字：那条线在两处 __all__ 里都有，不属于本文这个状态。该往依赖与安装方向查。
报错来自 transformers 的接口不匹配：pyproject.toml 的主依赖对 transformers 同时写了下限与上限约束，而 [project.optional-dependencies] 里的 streamingtts 这一组用 == 把它钉死在一个精确版本上。两处口径不一样，你按不按 extras 装，最后拿到的 transformers 就可能落在不同的接口上（这类版本约束随仓库更新变动，具体数值以 pyproject.toml 最新内容为准）。这是依赖问题，不是代码被移除的问题。
你查的是 ASR 相关的类：ASR 是另一条线，文档在 docs/vibevoice-asr.md，别和 TTS 的状态混在一起。VibeVoice 名下的 ASR、CPU 边缘、TTS、Realtime 是不同模型，文档各自独立。
你 clone 的其实是社区 fork：那份仓库的状态不在本文依据范围内。本文只依据 github.com/microsoft/VibeVoice。

最后提醒一句用得上的判断习惯：代码文件在仓库里 ≠ 这个功能官方可用。 这次的例子里，判定依据不在代码有没有，而在 README 的移除记录、文档里那句 Disabled、包 __all__ 的导出边界，以及文件首行那句 fork 来源注释——四处放在一起才是完整的状态。

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