149 lines
4.9 KiB
Markdown
149 lines
4.9 KiB
Markdown
# 🚀 云端无人机语音服务
|
||
|
||
基于 **FastAPI + WebSocket** 的云端语音交互服务，为无人机提供 **LLM 意图识别** 和 **TTS 文字转语音** 能力。
|
||
|
||
## 📋 特性
|
||
|
||
- ✅ **完整协议实现**: Cloud Voice Protocol v1.0 (text_uplink)
|
||
- ✅ **LLM 意图识别**: 阿里云百炼 Qwen 模型，区分飞控指令与闲聊
|
||
- ✅ **TTS 本地推理**: Kokoro 高效本地合成语音 (24kHz PCM)
|
||
- ✅ **流式输出**: LLM 结果 + TTS 音频块流式下发
|
||
- ✅ **并发支持**: 最多 4 路无人机并发会话
|
||
- ✅ **模块化架构**: 易于扩展新的 LLM/TTS 提供者
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
voicellmcloud/
|
||
├── 📂 app/ # 核心应用代码
|
||
│ ├── main.py # FastAPI 入口
|
||
│ ├── config.py # 配置管理
|
||
│ ├── protocols/ # 协议层（消息模型、验证）
|
||
│ ├── websocket/ # WebSocket 管理（会话、消息处理）
|
||
│ ├── services/ # 业务服务接口（LLM、TTS、意图识别）
|
||
│ ├── providers/ # 第三方服务实现（阿里云 LLM、Kokoro TTS）
|
||
│ └── utils/ # 工具模块（日志、音频处理）
|
||
│
|
||
├── 📂 test/ # 测试代码
|
||
│ ├── test_01_basic.py # 基础功能测试
|
||
│ ├── test_03_errors.py # 错误处理测试
|
||
│ ├── test_04_concurrent.py # 多会话并发测试
|
||
│ ├── test_05_performance.py # 性能基准测试
|
||
│ ├── test_07_orangepi.py # 香橙派客户端模拟
|
||
│ └── test_08_tts_stream.py # TTS 音频流完整测试
|
||
│
|
||
├── 📂 scripts/ # 启动脚本
|
||
│ ├── run_server.py # 推荐：直接启动（日志完整输出）
|
||
│ ├── start.sh # Linux/macOS 启动脚本
|
||
│ └── start.bat # Windows 启动脚本
|
||
│
|
||
├── 📂 examples/ # 示例代码
|
||
│ ├── cloud_voice_client.py # 香橙派客户端适配器（参考实现）
|
||
│ ├── test_client.py # 测试客户端
|
||
│ └── test_kokoro.py # Kokoro TTS 模型验证
|
||
│
|
||
├── 📂 docs/ # 文档
|
||
│ ├── README.md # 完整项目文档（架构、配置、部署）
|
||
│ ├── QUICKSTART.md # 10 分钟快速入门
|
||
│ ├── API_SPECIFICATION.md # 接口规范（给客户端团队）
|
||
│ ├── CLIENT_INTEGRATION_GUIDE.md # 香橙派客户端集成指南
|
||
│ └── CLOUD_VOICE_PROTOCOL_v1_text_uplink.md # 协议规范原文
|
||
│
|
||
├── 📂 models/ # TTS 模型文件（需自行下载）
|
||
│ └── Kokoro-82M-v1.1-zh-ONNX/
|
||
│
|
||
├── 📂 Client/ # 香橙派客户端参考代码（原始项目）
|
||
│ └── voice_drone_assistant/
|
||
│
|
||
├── requirements.txt # Python 依赖清单
|
||
├── .env.example # 环境配置示例
|
||
├── .env # 环境配置（实际使用，git 忽略）
|
||
└── .gitignore # Git 忽略规则
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境
|
||
|
||
```bash
|
||
# 复制配置示例
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env，修改以下配置：
|
||
# - DASHSCOPE_API_KEY: 阿里云百炼 API Key
|
||
# - BEARER_TOKEN: 鉴权 Token（客户端需一致）
|
||
```
|
||
|
||
### 3. 启动服务
|
||
|
||
**推荐方式（日志完整输出）：**
|
||
```bash
|
||
python scripts/run_server.py
|
||
```
|
||
|
||
**或使用 uvicorn 命令：**
|
||
```bash
|
||
python -m uvicorn app.main:app --host 0.0.0.0 --port 8765
|
||
```
|
||
|
||
### 4. 验证服务
|
||
|
||
```bash
|
||
# 健康检查
|
||
curl http://localhost:8765/health
|
||
```
|
||
|
||
## 📚 文档导航
|
||
|
||
| 文档 | 说明 | 适用对象 |
|
||
|------|------|---------|
|
||
| [快速入门](docs/QUICKSTART.md) | 10 分钟启动指南 | 新开发者 |
|
||
| [完整文档](docs/README.md) | 架构、配置、部署 | 后端开发 |
|
||
| [接口规范](docs/API_SPECIFICATION.md) | WebSocket 协议详情 | 客户端团队 |
|
||
| [客户端集成](docs/CLIENT_INTEGRATION_GUIDE.md) | 香橙派端修改指南 | 嵌入式开发 |
|
||
|
||
## 🧪 运行测试
|
||
|
||
```bash
|
||
# 基础功能测试
|
||
python test/test_01_basic.py
|
||
|
||
# TTS 音频流完整测试
|
||
python test/test_08_tts_stream.py
|
||
|
||
# 性能测试
|
||
python test/test_05_performance.py
|
||
```
|
||
|
||
## 📊 性能指标
|
||
|
||
| 指标 | 数值 |
|
||
|------|------|
|
||
| LLM 推理延迟 | 1-3 秒（阿里云 qwen-plus） |
|
||
| TTS 首字节延迟 | 0.5-3 秒（Kokoro 本地） |
|
||
| 音频实时率 | 1.8x（远超实时） |
|
||
| 最大并发 | 4 sessions |
|
||
|
||
## 🔮 后续规划
|
||
|
||
- [ ] 支持本地 H200 部署 LLM (vLLM/TGI)
|
||
- [ ] WebSocket TLS (WSS) 支持
|
||
- [ ] Prometheus 指标监控
|
||
- [ ] Docker 容器化部署
|
||
|
||
## 📄 许可证
|
||
|
||
内部项目 - 无人机云端语音交互服务
|
||
|
||
---
|
||
|
||
**版本**: v1.0.0
|
||
**更新日期**: 2024-04-07
|
||
**协议版本**: Cloud Voice Protocol v1.0 (text_uplink)
|