174 lines
8.3 KiB
Markdown
174 lines
8.3 KiB
Markdown
# VoiceLLM Cloud — 项目总结与部署手册
|
||
|
||
本文档概括 **voicellmcloud**（云端语音与意图服务）的定位与端到端流程，并给出从开发试跑到生产部署的检查清单与排障要点。细节协议仍以 `CLOUD_VOICE_PROTOCOL_v1_text_uplink.md`、`FLIGHT_INTENT_SCHEMA_v1.md` 为准。
|
||
|
||
---
|
||
|
||
## 1. 项目总结
|
||
|
||
### 1.1 定位
|
||
|
||
基于 **FastAPI + WebSocket** 的 **text_uplink** 服务：机载或地面客户端上行 **文本**（来自设备 STT 或调试键盘），云端完成 **大模型理解与分流**、**结构化飞控意图** 与 **TTS 音频下发**。云端 **不直接驱动 PX4**；飞控执行由 **伴飞客户端 / 翻译桥 / ROS** 消费 `dialog_result.flight_intent` 或本地 Socket `Command` 完成。
|
||
|
||
### 1.2 核心能力
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| 会话协议 | Cloud Voice Protocol v1.0，`proto_version` / `transport_profile: "text_uplink"` |
|
||
| LLM | 默认 **阿里云 DashScope**（如 `qwen-plus`），支持 **流式输出**（`llm.text_delta`） |
|
||
| 意图 | `routing`: `flight_intent`（严格 JSON，见 **FLIGHT_INTENT_SCHEMA v1**）或 `chitchat` |
|
||
| TTS | 本地推理：`TTS_PROVIDER=kokoro`（ONNX，默认模型目录见配置）或 `piper`（需另装 `piper-tts` 与语音包） |
|
||
| 多会话 | `MAX_CONCURRENT_SESSIONS` 限制并发会话数 |
|
||
| 长连接 | Uvicorn **WebSocket Ping/Pong**（如 `scripts/run_server.py` 中 interval/timeout），减轻 NAT/代理空闲断线 |
|
||
|
||
### 1.3 飞控意图（与客户端/桥协作）
|
||
|
||
- 合法 `flight_intent` 仅含文档 §3.7 所列 `type` 与允许的 `args`；**时长**用 **`wait` + `seconds`**，**不得**在 `hover`/`hold` 中写 `duration`。
|
||
- 可选 **`trace_id`**；**`takeoff`** 可选 **`relative_altitude_m`**。
|
||
- 客户端侧可参考 `Client/voice_drone_assistant`：云端结果映射为 Socket `Command`（含已对齐的 **`return_home`**）或由 **桥** 顺序消费整段 `actions`。
|
||
|
||
### 1.4 仓库与模块（服务端）
|
||
|
||
```
|
||
app/main.py FastAPI 入口、/health、WebSocket 挂载
|
||
app/config.py 环境变量 / .env（Pydantic Settings）
|
||
app/websocket/ 会话、消息处理与流式 turn
|
||
app/services/ LLM/TTS 接口、意图解析与 TTS 分句
|
||
app/providers/ DashScope LLM、Kokoro / Piper TTS
|
||
app/protocols/models.py 协议消息体（含 FlightIntentPayload）
|
||
scripts/run_server.py 带 WS 保活的 Uvicorn 启动（host/port 读取 settings）
|
||
docs/ 协议、Schema、实施计划与本手册
|
||
```
|
||
|
||
### 1.5 文档索引
|
||
|
||
| 文档 | 用途 |
|
||
|------|------|
|
||
| `CLOUD_VOICE_PROTOCOL_v1_text_uplink.md` | WebSocket 消息类型与时序 |
|
||
| `FLIGHT_INTENT_SCHEMA_v1.md` | `flight_intent` 字段、校验分级、桥与 ROS 参考 |
|
||
| `FLIGHT_INTENT_IMPLEMENTATION_PLAN.md` | 分阶段交付与验收 |
|
||
| `API_SPECIFICATION.md` / `PX4_CLIENT_CONTEXT.md` | 对外 API 说明、PX4 上下文上报 |
|
||
| `CLOUD_VOICE_DIALOG_v1.md` | **dialog_result v1**：`protocol`、`confirm`、飞控门控 |
|
||
| `CLOUD_VOICE_FLIGHT_CONFIRM_v1.md` | 历史备选（pending / `turn.confirmation`） |
|
||
| `QUICKSTART.md` | 最短路径试跑 |
|
||
| `STRUCTURE.md` | 目录与模块职责 |
|
||
|
||
---
|
||
|
||
## 2. 部署手册
|
||
|
||
### 2.1 环境与依赖
|
||
|
||
- **Python**：3.10+
|
||
- **网络**：可访问 DashScope API（大陆外注意线路与合规）
|
||
- **磁盘**：TTS 模型（Kokoro 一部署套约数百 MB；Piper 语音包约数十 MB 级）
|
||
|
||
```bash
|
||
cd /path/to/voicellmcloud
|
||
python -m venv .venv
|
||
# Windows: .venv\Scripts\activate
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
使用 **Piper** 时需额外安装语音推理库（若未记入 `requirements.txt`）：
|
||
|
||
```bash
|
||
pip install piper-tts
|
||
python -m piper.download_voice zh_CN-huayan-medium
|
||
```
|
||
|
||
使用 **Kokoro** 时：将 ONNX 与配置放到 `TTS_MODEL_DIR` 下约定子目录（参见 `app/providers/kokoro_tts.py`），并设置 `TTS_VOICE_NAME` 等与引擎一致。
|
||
|
||
### 2.2 配置（`.env`）
|
||
|
||
复制 `docs` 同级的 `.env.example` 为 `.env`，至少检查：
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `WS_HOST` / `WS_PORT` | HTTP/WebSocket 监听；客户端 URL 必须一致 |
|
||
| `BEARER_TOKEN` | 与客户端 `session.start.auth_token` 一致 |
|
||
| `DASHSCOPE_API_KEY` | 百炼 API Key；**勿**提交到版本库 |
|
||
| `LLM_MODEL` / `LLM_CONTEXT_TURNS` | 模型名与历史轮数 |
|
||
| `TTS_PROVIDER` | `kokoro` 或 `piper` |
|
||
| `TTS_MODEL_DIR` / `TTS_VOICE_NAME` | 模型路径与音色 |
|
||
| `MAX_CONCURRENT_SESSIONS` | 并发会话上限 |
|
||
|
||
**生产建议**：通过密钥管理或部署平台注入环境变量，避免在镜像中硬编码 Key。
|
||
|
||
### 2.3 启动方式
|
||
|
||
**推荐（与 `.env` 端口一致，且带 WS 保活）**：
|
||
|
||
```bash
|
||
# 在项目根目录执行
|
||
python scripts/run_server.py
|
||
```
|
||
|
||
`scripts/run_server.py` 使用 **`settings.WS_HOST` / `settings.WS_PORT`**，与 `.env` 对齐。
|
||
|
||
**标准 Uvicorn（可配合 systemd / Docker CMD）**：
|
||
|
||
```bash
|
||
python -m uvicorn app.main:app --host 0.0.0.0 --port 8765
|
||
```
|
||
|
||
若需与 `run_server.py` 相同的 Ping/Pong，可在代码层已用 `uvicorn.Config(ws_ping_interval=..., ws_ping_timeout=...)` 的封装启动，或在前置代理上保持连接活跃。
|
||
|
||
**开发加載**：
|
||
|
||
```bash
|
||
python -m uvicorn app.main:app --host 0.0.0.0 --port 8765 --reload
|
||
```
|
||
|
||
### 2.4 健康检查与连通性
|
||
|
||
- **HTTP**：`GET http://<host>:<port>/health`
|
||
期望 JSON 含 `"status":"ok"`、`llm_provider`、`tts_provider`、`active_sessions`。
|
||
- **仅 TTS（机端播报）**：在既有 WebSocket 上发 `tts.synthesize`（见 `API_SPECIFICATION.md` §3.3），下行 `tts_audio_chunk` + `turn.complete`；与 `turn.text` 互斥排队。
|
||
- **WebSocket**：`ws://<host>:<口>/v1/voice/session`（路径以 `app/config.py` 中 `WS_PATH` 为准）。
|
||
|
||
防火墙与安全组需放行 **TCP 端口**（HTTP 与 WS 同端口）。
|
||
|
||
### 2.5 生产部署要点
|
||
|
||
1. **进程管理**：systemd、supervisor 或 Kubernetes Deployment；崩溃自拉起；限制文件句柄与内存。
|
||
2. **TLS**：公网场景在入口使用 **WSS**（Nginx / Caddy / 云 LB 终结 TLS），后端仍可为 `ws://127.0.0.1:端口`。
|
||
3. **日志**：当前主用 **loguru** stderr；可接入集中日志；注意 **勿**在日志中打印完整 Token 或用户隐私。
|
||
4. **横向扩展**：有状态会话绑定单机 WebSocket 连接；多实例时需 **会话粘性** 或改为共享后端架构（超出本仓库默认范围）。
|
||
5. **Windows 控制台**：若出现日志编码问题，可设置 `PYTHONUTF8=1` 或使用 UTF-8 终端。
|
||
|
||
### 2.6 客户端对接 checklist
|
||
|
||
- [ ] `session.start` 带齐 `session_id`、`client.device_id`；可选 `client.px4`（见 `PX4_CLIENT_CONTEXT.md`）。
|
||
- [ ] `auth_token` 与云端 `BEARER_TOKEN` 一致（若启用鉴权）。
|
||
- [ ] 处理消息顺序：`dialog_result` → `llm.text_delta`（可选）→ `tts_audio_chunk`（JSON 帧 + binary PCM）→ `turn.complete`。
|
||
- [ ] 飞控路径：`routing === "flight_intent"` 时解析 `flight_intent.actions`，**禁止**仅用 `summary` 驱机。
|
||
- [ ] 伴飞桥扩展 Socket 时识别 **`return_home`** 等与 Schema 一致的 `Command.command` 字面量。
|
||
|
||
### 2.7 常见问题
|
||
|
||
| 现象 | 排查 |
|
||
|------|------|
|
||
| `/health` 不可用 | 端口错误、进程未起、防火墙拦截 |
|
||
| WebSocket 秒断 | NAT 空闲超时；启用服务端/代理 **Ping-Pong**；客户端勿过早 `close` |
|
||
| LLM 无响应或超时 | `DASHSCOPE_API_KEY`、网络、`LLM_TIMEOUT` |
|
||
| TTS 初始化失败 | `TTS_PROVIDER` 与模型路径、`TTS_VOICE_NAME` 是否匹配 |
|
||
| `flight_intent` 总失败 | 模型输出非严格 JSON 或 `hover` 带非法 `args`；已加强 system prompt；服务端 L1–L3 会拒绝非法体 |
|
||
| Windows 下打印/`run_server` 乱码 | 终端 UTF-8 或 `PYTHONUTF8=1` |
|
||
|
||
### 2.8 自动化测试（可选）
|
||
|
||
仓库 `test/` 下含 WebSocket 冒烟用例；运行前设置环境变量指向已启动的服务（如 `VOICE_TEST_WS_URL`），并安装 `websockets`、`pytest` 等依赖。具体见各测试文件头部说明。
|
||
|
||
---
|
||
|
||
## 3. 版本与维护
|
||
|
||
- **协议**：Cloud Voice Protocol v1.0 (text_uplink)；飞控意图 **Schema version 1**。
|
||
- **文档维护**：协议或 `flight_intent` 变更时，同步更新 `FLIGHT_INTENT_SCHEMA_v1.md`、`API_SPECIFICATION.md` 与本手册相关小节。
|
||
|
||
---
|
||
|
||
**文档版本**：2026-04-07；与当前仓库 `app/` 实现及 `docs` 内协议描述对齐。
|