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

Made-with: Cursor

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

8.3 KiB

Raw Permalink Blame History

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 级）

cd /path/to/voicellmcloud
python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate
pip install -r requirements.txt

使用 Piper 时需额外安装语音推理库（若未记入 requirements.txt）：

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 保活）：

# 在项目根目录执行
python scripts/run_server.py

scripts/run_server.py 使用 settings.WS_HOST / settings.WS_PORT，与 .env 对齐。

标准 Uvicorn（可配合 systemd / Docker CMD）：

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=...) 的封装启动，或在前置代理上保持连接活跃。

开发加載：

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 生产部署要点

进程管理：systemd、supervisor 或 Kubernetes Deployment；崩溃自拉起；限制文件句柄与内存。
TLS：公网场景在入口使用 WSS（Nginx / Caddy / 云 LB 终结 TLS），后端仍可为 ws://127.0.0.1:端口。
日志：当前主用 loguru stderr；可接入集中日志；注意勿在日志中打印完整 Token 或用户隐私。
横向扩展：有状态会话绑定单机 WebSocket 连接；多实例时需 会话粘性 或改为共享后端架构（超出本仓库默认范围）。
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 内协议描述对齐。

8.3 KiB Raw Permalink Blame History Unescape Escape