Fish Speech 1.5开发者速查手册：模型权重路径、日志位置、缓存目录全标注

LapisLion88

708人浏览 · 2026-03-19 00:25:15

LapisLion88 · 2026-03-19 00:25:15 发布

Fish Speech 1.5开发者速查手册：模型权重路径、日志位置、缓存目录全标注

如果你正在使用Fish Speech 1.5镜像，是不是经常遇到这些问题：模型权重到底放在哪里？生成的音频文件去哪了？服务启动失败该看哪个日志？别急，这篇速查手册就是为你准备的。

作为开发者，我们最需要的就是清晰的路径指引。今天我就把Fish Speech 1.5（内置模型版）v1镜像里的所有关键文件位置、目录结构、配置路径都给你标注清楚，让你开发调试时不再迷路。

1. 核心文件系统全览

先来个整体认识，Fish Speech 1.5镜像的文件系统主要分为几个关键区域：

1.1 根目录结构概览

进入容器后，你会看到这样的目录布局：

/root/
├── fish-speech/          # 主项目目录
├── start_fish_speech.sh  # 启动脚本
├── fish_speech.log       # 运行日志
└── .cache/              # 用户缓存（部分依赖）

1.2 各目录功能说明

/root/fish-speech/：这是Fish Speech项目的核心代码库，所有源代码、工具脚本都在这里
/root/start_fish_speech.sh：一键启动脚本，负责按正确顺序启动后端API和前端WebUI
/root/fish_speech.log：最重要的日志文件，所有服务启动、运行、错误信息都记录在这里
/tmp/：临时文件目录，生成的音频文件默认存放在这里

2. 模型权重与配置文件路径

这是大家最关心的部分——模型文件到底在哪？

2.1 模型权重存放位置

Fish Speech 1.5的模型权重存放在固定路径：

/root/fish-speech/checkpoints/fish-speech-1___5/

在这个目录下，你会找到两个核心模型文件：

# 查看模型文件
ls -lh /root/fish-speech/checkpoints/fish-speech-1___5/

# 输出示例：
# -rw-r--r-- 1 root root 1.2G Jan  1 00:00 model.pth
# -rw-r--r-- 1 root root 180M Jan  1 00:00 firefly-gan-vq-fsq-8x1024-21hz-generator.pth

文件说明：

model.pth（约1.2GB）
- 这是LLaMA架构的文本转语义主模型
- 负责将输入的文本转换为语义表示
- 文件较大，首次加载需要一些时间
firefly-gan-vq-fsq-8x1024-21hz-generator.pth（约180MB）
- VQGAN声码器模型
- 负责将语义表示转换为实际的音频波形
- 支持24kHz采样率输出

2.2 配置文件路径

Fish Speech的配置文件分散在几个地方：

# 主要配置文件
/root/fish-speech/configs/

# 模型配置文件
/root/fish-speech/configs/fish_speech.yaml

# 声码器配置
/root/fish-speech/configs/vqgan/

如果你需要调整模型参数，可以修改这些配置文件。不过建议先备份原文件，因为镜像已经做了优化配置。

3. 服务与日志文件位置

了解服务运行状态，必须知道日志在哪。

3.1 服务启动脚本

启动脚本是入口，理解它有助于排查问题：

# 查看启动脚本内容
cat /root/start_fish_speech.sh

# 脚本主要做三件事：
# 1. 启动后端FastAPI服务（端口7861）
# 2. 等待后端就绪
# 3. 启动前端Gradio WebUI（端口7860）

3.2 日志文件详解

主日志文件：

/root/fish_speech.log

这个日志记录了完整的启动和运行过程：

# 实时查看日志（推荐）
tail -f /root/fish_speech.log

# 查看最后100行
tail -100 /root/fish_speech.log

# 查看错误信息
grep -i error /root/fish_speech.log

日志中的关键信息：

后端服务启动：会显示"Starting API server..."和"Uvicorn running on..."
前端服务启动：显示"Starting Gradio server..."和"Running on local URL:"
模型加载：显示"Loading model from checkpoint..."和模型加载进度
推理过程：显示文本处理、语音生成的时间消耗

3.3 服务进程检查

如果服务没起来，可以检查进程：

# 检查后端API服务（端口7861）
ps aux | grep api_server.py
lsof -i :7861

# 检查前端WebUI服务（端口7860）
ps aux | grep web_ui.py
lsof -i :7860

# 检查GPU使用情况
nvidia-smi

4. 生成文件与缓存目录

生成的音频文件去哪了？缓存文件在哪？

4.1 音频生成目录

默认情况下，生成的音频文件存放在临时目录：

# 查看最近生成的音频文件
ls -lh /tmp/fish_speech_*.wav

# 示例输出：
# -rw-r--r-- 1 root root 480K Mar 15 10:30 /tmp/fish_speech_123456.wav
# -rw-r--r-- 1 root root 720K Mar 15 10:31 /tmp/fish_speech_789012.wav

文件命名规则：

格式：fish_speech_{timestamp}.wav
位置：/tmp/目录下
格式：WAV格式，24kHz采样率，单声道

4.2 缓存文件位置

模型推理过程中会产生一些缓存文件：

# PyTorch模型缓存
~/.cache/torch/

# HuggingFace相关缓存（如果用到）
~/.cache/huggingface/

# 临时推理缓存
/tmp/fish_speech_cache/

清理缓存建议： 如果磁盘空间不足，可以清理这些缓存，但注意清理后首次运行会变慢：

