699 lines
19 KiB
Markdown
699 lines
19 KiB
Markdown
# Qwen3-TTS Docker 快速部署文档
|
||
|
||
## 模型版本选择
|
||
|
||
**当前部署模型：Qwen3-TTS-24Hz-1.7B-Base-VoiceClone**
|
||
|
||
这是 Qwen3-TTS 系列中**功能最全面、音质最高**的模型版本，支持高质量声音克隆。
|
||
|
||
### 模型对比表
|
||
|
||
| 模型名称 | 采样率 | 参数量 | 体积 | 音质 | 速度 | 特殊功能 | 适用场景 |
|
||
|---------|--------|--------|------|------|------|---------|---------|
|
||
| Qwen3-TTS-12Hz-0.6B-CustomVoice | 12kHz | 0.6B | 1.7GB | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 9种预设声音 | 性能优先 |
|
||
| Qwen3-TTS-12Hz-1.7B-CustomVoice | 12kHz | 1.7B | ~4GB | ⭐⭐⭐⭐ | ⭐⭐⭐ | 9种预设声音 | 需要更高音质 |
|
||
| Qwen3-TTS-24Hz-0.6B-CustomVoice | 24kHz | 0.6B | ~2GB | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 9种预设声音 | 高质量需求 |
|
||
| Qwen3-TTS-24Hz-1.7B-CustomVoice | 24kHz | 1.7B | ~5GB | ⭐⭐⭐⭐⭐ | ⭐⭐ | 9种预设声音 | 最高音质（无克隆） |
|
||
| Qwen3-TTS-12Hz-Base-VoiceClone | 12kHz | 0.6B | ~2GB | ⭐⭐⭐ | ⭐⭐⭐⭐ | 声音克隆 | 自定义声音 |
|
||
| **Qwen3-TTS-24Hz-1.7B-Base-VoiceClone** | **24kHz** | **1.7B** | **~6.8GB** | **⭐⭐⭐⭐⭐** | **⭐⭐** | **声音克隆** | **功能最全面** |
|
||
|
||
**当前模型特点：**
|
||
- **24kHz 采样率**：双倍于 12Hz 模型，音质更清晰自然
|
||
- **1.7B 参数**：模型表达能力最强
|
||
- **声音克隆**：支持自定义声音训练和生成
|
||
- **功能最全面**：兼具基础模型 + 声音克隆功能
|
||
|
||
**推荐方案：**
|
||
- **默认当前选择**：`Qwen3-TTS-24Hz-1.7B-Base-VoiceClone`（功能最全面 + 最高音质）
|
||
- **性能优先**：`Qwen3-TTS-12Hz-0.6B-CustomVoice`
|
||
- **高质量（无克隆）**：`Qwen3-TTS-24Hz-1.7B-CustomVoice`
|
||
|
||
---
|
||
|
||
## 快速开始（3 步部署）
|
||
|
||
### 步骤 1：下载模型
|
||
|
||
```bash
|
||
# 进入工作目录
|
||
cd ~/Qwen3-TTS
|
||
mkdir -p model
|
||
cd model
|
||
|
||
# 安装 ModelScope CLI（国内用户推荐）
|
||
python3 -m pip install -U modelscope
|
||
|
||
# 下载 Tokenizer（约 651MB）
|
||
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-24Hz --local_dir ./Qwen3-TTS-Tokenizer-24Hz
|
||
|
||
# 下载 Qwen3-TTS-24Hz-1.7B-Base-VoiceClone 模型（约 6.8GB）
|
||
# 这是功能最全面、音质最高的模型，支持声音克隆
|
||
modelscope download --model Qwen/Qwen3-TTS-24Hz-1.7B-Base-VoiceClone --local_dir ./Qwen3-TTS-24Hz-1.7B-Base-VoiceClone
|
||
```
|
||
|
||
**说明：**
|
||
- **ModelScope**：阿里云模型托管平台，国内下载速度快
|
||
- **Tokenizer**：分词器，将文本转换为模型能理解的 token（24Hz 版本）
|
||
- **TTS 模型**：核心模型，1.7B 参数 + 24Hz 采样率 + 声音克隆功能
|
||
|
||
### 步骤 2：创建文件
|
||
|
||
```bash
|
||
cd ~/Qwen3-TTS
|
||
```
|
||
|
||
#### 创建 app.py（已配置为 24Hz-1.7B-Base-VoiceClone 模型）
|
||
|
||
```bash
|
||
cat > app.py << 'EOF'
|
||
from fastapi import FastAPI, Body
|
||
import soundfile as sf
|
||
import io
|
||
import torch
|
||
import sys
|
||
import base64
|
||
|
||
# 添加路径以支持导入
|
||
sys.path.insert(0, '/app')
|
||
|
||
from qwen_tts import Qwen3TTSModel
|
||
|
||
# ========== 当前配置：Qwen3-TTS-24Hz-1.7B-Base-VoiceClone ==========
|
||
# 功能最全面、音质最高的模型，支持声音克隆
|
||
# - 24kHz 采样率：音质更清晰自然
|
||
# - 1.7B 参数：模型表达能力最强
|
||
# - Base-VoiceClone：支持自定义声音克隆
|
||
MODEL_PATH = '/app/model/Qwen3-TTS-24Hz-1.7B-Base-VoiceClone'
|
||
TOKENIZER_PATH = '/app/model/Qwen3-TTS-Tokenizer-24Hz'
|
||
|
||
# 如需切换到其他模型，请修改以下路径并重新构建镜像
|
||
# ==========================================================
|
||
|
||
app = FastAPI(title="Qwen3-TTS API")
|
||
|
||
# 全局模型
|
||
model = None
|
||
|
||
@app.on_event("startup")
|
||
async def startup_event():
|
||
global model
|
||
print("正在加载 TTS 模型...")
|
||
print(f"模型路径: {MODEL_PATH}")
|
||
print(f"模型版本: Qwen3-TTS-24Hz-1.7B-Base-VoiceClone")
|
||
print("提示: 1.7B 模型加载需要较长时间，请耐心等待...")
|
||
model = Qwen3TTSModel.from_pretrained(
|
||
MODEL_PATH,
|
||
tokenizer_path=TOKENIZER_PATH,
|
||
device_map='cpu',
|
||
dtype=torch.float32
|
||
)
|
||
print("TTS 模型初始化完成")
|
||
|
||
@app.get("/")
|
||
async def root():
|
||
return {
|
||
"status": "running",
|
||
"mode": "production",
|
||
"model": "Qwen3-TTS-24Hz-1.7B-Base-VoiceClone",
|
||
"features": ["voice_clone", "high_quality", "24khz"]
|
||
}
|
||
|
||
@app.post("/tts")
|
||
async def tts(text: str = Body(..., media_type='application/json')):
|
||
"""
|
||
注意：必须使用 Body(...) 解析请求体，否则会返回 422 错误
|
||
请求格式: POST /tts，Body 为 JSON 字符串 "文本内容"
|
||
|
||
超时设置：长文本推理可能需要较长时间，建议客户端设置超时时间 > 120 秒
|
||
CPU 推理速度：约 0.5-2 秒/字符（1.7B 模型较慢，比 0.6B 模型慢约 2-3 倍）
|
||
"""
|
||
if not model:
|
||
return {"code": 500, "msg": "模型未初始化"}
|
||
|
||
try:
|
||
print(f"收到TTS请求，文本长度: {len(text)} 字符")
|
||
wavs, sr = model.generate_custom_voice(text, speaker='serena')
|
||
print(f"音频生成完成，采样率: {sr}, 音频时长: {len(wavs[0])/sr:.2f}秒")
|
||
|
||
# 转换为 WAV 格式
|
||
buffer = io.BytesIO()
|
||
sf.write(buffer, wavs[0], sr, format='WAV')
|
||
buffer.seek(0)
|
||
|
||
audio_data = buffer.read()
|
||
audio_b64 = base64.b64encode(audio_data).decode('utf-8')
|
||
print(f"编码完成，base64 长度: {len(audio_b64)}")
|
||
|
||
return {
|
||
"code": 0,
|
||
"msg": "success",
|
||
"text": text,
|
||
"audio": audio_b64
|
||
}
|
||
except Exception as e:
|
||
import traceback
|
||
print(f"Error: {traceback.format_exc()}")
|
||
return {"code": 500, "msg": f"TTS处理错误: {str(e)}"}
|
||
EOF
|
||
```
|
||
|
||
#### 创建 requirements.txt
|
||
|
||
```bash
|
||
cat > requirements.txt << 'EOF'
|
||
fastapi>=0.104.0
|
||
uvicorn>=0.24.0
|
||
numpy>=1.24.0
|
||
torch>=2.0.0
|
||
librosa>=0.10.0
|
||
soundfile>=0.12.0
|
||
safetensors>=0.4.0
|
||
qwen-tts>=0.1.0
|
||
EOF
|
||
```
|
||
|
||
#### 创建 Dockerfile
|
||
|
||
```bash
|
||
cat > Dockerfile.bak << 'EOF'
|
||
FROM python:3.12-slim
|
||
|
||
WORKDIR /app
|
||
|
||
# 安装系统依赖
|
||
RUN apt-get update && apt-get install -y \
|
||
git \
|
||
ffmpeg \
|
||
libsndfile1 \
|
||
&& rm -rf /var/lib/apt/lists/*
|
||
|
||
# 安装 qwen-tts（包含 qwen_tts 模块）
|
||
RUN pip install --no-cache-dir qwen-tts
|
||
|
||
# 复制应用文件
|
||
COPY app.py .
|
||
COPY requirements.txt .
|
||
|
||
# 安装额外依赖
|
||
RUN pip install --no-cache-dir -r requirements.txt
|
||
|
||
EXPOSE 8000
|
||
|
||
# 增加超时设置（180秒，1.7B 模型需要更长时间）
|
||
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000", "--timeout-keep-alive", "180", "--limit-concurrency", "1"]
|
||
EOF
|
||
```
|
||
|
||
### 步骤 3：构建并启动
|
||
|
||
```bash
|
||
cd ~/Qwen3-TTS
|
||
|
||
# 构建镜像
|
||
docker build -t qwen3-tts:latest .
|
||
|
||
# 启动容器（挂载模型目录，增加内存限制）
|
||
docker run -d \
|
||
--name tts-service \
|
||
-p 8000:8000 \
|
||
-v ~/Qwen3-TTS/model:/app/model:ro \
|
||
--memory="8g" \
|
||
--restart unless-stopped \
|
||
qwen3-tts:latest
|
||
|
||
# 等待服务启动（1.7B 模型需要更长时间，约15-30秒）
|
||
sleep 20
|
||
|
||
# 验证服务
|
||
curl http://localhost:8000/
|
||
```
|
||
|
||
**预期输出：**
|
||
```json
|
||
{
|
||
"status": "running",
|
||
"mode": "production",
|
||
"model": "Qwen3-TTS-24Hz-1.7B-Base-VoiceClone",
|
||
"features": ["voice_clone", "high_quality", "24khz"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 切换到其他模型版本
|
||
|
||
### 切换到性能优先模型（12Hz-0.6B-CustomVoice）
|
||
|
||
```bash
|
||
# 1. 下载新模型
|
||
cd ~/Qwen3-TTS/model
|
||
modelscope download --model Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice --local_dir ./Qwen3-TTS-12Hz-0.6B-CustomVoice
|
||
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz --local_dir ./Qwen3-TTS-Tokenizer-12Hz
|
||
|
||
# 2. 修改 app.py 中的 MODEL_PATH 和 TOKENIZER_PATH
|
||
# MODEL_PATH = '/app/model/Qwen3-TTS-12Hz-0.6B-CustomVoice'
|
||
# TOKENIZER_PATH = '/app/model/Qwen3-TTS-Tokenizer-12Hz'
|
||
|
||
# 3. 重新构建并启动
|
||
cd ~/Qwen3-TTS
|
||
docker stop tts-service
|
||
docker build -t qwen3-tts:v12hz .
|
||
docker run -d --name tts-service -p 8000:8000 -v ~/Qwen3-TTS/model:/app/model:ro qwen3-tts:v12hz
|
||
```
|
||
|
||
### 切换到最高音质模型（24Hz-1.7B-CustomVoice，无声音克隆）
|
||
|
||
```bash
|
||
# 1. 下载新模型
|
||
cd ~/Qwen3-TTS/model
|
||
modelscope download --model Qwen/Qwen3-TTS-24Hz-1.7B-CustomVoice --local_dir ./Qwen3-TTS-24Hz-1.7B-CustomVoice
|
||
|
||
# 2. 修改 app.py 中的路径
|
||
# MODEL_PATH = '/app/model/Qwen3-TTS-24Hz-1.7B-CustomVoice'
|
||
# TOKENIZER_PATH = '/app/model/Qwen3-TTS-Tokenizer-24Hz'
|
||
|
||
# 3. 重新构建并启动
|
||
cd ~/Qwen3-TTS
|
||
docker stop tts-service
|
||
docker build -t qwen3-tts:v24hz-noclone .
|
||
docker run -d --name tts-service -p 8000:8000 -v ~/Qwen3-TTS/model:/app/model:ro qwen3-tts:v24hz-noclone
|
||
```
|
||
|
||
---
|
||
|
||
## API 使用
|
||
|
||
### 健康检查
|
||
|
||
```bash
|
||
curl http://localhost:8000/
|
||
```
|
||
|
||
### 文本转语音
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/tts \
|
||
-H "Content-Type: application/json" \
|
||
-d '"你好，这是一个测试"'
|
||
```
|
||
|
||
**注意：** Body 必须是 JSON 字符串格式，不能是 JSON 对象 `{"text": "..."}`
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"text": "你好，这是一个测试",
|
||
"audio": "UklGRiTCAQBXQVZFZm10IBAAAAABAAEAwF0AAIC7AAACABAAZGF0YQD..."
|
||
}
|
||
```
|
||
|
||
### 长文本处理
|
||
|
||
**重要提示：**
|
||
- 1.7B 模型推理速度较慢（约 1-3 秒/字符）
|
||
- 短文本（< 20 字）：约 15-30 秒
|
||
- 中等文本（20-50 字）：约 50-120 秒
|
||
- 长文本（50-100 字）：约 120-240 秒
|
||
|
||
**客户端必须设置超时时间 >= 180 秒**，否则会收到 `EOF` 错误。
|
||
|
||
### Go 调用示例（带超时设置）
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"bytes"
|
||
"encoding/base64"
|
||
"encoding/json"
|
||
"fmt"
|
||
"net/http"
|
||
"os"
|
||
"time"
|
||
)
|
||
|
||
type TTSResponse struct {
|
||
Code int `json:"code"`
|
||
Msg string `json:"msg"`
|
||
Text string `json:"text"`
|
||
Audio string `json:"audio"`
|
||
}
|
||
|
||
func TTS(text string) ([]byte, error) {
|
||
// 必须使用 JSON 字符串格式：`"文本内容"`
|
||
jsonText := fmt.Sprintf(`"%s"`, text)
|
||
|
||
// 创建带超时的 HTTP 客户端（180秒超时，1.7B 模型需要更长时间）
|
||
client := &http.Client{
|
||
Timeout: 180 * time.Second,
|
||
}
|
||
|
||
resp, err := client.Post(
|
||
"http://localhost:8000/tts",
|
||
"application/json",
|
||
bytes.NewBufferString(jsonText),
|
||
)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
defer resp.Body.Close()
|
||
|
||
var result TTSResponse
|
||
if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
|
||
return nil, err
|
||
}
|
||
|
||
if result.Code != 0 {
|
||
return nil, fmt.Errorf("TTS error: %s", result.Msg)
|
||
}
|
||
|
||
return base64.StdEncoding.DecodeString(result.Audio)
|
||
}
|
||
|
||
func main() {
|
||
// 长文本测试
|
||
longText := "欢迎使用红动未来数字人服务平台，我们将为您提供最优质的AI数字人解决方案。人工智能技术正在改变我们的生活，让我们一起探索未来的无限可能。"
|
||
|
||
audio, err := TTS(longText)
|
||
if err != nil {
|
||
panic(err)
|
||
}
|
||
|
||
os.WriteFile("output.wav", audio, 0644)
|
||
fmt.Println("音频已保存到 output.wav")
|
||
}
|
||
```
|
||
|
||
### Python 调用示例（带超时设置）
|
||
|
||
```python
|
||
import requests
|
||
import base64
|
||
|
||
def tts(text, timeout=180):
|
||
"""
|
||
TTS 文本转语音
|
||
|
||
Args:
|
||
text: 要转换的文本
|
||
timeout: 超时时间（秒），1.7B 模型建议 >= 180 秒
|
||
"""
|
||
# 必须使用 JSON 字符串格式
|
||
response = requests.post(
|
||
"http://localhost:8000/tts",
|
||
data=f'"{text}"',
|
||
headers={"Content-Type": "application/json"},
|
||
timeout=timeout # 设置超时
|
||
)
|
||
|
||
result = response.json()
|
||
if result["code"] != 0:
|
||
raise Exception(f"TTS error: {result['msg']}")
|
||
|
||
return base64.b64decode(result["audio"])
|
||
|
||
# 使用
|
||
short_text = "你好，这是一个测试"
|
||
long_text = "欢迎使用红动未来数字人服务平台，我们将为您提供最优质的AI数字人解决方案。"
|
||
|
||
# 短文本（30秒超时）
|
||
audio_data = tts(short_text, timeout=30)
|
||
with open("short_output.wav", "wb") as f:
|
||
f.write(audio_data)
|
||
|
||
# 长文本（180秒超时）
|
||
audio_data = tts(long_text, timeout=180)
|
||
with open("long_output.wav", "wb") as f:
|
||
f.write(audio_data)
|
||
```
|
||
|
||
---
|
||
|
||
## 服务管理
|
||
|
||
```bash
|
||
# 查看日志
|
||
docker logs -f tts-service
|
||
|
||
# 查看最近50行日志
|
||
docker logs --tail 50 tts-service
|
||
|
||
# 停止服务
|
||
docker stop tts-service
|
||
|
||
# 启动服务
|
||
docker start tts-service
|
||
|
||
# 重启服务
|
||
docker restart tts-service
|
||
|
||
# 删除容器
|
||
docker stop tts-service && docker rm tts-service
|
||
|
||
# 删除镜像
|
||
docker rmi qwen3-tts:latest
|
||
|
||
# 进入容器
|
||
docker exec -it tts-service /bin/bash
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排查
|
||
|
||
### 1. 端口被占用
|
||
|
||
```bash
|
||
# 查找占用 8000 端口的进程
|
||
lsof -ti:8000
|
||
|
||
# 停止占用端口的进程
|
||
lsof -ti:8000 | xargs kill -9
|
||
|
||
# 或修改映射端口
|
||
docker run -d -p 8001:8000 --name tts-service qwen3-tts:latest
|
||
```
|
||
|
||
### 2. API 返回 422 错误
|
||
|
||
**原因：** 请求格式不正确，必须使用 JSON 字符串格式
|
||
|
||
**正确请求：**
|
||
```bash
|
||
curl -X POST http://localhost:8000/tts \
|
||
-H "Content-Type: application/json" \
|
||
-d '"你好"'
|
||
```
|
||
|
||
**错误请求：**
|
||
```bash
|
||
# ❌ 错误：这是 JSON 对象，不是字符串
|
||
curl -X POST http://localhost:8000/tts \
|
||
-d '{"text": "你好"}'
|
||
```
|
||
|
||
### 3. 长文本返回 EOF 错误
|
||
|
||
**原因：** 1.7B 模型推理更慢，长文本处理时间超过客户端超时时间
|
||
|
||
**解决方案：**
|
||
1. **客户端设置超时 >= 180 秒**
|
||
2. **缩短文本长度**（建议单次请求 < 100 字）
|
||
3. **使用 GPU 加速**（如果可用）
|
||
4. **切换到 0.6B 模型**（更快但质量略低）
|
||
|
||
**Go 客户端：**
|
||
```go
|
||
client := &http.Client{
|
||
Timeout: 180 * time.Second, // 设置 180 秒超时
|
||
}
|
||
```
|
||
|
||
**Python 客户端：**
|
||
```python
|
||
response = requests.post(
|
||
"http://localhost:8000/tts",
|
||
data=f'"{text}"',
|
||
timeout=180 # 设置 180 秒超时
|
||
)
|
||
```
|
||
|
||
### 4. 音频无声音或文件过小
|
||
|
||
```bash
|
||
# 查看日志检查模型是否加载
|
||
docker logs tts-service | grep "TTS 模型初始化完成"
|
||
|
||
# 检查模型文件
|
||
docker exec tts-service ls -la /app/model/
|
||
|
||
# 测试 API 返回的音频数据大小（应该 > 10KB）
|
||
curl -s http://localhost:8000/tts -d '"测试"' | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d['audio']))"
|
||
```
|
||
|
||
### 5. 内存不足
|
||
|
||
```bash
|
||
# 增加内存限制（1.7B 模型建议 >= 8GB）
|
||
docker run -d --name tts-service -p 8000:8000 --memory="8g" qwen3-tts:latest
|
||
|
||
# 或增加更多内存
|
||
docker run -d --name tts-service -p 8000:8000 --memory="12g" qwen3-tts:latest
|
||
```
|
||
|
||
### 6. 服务启动后无法访问
|
||
|
||
```bash
|
||
# 检查容器状态
|
||
docker ps | grep tts-service
|
||
|
||
# 检查端口映射
|
||
docker port tts-service
|
||
|
||
# 检查服务是否正常响应
|
||
curl http://localhost:8000/
|
||
```
|
||
|
||
### 7. 推理速度过慢
|
||
|
||
**1.7B 模型优化方案：**
|
||
```bash
|
||
# 限制并发为 1（避免 CPU 争抢）
|
||
docker run -d --name tts-service -p 8000:8000 qwen3-tts:latest \
|
||
uvicorn app:app --limit-concurrency 1
|
||
|
||
# 增加 CPU 资源
|
||
docker run -d --name tts-service -p 8000:8000 --cpus="8.0" qwen3-tts:latest
|
||
```
|
||
|
||
**GPU 加速（需要 NVIDIA GPU）：**
|
||
```bash
|
||
# 修改 app.py 中的 device_map='cpu' 为 device_map='cuda:0'
|
||
# 重新构建镜像并运行
|
||
docker run -d --name tts-service --gpus all -p 8000:8000 qwen3-tts:latest
|
||
```
|
||
|
||
**切换到更快的模型：**
|
||
- 如果对速度要求高，可切换到 `Qwen3-TTS-12Hz-0.6B-CustomVoice`
|
||
- 推理速度可提升 3-5 倍
|
||
|
||
### 8. 模型加载失败
|
||
|
||
**检查模型路径：**
|
||
```bash
|
||
# 查看容器内模型目录
|
||
docker exec tts-service ls -la /app/model/
|
||
|
||
# 确认 app.py 中的 MODEL_PATH 和 TOKENIZER_PATH 正确
|
||
docker exec tts-service cat /app/app.py | grep "MODEL_PATH\|TOKENIZER_PATH"
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题 FAQ
|
||
|
||
**Q: 为什么选择 Qwen3-TTS-24Hz-1.7B-Base-VoiceClone？**
|
||
|
||
A: 这是 Qwen3-TTS 系列中功能最全面、音质最高的模型：
|
||
- **24kHz 采样率**：双倍于 12Hz 模型，音质更清晰自然
|
||
- **1.7B 参数**：模型表达能力最强
|
||
- **声音克隆**：支持自定义声音训练和生成
|
||
|
||
**Q: 1.7B 模型推理速度慢怎么办？**
|
||
|
||
A: 可以采取以下措施：
|
||
1. 客户端设置超时 >= 180 秒
|
||
2. 使用 GPU 加速（速度提升 10-20 倍）
|
||
3. 切换到 0.6B 模型（速度提升 3-5 倍）
|
||
4. 缩短单次请求文本长度
|
||
|
||
**Q: 为什么 Body 必须是 JSON 字符串而不是 JSON 对象？**
|
||
|
||
A: FastAPI 使用 `Body(..., media_type='application/json')` 解析时，直接接收 JSON 字符串。如果使用 `{"text": "..."}` 格式，需要修改 `app.py` 使用 Pydantic 模型。当前实现更简洁，直接传递字符串即可。
|
||
|
||
**Q: 24Hz 和 12Hz 模型有什么区别？**
|
||
|
||
A:
|
||
- **24Hz**：采样率 24kHz，音质更清晰自然，适合高质量需求
|
||
- **12Hz**：采样率 12kHz，推理速度快，适合实时应用
|
||
|
||
**Q: 1.7B 和 0.6B 模型有什么区别？**
|
||
|
||
A:
|
||
- **1.7B**：参数量更大，音质更高，但推理速度慢，内存占用大（推荐 GPU）
|
||
- **0.6B**：参数量小，推理快，内存占用少，适合 CPU 环境
|
||
|
||
**Q: CustomVoice 和 Base 模型有什么区别？**
|
||
|
||
A:
|
||
- **CustomVoice**：内置 9 种预设声音，开箱即用
|
||
- **Base**：基础模型，支持自定义训练和声音克隆
|
||
|
||
**Q: 长文本推理需要多长时间？**
|
||
|
||
A: 1.7B 模型 CPU 推理速度约 1-3 秒/字符：
|
||
- 短文本（< 20 字）：约 15-30 秒
|
||
- 中等文本（20-50 字）：约 50-120 秒
|
||
- 长文本（50-100 字）：约 120-240 秒
|
||
|
||
**Q: 为什么长文本会返回 EOF 错误？**
|
||
|
||
A: 1.7B 模型推理时间长，如果客户端超时时间设置过短会断开连接。解决方案：
|
||
1. 客户端设置超时 >= 180 秒
|
||
2. 缩短单次请求文本长度
|
||
3. 使用 GPU 加速
|
||
4. 切换到 0.6B 模型
|
||
|
||
**Q: 支持哪些声音？**
|
||
|
||
A: CustomVoice 模型支持 9 种预设声音：serena, vivian, uncle_fu, ryan, aiden, ono_anna, sohee, eric, dylan
|
||
|
||
**Q: 可以自定义声音吗？**
|
||
|
||
A: 可以，Base-VoiceClone 模型支持声音克隆功能，详见 Qwen3-TTS 官方文档
|
||
|
||
**Q: 支持哪些语言？**
|
||
|
||
A: 中文、英文、日语、韩语、德语、法语、俄语、葡萄牙语、西班牙语、意大利语
|
||
|
||
**Q: 音频采样率是多少？**
|
||
|
||
A: 24kHz (24000 Hz) - 比标准 CD 音质（44.1kHz）略低，但比 12Hz 模型清晰很多
|
||
|
||
**Q: 生成的音频文件格式是什么？**
|
||
|
||
A: WAV 格式，Microsoft PCM, 16 bit, mono
|
||
|
||
**Q: 如何提高推理速度？**
|
||
|
||
A:
|
||
1. 使用 GPU 加速（device_map='cuda:0'）
|
||
2. 使用更小的模型（0.6B 而非 1.7B）
|
||
3. 使用 12Hz 模型而非 24Hz 模型
|
||
4. 限制并发请求（limit-concurrency=1）
|
||
5. 增加 CPU 核心数（--cpus="8.0"）
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
~/Qwen3-TTS/
|
||
├── app.py # FastAPI 服务代码
|
||
├── Dockerfile # Docker 镜像构建文件
|
||
├── requirements.txt # Python 依赖
|
||
└── model/ # 模型文件目录
|
||
├── Qwen3-TTS-Tokenizer-24Hz/ # 24Hz 分词器（651MB）
|
||
└── Qwen3-TTS-24Hz-1.7B-Base-VoiceClone/ # 24Hz 1.7B 模型（6.8GB）
|
||
```
|
||
|
||
---
|
||
|
||
## 相关链接
|
||
|
||
- 官方文档：https://github.com/QwenLM/Qwen3-TTS
|
||
- ModelScope：https://modelscope.cn/models?name=Qwen3-TTS
|
||
- FastAPI 文档：https://fastapi.tiangolo.com/
|