系统要求

GPU 显存：24GB（用于推理）
系统：Linux、WSL

系统设置

Fish Audio S2 支持多种安装方式。请选择最适合你当前开发环境的方案。

前置依赖：先安装音频处理所需的系统依赖：

apt install portaudio19-dev libsox-dev ffmpeg

Conda

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

# GPU 安装（选择 CUDA 版本：cu126、cu128、cu129）
pip install -e .[cu129]

# 仅 CPU 安装
pip install -e .[cpu]

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

# 如果因 pyaudio 导致安装报错，可以先执行：
# conda install pyaudio
# 然后重新执行 pip install -e .

UV

UV 可以更快地完成依赖解析与安装：

# GPU 安装（选择 CUDA 版本：cu126、cu128、cu129）
uv sync --python 3.12 --extra cu129

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

Intel Arc XPU 支持

如果你使用 Intel Arc GPU，可按以下方式安装 XPU 支持：

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

# 安装必需的 C++ 标准库
conda install libstdcxx -c conda-forge

# 安装支持 Intel XPU 的 PyTorch
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/xpu

# 安装 Fish Speech
pip install -e .

Warning

compile 选项暂不支持 Windows 和 macOS。若你希望启用 compile，请手动安装 Triton。

Docker 设置

Fish Audio S2 系列模型提供多种 Docker 部署方式，适配不同场景。你可以直接使用 Docker Hub 预构建镜像，也可以用 Docker Compose 本地构建，或手动构建自定义镜像。

我们提供 WebUI 与 API Server 的 GPU（默认 CUDA126）和 CPU 镜像。你可以直接用 Docker Hub 镜像，也可以在本地构建。如果你只想使用预构建镜像，请参考inference guide。

前置条件

已安装 Docker 和 Docker Compose
（GPU 场景）已安装 NVIDIA Docker runtime
CUDA 推理建议至少 24GB 显存

使用 Docker Compose

如果你需要开发或自定义，推荐使用 Docker Compose 在本地构建并运行：

# 先克隆仓库
git clone https://github.com/fishaudio/fish-speech.git
cd fish-speech

# 使用 CUDA 启动 WebUI
docker compose --profile webui up

# 启用 compile 优化启动 WebUI
COMPILE=1 docker compose --profile webui up

# 启动 API Server
docker compose --profile server up

# 启用 compile 优化启动 API Server
COMPILE=1 docker compose --profile server up

# 仅 CPU 部署
BACKEND=cpu docker compose --profile webui up

Docker Compose 环境变量

你可以通过环境变量定制部署参数：

# .env 文件示例
BACKEND=cuda              # 或 cpu
COMPILE=1                 # 启用 compile 优化
GRADIO_PORT=7860          # WebUI 端口
API_PORT=8080             # API Server 端口
UV_VERSION=0.8.15         # UV 包管理器版本

命令执行后会自动构建镜像并启动容器。你可以通过 http://localhost:7860 访问 WebUI，通过 http://localhost:8080 访问 API Server。

手动 Docker 构建

如果你需要更细粒度的构建控制，可以手动构建：

# 构建支持 CUDA 的 WebUI 镜像
docker build \
    --platform linux/amd64 \
    -f docker/Dockerfile \
    --build-arg BACKEND=cuda \
    --build-arg CUDA_VER=12.6.0 \
    --build-arg UV_EXTRA=cu126 \
    --target webui \
    -t fish-speech-webui:cuda .

# 构建支持 CUDA 的 API Server 镜像
docker build \
    --platform linux/amd64 \
    -f docker/Dockerfile \
    --build-arg BACKEND=cuda \
    --build-arg CUDA_VER=12.6.0 \
    --build-arg UV_EXTRA=cu126 \
    --target server \
    -t fish-speech-server:cuda .

# 构建仅 CPU 镜像（支持多平台）
docker build \
    --platform linux/amd64,linux/arm64 \
    -f docker/Dockerfile \
    --build-arg BACKEND=cpu \
    --target webui \
    -t fish-speech-webui:cpu .

# 构建开发镜像
docker build \
    --platform linux/amd64 \
    -f docker/Dockerfile \
    --build-arg BACKEND=cuda \
    --target dev \
    -t fish-speech-dev:cuda .

构建参数

BACKEND：cuda 或 cpu（默认：cuda）
CUDA_VER：CUDA 版本（默认：12.6.0）
UV_EXTRA：UV 的 CUDA 扩展（默认：cu126）
UBUNTU_VER：Ubuntu 版本（默认：24.04）
PY_VER：Python 版本（默认：3.12）

卷挂载

两种方法都需要挂载以下目录：

./checkpoints:/app/checkpoints - 模型权重目录
./references:/app/references - 参考音频目录

环境变量

COMPILE=1 - 启用 torch.compile，可提升推理速度（约 10 倍）
GRADIO_SERVER_NAME=0.0.0.0 - WebUI 服务地址
GRADIO_SERVER_PORT=7860 - WebUI 服务端口
API_SERVER_NAME=0.0.0.0 - API 服务地址
API_SERVER_PORT=8080 - API 服务端口

Note

Docker 容器默认从 /app/checkpoints 读取模型权重。启动容器前请先下载好所需权重。

Warning

GPU 支持需要 NVIDIA Docker runtime。若仅使用 CPU，请移除 --gpus all 并使用 CPU 镜像。