服务中断后自动恢复：VibeVoice 仓库自带的恢复脚本覆盖了什么
先说清楚本文讲的是哪一条链路：VibeVoice 仓库里的 vllm_plugin/ 是 ASR 模型的 vLLM 部署插件，对应文档是 docs/vibevoice-vllm-asr.md，和 docs/vibevoice-tts.md、docs/vibevoice-realtime-0.5b.md 讲的是不同模型。下面提到的两个脚本都在 vllm_plugin/tests/ 下，只服务于 ASR 这条线。
现象：长音频转到一半，输出开始鬼打墙
典型的场景是这样：你按文档把服务起在容器里，拿一段会议录音去转写，前面几分钟的分段都正常出来了，转到某一段之后，输出开始一遍一遍重复同一句话，或者同一个 JSON 片段反复刷屏，怎么都停不下来。也可能是另一种：流到一半直接没了，脚本打印完时间统计就退出了。
这两种现象在终端上看着很像，处置方式却完全相反。仓库里的 vllm_plugin/tests/test_api_auto_recover.py 只自动兜住其中一种。
第一步：确认是不是重复循环
判定动作很直接——带 --debug 重跑一次。文档 docs/vibevoice-vllm-asr.md 给出的调用方式是：
# With auto-recovery from repetition loops (for long audio)
docker exec -it vibevoice-vllm python3 vllm_plugin/tests/test_api_auto_recover.py /app/audio.wav
脚本自身的 docstring 里另给了一条带开关的用法示例：
# Debug mode (show recovery info)
python3 test_api_auto_recover.py audio.wav --debug
以上两段分别原样取自仓库文档与脚本 docstring。--debug 是脚本 argparse 里定义的开关，帮助文本写的是 Show recovery debug info。加上它之后，脚本内部的 _log() 会把恢复信息写到 stderr（注意不是 stdout，转写正文走的是 stdout，两者是分开的）。
看 stderr 里出现的是哪一类标记，问题就定性了：
| stderr 里看到的 | 代码里的出处 | 说明 |
|---|---|---|
[LOOP DETECTED at char N] | 检测到重复后立刻打印 | 确认是重复循环，恢复逻辑会接管 |
[RECOVERY #n] Continuing from ... chars | 进入重试且有可用前缀 | 从已确认内容续写 |
[RECOVERY #n] Restarting from scratch | 进入重试但没有可用前缀 | 整段从头再来 |
[TIMEOUT] | requests.exceptions.Timeout 分支 | 不是重复循环 |
[ERROR] <状态码> - ... | HTTP 状态码非 200 的分支 | 不是重复循环 |
只有第一类标记出现，才说明你撞上的是这个脚本设计要处理的那种故障。
第二步：脚本模拟并处置的到底是什么故障
值得先把一件事挑明：test_api_auto_recover.py 是一个可执行的手动调用脚本，__main__ 走 argparse 取参数，文件里没有 assert，也没有 pytest 的测试函数。所以「自带的恢复测试」这个说法，准确地讲是「自带一份带恢复逻辑的调用样例」，它把恢复策略写进了正常请求路径，而不是用断言去校验某个模块的行为。
它认定的故障只有一种：模型输出进入重复循环。判定交给文件里的 RepetitionDetector 类，_check_repetition() 用了两种办法。第一种是拿窗口末尾的定长子串当候选 pattern，从尾部往前逐段比对，数出它连续重复了几次；第二种是把窗口按空格切成词，取末尾 2 到 5 个词组成的短语，同样往前数连续重复次数。任意一种数到的次数达到阈值，就判为循环。
这里有个细节值得注意：RepetitionDetector.__init__ 的形参默认值与 stream_with_recovery() 里实际构造时传入的值并不一致——构造处显式传了 min_pattern_len=10、min_repeats=10、window_size=400，并在行内注释写明「Must repeat 10+ times」。也就是说类签名上的默认阈值并不是这条链路实际生效的阈值，你想调灵敏度，改构造处那三个实参才有用。这些都是仓库当前代码里的值，随版本可能变动。
_is_meaningful() 还做了一层过滤：把 pattern 去掉首尾空白后，如果去重后的字符种类太少（代码里的判断是 len(set(clean)) < 3），就认为这段是垃圾内容——垃圾内容一份都不保留，有意义的内容则保留一份实例，剩下的重复部分丢弃。
第三步：检测到之后，代码做了哪些恢复动作
按 stream_with_recovery() 的实现，一次恢复包含这么几步。
采样参数切换。 首次请求是贪心解码，payload 里 temperature 为 0.0、top_p 为 1.0；进入恢复态后按 recovery_temp = 0.1 + 0.1 * retry_count 逐次抬高温度，top_p 改成 0.95。函数 docstring 把这条策略写成「temperature=0.2/0.3/0.4 for retry 1/2/3」。这些是仓库当前代码里的值，随版本可能变动。
用已确认内容当前缀续写。 重试时脚本会往 messages 里追加一条 {"role": "assistant", "content": accumulated_text}，代码注释写的是「vLLM will continue from here」。前缀取的不是检测器算出的 good_end，而是 user_safe_printed_len——即已经打印给用户看过的那一截。
打印边界与回滚边界对齐。 这是整个脚本里最容易被忽略、也最值得抄走的一处设计。它不是拿到内容就往屏幕上刷，而是先算 safe_end = max(0, len(full_text) - detector.window_size)，再用 _find_safe_print_boundary() 在这个位置之前找最后一个 },（转写结果是 JSON 段序列，}, 就是段与段的分隔），只把边界之前的内容打给用户。代码注释自述其意图是「ensures user never sees content that might be rolled back」。所以一旦回滚，被丢弃的永远是用户还没看到的那部分。
没有可用前缀就整段重来。 如果 user_safe_printed_len 还是 0，说明连一个完整分段都没确认过，accumulated_text 会被清空，从头再请求一次。
续写产生的格式毛刺就地修。 从 assistant 前缀继续时，模型可能在开头补上 [{、[，或者把前缀结尾的 },、} 又重复一遍，代码对这四种情况分别做了剥离并打 [STRIPPED leading ...] 日志。另外还有一条正则 ^\{"(\d+\.?\d*), 专门修「模型漏写 Start 键」的畸形 JSON，把 {"2.99, 补回成 {"Start":2.99,（这个 2.99 只是注释里的示例值），日志是 [FIXED malformed JSON: added Start key]。
重试次数用尽的行为。 max_retries 在调用处传的是 3。超出后脚本打印 [Error] Transcription failed due to model output anomaly. Please try another audio or contact support. 并 return None；外层的 test_transcription_with_recovery() 拿到 None 会打印失败提示并直接返回，不会写输出文件。
第四步：处置完怎么验证
三个可查的点。
一是看结尾统计。正常返回时脚本会打印 📄 Final output length: <N> chars；如果这行没出现、只看到失败提示，说明走的是 return None 分支。
二是检查落盘内容的段边界。传了 output_path 时结果才会写文件；由于打印与截断都锚在 }, 上，正常收尾的结果应当是完整的 JSON 段序列，如果你看到某段在中途被切开，那大概率不是恢复逻辑造成的。
三是拿不带恢复逻辑的版本做对照。同目录下的 test_api.py 是同一条 API 调用路径的精简版，请求体固定 temperature: 0.0、top_p: 1.0、stream: True，没有任何检测与重试，收到什么就打什么。同一段音频两个脚本都跑一遍，能把「模型输出问题」和「脚本处理问题」分开。顺带一提，test_api.py 结尾会打印一个 RTF（Real-Time Factor）指标，恢复版没有这一项。
第五步：哪些情况说明不是这个原因
这一步比前面四步都重要，因为脚本名字叫 auto_recover，很容易让人以为它什么中断都能兜。它不能。
- HTTP 状态码非 200：代码里是
_log一条[ERROR]然后return accumulated_text，没有重试。模型名不匹配、服务还没起来、反向代理没通，都落在这里。 - 请求超时：
requests.exceptions.Timeout分支同样是直接返回已累计文本，不重试。这里有个容易踩空的地方：timeout只是stream_with_recovery()的一个形参并带默认值，调用处并没有显式传它，外层的test_transcription_with_recovery()也没有这个参数，命令行更没有对应开关（argparse只定义了audio_path、output_path、--url、--hotwords、--debug）。也就是说想调超时只能改代码，从命令行是调不动的。 - 其它异常：兜底的
except Exception也是打一条日志、返回已累计文本。 - 音频准备阶段失败：
ffprobe取时长或读文件出错，会在发请求之前就被try/except捕获并return，连恢复逻辑的门都没进。文档的排查小节里写明要先确认 FFmpeg 可用。 - 输出被截断但并不重复：那更可能是生成长度到顶，跟循环检测无关。
换句话说，这份脚本自动恢复的是模型侧的输出异常，不是服务侧的中断。服务中断这一类，代码的行为是「把已经拿到的内容还给你，然后结束」，后续要不要重发请求，得你自己在外层做。
顺着源码还能看到两处「写了但没走通」的地方，读代码时别被带偏：文件里定义了 _find_last_segment_boundary()，但流程里实际调用的是 _find_safe_print_boundary()；RepetitionDetector 定义了公开方法 add_text()，而主循环是直接给 detector.text 赋值再调私有的 _check_repetition()。另外 stream_with_recovery() 的形参 audio_data_url 与 prompt_text 在函数体里没有被引用——重试所需的音频与提示词是靠复制 base_messages 带过去的。这几处只是陈述源码现状，不揣测作者意图。
Windows 上的两处差异
文档里的启动命令用了 -v $(pwd):/app，这在 PowerShell 里不成立，PowerShell 的写法是 ${PWD}；Git Bash 下 docker exec -it 有时需要前置 winpty 才不报输入设备错误。这两条是通用的容器使用经验，不是 VibeVoice 官方文档的内容，按你自己的环境调整。文档本身写明的一条硬约束是：音频/视频文件必须放在挂载进容器的目录里（示例中是 /app），否则脚本在容器内读不到。
该项目持续更新，上面涉及的脚本路径、参数名与代码里的取值都随版本变动，请以仓库最新内容为准。
本文依据 github.com/microsoft/VibeVoice 仓库与 Hugging Face 模型卡于 2026-08-18 的公开内容整理，
事实来自仓库内的文档与源码。我们没有下载权重、没有跑过推理、也没有做过训练，
因此不涉及显存占用、推理速度、识别准确率与音质的任何描述，也不与其它模型做比较或排名。
该项目持续更新，文中涉及的模块路径、配置字段与接口写法随版本变动，请以仓库最新内容为准。
仓库 README 的风险与限制一节写明：该模型仅供研究与开发用途， 未经进一步测试与开发不建议用于商业或真实场景，并特别提示了合成语音被用于伪造与虚假信息的风险。 使用合成语音时应遵守所在司法辖区的法律法规，并在分享 AI 生成内容时主动披露。
安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。