F5-TTS 语音合成失败排查：定位 5 类无输出与音质异常现场
【免费下载链接】F5-TTSOfficial code for "F5-TTS: A Fairytaler that Fakes Fluent and Faithful Speech with Flow Matching"项目地址: https://gitcode.com/gh_mirrors/f5/F5-TTS
$ f5-tts_infer-cli Using F5TTS_v1_Base... vocab : .../infer/examples/vocab.txt model : .../model_1250000.safetensors Voice: main （进程结束，tests/ 里没有任何 .wav）先跑通官方示例再谈自定义，这是整篇的分诊前提。下面按你实际看到的现象分 5 类现场，每类都按"看到什么 → 去哪里查 → 改哪里"推进，动作全部落在你本地（改 toml、加命令行参数、换 ckpt 路径），不碰仓库源码。
现场一：命令跑完退出码 0，目录里却没有 wav
这一节解决"没报错、就是没文件"。
输出其实写了，只是你没看那个目录
默认output_dir是tests，output_file是带时间戳的infer_cli_<时间>.wav，所以成品落在./tests/而不是你当前目录。打开 src/f5_tts/infer/infer_cli.py 第 200 行附近可看到这两行默认值。
ls -t tests/*.wav确认文件在不在。若确实要固定位置，显式传-o/-w，或在 toml 里写output_dir/output_file——显式传参能覆盖默认时间戳名，避免你找不到刚生成的那个文件。
成品为空是因为"没东西可拼"
最终落盘有一个前置条件：generated_audio_segments非空。当gen_text是纯空白、或gen_file指向一个空文件时，列表为空，脚本直接跳过写文件，退出码仍是 0，于是看起来"成功了却没产物"。
另有一种隐形的慢：ref_text留空会触发 Whisper 对参考音频做转写，这一步要联网并占额外显存，慢时像卡死。排查顺序是先确认gen_text非空，再决定要不要手写ref_text绕过 ASR。
现场二：还没开始生成就抛错，YAML 与检查点对不上
这一节解决OmegaConf.load、get_class、检查点下载一类的加载期报错。
模型名必须与 configs 下的文件名逐字一致
model参数会被拼成configs/{model}.yaml去加载，名字差一个字符就FileNotFound；YAML 里的backbone字段再决定get_class去哪个类。打开 src/f5_tts/configs/ 看有哪些可选：F5TTS_v1_Base、F5TTS_Base、E2TTS_Base等。
ls src/f5_tts/configs/把 toml 里的model改成上面某个真实存在的文件名。之所以强调逐字一致，是因为这行是字符串直接拼路径，没有模糊匹配兜底。
检查点默认联网下载，可换成本地路径
不传--ckpt_file时，脚本用hf://SWivid/F5-TTS/{model}/model_1250000.safetensors自动拉取，断网或代理不通就会失败。⚠️ 若你用的是社区微调模型，还要按 src/f5_tts/infer/SHARED.md 里每个模型给出的 ckpt 与 vocab 路径来，别套默认路径。
f5-tts_infer-cli -c my.toml \ --ckpt_file ckpts/F5TTS_v1_Base/model_1250000.safetensors \ --vocab_file ckpts/F5TTS_v1_Base/vocab.txt换本地路径能绕开网络这层；社区模型必须同时换--vocab_file，否则 token 对不上，后面合成会是乱音。
现场三：wav 落盘了，但内容是空白或杂音
这一节解决"有文件、没声音"和"有声音、听不清"。
纯静音先查 FFmpeg 与声码器
官方 infer README 明确写了：生成结果是纯静音时，优先查 FFmpeg 是否装好。参考音频预处理依赖pydub+ ffmpeg 解码，缺 ffmpeg 时读出来的参考音频是空的，整条链路就跟着空。
ffmpeg -version conda install ffmpeg # 未安装时装好 ffmpeg 再重跑一次，这是空白输出最常见的原因。
中文杂音多半是 tokenizer 与 vocab 不配套
F5TTS_v1_Base的tokenizer是pinyin，默认 vocab 是infer/examples/vocab.txt。若你换成了社区微调模型却没换 vocab，convert_char_to_pinyin产出的拼音不在 vocab 表里，会被替换成占位符，听起来是杂音或漏字。数字同理：想让数字按中文读，需先转成中文汉字，否则默认按英文读。
对齐规则很简单：模型和 vocab 必须来自同一个发布包，以仓库当前 HEAD 为准。
现场四：音调漂移、爆音：采样率与声码器错配
这一节解决"能出声但音高/音色不对"，根子通常在 vocos 与 bigvgan 的混用。
声码器与 mel 配置有断言，错配会直接中断
默认target_sample_rate = 24000、n_mel_channels = 100，默认声码器是vocos（即 F5-TTS 24kHz 采样率）。infer_cli.py第 277 行附近对非F5TTS_Base的模型有一条断言：vocoder_name必须等于 YAML 里mel_spec.mel_spec_type。你给 v1 模型手动--vocoder_name bigvgan，就会在这条断言上中断，而不是出坏音。
# 仅 F5TTS_Base 支持 bigvgan f5-tts_infer-cli --model F5TTS_Base \ --vocoder_name bigvgan --load_vocoder_from_localv1 系列请保持vocos默认，别手动切 vocoder；这条断言存在的意义就是挡住这种错配。
本地 bigvgan 要先 init 子模块
bigvgan 走的是third_party/BigVGAN子模块。若没初始化，import bigvgan会失败并提示按 README init submodule。这不是模型问题，是依赖没拉全——用--load_vocoder_from_local前确认子模块已更新，否则声码器加载不进来。
现场五：参考音频被截断、念错语言：输入侧问题
这一节解决"能生成但内容不对"，问题出在喂进去的参考音频和文本。
超过 12 秒会被自动裁剪，结尾要留静音
参考音频超过 ~12 秒会被三级裁剪逻辑压到 12 秒，src/f5_tts/infer/utils_infer.py 先按长静音切、再按短静音切、最后硬截。裁剪点落在词中间，合成就会断词。正确做法：参考音频控制在 12 秒内，且结尾留约 1 秒静音——留尾部静音能让裁剪点避开词尾。
ref_text 与 ref_audio 不一致会直接念乱
ref_text是参考音频的逐字转录，两者对不上时，模型学到的是错误的音文对齐，整段生成都歪。排查时先听参考音频、再逐字核对ref_text；长文本会被chunk_text自动分块，分块按句末标点切，英文句末后面要留一个空格才算一句。
生成偏长时可用--fix_duration锁总时长；显存吃紧时可降--nfe_step——但降nfe_step是牺牲一点质量换显存，不是修音质的手段，别用它去掩盖声码器或 vocab 的错配。
上线前自检清单
- ✅ 官方示例
f5-tts_infer-cli能产出tests/*.wav，再动自定义 toml - toml 里
model与configs/下文件名逐字一致；社区模型同时带--ckpt_file和--vocab_file ffmpeg -version有输出；v1 系列保持 vocos 默认声码器- 参考音频 <12s、结尾留约 1s 静音，且
ref_text逐字与音频一致
【免费下载链接】F5-TTSOfficial code for "F5-TTS: A Fairytaler that Fakes Fluent and Faithful Speech with Flow Matching"项目地址: https://gitcode.com/gh_mirrors/f5/F5-TTS
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
/YOLO蘑菇检测)
)
