# 🚀 云端无人机语音服务

基于 **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)