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是testsoutput_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去加载名字差一个字符就FileNotFoundYAML 里的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。若你换成了社区微调模型却没换 vocabconvert_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再动自定义 tomltoml 里model与configs/下文件名逐字一致社区模型同时带--ckpt_file和--vocab_fileffmpeg -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），仅供参考 
长河君 · 2026/11/2 6:14:04 · 阅读 1.2k F5-TTS 语音合成失败排查：定位 5 类无输出与音质异常现场
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是testsoutput_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去加载名字差一个字符就FileNotFoundYAML 里的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。若你换成了社区微调模型却没换 vocabconvert_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再动自定义 tomltoml 里model与configs/下文件名逐字一致社区模型同时带--ckpt_file和--vocab_fileffmpeg -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），仅供参考