Fish Speech：开源多语言声音克隆与 TTS（S2-Pro / Drama 3）部署指南

Fish Speech 是 Fish Audio 团队开源的新一代多语言语音合成（TTS）模型项目。仓库当前版本为 3.0.0，同一套代码同时服务两代旗舰模型：上一代 S2-Pro（4B 参数）与新一代 Drama 3（35B-A3B MoE 架构，每个 token 激活 3B 参数）。项目支持零样本声音克隆、多说话人生成、自然语言标签控制情感与韵律，并提供命令行推理、OpenAI 风格的 API Server 与现代化 WebUI 三种使用方式。代码库及其关联模型权重均以 FISH AUDIO COMMUNITY LICENSE 发布，其中 S2-Pro 权重另行适用 Fish Audio Research License；官方同时声明不对任何非法使用承担责任，使用者需自行遵守当地 DMCA 等相关法规。该项目曾登上 Product Hunt 当日榜首，并入选 Trendshift 热门仓库榜单，在 Discord、QQ 频道等社区拥有活跃用户群体。

一、项目官方信息

二、官方图片

Fish Speech 仓库社交预览图：

S2-Pro 在 EmergentTTS-Eval 等基准上的综合可表现性（totalability）对比：

三、模型与核心能力

Fish Speech 目前提供两个模型，模型类型由权重目录中的 config.json 自动识别，两代模型共用同一套命令行与 API Server：

Drama 3 的主要特性

Drama 3 在 S2 系列基础上全方位升级，除延续多说话人、声音克隆与自然语言控制外，在长音频、交互方式与可编辑性上取得明确突破：

• 多轮导演式修正：可以直接对前一轮生成结果下指令，例如说「再温柔一点、再悲伤一点」，模型会结合上下文重新生成，而不是从头再来，像导演对配音演员说戏一样。
• 语音填空与精准编辑：像编辑文本一样编辑语音，例如把「周三」改成「周四」做单词级局部替换，周围音色与过渡保持自然。
• 剧本式多角色场景制作：根据一段剧本描述，一次性配出含多个角色的完整场景，长文本支持流式合成。
• 长对话与长语音：面向长录音、长时间会话设计，长内容中角色与音色保持稳定。
• 更强的表现力：笑声、哭腔、耳语、戏剧化情绪不再被参考音频「拉平」，演绎更接近真人表演。
• 多语言声音克隆：跨语言音色克隆的错误率（CER / WER）达到新的 SOTA 水平。
• 自然语言标签控制：沿用 [whisper]、[angry]、[laughing] 等行内标签，在文本中直接控制情绪与韵律。

Drama 3 相比 S2-Pro 的能力变化如下：多说话人从普通支持升级为剧本式多角色场景制作；声音克隆保留且多语言错误率更低；行内自然语言指令两代均支持；局部编辑/语音填空与多轮导演修正为 Drama 3 独有；长内容从分块生成升级为带流式的长对话与长语音；笑声、哭腔、耳语等强情绪表现明显更强。在公开基准上，Drama 3 在多语言声音克隆（MiniMax Multilingual Testset）、自由形式语音编辑（Ming-Freeform）、多轮情绪修正（Step-Audio-Edit）三项评测中，控制精度、多语言错误率与风格准确度全面超越前代，完整架构、训练配方与评测结果见 Drama 3 技术报告。

S2-Pro 的主要特性

S2-Pro 是上一代旗舰，具备自然语言可控与情绪化语音生成能力，支持近百种语言，体积小到可以在消费级 GPU 上部署：行内可用 [pause]、[excited]、[whisper] 等标签在文本任意位置控制韵律与情绪；原生多说话人生成用说话人 ID 在同一段文本内区分角色，无需逐角色生成再拼接；快速声音克隆只需 10–30 秒参考音频即可复刻音色；长音频可一次性流式输出；生产级流式在单张 H200 上 RTF 达 0.195，首包音频延迟约 100 ms。在线体验可访问 Fish Audio 官网，细节见官方博客与S2 技术报告。

S2-Pro 的基准成绩（官方公布）：Seed-TTS Eval 中文 WER 0.54%、英文 0.99%，均为全部参评模型（含闭源系统）中最低；Audio Turing Test 含指令后验均值 0.515；EmergentTTS-Eval 胜率 81.88% 为全场最高；Fish Instruction Benchmark 的 TAR 93.3%、质量 4.51/5.0；多语言 MiniMax Testset 中 24 种语言里 11 种取得最佳 WER、17 种取得最佳 SIM。对比之下，Qwen3-TTS 为 0.77/1.24，MiniMax Speech-02 为 0.99/1.90，Seed-TTS 为 1.12/2.25；Audio Turing Test 上 0.515 较 Seed-TTS（0.417）提升 24%、较 MiniMax-Speech（0.387）提升 33%。在 EmergentTTS-Eval 的细分维度上，S2-Pro 在副语言学维度胜率 91.61%、疑问句维度 84.41%、句法复杂度维度 83.39%，说明其对口语副语言信息与复杂句式的理解同样领先。

