Piper TTS部署方案 Ubuntu

guoqingshan edited this page 2026-08-02 12:34:25 +08:00

Table of Contents

• Piper TTS 部署方案（Ubuntu）
• 1. 方案说明
• 2. 安装基础依赖
• 3. 安装 Piper
• 4. 下载语音模型
• 5. 测试 Piper
• 6. 配置 spanish-diary 后端
• 7. 测试后端 TTS 接口
• 8. 前端回退逻辑
• 9. 缓存目录
• 10. 常见问题
• 10.1 接口返回 503：Piper 未配置或未安装
• 10.2 提示模型不存在
• 10.3 生成失败，提示 espeak-ng
• 10.4 缓存目录无权限
• 10.5 浏览器中朗读没有声音
• 11. 总结

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Piper TTS 部署方案（Ubuntu）

1. 方案说明

spanish-diary 的朗读采用双引擎策略：

系统 Web Speech API 优先
手机无 TTS 语音或浏览器不支持时
自动回退到自建 Piper TTS

Piper 是轻量级本地神经网络 TTS，支持西班牙语、英语、中文，适合 CPU 服务器部署。

本项目不会单独启动 Piper 服务，而是由 spanish-diary 后端直接调用 Piper 命令行生成 WAV，并按“语言 + 文本”缓存，避免重复生成。

2. 安装基础依赖

sudo apt update
sudo apt install -y python3-venv python3-pip espeak-ng

3. 安装 Piper

sudo mkdir -p /opt/piper
sudo python3 -m venv /opt/piper/venv
sudo /opt/piper/venv/bin/pip install --upgrade pip
sudo /opt/piper/venv/bin/pip install piper-tts

验证：

/opt/piper/venv/bin/piper --help

4. 下载语音模型

创建模型目录：

sudo mkdir -p /opt/piper/voices
cd /opt/piper/voices

下载英语：

sudo curl -L -o en_US-lessac-medium.onnx https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/medium/en_US-lessac-medium.onnx
sudo curl -L -o en_US-lessac-medium.onnx.json https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json

下载西班牙语：

sudo curl -L -o es_ES-davefx-medium.onnx https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/es/es_ES/davefx/medium/es_ES-davefx-medium.onnx
sudo curl -L -o es_ES-davefx-medium.onnx.json https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/es/es_ES/davefx/medium/es_ES-davefx-medium.onnx.json

下载中文：

sudo curl -L -o zh_CN-huayan-medium.onnx https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/zh/zh_CN/huayan/medium/zh_CN-huayan-medium.onnx
sudo curl -L -o zh_CN-huayan-medium.onnx.json https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/zh/zh_CN/huayan/medium/zh_CN-huayan-medium.onnx.json

国内服务器如果无法访问 Hugging Face，可以把下载地址中的 huggingface.co 替换为 hf-mirror.com，例如：

https://hf-mirror.com/rhasspy/piper-voices/resolve/v1.0.0/es/es_ES/davefx/medium/es_ES-davefx-medium.onnx

5. 测试 Piper

echo 'Hola, buenos días' | /opt/piper/venv/bin/piper \
  --model /opt/piper/voices/es_ES-davefx-medium.onnx \
  --output_file /tmp/hola.wav

生成后检查：

ls -lh /tmp/hola.wav

英语和中文同理：

echo 'Good morning' | /opt/piper/venv/bin/piper --model /opt/piper/voices/en_US-lessac-medium.onnx --output_file /tmp/en.wav
echo '早上好' | /opt/piper/venv/bin/piper --model /opt/piper/voices/zh_CN-huayan-medium.onnx --output_file /tmp/zh.wav

6. 配置 spanish-diary 后端

spanish-diary 后端通过环境变量读取 Piper 配置：

PIPER_BIN
PIPER_MODELS_DIR
TTS_CACHE_DIR

创建 systemd 配置覆盖文件：

sudo mkdir -p /etc/systemd/system/spanish-diary.service.d
sudo tee /etc/systemd/system/spanish-diary.service.d/piper.conf > /dev/null <<'EOF'
[Service]
Environment=PIPER_BIN=/opt/piper/venv/bin/piper
Environment=PIPER_MODELS_DIR=/opt/piper/voices
Environment=TTS_CACHE_DIR=/opt/spanish-diary/server/data/tts_cache
EOF

创建缓存目录并设置权限：

sudo mkdir -p /opt/spanish-diary/server/data/tts_cache
sudo chown -R spanish-diary:spanish-diary /opt/spanish-diary/server/data

重新加载并重启：

sudo systemctl daemon-reload
sudo systemctl restart spanish-diary

7. 测试后端 TTS 接口

先登录获取 Cookie：

curl -c /tmp/cookies.txt \
  -X POST http://127.0.0.1:5000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

调用 TTS：

curl -b /tmp/cookies.txt \
  -X POST http://127.0.0.1:5000/api/tts \
  -H "Content-Type: application/json" \
  -d '{"text":"Hola","lang":"es"}' \
  --output /tmp/hola.wav

检查返回文件：

file /tmp/hola.wav
ls -lh /tmp/hola.wav

支持语言：

es：西班牙语
en：英语
zh：中文

8. 前端回退逻辑

前端 speech.js 的行为：

1. 浏览器支持 Web Speech API 且已加载系统语音
   → 使用手机/电脑系统 TTS
2. 浏览器不支持，或语音列表始终为空
   → 调用 /api/tts 获取 Piper WAV
3. 后端缓存相同文本
   → 直接返回缓存音频，不重复生成

9. 缓存目录

Piper 生成结果缓存在：

/opt/spanish-diary/server/data/tts_cache

文件名格式：

es_xxxxxxxxxxxxxxxxxxxxxxxx.wav
en_xxxxxxxxxxxxxxxxxxxxxxxx.wav
zh_xxxxxxxxxxxxxxxxxxxxxxxx.wav

清理缓存：

sudo systemctl stop spanish-diary
sudo find /opt/spanish-diary/server/data/tts_cache -name '*.wav' -delete
sudo systemctl start spanish-diary

10. 常见问题

10.1 接口返回 503：Piper 未配置或未安装

检查环境变量是否已写入 systemd：

systemctl cat spanish-diary | grep PIPER

检查 Piper 可执行文件：

ls -l /opt/piper/venv/bin/piper

10.2 提示模型不存在

确认模型文件在 /opt/piper/voices：

ls -lh /opt/piper/voices

10.3 生成失败，提示 espeak-ng

Piper 依赖 espeak-ng：

sudo apt install -y espeak-ng

10.4 缓存目录无权限

sudo mkdir -p /opt/spanish-diary/server/data/tts_cache
sudo chown -R spanish-diary:spanish-diary /opt/spanish-diary/server/data
sudo systemctl restart spanish-diary

10.5 浏览器中朗读没有声音

• 确认已通过 http://localhost:5000 或域名访问，而不是本地 file://
• 确认当前用户已登录
• 手机系统有 TTS 语音包时优先使用系统语音；没有时自动回退 Piper

11. 总结

1. 安装 espeak-ng 和 piper-tts
2. 下载 es/en/zh 三个 Piper 模型
3. 配置 spanish-diary 的 PIPER_BIN、PIPER_MODELS_DIR、TTS_CACHE_DIR
4. 重启 spanish-diary
5. 前端系统 TTS 不可用时自动回退 Piper
6. WAV 按文本哈希缓存，避免重复生成