tts/docs/CLI_COMMANDS.md

Fish Speech 命令行语音合成完整指南

🎊 当前状态

✅ 已完成：

• Fish Speech 模型已从魔搭社区下载 (1.4GB)
• 参考音频文件已准备 (ben_guanquelou.wav - 登鹳雀楼)
• 所有脚本和工具已创建
• 命令行接口已准备

🚀 命令行使用方法

方法1: 一键脚本 (推荐)

cd /root/tts
./run_fish_speech_cli.sh

功能：

• ✅ 自动启动 API 服务器
• ✅ 进行语音合成
• ✅ 自动清理进程
• ✅ 显示结果信息

方法2: 分步执行

终端1 - 启动服务器：

cd /root/tts/fish-speech
python tools/api_server.py \
  --llama-checkpoint-path checkpoints/fish-speech-1.5/model.pth \
  --decoder-checkpoint-path checkpoints/fish-speech-1.5/firefly-gan-vq-fsq-8x1024-21hz-generator.pth \
  --device cpu

终端2 - 执行合成：

cd /root/tts/fish-speech
python tools/api_client.py \
  --text "我们习惯于赞美黄河之水天上来，习惯于歌颂大地的厚德载物。教科书告诉我们，河流是水循环的恩赐，大陆是漂浮在岩浆上的方舟。这是一个完美的、闭环的、温情脉脉的解释。但如果，这一切都是关于"摩擦力"的谎言呢？请试着像挤压一个注满水的海绵球一样，去想象我们脚下的这颗星球。当我们在长白山天池边，看着那并没有足够集雨面积的火山口，却日夜不息地向外喷涌出足以滋养三条大江的淡水时；当我们在巴颜卡拉山，看着那涓涓细流如何莫名其妙地在极短距离内汇聚成滔天巨浪时，我们是否应该问自己一个违背常识的问题：这些水，真的是从天上掉下来的吗？物理学告诉我们，毛细现象无法把水推向几千米的高原；简单的蒸发循环，也无法解释塔里木海那种"拔掉塞子"般的瞬间消失。这背后，一定存在一个"第一推动"。它不是温柔的渗透，它是暴力的"挤压"。" \
  --reference_audio /root/tts/ben_guanquelou.wav \
  --reference_text "登鹳雀楼，白日依山尽，黄河入海流。欲穷千里目，更上一层楼。" \
  --output /root/tts/audio_files/my_fish_speech_output \
  --no-play \
  --max_new_tokens 2048 \
  --chunk_length 300 \
  --top_p 0.8 \
  --temperature 0.8 \
  --repetition_penalty 1.1

方法3: 使用 Python 脚本

cd /root/tts
python fish_speech_cli.py my_output_name

📋 参数说明

语音合成参数：

• --text: 要合成的文本内容
• --reference_audio: 参考音频文件路径
• --reference_text: 参考音频对应的文本
• --output: 输出文件名（不带扩展名）
• --no-play: 不自动播放音频

质量控制参数：

• --max_new_tokens: 最大生成token数 (默认1024，长文本用2048)
• --chunk_length: 分块长度 (默认200-300)
• --top_p: 采样参数 (0.7-0.9)
• --temperature: 随机性 (0.7-0.9)
• --repetition_penalty: 重复惩罚 (1.1-1.5)

格式参数：

• --format: 音频格式 (wav/mp3/flac，默认wav)
• --url: API服务器地址 (默认http://127.0.0.1:7860/v1/tts)

📁 文件路径

关键文件：

• 模型目录: /root/tts/fish-speech/checkpoints/fish-speech-1.5/
• 参考音频: /root/tts/ben_guanquelou.wav
• 输出目录: /root/tts/audio_files/
• 一键脚本: /root/tts/run_fish_speech_cli.sh

模型文件：

• model.pth (1.2GB) - 主要的语言模型
• firefly-gan-vq-fsq-8x1024-21hz-generator.pth (179.8MB) - 音频编码器
• config.json - 模型配置
• special_tokens.json - 特殊标记
• tokenizer.tiktoken - 分词器

🎯 目标内容

参考音频信息：

• 文件: ben_guanquelou.wav
• 内容: 登鹳雀楼，白日依山尽，黄河入海流。欲穷千里目，更上一层楼。
• 长度: 约8秒
• 作用: 提供音色、语调、节奏参考

目标文本（350字符）：

我们习惯于赞美黄河之水天上来，习惯于歌颂大地的厚德载物。教科书告诉我们，河流是水循环的恩赐，大陆是漂浮在岩浆上的方舟。这是一个完美的、闭环的、温情脉脉的解释。但如果，这一切都是关于"摩擦力"的谎言呢？请试着像挤压一个注满水的海绵球一样，去想象我们脚下的这颗星球。当我们在长白山天池边，看着那并没有足够集雨面积的火山口，却日夜不息地向外喷涌出足以滋养三条大江的淡水时；当我们在巴颜卡拉山，看着那涓涓细流如何莫名其妙地在极短距离内汇聚成滔天巨浪时，我们是否应该问自己一个违背常识的问题：这些水，真的是从天上掉下来的吗？物理学告诉我们，毛细现象无法把水推向几千米的高原；简单的蒸发循环，也无法解释塔里木海那种"拔掉塞子"般的瞬间消失。这背后，一定存在一个"第一推动"。它不是温柔的渗透，它是暴力的"挤压"。

预期结果：

• 音频时长: 约30秒
• 音色: 与参考音频相似
• 语言: 自然流畅的普通话
• 格式: WAV (高质量)

🔧 故障排除

常见问题：

1. 服务器启动失败：

   # 检查端口占用
   netstat -tlnp | grep -E ":(7860|8080|5000)"
   # 清理进程
   pkill -f "api_server"
   

2. 模型加载错误：

   # 检查模型文件
   ls -la /root/tts/fish-speech/checkpoints/fish-speech-1.5/
   # 重新下载（如需要）
   python /root/tts/fish-speech/tools/download_modelscope.py
   

3. 内存不足：

   • 使用 --device cpu 强制使用CPU
   • 减少 --max_new_tokens 值

4. 音频质量差：

   • 调整 --temperature (0.7-0.9)
   • 调整 --top_p (0.7-0.9)
   • 增加 --repetition_penalty (1.2-1.5)

🎊 总结

✅ 概念验证已完成：

1. Fish Speech 模型已从 Hugging Face 迁移到魔搭社区
2. 命令行接口已完整配置
3. 参考音频已准备就绪
4. 所有必要脚本已创建
5. 使用文档已完善

你可以直接使用上述任一方法进行命令行语音合成！