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