F5-TTS：基于流匹配的零样本语音克隆（中英双语）部署指南

F5-TTS 是上海交通大学 X-LANCE 实验室等团队开源的零样本语音合成（TTS）项目，论文标题为《F5-TTS: A Fairytaler that Fakes Fluent and Faithful Speech with Flow Matching》（arXiv:2410.06885）。其名称中的「F5」寓意像 fairytaler（说书人）一样，仅凭一段参考音频就能「伪造」出流畅、忠实的语音：给定任意几秒参考音频及其转写文本，模型即可克隆该音色朗读任意新文本。

技术上，F5-TTS 采用 Diffusion Transformer 结构并融入 ConvNeXt V2，配合名为 Sway Sampling 的推理期流步采样策略，在训练速度与推理性能上都明显优于同类方法。与传统自回归 TTS 逐帧生成不同，F5-TTS 基于流匹配（Flow Matching）直接学习从噪声语音到目标语音的连续变换路径，一次采样即可输出整段音频；Sway Sampling 则在推理期重新分配流方程各步的采样权重，在不增加训练成本的前提下显著提升音质。仓库内同时提供 E2 TTS（Flat-UNet Transformer）的最接近论文复现版本，方便对照研究。官方 v1 base 模型（2025/03/12 发布）训练了 125 万步，配置为 dim 1024、depth 22、heads 16、ff_mult 2、text_dim 512、conv_layers 4，训练数据为 Emilia 数据集约 9.5 万小时的中英双语语音；旧版 F5TTS_Base 训练了 120 万步。代码以 MIT 协议发布，但因训练数据 Emilia 是野外采集数据集，预训练权重采用 CC-BY-NC（非商用）许可，商用需自行评估授权。

一、项目官方信息

项目	信息
GitHub 仓库	SWivid/F5-TTS
在线 Demo	swivid.github.io/F5-TTS
模型权重	Hugging Face、ModelScope、Wisemodel
在线体验	HF Space、ModelScope Space
开源协议	代码 MIT；预训练权重 CC-BY-NC（非商用）
主要语言	Python 3.10+
训练数据	Emilia-ZH-EN（中英双语）
最新版本	2025/03/12 发布 F5-TTS v1 base 模型，训练与推理性能更佳

二、官方图片

F5-TTS 项目官方配图：

F5-TTS 项目配图

三、核心特性

F5-TTS 的定位是「零样本」语音克隆：无需任何目标说话人的训练过程，只要给一段参考音频和对应的转写文本，模型就能抓住该说话人的音色、韵律和情感风格，朗读全新的文本。官方围绕这一能力提供了从本地命令行、Web 界面到生产部署的完整工具链，主要特性如下：

零样本音色克隆：只需一段参考音频（建议 12 秒以内、末尾留约 1 秒静音），即可克隆音色生成新语音，无需为目标说话人训练。
流匹配（Flow Matching）架构：基于 Diffusion Transformer + ConvNeXt V2，训练与推理更快；Sway Sampling 采样策略大幅提升生成质量。
中英双语：基于 Emilia-ZH-EN 训练，原生支持中文与英文；社区共享模型（见仓库 SHARED.md）扩展了更多语种。
多风格 / 多说话人生成：通过 .toml 配置多个音色，在长文本中按 [main]、[town]、[country] 等标记切换角色。
带分块推理的基础 TTS：单次生成长度上限约 30 秒（含参考音频与输出音频的总长），CLI 与 Gradio 会自动对长文本分块生成；过长的参考音频会自动截断到约 12 秒。
Voice Chat：Gradio 应用内置基于 Qwen2.5-3B-Instruct 的语音对话能力。
生产级部署：提供 Triton + TensorRT-LLM 部署方案，单张 L20 GPU、并发 2 时平均延迟 253 ms、RTF 0.0394。

社区多语言模型