# 清理临时音频文件（保留最近的文件）
find /tmp -name "fish_speech_*.wav" -mtime +1 -delete

# 清理PyTorch缓存（谨慎操作）
rm -rf ~/.cache/torch/checkpoints/

5. 源代码与工具脚本位置

如果你想深入了解或修改代码，需要知道源代码在哪。

5.1 核心源代码目录

/root/fish-speech/fish_speech/     # 核心模型代码
/root/fish-speech/tools/           # 工具脚本
/root/fish-speech/web_ui.py        # Web界面
/root/fish-speech/api_server.py    # API服务

5.2 重要工具脚本

# API服务器
/root/fish-speech/tools/api_server.py

# Web界面（自研版本）
/root/fish-speech/web_ui.py

# 命令行工具
/root/fish-speech/tools/cli.py

# 批量处理脚本
/root/fish-speech/tools/batch_infer.py

5.3 自定义修改建议

如果你想修改代码，建议先复制到其他目录：

# 备份原文件
cp /root/fish-speech/web_ui.py /root/fish-speech/web_ui.py.backup

# 修改后重启服务
bash /root/start_fish_speech.sh

6. 环境配置与依赖

了解环境配置有助于解决依赖问题。

6.1 Python环境

# Python版本
python --version  # 3.11.x

# 虚拟环境位置（如果有）
/root/venv/ 或 /opt/conda/envs/fish-speech/

# 查看已安装包
pip list | grep -E "(torch|gradio|fastapi)"

6.2 关键依赖版本

镜像中预装了这些关键版本：

PyTorch 2.5.0 + CUDA 12.4
Gradio 6.2.0
FastAPI 0.104.1
Transformers 4.36.0

6.3 环境变量配置

镜像设置了这些环境变量：

# 查看环境变量
env | grep -E "(GRADIO|CUDA|PYTORCH)"

# 重要环境变量：
# GRADIO_CDN=false          # 禁用CDN，离线可用
# CUDA_VISIBLE_DEVICES=0    # 使用第一块GPU
# PYTORCH_CUDA_ALLOC_CONF=... # 内存分配配置

7. 常见问题排查路径指南

遇到问题？按这个路径排查。

7.1 服务启动失败

排查步骤：

先看日志：tail -50 /root/fish_speech.log
检查端口：lsof -i :7860 和 lsof -i :7861
检查模型文件：确认/root/fish-speech/checkpoints/下的文件完整
检查GPU：nvidia-smi查看GPU状态

常见错误：

# 错误：模型文件找不到
# 解决：检查checkpoints目录权限和文件完整性

# 错误：CUDA out of memory
# 解决：减少batch size或清理其他GPU进程

# 错误：端口被占用
# 解决：kill占用进程或修改端口

7.2 音频生成失败

排查步骤：

检查输入文本：是否过长？包含特殊字符？
查看临时目录：ls -lh /tmp/fish_speech_*.wav
检查磁盘空间：df -h /tmp
查看详细日志：grep -A5 -B5 "生成" /root/fish_speech.log

7.3 性能问题排查

如果生成速度慢：

# 检查GPU使用率
nvidia-smi -l 1

# 检查CPU和内存
top

# 检查磁盘IO
iostat -x 1

# 查看模型加载时间
grep "Loading" /root/fish_speech.log

8. 开发调试实用技巧

分享几个我在使用中总结的实用技巧。

8.1 快速测试API

不用打开浏览器，直接命令行测试：

# 简单测试
curl -X POST http://127.0.0.1:7861/v1/tts \
  -H "Content-Type: application/json" \
  -d '{"text":"测试一下API是否正常","reference_id":null}' \
  --output test.wav

# 检查生成的文件
file test.wav
ls -lh test.wav

8.2 批量生成脚本

创建自己的批量处理脚本：

#!/usr/bin/env python3
import requests
import json
import time

api_url = "http://127.0.0.1:7861/v1/tts"

texts = [
    "第一段要生成的文本",
    "这是第二段内容",
    "继续生成第三段"
]

for i, text in enumerate(texts):
    print(f"生成第{i+1}段音频...")
    
    payload = {
        "text": text,
        "reference_id": None,
        "max_new_tokens": 1024
    }
    
    response = requests.post(api_url, json=payload)
    
    with open(f"output_{i+1}.wav", "wb") as f:
        f.write(response.content)
    
    time.sleep(1)  # 避免请求过快

print("批量生成完成！")

8.3 监控服务状态

创建简单的监控脚本：

#!/bin/bash
# monitor_fish_speech.sh

# 检查服务进程
check_process() {
    if ps aux | grep -q "[a]pi_server.py"; then
        echo " 后端API服务运行中"
    else
        echo " 后端API服务未运行"
    fi
    
    if ps aux | grep -q "[w]eb_ui.py"; then
        echo " 前端WebUI服务运行中"
    else
        echo " 前端WebUI服务未运行"
    fi
}

# 检查端口
check_port() {
    if lsof -i :7860 > /dev/null; then
        echo " 端口7860（WebUI）已监听"
    else
        echo " 端口7860未监听"
    fi
    
    if lsof -i :7861 > /dev/null; then
        echo " 端口7861（API）已监听"
    else
        echo " 端口7861未监听"
    fi
}

# 检查GPU内存
check_gpu() {
    echo "GPU使用情况："
    nvidia-smi --query-gpu=memory.used,memory.total --format=csv,noheader
}

# 执行所有检查
check_process
check_port
check_gpu