此外，Fish Speech 的多说话人机制在两代模型间有本质区别：S2-Pro 按参考音频的传入顺序决定角色，而 Drama 3 改用 <|speaker:0|> 到 <|speaker:15|> 共 16 个说话人标签显式指定角色，参考音频顺序不再重要，这使得剧本式多角色配音可以在同一段文本中自由切换角色。长文本切分策略也不同：S2-Pro 按 chunk_length（默认 200）机械分块；Drama 3 则自动按约 300 个 UTF-8 字符切块、每块最多安排 3 个说话人，并尽量在句子边界断开，同时把第一块与最近生成的一块作为上下文回喂，保证长对话中音色一致。单次生成长度上，Drama 3 默认每块约 1024 帧（约 47 秒），--single_chunk 整段模式下也是 1024 帧；当 --max_new_tokens=0 时每块放宽到 600 帧、整段模式放宽到 2048 帧（约 95 秒），且任何情况下总帧数不超过 10240 帧减去提示长度。

四、环境要求

操作系统要求 Linux 或 WSL。安装前需先准备音频处理系统依赖：

apt install portaudio19-dev libsox-dev ffmpeg

五、部署步骤

1. 克隆仓库并安装依赖

git clone https://github.com/fishaudio/fish-speech.git
cd fish-speech

Conda 方式（官方推荐 Python 3.12）：

conda create -n fish-speech python=3.12
conda activate fish-speech

# GPU 安装（CUDA 可选 cu126 / cu128 / cu129）
pip install --extra-index-url https://download.pytorch.org/whl/cu129 -e ".[cu129]"

# 仅 CPU 安装
pip install --extra-index-url https://download.pytorch.org/whl/cpu -e ".[cpu]"

# 默认安装（使用 PyTorch 默认索引）
pip install -e .

若 pyaudio 导致安装报错，可先执行 conda install pyaudio 再重试。UV 方式依赖解析更快：

# GPU 安装
uv sync --python 3.12 --extra cu129
# 仅 CPU 安装
uv sync --python 3.12 --extra cpu

Intel Arc XPU 仅支持 S2-Pro（Drama 3 必须 NVIDIA GPU），需先安装 nightly 版 XPU 支持的 PyTorch 再 pip install -e .。注意：compile 选项暂不支持 Windows 与 macOS，如需启用需手动安装 Triton。

2. 下载模型权重

先安装 Hugging Face 命令行工具，再把两代模型权重放到同一个 checkpoints 目录：

pip install -U "huggingface_hub[cli]"

# Drama 3
hf download fishaudio/drama-3 --local-dir checkpoints/drama-3

# S2-Pro（建议一并下载）
hf download fishaudio/s2-pro --local-dir checkpoints/s2-pro

如果 Drama 3 权重目录中没有 codec.pth，服务端会自动改用 checkpoints/s2-pro/codec.pth 中的 S2-Pro codec。

3. Docker 部署（推荐生产环境）

官方提供 API Server 的 GPU（默认 CUDA 12.6）与 CPU 预构建镜像，镜像已内置 WebUI，容器启动后打开 http://localhost:8080/ui 即可使用。GPU 镜像可运行两个模型，CPU 镜像仅支持 S2-Pro。前置条件：已安装 Docker 与 Docker Compose；GPU 场景需安装 NVIDIA Docker runtime（Drama 3 必需）。

运行预构建镜像（Drama 3，SM89 及以上显卡只暴露一张卡，较老显卡改用 --gpus all）：

docker run --gpus device=0 \
    -v ./checkpoints:/app/checkpoints \
    -e LLAMA_CHECKPOINT_PATH=checkpoints/drama-3 \
    -p 8080:8080 \
    fishaudio/fish-speech:server-cuda

S2-Pro：

docker run --gpus all \
    -v ./checkpoints:/app/checkpoints \
    -e LLAMA_CHECKPOINT_PATH=checkpoints/s2-pro \
    -e DECODER_CHECKPOINT_PATH=checkpoints/s2-pro/codec.pth \
    -p 8080:8080 \
    fishaudio/fish-speech:server-cuda

也可用 Docker Compose 本地构建启动：

docker compose --profile server up
# 加载 Drama 3 并固定单卡
LLAMA_CHECKPOINT_PATH=checkpoints/drama-3 DEVICE=cuda:0 docker compose --profile server up
# 启用 compile 优化（仅 S2-Pro）
COMPILE=1 docker compose --profile server up
# 仅 CPU 部署（仅 S2-Pro）
BACKEND=cpu docker compose --profile server up