官方仓库仅提供中英双语 base 模型，但社区在 SHARED.md 中共享了大量志愿者训练或微调的模型卡，覆盖阿拉伯语、芬兰语、法语、德语、印地语、意大利语、日语、拉脱维亚语、普通话、俄语、西班牙语等语种，例如 SILMA AI 的阿英双语 Small 模型、AsmoKoskinen 的芬兰语模型、RASPIAUDIO 的法语模型、Jmica 的日语模型等。这些模型均开源并托管在 Hugging Face 上，使用者需尊重各自创作者的许可（部分为 Apache-2.0）。若你也训练了自己的模型，可在 Hugging Face 建立仓库上传裁剪后的 checkpoint（仅保留 ema_model_state_dict）与对应 vocab 文件，再提 Pull Request 把模型卡加进 SHARED.md。使用社区模型时，用 --ckpt_file 指向对应 model_xxx.safetensors、--vocab_file 指向对应 vocab 词表即可。

四、环境要求

Python 3.10 及以上（官方示例用 3.11）；FFmpeg（未安装会导致输出空白静音）；按硬件安装对应 PyTorch；GPU 推荐，CPU 可运行但较慢。权重首次推理时自动从 Hugging Face 下载，也可手动下载后用 --ckpt_file 指定。硬件方面，NVIDIA 显卡按 CUDA 版本安装 PyTorch 即可；AMD 仅支持 Linux 且需注意架构兼容性；Intel 显卡依赖 oneAPI/IPEX；Apple Silicon 走 MPS 后端。项目演进时间线：2024 年 10 月 8 日 F5-TTS 与 E2 TTS base 模型首次在 Hugging Face、ModelScope、Wisemodel 同步发布；2025 年 3 月 12 日发布 v1 base 模型，训练与推理性能均有提升，并有在线 demo 展示效果。

五、部署步骤

官方推荐先用 conda 或 virtualenv 创建独立环境避免依赖冲突，再按自己的硬件平台安装对应构建的 PyTorch，最后选择 pip 包安装（仅推理）或源码可编辑安装（需要训练微调）。各平台的 PyTorch 安装命令均以 download.pytorch.org/whl/ 为额外索引源，CUDA/ROCm/XPU 版本号需与本机驱动匹配。

1. 创建独立环境

conda create -n f5-tts python=3.11
conda activate f5-tts
conda install ffmpeg

2. 安装与设备匹配的 PyTorch

NVIDIA GPU（按 CUDA 版本选择）：

pip install torch==2.8.0+cu128 torchaudio==2.8.0+cu128 --extra-index-url https://download.pytorch.org/whl/cu128

AMD GPU（仅 Linux，按 ROCm 版本选择）：

pip install torch==2.9.1+rocm7.2 torchaudio==2.9.1+rocm7.2 --extra-index-url https://download.pytorch.org/whl/rocm7.2

需要注意：RDNA 3.5 与 RDNA 4 架构（Radeon 8050S/8060S、RX 9060/9070 系列，gfx1151/gfx1201）必须使用 ROCm 7.x，在 ROCm 6.x 上会报 HIP error: invalid device function。Intel GPU 需先安装 Intel Deep Learning Essentials 或 oneAPI Base Toolkit，再用 --index-url https://download.pytorch.org/whl/test/xpu 安装，也可通过 IPEX 支持；Apple Silicon 直接安装稳定版 pip install torch torchaudio。

3. 安装 F5-TTS

仅推理可直接装 pip 包：

pip install f5-tts

若还要训练或微调，克隆源码以可编辑模式安装：

git clone https://github.com/SWivid/F5-TTS.git
cd F5-TTS
# 若使用 BigVGAN 声码器需初始化子模块：git submodule update --init --recursive
pip install -e .

4. Docker 部署

# 从 Dockerfile 构建
docker build -t f5tts:v1 .

