# 《军事科技》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

---

*本文档记录系统架构和设计决策，应在开发过程中保持更新。*