LKTX 1650f046b6 Add voicellmcloud (cloud service) under voicellmcloud/

Made-with: Cursor

2026-04-14 10:08:41 +08:00

4.9 KiB

Raw Blame History

🚀 云端无人机语音服务

基于 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. 安装依赖

pip install -r requirements.txt

2. 配置环境

# 复制配置示例
cp .env.example .env

# 编辑 .env，修改以下配置：
# - DASHSCOPE_API_KEY: 阿里云百炼 API Key
# - BEARER_TOKEN: 鉴权 Token（客户端需一致）

3. 启动服务

推荐方式（日志完整输出）：

python scripts/run_server.py

或使用 uvicorn 命令：

python -m uvicorn app.main:app --host 0.0.0.0 --port 8765

4. 验证服务

# 健康检查
curl http://localhost:8765/health

📚 文档导航

文档	说明	适用对象
快速入门	10 分钟启动指南	新开发者
完整文档	架构、配置、部署	后端开发
接口规范	WebSocket 协议详情	客户端团队
客户端集成	香橙派端修改指南	嵌入式开发

🧪 运行测试

# 基础功能测试
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)

4.9 KiB Raw Blame History Unescape Escape