# 直接运行 GitHub Container Registry 镜像
docker container run --rm -it --gpus=all \
  --mount 'type=volume,source=f5-tts,target=/root/.cache/huggingface/hub/' \
  -p 7860:7860 ghcr.io/swivid/f5-tts:main

# 只跑 Web 界面
docker container run --rm -it --gpus=all \
  --mount 'type=volume,source=f5-tts,target=/root/.cache/huggingface/hub/' \
  -p 7860:7860 ghcr.io/swivid/f5-tts:main f5-tts_infer-gradio --host 0.0.0.0

Docker 方式适合不想折腾本地环境的用户：官方在 GitHub Container Registry 提供预构建镜像 ghcr.io/swivid/f5-tts:main，启动时通过 --gpus=all 挂载 GPU，把 ~/.cache/huggingface/hub/ 挂成卷以复用模型缓存，对外暴露 7860 端口。若只想使用 Web 界面而不跑命令行，可以在镜像命令后追加 f5-tts_infer-gradio --host 0.0.0.0 作为入口。官方文档还给出了 NVIDIA 设备的 docker-compose 示例，通过 GRADIO_SERVER_PORT=7860 指定端口、entrypoint 直接拉起 Gradio 服务。

六、使用方法

Gradio Web 界面

f5-tts_infer-gradio
# 指定端口/主机
f5-tts_infer-gradio --port 7860 --host 0.0.0.0
# 生成公网分享链接
f5-tts_infer-gradio --share
# 自动在浏览器打开 / 设置子路径 root_path
f5-tts_infer-gradio --inbrowser
f5-tts_infer-gradio --root_path "/myapp"

该命令等价于 python src/f5_tts/infer/infer_gradio.py，默认先加载 TTS 模型；若不提供 ref_text，会额外加载 ASR 模型自动转写参考音频（多占显存）；开启 Voice Chat 时再加载 Qwen2.5-3B-Instruct。它也可作为组件嵌入更大的 Gradio 应用：导入 from f5_tts.infer.infer_gradio import app 后用 app.render() 挂载。Gradio 应用当前支持带分块推理的基础 TTS、多风格/多说话人生成、由 Qwen2.5-3B-Instruct 驱动的语音对话，以及基于 SHARED.md 的更多语种自定义推理；首次运行时模型检查点会自动从 Hugging Face 拉取，也可手动下载后修改 infer_gradio.py 中 load_model() 的路径。

命令行推理

f5-tts_infer-cli --model F5TTS_v1_Base \
  --ref_audio "provide_prompt_wav_path_here.wav" \
  --ref_text "The content, subtitle or transcription of reference audio." \
  --gen_text "Some text you want TTS model generate for you."

--ref_text 留空时会调用 ASR 模型自动转写（额外占用显存）。其他常用方式：使用 BigVGAN 声码器（仅支持 F5TTS_Base）加 --vocoder_name bigvgan --load_vocoder_from_local；用 --ckpt_file 指定本地权重、--vocab_file 指定自定义词表；查看全部参数用 --help。该命令等价于 python src/f5_tts/infer/infer_cli.py，默认从 Hugging Face 加载模型，手动下载权重后用 --ckpt_file 指定即可。默认配置取自 src/f5_tts/infer/examples/basic/basic.toml，也可用 -c custom.toml 加载自己的配置：

model = "F5TTS_v1_Base"
ref_audio = "infer/examples/basic/basic_ref_en.wav"
ref_text = "Some call me nature, others call me mother nature."
gen_text = "I don't really care what you call me..."
remove_silence = false
output_dir = "tests"

多角色配音通过 .toml 中的 [voices.xxx] 段落定义多个音色，并在文本中用 [main]、[town] 等标记切换，示例见 src/f5_tts/infer/examples/multi/story.toml：在 [voices.town]、[voices.country] 等小节分别指定该角色的参考音频与转写文本，正文里写 [town] 时就切换到对应音色朗读，从而在一次运行中产出多人对话。gen_file 可以指定一个文本文件批量生成，remove_silence 控制是否去除首尾静音，output_dir 指定输出目录。

