在 Colab 上跑官方 notebook：VibeVoice 仓库给的那份怎么用

VibeVoice 仓库里给了一份 Colab notebook：demo/vibevoice_realtime_colab.ipynb。它对应的是 VibeVoice-Realtime-0.5B 这个模型，不是别的成员——docs/vibevoice-realtime-0.5b.md 写明这个实时变体只支持单说话人，且主要面向英文，其它语言可能产生不可预期的结果。仓库 README 的模型表里，VibeVoice-TTS-1.5B 那一行的 Quick Try 标的是 Disabled，Realtime-0.5B 那一行指向的才是这份 Colab。所以你在 Colab 上打开的这份，和网上那些讲 VibeVoice-TTS 的教程不是同一件事。

notebook 的结构很简单：Step 1 一个大单元做环境准备，Step 2 一个大单元启动服务并打隧道，中间夹着两处标了 [Optional] 的说明，底下挂着三个可选单元（Hugging Face 登录、重下模型、下实验音色）。麻烦几乎全出在这几个单元的顺序和它们打印的那些对勾上。

一、单元跑完全是 ✅，环境却不对

现象：Step 1 从头到尾打印了三条带 ✅ 的消息，看起来一切正常，但后面启动服务时报错，或者根本没有 GPU。

怎么确认：把 Step 1 的输出从头往下读，重点看两处。

第一处是开头的 GPU 检查，它的判定条件在 notebook 里写得很直白：

import torch
if torch.cuda.is_available() and "T4" in torch.cuda.get_device_name(0):
    print("✅ T4 GPU detected")
else:
    print(...)

注意 else 分支只是 print 一段警告文字，没有 raise，也没有 sys.exit。也就是说运行时类型选错了，这个单元照样会继续往下执行安装和下载，最后依旧打印后面那两条 ✅。判定动作就是往上翻，看有没有出现那段以 ⚠️ WARNING: T4 GPU not detected 开头的文字。

第二处是克隆仓库那一行：

![ -d /content/VibeVoice ] || git clone --quiet --branch main --depth 1 https://github.com/microsoft/VibeVoice.git /content/VibeVoice
print("✅ Cloned VibeVoice repository")

|| 是短路：目录已经存在就不会执行 git clone。而下一行的 print 是无条件的。两处放在一起看，结论是——同一个 runtime 里第二次执行这个单元，你看到的 ”✅ Cloned” 并不代表这次真的拉取了代码，仓库还是上一次那份。

处置：运行时类型按 notebook 警告文字里给的路径改（Runtime → Change runtime type → 选 T4 GPU → 弹出 Disconnect and delete runtime 时点 OK → Save）。想要一份干净的代码，就断开并删除 runtime 后重来，或者自己把 /content/VibeVoice 删掉再执行该单元。

怎么验证：改完重跑 Step 1，第一条应当是 ✅ T4 GPU detected；想确认克隆确实发生了，看这次有没有被 -d 判断短路掉——目录不存在时 git clone 才会真的执行。

什么情况说明不是这个原因：如果 ✅ T4 GPU detected 出现了，/content/VibeVoice 也是这次新建的，那后续报错就与运行时类型和代码新旧无关，往下一节看。

二、安装单元和 transformers 的版本

Step 1 的安装行是：

!uv pip --quiet install --system -e /content/VibeVoice[streamingtts]

-e 是可编辑安装，装的是刚克隆下来那个目录；[streamingtts] 是 extra。这个 extra 在 pyproject.toml 里只做一件事：

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

而同一个文件的基础依赖写的是 transformers>=4.51.3,<5.0.0。这两处摆在一起就能看出，带不带这个方括号后缀，装出来的 transformers 是完全不同的约束：带上是钉死一个版本，不带是一个范围。照抄 notebook 的写法时别把方括号丢了——在有些 shell 里方括号会被当成通配符，需要加引号，Colab 的这一行是直接写的。另外 pyproject.toml 的 requires-python 是 >=3.10。以上均为仓库当前文件里的声明，随版本可能变动。

判定动作：安装单元加了 --quiet，出错信息容易被淹没。把 --quiet 去掉重跑一次，看解析依赖时有没有冲突提示，比事后猜要快。

什么情况说明不是这个原因：如果后面报错的堆栈里根本没有出现 transformers 或 vibevoice 的导入行，那就不是装的问题。

三、模型下载迟迟不结束

Step 1 的最后一步是 snapshot_download("microsoft/VibeVoice-Realtime-0.5B", local_dir="/content/models/VibeVoice-Realtime-0.5B")。

notebook 自己在下一个 markdown 单元里给了处置，原话的意思是：下载若超过约一分钟大概率是卡住了，做三件事——中断执行、登录 Hugging Face、再下一次。对应的就是那两个 [Optional] 单元：一个执行 login()，另一个把同样的 snapshot_download 再调一遍。

处置：点中断，执行 login() 那个单元，按提示完成登录，再执行重下那个单元。注意 local_dir 要和 Step 2 里 --model_path 指的目录保持一致，两处在 notebook 里都是 /content/models/VibeVoice-Realtime-0.5B。

怎么验证：重下的单元末尾会打印 ✅ Downloaded model: microsoft/VibeVoice-Realtime-0.5B；更实在的验证是直接列一下 local_dir，看权重文件在不在。

什么情况说明不是这个原因：如果 Step 2 的报错是找不到音色文件或端口相关，那和模型下载无关。

四、Step 2 一直不打印 Public URL

现象：Step 2 的单元一直在转，没有报错，也不出那条 ✅ Public URL:。

这个单元的逻辑要先看明白：它用 subprocess.Popen 起了两个进程，一个是

