military-tech-voice3.0/design.md

《军事科技》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 语音合成接口

请求

POST /api/tts/synthesize
Content-Type: application/json

{
  "text": "😊大家好，欢迎收看《军事科技》",
  "model": "minimax"  // 或 "cosyvoice"
}

响应

{
  "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服务支持的语气标签

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 启动命令

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

---

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