docs: 添加Piper TTS部署方案（Ubuntu）
@@ -0,0 +1,260 @@
|
||||
# Piper TTS 部署方案（Ubuntu）
|
||||
|
||||
## 1. 方案说明
|
||||
|
||||
`spanish-diary` 的朗读采用双引擎策略：
|
||||
|
||||
```text
|
||||
系统 Web Speech API 优先
|
||||
手机无 TTS 语音或浏览器不支持时
|
||||
自动回退到自建 Piper TTS
|
||||
```
|
||||
|
||||
Piper 是轻量级本地神经网络 TTS，支持西班牙语、英语、中文，适合 CPU 服务器部署。
|
||||
|
||||
本项目不会单独启动 Piper 服务，而是由 `spanish-diary` 后端直接调用 Piper 命令行生成 WAV，并按“语言 + 文本”缓存，避免重复生成。
|
||||
|
||||
## 2. 安装基础依赖
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y python3-venv python3-pip espeak-ng
|
||||
```
|
||||
|
||||
## 3. 安装 Piper
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
验证：
|
||||
|
||||
```bash
|
||||
/opt/piper/venv/bin/piper --help
|
||||
```
|
||||
|
||||
## 4. 下载语音模型
|
||||
|
||||
创建模型目录：
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/piper/voices
|
||||
cd /opt/piper/voices
|
||||
```
|
||||
|
||||
下载英语：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
下载西班牙语：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
下载中文：
|
||||
|
||||
```bash
|
||||
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`，例如：
|
||||
|
||||
```text
|
||||
https://hf-mirror.com/rhasspy/piper-voices/resolve/v1.0.0/es/es_ES/davefx/medium/es_ES-davefx-medium.onnx
|
||||
```
|
||||
|
||||
## 5. 测试 Piper
|
||||
|
||||
```bash
|
||||
echo 'Hola, buenos días' | /opt/piper/venv/bin/piper \
|
||||
--model /opt/piper/voices/es_ES-davefx-medium.onnx \
|
||||
--output_file /tmp/hola.wav
|
||||
```
|
||||
|
||||
生成后检查：
|
||||
|
||||
```bash
|
||||
ls -lh /tmp/hola.wav
|
||||
```
|
||||
|
||||
英语和中文同理：
|
||||
|
||||
```bash
|
||||
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 配置：
|
||||
|
||||
```text
|
||||
PIPER_BIN
|
||||
PIPER_MODELS_DIR
|
||||
TTS_CACHE_DIR
|
||||
```
|
||||
|
||||
创建 systemd 配置覆盖文件：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
创建缓存目录并设置权限：
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/spanish-diary/server/data/tts_cache
|
||||
sudo chown -R spanish-diary:spanish-diary /opt/spanish-diary/server/data
|
||||
```
|
||||
|
||||
重新加载并重启：
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart spanish-diary
|
||||
```
|
||||
|
||||
## 7. 测试后端 TTS 接口
|
||||
|
||||
先登录获取 Cookie：
|
||||
|
||||
```bash
|
||||
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：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
检查返回文件：
|
||||
|
||||
```bash
|
||||
file /tmp/hola.wav
|
||||
ls -lh /tmp/hola.wav
|
||||
```
|
||||
|
||||
支持语言：
|
||||
|
||||
```text
|
||||
es：西班牙语
|
||||
en：英语
|
||||
zh：中文
|
||||
```
|
||||
|
||||
## 8. 前端回退逻辑
|
||||
|
||||
前端 `speech.js` 的行为：
|
||||
|
||||
```text
|
||||
1. 浏览器支持 Web Speech API 且已加载系统语音
|
||||
→ 使用手机/电脑系统 TTS
|
||||
2. 浏览器不支持，或语音列表始终为空
|
||||
→ 调用 /api/tts 获取 Piper WAV
|
||||
3. 后端缓存相同文本
|
||||
→ 直接返回缓存音频，不重复生成
|
||||
```
|
||||
|
||||
## 9. 缓存目录
|
||||
|
||||
Piper 生成结果缓存在：
|
||||
|
||||
```text
|
||||
/opt/spanish-diary/server/data/tts_cache
|
||||
```
|
||||
|
||||
文件名格式：
|
||||
|
||||
```text
|
||||
es_xxxxxxxxxxxxxxxxxxxxxxxx.wav
|
||||
en_xxxxxxxxxxxxxxxxxxxxxxxx.wav
|
||||
zh_xxxxxxxxxxxxxxxxxxxxxxxx.wav
|
||||
```
|
||||
|
||||
清理缓存：
|
||||
|
||||
```bash
|
||||
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：
|
||||
|
||||
```bash
|
||||
systemctl cat spanish-diary | grep PIPER
|
||||
```
|
||||
|
||||
检查 Piper 可执行文件：
|
||||
|
||||
```bash
|
||||
ls -l /opt/piper/venv/bin/piper
|
||||
```
|
||||
|
||||
### 10.2 提示模型不存在
|
||||
|
||||
确认模型文件在 `/opt/piper/voices`：
|
||||
|
||||
```bash
|
||||
ls -lh /opt/piper/voices
|
||||
```
|
||||
|
||||
### 10.3 生成失败，提示 espeak-ng
|
||||
|
||||
Piper 依赖 espeak-ng：
|
||||
|
||||
```bash
|
||||
sudo apt install -y espeak-ng
|
||||
```
|
||||
|
||||
### 10.4 缓存目录无权限
|
||||
|
||||
```bash
|
||||
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. 总结
|
||||
|
||||
```text
|
||||
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 按文本哈希缓存，避免重复生成
|
||||
```
|
||||
Reference in New Issue
Block a user