# 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` 内协议描述对齐。