149 lines
8.6 KiB
Markdown
149 lines
8.6 KiB
Markdown
# voice_drone_assistant — 项目说明与配置指南
|
||
|
||
面向部署与二次开发：**目录结构**、**配置文件用法**、**启动与日常操作**、**与云端/飞控的关系**。**外场统一部署与双终端启动顺序**见 **`docs/DEPLOYMENT_AND_OPERATIONS.md`**；协议细节以 `docs/llmcon.md` 为准。
|
||
|
||
---
|
||
|
||
## 1. 项目做什么
|
||
|
||
- **麦克风** → 预处理（降噪/AGC）→ **VAD 切段** → **SenseVoice STT** → **唤醒词**
|
||
- **关键词起飞（offboard 演示，默认关闭）**：`system.yaml` → **`assistant.local_keyword_takeoff_enabled`** 或 **`ROCKET_LOCAL_KEYWORD_TAKEOFF=1`** 开启后，`keywords.yaml` 里 **`takeoff` 词表**（如「起飞演示」）→ 提示音 + offboard 脚本；飞控主路径推荐 **云端 `flight_intent` + ROS 伴飞桥**
|
||
- **其它语音**：本地 **Qwen + Kokoro**，或 **云端 WebSocket**（LLM + TTS 上云，见 `cloud_voice`）
|
||
- 可选通过 **TCP Socket** 下发结构化飞控命令（`VoiceCommandRecognizer` 路径；`TakeoffPrintRecognizer` 默认不在启动时连 Socket，飞控多为云端 JSON + 可选 `ROCKET_CLOUD_EXECUTE_FLIGHT`）
|
||
|
||
---
|
||
|
||
## 2. 目录结构（仓库根 = `voice_drone_assistant/`）
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `main.py` | 程序入口（会 `chdir` 到本目录并跑 `voice_drone.main_app`） |
|
||
| `with_system_alsa.sh` | 在 Conda/残缺 ALSA 环境下修正 `LD_LIBRARY_PATH`，建议始终包一层启动 |
|
||
| `requirements.txt` | Python 依赖（含 `websocket-client` 等） |
|
||
| **`voice_drone/main_app.py`** | 主流程：唤醒、问候/快路径、关麦、LLM/云端、TTS、offboard |
|
||
| **`voice_drone/core/`** | 音频采集、预处理、VAD、STT、TTS、Socket、云端 WS、唤醒、命令、文本预处理、配置加载 |
|
||
| **`voice_drone/flight_bridge/`** | 伴飞桥（ROS1+MAVROS）：`flight_intent` → 飞控；说明见 **`docs/FLIGHT_BRIDGE_ROS1.md`** |
|
||
| **`voice_drone/config/`** | 各类 YAML，见下文「配置文件」 |
|
||
| **`voice_drone/logging_/`** | 日志与彩色输出 |
|
||
| **`voice_drone/tools/`** | `config_loader` 等工具 |
|
||
| **`docs/`** | `PROJECT_GUIDE.md`（本文）、`llmcon.md`（云端协议）、`clientguide.md`（联调与示例） |
|
||
| **`scripts/`** | `run_px4_offboard_one_terminal.sh`；**伴飞桥** `run_flight_bridge_with_mavros.sh`（含 MAVROS）、`run_flight_intent_bridge_ros1.sh`（仅桥）；另有 `generate_wake_greeting_wav.py`、`bundle_for_device.sh` |
|
||
| **`assets/tts_cache/`** | 唤醒问候等预生成 WAV（可自动生成） |
|
||
| **`models/`** | STT/TTS/VAD ONNX 等（需自备或 bundle，见 `models/README.txt`） |
|
||
|
||
---
|
||
|
||
## 3. 配置文件一览
|
||
|
||
配置由 `voice_drone/core/configuration.py` 在进程启动时读入；主文件为 **`voice_drone/config/system.yaml`**（路径相对 **`voice_drone_assistant` 根目录**）。
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| **`system.yaml`** | **总控**：`audio`（采样、设备、AGC、降噪）、`vad`、`stt`、`tts`、`cloud_voice`、`socket_server`、`text_preprocessor`、`recognizer`（VAD 能量门槛、尾静音、问候/TTS 关麦等） |
|
||
| **`wake_word.yaml`** | 唤醒词主词、变体、模糊/部分匹配策略 |
|
||
| **`keywords.yaml`** | 命令关键词与同义词（供文本预处理映射到 `Command`） |
|
||
| **`command_.yaml`** | 各飞行动作默认 `distance/speed/duration`（与 `Command` 联动） |
|
||
| **`cloud_voice_px4_context.yaml`** | 云端 **`session.start.client` 扩展**：`vehicle_class`、`mav_type`、`default_setpoint_frame`、`extras` 等，供服务端 LLM 生成 PX4 相关指令；路径在 `system.yaml` → `cloud_voice.px4_context_file`，也可用环境变量 **`ROCKET_CLOUD_PX4_CONTEXT_FILE`** 覆盖 |
|
||
|
||
修改 YAML 后需**重启** `main.py` 生效（`SYSTEM_CLOUD_VOICE_PX4_CONTEXT` 等在 import 时加载一次）。
|
||
|
||
---
|
||
|
||
## 4. `system.yaml` 常用区块（索引）
|
||
|
||
- **`audio`**：采样率、`frame_size`、`input_device_index`（`null` 则枚举设备）、`prefer_stereo_capture`（ES8388 等）、`noise_reduce`、`agc*`、`agc_release_alpha`
|
||
- **`vad`**：Silero 用阈值、`end_frame` 等（能量 VAD 时部分由 `recognizer` 覆盖）
|
||
- **`stt`**：SenseVoice 模型路径、ORT 线程等
|
||
- **`tts`**：Kokoro 目录、音色 `voice`、`speed`、`output_device`、`playback_*`
|
||
- **`cloud_voice`**：`enabled`、`server_url`、`auth_token`、`device_id`、`timeout`、`fallback_to_local`、`px4_context_file`
|
||
- **`socket_server`**：试飞控 TCP 地址、`reconnect_interval`、`max_retries`（`-1` 为断线持续重连直至成功）
|
||
- **`recognizer`**：`trailing_silence_seconds`、`vad_backend`（`energy`/`silero`）、`energy_vad_*`、`energy_vad_utt_peak_decay`、`energy_vad_end_peak_ratio`、`pre_speech_max_seconds`、`ack_pause_mic_for_playback`、应答 TTS 等
|
||
|
||
更细的参数含义以各 YAML 内注释为准。
|
||
|
||
---
|
||
|
||
## 5. 系统使用方式
|
||
|
||
### 5.1 推荐启动命令
|
||
|
||
在 **`voice_drone_assistant` 根目录**：
|
||
|
||
```bash
|
||
bash with_system_alsa.sh python main.py
|
||
```
|
||
|
||
或使用模块方式：
|
||
|
||
```bash
|
||
bash with_system_alsa.sh python -m voice_drone.main_app
|
||
```
|
||
|
||
录音设备：**首次**可交互选择；非交互时可设 `ROCKET_INPUT_DEVICE_INDEX` 或使用 `main.py --input-index N` / `--non-interactive`（详见 `main_app` 内 `argparse` 与文件头注释）。
|
||
|
||
### 5.2 典型工作流（默认 `TakeoffPrintRecognizer`）
|
||
|
||
1. 说唤醒词（如「无人机」）；若**同句带指令**，会**跳过问候与滴声**，直接关麦处理：命中 `keywords.yaml` 的 **takeoff** 则 offboard，否则走 LLM/云端。
|
||
2. 若**只唤醒**，则问候（或缓存 WAV）+ 可选滴声 → 再说**一句**指令。
|
||
3. 云端模式：指令以文本上云，TTS 多为服务端 PCM；本地模式：Qwen 推理 + Kokoro 播报。
|
||
|
||
### 5.3 云端语音（可选）
|
||
|
||
- `system.yaml` 里 `cloud_voice.enabled: true`，或环境变量 **`ROCKET_CLOUD_VOICE=1`**
|
||
- **`ROCKET_CLOUD_WS_URL`**、`ROCKET_CLOUD_AUTH_TOKEN`、可选 **`ROCKET_CLOUD_DEVICE_ID`**（可覆盖 yaml）
|
||
- PX4 语境：见 `cloud_voice_px4_context.yaml` / **`ROCKET_CLOUD_PX4_CONTEXT_FILE`**
|
||
- 协议与消息类型： **`docs/llmcon.md`**
|
||
- 飞控 JSON 是否机端执行： **`ROCKET_CLOUD_EXECUTE_FLIGHT=1`**；走 ROS 伴飞桥时再设 **`ROCKET_FLIGHT_INTENT_ROS_BRIDGE=1`**（详见 **`docs/DEPLOYMENT_AND_OPERATIONS.md`**）
|
||
|
||
### 5.4 本地大模型与 TTS
|
||
|
||
- GGUF：`cache/` 默认路径或 **`ROCKET_LLM_GGUF`**
|
||
- 关闭对话：**`ROCKET_LLM_DISABLE=1`**
|
||
- 流式输出：**`ROCKET_LLM_STREAM=0`** 可改为整段生成后再播（调试）
|
||
- 详细列表见 **`voice_drone/main_app.py` 文件头部注释**。
|
||
|
||
### 5.5 其它实用环境变量（摘录）
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `ROCKET_ENERGY_VAD` | `1` 时使用能量 VAD（板载麦常见） |
|
||
| `ROCKET_PRINT_STT` / `ROCKET_PRINT_VAD` | 终端打印 STT/VAD 诊断 |
|
||
| `ROCKET_CLOUD_TURN_RETRIES` | 云端 WS 单轮失败重连重试次数（默认 3） |
|
||
| `ROCKET_PRINT_LLM_STREAM` | 云端流式字 `llm.text_delta` 打印到终端 |
|
||
| `ROCKET_WAKE_PROMPT_BEEP` | `0` 关闭问候后滴声 |
|
||
| `ROCKET_MIC_RESTART_SETTLE_MS` | 播完 TTS 恢复麦克风后的等待毫秒 |
|
||
|
||
---
|
||
|
||
## 6. 相关文档与代码入口
|
||
|
||
| 文档 | 内容 |
|
||
|------|------|
|
||
| **`README.md`** | 简版说明、bundle 到香橙派、与原仓库关系 |
|
||
| **`docs/DEPLOYMENT_AND_OPERATIONS.md`** | **部署与外场启动**：拓扑、`ROS_MASTER_URI`、双终端启动顺序、环境变量速查、联调 |
|
||
| **`docs/PROJECT_GUIDE.md`** | 本文：目录、配置、使用方式总览 |
|
||
| **`docs/FLIGHT_BRIDGE_ROS1.md`** | ROS1 伴飞桥、MAVROS、`/input`、`rostopic pub` |
|
||
| **`docs/llmcon.md`** | 云端 WebSocket 消息类型与客户端约定 |
|
||
| **`docs/CLOUD_VOICE_FLIGHT_CONFIRM_v1.md`** | 云端 **`dialog_result` v1**（`protocol=cloud_voice_dialog_v1`，闲聊/飞控分流 + `confirm`） |
|
||
|
||
| 能力 | 主要代码 |
|
||
|------|-----------|
|
||
| 音频采集/AGC | `voice_drone/core/audio.py` |
|
||
| 能量/Silero VAD | `voice_drone/core/recognizer.py`、`voice_drone/core/vad.py` |
|
||
| STT | `voice_drone/core/stt.py` |
|
||
| 本地 LLM 提示词 | `voice_drone/core/qwen_intent_chat.py`（`FLIGHT_INTENT_CHAT_SYSTEM`） |
|
||
| 云端会话 | `voice_drone/core/cloud_voice_client.py` |
|
||
| 主流程 | `voice_drone/main_app.py` |
|
||
| 配置聚合 | `voice_drone/core/configuration.py` |
|
||
|
||
---
|
||
|
||
## 7. 版本与维护
|
||
|
||
- 配置项会随功能迭代增加；若与运行日志或 `llmcon` 不一致，以**当前仓库 YAML + 代码**为准。
|
||
- 新增仅与云端相关的字段时，请同时通知服务端解析 **`session.start.client`**（含 PX4 扩展块）。
|
||
|
||
---
|
||
|
||
*文档版本：与仓库同步维护；更新日期见 Git 提交。*
|