容器需挂载 ./checkpoints:/app/checkpoints（模型权重）与 ./references:/app/references（参考音频）两个目录。常用环境变量：COMPILE=1 启用 torch.compile（推理提速约 10 倍，仅 S2-Pro）；LLAMA_CHECKPOINT_PATH 指定主模型权重路径；DECODER_CHECKPOINT_PATH 指定 codec 权重；DEVICE 指定推理设备如 cuda:0；FISH_DRAMA3_FP8_EXPERTS=0/1 强制 Drama 3 使用反量化或 FP8 专家；FISH_DRAMA3_CUDA_GRAPH=0 关闭 CUDA graph 解码；API_SERVER_PORT 默认 8080。手动构建时可用 BACKEND、CUDA_VER（默认 12.6.0）、UV_EXTRA、UBUNTU_VER（默认 24.04）、PY_VER（默认 3.12）等构建参数。

六、使用方法

命令行推理

S2-Pro 走「VQ tokens → Semantic tokens → 音频」三步流水线。第一步从参考音频提取 VQ tokens（会生成 fake.npy 与 fake.wav）：

python fish_speech/models/dac/inference.py \
    -i "test.wav" \
    --checkpoint-path "checkpoints/s2-pro/codec.pth"

第二步从文本生成 Semantic tokens（生成 codes_N 文件；不支持 bf16 的 GPU 可加 --half）：

python fish_speech/models/text2semantic/inference.py \
    --text "您想要转换的文本" \
    --prompt-text "您的参考文本" \
    --prompt-tokens "fake.npy"

第三步由语义令牌解码出音频：

python fish_speech/models/dac/inference.py -i "codes_0.npy"

Drama 3 一步到位，--output 直接写出解码后的音频：

python fish_speech/models/text2semantic/inference.py \
    --checkpoint-path checkpoints/drama-3 \
    --text "您想要转换的文本" \
    --prompt-audio "reference.wav" \
    --prompt-text "您的参考文本" \
    --output "output.wav" \
    --device cuda:0

较早 GPU 上可指定多张卡，如 --device cuda:0,cuda:1,cuda:2,cuda:3，最后一张卡负责音频解码器与 codec。

API Server

启动 Drama 3：

python tools/api_server.py \
    --listen 0.0.0.0:8080 \
    --llama-checkpoint-path checkpoints/drama-3 \
    --device cuda:0

启动 S2-Pro：

python tools/api_server.py \
    --listen 0.0.0.0:8080 \
    --llama-checkpoint-path checkpoints/s2-pro \
    --decoder-checkpoint-path checkpoints/s2-pro/codec.pth \
    --decoder-config-name modded_dac_vq

共用启动参数：--compile（仅 S2-Pro）、--half（fp16 模式）、--api-key（bearer token 鉴权）、--workers（工作进程数）、--max-text-length（限制单次请求文本长度，0 为不限制）。健康检查：

curl -X GET http://127.0.0.1:8080/v1/health