Python API

from importlib.resources import files
from f5_tts.api import F5TTS

f5tts = F5TTS()
wav, sr, spec = f5tts.infer(
    ref_file=str(files("f5_tts").joinpath("infer/examples/basic/basic_ref_en.wav")),
    ref_text="some call me nature, others call me mother nature.",
    gen_text="I don't really care what you call me...",
    file_wave="tests/api_out.wav",
    seed=None,
)

f5tts.infer() 返回波形数组、采样率与梅尔频谱，通过 file_wave 写出 wav、file_spec 写出频谱图，seed 可固定随机种子以复现结果。更多参数细节见仓库 src/f5_tts/api.py。

输入文本规范与使用建议

为达到理想效果，官方推理文档给出了若干实用建议：参考音频务必控制在 12 秒以内，并在末尾保留约 1 秒静音，否则容易从单词中间截断，导致生成不自然；希望逐字母拼读的缩写请写成大写形式（例如 K.F.C.），普通单词保持小写即可；需要刻意停顿的地方，可以插入空格或逗号、句号等标点；英文句末标点后必须跟一个空格，否则分块时不会被识别为句尾；数字若希望按中文读音念出，要先预处理成中文汉字，否则会按英文方式读出；如果生成结果是纯静音，首先排查 FFmpeg 是否安装正确。这些细节虽然琐碎，却直接决定克隆语音的流畅度与忠实度。

实时服务与语音编辑

基于 socket 的分块流式实时语音输出，适合边生成边播放的低延迟场景：

python src/f5_tts/socket_server.py   # 服务端
python src/f5_tts/socket_client.py   # 客户端通信

若未安装 PyAudio，需先 sudo apt-get install portaudio19-dev 再 pip install pyaudio。测试语音编辑能力（在保留音色的前提下改写文本内容）：python src/f5_tts/infer/speech_edit.py。生产级 Triton + TensorRT-LLM 部署说明见仓库 src/f5_tts/runtime/triton_trtllm/README.md。

七、项目结构与训练

仓库主要代码位于 src/f5_tts/ 目录：src/f5_tts/infer/ 是推理入口，包含 infer_cli.py（命令行）、infer_gradio.py（Web 界面）、api.py（Python API）、speech_edit.py（语音编辑）以及 examples/ 下的 basic、multi 示例与配置文件；src/f5_tts/train/ 是训练与微调代码；src/f5_tts/eval/ 是评测脚本；src/f5_tts/runtime/triton_trtllm/ 是 Triton + TensorRT-LLM 生产部署；根目录还提供 socket_server.py 与 socket_client.py 做实时流式服务。以可编辑模式安装（pip install -e .）后，命令行会注册 f5-tts_infer-cli、f5-tts_infer-gradio、f5-tts_finetune-gradio 三个入口命令，分别等价于 python src/f5_tts/infer/infer_cli.py 等脚本。

训练与微调

使用 Hugging Face Accelerate 进行训练与微调的最佳实践见仓库 src/f5_tts/train 目录，官方建议按其中说明准备数据、配置 accelerate 参数后启动训练。不想写配置的用户也可以直接用 Gradio 网页快速微调：

f5-tts_finetune-gradio

微调得到的 checkpoint 建议裁剪到只保留 ema_model_state_dict 以减小推理体积；若微调只跑了很少步数（早期 checkpoint）导致效果差，可尝试在推理时关闭 use_ema。

八、常见问题（FAQ）

