一、部署前环境准备

1.1 基础环境检查

在Linux/Windows系统部署前，需确认已安装Miniconda3虚拟环境管理工具。可通过终端执行conda --version验证安装状态，若未显示版本号则需从官方托管仓库下载最新版安装包。建议选择Miniconda而非Anaconda以减少磁盘占用，两者核心功能完全一致。

1.2 系统级依赖更新

执行以下命令完成系统基础组件升级：

# Ubuntu/Debian系统
sudo apt update && sudo apt upgrade -y
# CentOS/RHEL系统
sudo yum update -y
# Windows系统需通过PowerShell以管理员身份运行
winget upgrade --all

此步骤确保编译工具链、SSL证书库等底层组件保持最新状态，避免后续依赖安装时出现兼容性问题。

二、虚拟环境构建

2.1 专用环境创建

推荐使用独立虚拟环境隔离项目依赖，执行以下命令：

conda create -n fish_speech python=3.9 -y
conda activate fish_speech

选择Python 3.9版本因多数语音处理库对其兼容性最佳，后续可通过python --version验证环境激活状态。

2.2 环境变量优化

在.bashrc(Linux)或系统环境变量(Windows)中添加以下配置：

export PYTHONPATH=$PYTHONPATH:/path/to/fish-speech
export CUDA_VISIBLE_DEVICES=0  # 多GPU时指定设备

此配置确保Python能正确识别项目路径，并优化GPU资源分配。

三、模型资源获取

3.1 官方模型下载

通过Git克隆项目仓库获取完整代码：

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

建议使用Git LFS管理大型模型文件，若未安装可执行git lfs install后重试。

3.2 预训练模型加载

项目提供多种预训练权重，根据需求选择：

# 基础语音合成模型
wget https://example.com/models/base_tts.pt -O models/base_tts.pt
# 高保真语音识别模型
wget https://example.com/models/asr_large.pt -O models/asr_large.pt

实际部署时应替换为官方提供的模型托管地址，建议使用对象存储服务加速下载。

四、依赖管理方案

4.1 核心依赖安装

执行项目提供的requirements.txt时可能遇到PyAudio编译失败问题，解决方案如下：

# Ubuntu系统先安装系统依赖
sudo apt install portaudio19-dev python3-pyaudio
# 通用解决方案
pip install pyaudio --no-deps  # 跳过系统依赖检查
pip install -e .  # 安装项目核心依赖

对于Windows用户，建议直接下载预编译的PyAudio wheel文件手动安装。

4.2 深度学习框架配置

根据硬件选择合适的PyTorch版本：

# CUDA 11.7环境
pip install torch==1.13.1+cu117 -f https://download.pytorch.org/whl/torch_stable.html
# CPU环境
pip install torch==1.13.1+cpu -f https://download.pytorch.org/whl/torch_stable.html

可通过nvidia-smi验证GPU驱动状态，确保CUDA环境正常工作。

五、服务配置与启动

5.1 Web服务定制

修改/fish-speech/tools/run_webui.py配置文件：

if __name__ == "__main__":
    app.run(host='0.0.0.0', port=5000, debug=True)  # 开放所有网络接口
    # 原代码可能仅绑定localhost，修改后支持远程访问

对于生产环境，建议使用Gunicorn替代Flask内置服务器：

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 run_webui:app

5.2 性能优化参数

在配置文件中添加以下参数提升吞吐量：

os.environ["CUDA_LAUNCH_BLOCKING"] = "1"  # 减少GPU同步开销
os.environ["OMP_NUM_THREADS"] = "4"       # 控制OpenMP线程数

通过nvidia-smi dmon监控GPU利用率，动态调整批处理大小(batch_size)参数。

六、常见问题处理

6.1 依赖冲突解决

当出现ERROR: Cannot install...时，执行：

pip check  # 诊断依赖冲突
pip install --ignore-installed package_name  # 强制安装特定版本

建议维护requirements.freeze.txt记录精确依赖版本。

6.2 模型加载失败

若报错RuntimeError: Error(s) in loading state_dict，检查：

模型版本与代码库是否匹配
CUDA版本兼容性
存储设备是否可用(nvidia-smi/df -h)

6.3 端口占用处理

通过以下命令释放被占用端口：

# Linux系统
sudo lsof -i :5000
kill -9 <PID>
# Windows系统
netstat -ano | findstr 5000
taskkill /PID <PID> /F

七、扩展开发建议

7.1 模型微调

利用项目提供的训练脚本进行领域适配：

python train.py \
  --model_name base_tts \
  --train_data /path/to/dataset \
  --epochs 50 \
  --batch_size 32

建议使用混合精度训练(fp16)加速收敛。

7.2 服务监控方案

集成日志服务与监控告警：

import logging
from logging.handlers import RotatingFileHandler
logger = logging.getLogger(__name__)
handler = RotatingFileHandler('app.log', maxBytes=10MB, backupCount=5)
logger.addHandler(handler)

配合Prometheus+Grafana构建可视化监控面板。

本指南完整覆盖从环境搭建到生产部署的全流程，通过模块化设计和异常处理机制，确保服务稳定性。实际部署时建议结合容器化技术实现环境隔离，并定期更新模型权重以获得最佳效果。对于企业级应用，可考虑将服务部署在主流云服务商的GPU实例上，利用弹性伸缩能力应对流量波动。

Fish-Speech语音模型本地化部署全流程解析