python /content/VibeVoice/demo/vibevoice_realtime_demo.py --model_path /content/models/VibeVoice-Realtime-0.5B --port 8000

另一个是 ./cloudflared tunnel --url http://localhost:8000 --no-autoupdate。然后两个线程分别读它们的输出：read_srv 见到 "Uvicorn running on" 才把 server_ready 置 True，read_cf 用正则 (https://[a-z0-9-]+\.trycloudflare\.com) 抓公网地址。最后是 while True 加 time.sleep(0.25)，两个条件同时满足才打印，且这个循环本身没有退出分支——单元一直转是它的常态，不代表出错。

怎么确认是哪一头出了问题：看单元有没有在往外吐服务端日志。read_srv 里有 print(ln.strip())，服务进程的每一行输出都会打到单元底下；而 read_cf 只做正则匹配、匹配到就 break，不打印任何行。所以：

• 单元里能看到模型加载日志、甚至 Python 堆栈 → 问题在服务端。demo/vibevoice_realtime_demo.py 里 --device 默认是 cuda（这是仓库当前代码里的默认值，随版本可能变动），Colab 这一行也没有显式改它；而 demo/web/app.py 只对 mps 写了「不可用就退回 cpu」的分支，cuda 这一路在代码里没有对应的可用性检查与回落分支。
• 单元里一片安静、连 [startup] Loading processor from ... 都没有 → 服务进程可能压根没起来；再往上确认 Step 1 是否真的装成功。
• 服务端日志正常、结尾也有 Uvicorn 那行，就是不出地址 → 问题在隧道那一头，而它的输出被吞掉了。

处置：端口两处必须对上。vibevoice_realtime_demo.py 的 argparse 里 --port 默认是 3000（这是仓库当前代码里的默认值，随版本可能变动），Colab 单元显式传了 8000，隧道也写死了 http://localhost:8000。你要是只改了其中一个，隧道就会指向一个没人监听的端口。同理，./cloudflared 是相对路径，wget 下载它时的工作目录和 Step 2 执行时的工作目录必须是同一个，中途 %cd 过就要自己补路径。

需要换设备时可以这样组合（该脚本的 --device 取值在 argparse 里限定为 cpu、cuda、mpx、mps 四个）：

python demo/vibevoice_realtime_demo.py --model_path /content/models/VibeVoice-Realtime-0.5B --port 8000 --device cpu

以上为按仓库文档中的参数语义组合的示例，未经实测，以仓库最新内容与 --help 的实际输出为准。顺带一提，demo/web/app.py 里对 mpx 有一句 Note: device 'mpx' detected, treating it as 'mps'.，也就是把它当 mps 处理；mps 不可用时再退回 cpu。

怎么验证：地址只会打印一次（打印后代码把 public_url 置回了 None，而抓地址的那个线程匹配到就已经 break 了），别刷掉了才去找。

什么情况说明不是这个原因：如果服务端日志里出现的是 Voices directory not found 或 No voice preset (.pt) files found，那是音色的问题，见下一节。

五、实验音色必须在启动服务之前下

[Optional] 里的 !bash /content/VibeVoice/demo/download_experimental_voices.sh 位置在 Step 2 之前，这个顺序是有讲究的。

demo/web/app.py 里，加载音色的 _load_voice_presets() 把目录定在 BASE.parent / "voices" / "streaming_model"（BASE 是 web/ 目录，所以实际是 demo/voices/streaming_model），用 rglob("*.pt") 递归扫一遍；目录不存在或一个 .pt 都没有，就分别抛 Voices directory not found 和 No voice preset (.pt) files found。而这个方法是在 StreamingTTSService.load() 里调的，load() 又由挂在 FastAPI @app.on_event("startup") 上的 _startup() 调用——只在服务启动那一次扫描。下载脚本把压缩包解到 voices/streaming_model/experimental_voices，正好在 rglob 的覆盖范围内，但服务已经启动之后再下，新音色不会被扫到，得重启服务进程。

另外 load() 里读了 VOICE_PRESET 这个环境变量来选默认音色，交给 _determine_voice_key() 处理：取不到或名字对不上就回落到 en-Carter_man，连这个名字也不在扫出来的预设里时，取排序后的第一个并打印 [startup] Using fallback voice preset:；这些默认值同样以仓库最新代码为准。这些多语言音色在仓库里被明确标注为 experimental，docs/vibevoice-realtime-0.5b.md 也写明这些多语言表现未经充分测试，请谨慎使用。

六、想在 Windows 本机复刻这份 notebook

Colab 这一侧是 Linux，直接照搬到 Windows 会有几处对不上：

• download_experimental_voices.sh 是 bash 脚本，开头 set -e，内部用 wget 和 tar。Windows 上需要 WSL 或 Git Bash 这类环境，PowerShell 直接执行不了。
• notebook 下载的是 cloudflared-linux-amd64 这个二进制，Windows 上不能用。
• demo/web/app.py 里保留 model_path 为字符串那一行带着注释，说明 Path() 在 Windows 上会把 / 换成 \，从而破坏 Hugging Face 仓库 ID 的写法——传仓库 ID 而不是本地目录时，这个细节值得留意。
• docs/vibevoice-realtime-0.5b.md 给的安装路径是先起 NVIDIA 的 PyTorch 容器再 pip install -e .[streamingtts]，并提到 flash attention 需要另行安装；app.py 在 cuda 分支上首选 flash_attention_2，加载失败会打印一段提示后退到 sdpa，那段提示里明确写了只有 flash_attention_2 经过完整测试。

该项目持续更新，上面涉及的文件路径、参数名与默认值都以仓库最新内容为准。

---

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

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