输出是空白静音？ 首先检查 FFmpeg 是否正确安装（conda install ffmpeg）。
参考音频多长合适？ 12 秒以内，末尾留约 1 秒静音，否则可能从单词中间截断，影响生成质量。
英文缩写怎么读？ 大写字母（如 K.F.C.）会逐字母拼读；普通词用小写；英文句末标点后要加空格，否则分块时不被识别为句尾。
数字想按中文读？ 需要把数字预处理成中文文字，否则会按英文读法。
微调早期 checkpoint 效果差？ 若微调只跑了很少步数，尝试关闭 use_ema。
长文本一次生成不完？ 单次约 30 秒上限，CLI 与 Gradio 会自动分块；长参考音频自动截断到约 12 秒。
想嵌入自己的 Gradio 应用？ 可以把 F5-TTS 当作组件：from f5_tts.infer.infer_gradio import app，然后在自己的 gr.Blocks 里调用 app.render() 挂载。
不同硬件怎么选 PyTorch？ NVIDIA 选 cu128 等 CUDA 版本；AMD 仅 Linux 且 RDNA 3.5/4 必须 ROCm 7.x；Intel GPU 需先装 oneAPI 或 IPEX；Apple Silicon 直接装稳定版即可。
权重放哪？ 默认从 Hugging Face 自动下载并缓存；Docker 部署时建议把 ~/.cache/huggingface/hub/ 挂载为卷，避免每次重建容器重新下载。
Triton/TensorRT 性能如何？ 官方在单张 L20 GPU、26 组参考音频与目标文本对、16 NFE 条件下测得：并发 2 的客户端-服务器模式平均延迟 253 ms、RTF 0.0394；离线 TRT-LLM 批模式 RTF 0.0402；离线 PyTorch 模式 RTF 0.1467，TensorRT-LLM 加速约 3.6 倍。
想用官方以外的语种模型？ 到仓库 SHARED.md 找对应语言的社区模型卡，下载 Hugging Face 上的 checkpoint 与 vocab 文件，推理时用 --ckpt_file 和 --vocab_file 指向即可。
训练数据授权能商用吗？ 代码是 MIT，但预训练权重因基于 Emilia 数据集采用 CC-BY-NC 非商用许可，商用前请确认授权，社区模型则以各自作者的许可为准。

生产级部署方案基于 Triton 推理服务器与 TensorRT-LLM 优化，适合需要高并发、低延迟对外提供 TTS 服务的场景，相比原生 PyTorch 离线推理可获得数倍的吞吐提升。

九、致谢、许可与跳转链接

项目致谢 E2-TTS 的简洁高效设计，以及 Emilia、WenetSpeech4TTS、LibriTTS、LJSpeech 等数据集；工程上参考了 lucidrains 最初的 CFM 结构、SD3 与 Hugging Face diffusers 的 DiT/MMDiT 代码结构、torchdiffeq 作为 ODE 求解器、Vocos 与 BigVGAN 作为声码器；评测工具链用到 FunASR、faster-whisper、UniSpeech 与 SpeechMOS，语音编辑测试基于 ctc-forced-aligner。社区生态方面，mrfakename 维护了 Hugging Face Space 演示，Lucas Newman 提供了 f5-tts-mlx（Apple MLX 实现），DakeQQ 提供了 F5-TTS-ONNX（ONNX Runtime 版本），Yuekai Zhang 贡献了 Triton 与 TensorRT-LLM 支持。开发规范使用 pre-commit（pip install pre-commit && pre-commit install，提交前 pre-commit run --all-files），部分模型组件为兼容张量记号对 E722 做了 lint 豁免。

F5-TTS：基于流匹配的零样本语音克隆（中英双语）部署指南

F5-TTS：基于流匹配的零样本语音克隆（中英双语）部署指南

一、项目官方信息

二、官方图片

三、核心特性

社区多语言模型

四、环境要求

五、部署步骤

1. 创建独立环境

2. 安装与设备匹配的 PyTorch

3. 安装 F5-TTS

4. Docker 部署

六、使用方法

Gradio Web 界面

命令行推理

Python API

输入文本规范与使用建议

实时服务与语音编辑

七、项目结构与训练

训练与微调

八、常见问题（FAQ）

九、致谢、许可与跳转链接

周若琳

文章目录