返回 {"status":"ok"} 即服务正常。主要端点：POST /v1/tts（文本转语音，请求体为 msgpack）、GET /v1/tts/defaults、GET /v1/health、POST /v1/vqgan/encode、POST /v1/vqgan/decode、POST/GET/DELETE /v1/references/*（保存、列出、重命名、删除参考音色）、GET /ui（WebUI）。

客户端调用：

python tools/api_client.py \
    --url http://127.0.0.1:8080/v1/tts \
    --text "Hello from Fish Speech" \
    --output demo

常用客户端参数：--reference_audio / --reference_text（参考音频与转写文本，数量须一致）；--reference_speaker 指定每段参考音频的说话人 ID（0–15，会写成 <|speaker:N|> 前缀，是 Drama 3 的主要用法）；--reference_id 使用已保存音色；--format 支持 wav、pcm、mp3、opus；--streaming 流式返回；--single_chunk 整段一次生成（仅 Drama 3）；--chunk_length 默认 200（仅 S2-Pro）；--max_new_tokens 服务端默认 1024；--temperature / --top_p 默认 0.7 / 0.7；--seed 固定随机种子；--api_key；--no-play 合成后不播放（无音频设备的机器必加）。

模型行为差异

Drama 3 自动按约 300 字节（UTF-8）切分长文本、每块最多 3 个说话人，尽量在句末断开，并把第一块与最近一块回喂作为上下文；其说话人由 <|speaker:0|>–<|speaker:15|> 标签决定，与参考音频顺序无关，而 S2-Pro 由参考音频顺序决定角色。两代模型均忽略 repetition_penalty，采用内置重复感知采样。

WebUI

官方 Awesome WebUI 是基于 TypeScript 的现代化界面。从源码运行需先安装 Node.js 与 npm：

cd awesome_webui
npm install
npm run build

构建完成后回到项目根目录启动后端：

python tools/api_server.py --listen 0.0.0.0:8888 --compile

浏览器访问 http://localhost:8888/ui 即可（Docker 镜像已内置，无需构建）。

生产级高性能推理

官方强烈建议追求效率的用户使用推理框架加速：SGLang-Omni 方案见 SGLang-Omni 仓库说明；vLLM-Omni 方案见 vLLM-Omni Fish Speech S2 Pro Recipe 与用户指南。S2-Pro 在单张 H200 上 RTF 0.195、首包约 100 ms。

七、项目结构

仓库根目录的 pyproject.toml 声明了包名 fish-speech（当前 3.0.0）、requires-python >=3.10 与 torch==2.8.0、torchaudio==2.8.0、transformers==5.19.0 等核心依赖。主要目录与文件如下：fish_speech/ 是模型与推理核心库，其中 fish_speech/models/text2semantic/ 承载文本到语义令牌的生成模型，fish_speech/models/dac/ 承载描述音频编解码器（DAC，负责 VQ 编码与音频解码）；tools/ 目录提供各类可执行脚本，包括 tools/api_server.py（API 服务端）、tools/api_client.py（命令行客户端）、tools/run_webui.py 与 tools/e2e_webui.py（WebUI 入口）、tools/export_onnx.py（ONNX 导出）、tools/extract_model.py 等；tools/server/ 是 API 服务端内部实现，拆分为 model_manager.py、inference.py、views.py、agent/ 等模块；tools/webui/ 是内置 WebUI 的推理逻辑；awesome_webui/ 是基于 TypeScript 的现代化前端工程；docs/ 目录存放多语言文档（含英文、简体中文、葡萄牙语、日语、韩语、阿拉伯语、西班牙语版本）；checkpoints/ 为用户自行下载的权重目录。

八、常见问题（FAQ）

• Drama 3 能不能用 CPU 或 AMD 显卡跑？ 不能。Drama 3 只支持 NVIDIA GPU，且不支持 --compile；CPU 与 Apple MPS、AMD ROCm 均不可用。只有 S2-Pro 支持 CPU 部署。
• V100 等老显卡跑 Drama 3 会怎样？ SM80 之前的显卡不支持 bfloat16，Drama 3 会自动改用 float16（残差流保持 fp32）。该路径尚未在真实硬件上充分测试，如出现静音、噪声或 "non-finite logits" 报错，请向仓库提交 issue。
• 两个模型要装两遍吗？ 不用。同一套代码同时支持两代模型，模型类型由权重目录的 config.json 自动识别，命令行与 API Server 完全通用。
• repetition_penalty 为什么不生效？ 该参数仅为兼容旧接口保留，S2-Pro 与 Drama 3 都不使用它，两代模型均采用内置的重复感知采样。

• 无显卡设备上合成完一直自动播放？ 在无音频设备的机器上用 tools/api_client.py 时请加 --no-play。

• 新用户应该按什么顺序上手？ 官方文档分两步：先看安装文档完成环境配置、权重下载与 Docker 部署，再看推理文档熟悉命令行、API Server 与 WebUI。对追求效率的用户，官方明确建议改用 SGLang-Omni 做生产推理，而不是直接跑 PyTorch 原版服务。

• 服务端到底加载了哪个模型？ 由启动时 --llama-checkpoint-path 指向的权重目录决定，请求体里没有单独的模型字段，模型类型自动从该目录的 config.json 识别。
• 参考音频要准备多长？ S2-Pro 官方建议 10–30 秒参考音频即可复刻音色；调用时 --reference_audio 与 --reference_text 的数量必须一一对应，已保存的音色可用 --reference_id 复用。
• Docker 容器启动后找不到模型？ 容器默认从 /app/checkpoints 读取权重，启动前必须先把权重下载并挂载到该目录；GPU 场景还需安装 NVIDIA Docker runtime，纯 CPU 场景请去掉 --gpus all 并使用 CPU 镜像。

九、致谢与跳转链接

项目借鉴了 VITS2、Bert-VITS2、GPT VITS、MQTTS、GPT Fast、GPT-SoVITS 与 Qwen3 等开源工作，其技术路线可视为把大语言模型（LLM）与离散音频编解码 token 相结合的多语言 TTS 范式的代表性实践。

相关链接：

• 项目仓库：github.com/fishaudio/fish-speech
• Drama 3 权重：huggingface.co/fishaudio/drama-3
• S2-Pro 权重：huggingface.co/fishaudio/s2-pro
• 在线体验：fish.audio
• Docker 镜像：hub.docker.com/r/fishaudio/fish-speech