simonkoson
d6edc69c65
- Flask backend with MiniMax and CosyVoice TTS engines - Frontend UI with emotion tags, speed/pitch/volume controls - Nginx reverse proxy configuration - Dual engine support (MiniMax speech-2.8-hd, CosyVoice v3.5-flash)
257 lines
7.8 KiB
Markdown
257 lines
7.8 KiB
Markdown
# 《军事科技》AI配音员 - 系统设计文档
|
|
|
|
> 创建时间：2026-04-11
|
|
> 最后更新：2026-04-12
|
|
> 状态：开发中
|
|
|
|
---
|
|
|
|
## 1. 系统架构
|
|
|
|
### 1.1 整体架构图
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ 前端 (HTML/JS) │
|
|
│ http://101.42.29.217:5000 │
|
|
└─────────────────────┬───────────────────────────────────┘
|
|
│
|
|
▼ HTTP POST /api/tts/synthesize
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Flask 后端 (5000端口) │
|
|
│ ┌─────────────────────────────────────────────────┐ │
|
|
│ │ /api/tts/synthesize │ │
|
|
│ │ (根据model参数路由到对应的TTS服务) │ │
|
|
│ └─────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌───────────┴───────────┐ │
|
|
│ ▼ ▼ │
|
|
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ MiniMax API │ │ CosyVoice API │ │
|
|
│ │ (speech-2.8-hd) │ │(cosyvoice-v3-flash)│ │
|
|
│ └──────────────────┘ └──────────────────┘ │
|
|
│ │ │ │
|
|
│ ▼ ▼ │
|
|
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ /audio_uploads │ │ /audio_uploads │ │
|
|
│ │ (mp3文件) │ │ (mp3文件) │ │
|
|
│ └──────────────────┘ └──────────────────┘ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 1.2 技术栈
|
|
|
|
| 层级 | 技术 | 版本/说明 |
|
|
|------|------|-----------|
|
|
| 服务器 | 腾讯云Ubuntu | 101.42.29.217 |
|
|
| 后端框架 | Python Flask | Python 3.x |
|
|
| 跨域支持 | flask-cors | CORS enabled |
|
|
| TTS服务1 | MiniMax API | speech-2.8-hd模型 |
|
|
| TTS服务2 | CosyVoice (阿里云) | cosyvoice-v3-flash模型 |
|
|
| 前端 | HTML + JavaScript | 原生开发 |
|
|
| 音频格式 | MP3 | 32kHz, 128kbps |
|
|
|
|
---
|
|
|
|
## 2. API设计
|
|
|
|
### 2.1 接口列表
|
|
|
|
| 接口 | 方法 | 说明 |
|
|
|------|------|------|
|
|
| `/` | GET | 服务状态信息 |
|
|
| `/api/health` | GET | 健康检查 |
|
|
| `/api/tts/synthesize` | POST | 语音合成（统一入口） |
|
|
| `/api/tts/audio/` | GET | 获取音频文件 |
|
|
|
|
### 2.2 语音合成接口
|
|
|
|
**请求**
|
|
```json
|
|
POST /api/tts/synthesize
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"text": "😊大家好，欢迎收看《军事科技》",
|
|
"model": "minimax" // 或 "cosyvoice"
|
|
}
|
|
```
|
|
|
|
**响应**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"audio_url": "/api/tts/audio/minimax_a1b2c3d4.mp3"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 音色配置
|
|
|
|
### 3.1 MiniMax音色
|
|
|
|
| 属性 | 值 |
|
|
|------|-----|
|
|
| Voice ID | `lanhao_military_tech` |
|
|
| File ID | `386365413015965` |
|
|
| 模型 | `speech-2.8-hd` |
|
|
| 采样率 | 32000 Hz |
|
|
| 比特率 | 128000 bps |
|
|
| 格式 | mp3 |
|
|
|
|
### 3.2 CosyVoice音色
|
|
|
|
| 属性 | 值 |
|
|
|------|-----|
|
|
| Voice ID | `cosyvoice-v3.5-flash-bailian-e859a6e87823419f9c6b3eefb1a97dc3` |
|
|
| 模型 | `cosyvoice-v3.5-flash` |
|
|
| 类型 | 克隆音色 |
|
|
|
|
---
|
|
|
|
## 4. 语气控制设计
|
|
|
|
### 4.1 Emoji语气映射
|
|
|
|
这是本项目的核心特色功能。
|
|
|
|
| Emoji | 含义 | MiniMax标签 | CosyVoice参数 |
|
|
|-------|------|-------------|--------------|
|
|
| 😊 | 高兴/愉悦 | `(laughs)` | style: happy |
|
|
| 😕 | 疑问/困惑 | `(sighs)` | style: sad |
|
|
| ❗ | 强调/加重 | 无 | emphasis: high |
|
|
| 🔥 | 热情/激动 | `(laughs)` | style: excited |
|
|
| 😢 | 悲伤/低沉 | `(sighs)` | style: sad |
|
|
| 🤔 | 思考/停顿 | 无 | pause: 500ms |
|
|
| 😂 | 大笑 | `(laughs)` | style: happy |
|
|
| 😤 | 不满/生气 | 无 | style: angry |
|
|
|
|
### 4.2 实现方式
|
|
|
|
前端预处理：Emoji → TTS服务支持的语气标签
|
|
|
|
```javascript
|
|
function preprocessText(text) {
|
|
const emojiMap = {
|
|
'😊': '(laughs)',
|
|
'😕': '(sighs)',
|
|
'❗': '', // 强调通过重音实现
|
|
'🔥': '(laughs)',
|
|
'😢': '(sighs)',
|
|
'😂': '(laughs)'
|
|
};
|
|
|
|
for (const [emoji, tag] of Object.entries(emojiMap)) {
|
|
text = text.replace(new RegExp(emoji, 'g'), tag);
|
|
}
|
|
return text;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 文件结构
|
|
|
|
```
|
|
/workspace/military_tech_voice/
|
|
├── design.md # 本文档
|
|
├── PROJECT_STATUS.md # 项目状态文档
|
|
├── backend/
|
|
│ ├── .env # 环境变量
|
|
│ ├── app/
|
|
│ │ ├── __init__.py
|
|
│ │ ├── main.py # Flask主入口
|
|
│ │ ├── routes/
|
|
│ │ │ ├── __init__.py
|
|
│ │ │ ├── health.py # 健康检查
|
|
│ │ │ ├── tts.py # 统一TTS路由
|
|
│ │ │ ├── tts_minimax.py # MiniMax路由(参考)
|
|
│ │ │ └── tts_cosyvoice.py # CosyVoice路由(参考)
|
|
│ │ └── utils/
|
|
│ │ └── __init__.py
|
|
│ └── venv/ # Python虚拟环境
|
|
├── frontend/ # 前端目录(待开发)
|
|
│ └── index.html
|
|
├── models/ # 模型文件
|
|
├── audio_uploads/ # 音频输出目录
|
|
├── lanhao03.wav # 原始音频样本
|
|
└── get-docker.sh # Docker安装脚本
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 错误处理
|
|
|
|
### 6.1 错误代码
|
|
|
|
| 错误代码 | 含义 |
|
|
|----------|------|
|
|
| 400 | 请求参数错误 |
|
|
| 401 | API Key无效 |
|
|
| 403 | 无权限访问 |
|
|
| 404 | 文件不存在 |
|
|
| 500 | 服务器内部错误 |
|
|
| 502 | TTS服务返回错误 |
|
|
| 503 | TTS服务不可用 |
|
|
|
|
### 6.2 日志记录
|
|
|
|
- 使用Python logging模块
|
|
- 日志级别：INFO, WARNING, ERROR
|
|
- 记录内容：API请求、响应、错误信息
|
|
|
|
---
|
|
|
|
## 7. 部署配置
|
|
|
|
### 7.1 服务器配置
|
|
|
|
| 配置项 | 值 |
|
|
|--------|-----|
|
|
| 服务器IP | 101.42.29.217 |
|
|
| 端口 | 5000 |
|
|
| 操作系统 | Ubuntu |
|
|
| Python版本 | 3.x |
|
|
|
|
### 7.2 启动命令
|
|
|
|
```bash
|
|
cd /workspace/military_tech_voice/backend
|
|
source venv/bin/activate
|
|
python app/main.py
|
|
```
|
|
|
|
### 7.3 访问地址
|
|
|
|
- 本地：http://localhost:5000
|
|
- 远程：http://101.42.29.217:5000
|
|
|
|
---
|
|
|
|
## 8. 安全考虑
|
|
|
|
### 8.1 密钥保护
|
|
|
|
- API密钥存储在 `.env` 文件
|
|
- `.env` 文件已添加到 `.gitignore`
|
|
- 生产环境应使用环境变量而非硬编码
|
|
|
|
### 8.2 文件上传限制
|
|
|
|
- 最大文件大小：50MB
|
|
- 仅允许MP3格式
|
|
- 文件名使用UUID随机生成
|
|
|
|
---
|
|
|
|
## 9. 参考文档
|
|
|
|
- MiniMax API文档：https://platform.minimaxi.com
|
|
- CosyVoice文档：https://dashscope.aliyuncs.com
|
|
- Flask文档：https://flask.palletsprojects.com
|
|
- 腾讯云控制台：https://console.cloud.tencent.com
|
|
|
|
---
|
|
|
|
*本文档记录系统架构和设计决策，应在开发过程中保持更新。* |