265 lines
10 KiB
Markdown
265 lines
10 KiB
Markdown
# 无人机行为规划后端系统（重建版）需求说明
|
||
|
||
> 目标：基于端侧 Qwen3-4B（llama-server）和行为树，重建一个从自然语言到无人机行为树 JSON 的后端系统，支持未来扩展 RAG 和动态语义地图。
|
||
|
||
## 一、总体架构理念（务必遵守）
|
||
|
||
1. **大小脑解耦**
|
||
- 大模型（4B，小模型） = 「大脑」：只做语义理解、意图拆解、行为树结构生成，不直接管起飞/降落/避障。
|
||
- Python + py_trees + PX4/仿真 = 「小脑」：负责状态机管理、物理安全、控制执行（起飞、悬停、返航等）。
|
||
|
||
2. **四层流水线结构**
|
||
|
||
- 🔴 Layer 0：感知层（Perception & State）
|
||
纯代码。维护一个全局状态黑板 `DroneStateBlackboard`，至少包含：
|
||
- `is_in_air: bool`
|
||
- `position: {x, y, z}`（ENU）
|
||
- 后续可扩展电量、模式等。
|
||
|
||
- 🟡 Layer 1：意图路由层（Stage 1 Intent Router）
|
||
调用 LLM 做**极简意图分类和实体抽取**，只输出：
|
||
- `intents: list[str]`
|
||
- `entities: dict`
|
||
并实现 **Fast-Path 短路机制**：
|
||
- 若指令是纯原子控制（如“起飞”、“降落”、“悬停”），直接由代码执行，不进入规划阶段。
|
||
|
||
- 🟢 Layer 2：动态组装与外部计算（Dynamic Composer & MCP/RAG）
|
||
纯代码。
|
||
- 根据 `intents` 和 `entities`，从本地 `node_schema.json` 裁剪出**最小必要的节点定义**（行为树节点）。
|
||
- 使用工具（后续接 RAG）解析地点到坐标（ENU），大模型不做算术。
|
||
- 生成发给 Stage 2 LLM 的 **精简 System Prompt**。
|
||
|
||
- 🔵 Layer 3：宏观行为规划（Stage 2 Macro Planner）
|
||
调用 LLM（Qwen3-4B）：
|
||
- 输入：Layer 2 生成的 System Prompt + 用户原文（含 RAG 上下文）。
|
||
- 输出：业务行为树 JSON（**不包含起飞/降落**）。
|
||
|
||
- 🟣 Layer 4：执行包装与安全逻辑（Execution Wrapper）
|
||
纯代码 + py_trees：
|
||
- 将业务树解析为 py_trees 对象。
|
||
- 如果 `is_in_air == False`，自动在业务树前面**插入 `[SystemCheck -> Takeoff]` 子树**。
|
||
- 提供 tick 循环和未来的中断（用户打断、动态重规划）预留。
|
||
|
||
---
|
||
|
||
## 二、节点定义（给 LLM 的行为树节点池）
|
||
|
||
请在 `config/node_schema.json` 定义一个简洁的行为节点池（LLM 可见的动作），结构类似：
|
||
|
||
```json
|
||
{
|
||
"_instruction": "作为行为树规划器，你只能使用以下定义的节点和参数。",
|
||
"actions": {
|
||
"fly_to_waypoint": { "desc": "...", "params": { "x": "float", "y": "float", "z": "float" } },
|
||
"fly_sequence": { "desc": "...", "params": { "waypoints": "array of {x,y,z}" } },
|
||
"move_direction": { "desc": "...", "params": { "direction": "front|back|left|right|up|down", "distance": "float" } },
|
||
"search_pattern": { "desc": "...", "params": { "pattern_type": "spiral|grid", "radius": "float", "target_class": "string" } },
|
||
"rotate_search": { "desc": "...", "params": { "target_class": "string" } },
|
||
"track_object": { "desc": "...", "params": { "target_class": "string", "track_time": "float" } },
|
||
"take_photos": { "desc": "...", "params": { "target_class": "string", "count": "int" } },
|
||
"report_message": { "desc": "...", "params": { "message": "string" } },
|
||
"manual_confirmation": { "desc": "...", "params": { "prompt_message": "string" } }
|
||
},
|
||
"conditions": {
|
||
"object_detected": { "desc": "...", "params": { "target_class": "string" } }
|
||
},
|
||
"control_flow": {
|
||
"Sequence": { "desc": "...", "params": {}, "requires_children": true },
|
||
"Selector": { "desc": "...", "params": {}, "requires_children": true },
|
||
"Parallel": { "desc": "...", "params": { "policy": "success_on_one|success_on_all" }, "requires_children": true }
|
||
},
|
||
"decorators": {
|
||
"Timeout": { "desc": "...", "params": { "max_time": "float" }, "requires_child": true },
|
||
"Repeat": { "desc": "...", "params": { "times": "int" }, "requires_child": true }
|
||
}
|
||
}
|
||
```
|
||
|
||
> 注意：**起飞/降落等底层动作不要出现在这里**，由 Layer 4 包装硬编码处理。
|
||
|
||
---
|
||
|
||
## 三、Stage 1 Intent Router 的设计（重点）
|
||
|
||
### 1. LLM 提示词（Router System Prompt）
|
||
|
||
要求使用简洁、正交的 Intent 集合（避免同义词过多）：
|
||
|
||
- 原子意图（Atomic Intents）：仅用于 Fast-Path
|
||
- `atomic_takeoff`
|
||
- `atomic_land`
|
||
- `atomic_hover`
|
||
|
||
- 业务意图（Business Intents）
|
||
- `fly_task`：所有涉及空间移动/路径/巡逻
|
||
- `search_task`：搜索/侦查
|
||
- `track_task`：跟踪
|
||
- `photo_task`：拍照
|
||
- `interact_task`：上报/请求确认
|
||
|
||
**实体提取要求：**
|
||
|
||
- 地点实体统一用 `"locations"`，且必须为列表：
|
||
- `{"locations": ["大门"]}`
|
||
- `{"locations": ["大门", "广场"]}`（支持“先去A再去B”）
|
||
|
||
- 目标实体用 `"targets"` 列表：
|
||
- `{"targets": ["汽车", "行人"]}`
|
||
|
||
- 其他参数如 `"direction"`, `"distance"` 直接提取。
|
||
|
||
### 2. Python 层的“硬编码冲突处理”逻辑
|
||
|
||
在 `pipeline/router.py` 中：
|
||
|
||
- 定义集合：
|
||
|
||
```python
|
||
ATOMIC_INTENTS = {"atomic_takeoff", "atomic_land", "atomic_hover"}
|
||
BUSINESS_INTENTS = {"fly_task", "search_task", "track_task", "photo_task", "interact_task"}
|
||
```
|
||
|
||
- 处理流程：
|
||
|
||
- 若 `intents` 非空且 **全部属于 ATOMIC_INTENTS**：
|
||
→ 允许 Fast-Path（直接执行原子命令）。
|
||
|
||
- 若 `intents` 同时包含 atomic 和 business（如 `["atomic_takeoff", "fly_task"]`）：
|
||
→ **删除所有 atomic**，仅保留 business，走正常规划（起飞由 Layer 4 自动包装）。
|
||
|
||
- 若 `intents` 为空或包含未识别标签（小模型幻觉）：
|
||
→ 兜底为 `["fly_task", "search_task"]`，保证系统不崩。
|
||
|
||
---
|
||
|
||
## 四、RAG 模块设计（Layer 2 可选扩展）
|
||
|
||
### 1. 目录结构
|
||
|
||
`src/drone_planning/rag/`：
|
||
|
||
- `embedding_client.py`：封装 Qwen Embedding（llama-server 8090）。
|
||
- `vector_store.py`：ChromaDB 客户端，管理三个 Collection：
|
||
- `map_db`
|
||
- `rule_db`
|
||
- `few_shot_db`
|
||
- `retriever.py`：`RAGRetriever`：
|
||
- `dynamic_memory`：热数据表占位（未来语义地图）。
|
||
- `retrieve_context(intents, entities, user_text) -> dict`
|
||
- `ingestion.py`：从 `data/knowledge/*.jsonl` 读 NDJSON 灌入 ChromaDB。
|
||
- `schemas.py`（可选）：约定 JSONL 字段结构。
|
||
|
||
### 2. JSONL 格式约定（统一用 `.jsonl`，一行一 JSON）
|
||
|
||
- `data/knowledge/map_db.jsonl`：
|
||
|
||
```json
|
||
{"document": "喷泉在广场正中央，坐标 x=10, y=20", "location": "喷泉", "x": 10, "y": 20, "z": 0}
|
||
{"document": "A区是禁飞区，不得进入", "location": "A区", "zone_type": "no_fly"}
|
||
```
|
||
|
||
- `data/knowledge/rule_db.jsonl`：
|
||
|
||
```json
|
||
{"document": "夜间巡逻必须开启热成像", "intent": "search_task", "scene": "night"}
|
||
{"document": "起飞必须先做系统检查", "intent": "fly_task", "priority": "high"}
|
||
```
|
||
|
||
- `data/knowledge/few_shot_db.jsonl`：
|
||
|
||
```json
|
||
{"document": "飞到大门然后拍照", "intent": "fly_task", "tree_json": "{\"root\": {...}}"}
|
||
```
|
||
|
||
### 3. 检索策略（在 `retriever.py`）
|
||
|
||
- 热数据优先（Dynamic Semantic Map）：
|
||
- `dynamic_memory = {"locations": {...}, "targets": {...}}`
|
||
- 若某 location 在热内存中有坐标，直接返回，**不要查 ChromaDB**。
|
||
|
||
- 冷库次之（ChromaDB）：
|
||
- 根据 `entities["locations"]` 和 `intents` 用 metadata + 向量检索，从 `map_db` 和 `rule_db` 获取上下文。
|
||
- 使用 `user_text` 在 `few_shot_db` 中查 1–2 个相似任务的行为树，作为 few-shot 示例。
|
||
|
||
RAG 返回统一结构：
|
||
|
||
```python
|
||
{
|
||
"map_context": "若干行文本或结构化信息",
|
||
"rule_context": "规则文本汇总",
|
||
"few_shot_examples": [
|
||
{"instruction": "...", "tree_json": {...}},
|
||
...
|
||
]
|
||
}
|
||
```
|
||
|
||
### 4. 与 Composer 集成（`pipeline/composer.py`）
|
||
|
||
- 为 `build_system_prompt(...)` 增加参数 `rag_context: dict | None`。
|
||
- 在 Prompt 中插入三个区块（若非空）：
|
||
- `## RAG 地图上下文`
|
||
- `## RAG 规则约束`
|
||
- `## RAG 示例行为树`
|
||
|
||
- 坐标解析优先级：
|
||
1. 动态内存（语义地图，未来接入）。
|
||
2. RAG 地图（map_db 的 x,y,z）。
|
||
3. geo.py 的硬编码 `landmark_to_enu()`（兜底，不删除，作为最后一层 fallback）。
|
||
|
||
---
|
||
|
||
## 五、执行包装层（Layer 4，`execution`）
|
||
|
||
### 1. 行为节点实现（`execution/nodes.py`）
|
||
|
||
实现继承自 `py_trees.behaviour.Behaviour` 的 Mock 节点：
|
||
|
||
- `SystemCheckCondition`
|
||
- `TakeoffAction`
|
||
- `LandAction`
|
||
- `FlyToWaypointAction`
|
||
- `GenericAction`（兜底）
|
||
|
||
目前只打印日志并返回 `SUCCESS`，后续预留 ROS2/PX4 接口。
|
||
|
||
### 2. 树包装与 Tick 循环（`execution/tree_wrapper.py`）
|
||
|
||
- `parse_json_to_tree(node_dict)`：递归将 Planner 的 JSON 转换为 py_trees 树。
|
||
- `wrap_and_build_tree(business_tree)`：
|
||
- 读取 `DroneStateBlackboard.is_in_air`：
|
||
- 若 `False`：创建 `Sequence("Safe_Execution")`，依次添加：
|
||
- `SystemCheckCondition()`
|
||
- `TakeoffAction()`
|
||
- `business_tree`
|
||
- 若 `True`：直接返回 `business_tree`。
|
||
|
||
---
|
||
|
||
## 六、API 接口与 Orchestrator
|
||
|
||
- 使用 FastAPI 暴露 `POST /api/plan`：
|
||
- 输入：`{"text": "用户自然语言指令"}`。
|
||
- 调用顺序：
|
||
1. Layer 1 Router：若 Fast-Path，直接返回执行结果。
|
||
2. 否则，调用 RAG → Composer → Planner → Tree Wrapper，返回行为树 JSON 和日志。
|
||
|
||
---
|
||
|
||
## 七、请 Cursor 的工作顺序建议
|
||
|
||
1. 生成项目目录和基础依赖（`requirements.txt`，`pyproject.toml`）。
|
||
2. 实现：
|
||
- `core/blackboard.py`
|
||
- `llm_client/client.py`（指向 `http://localhost:8080/v1` for chat，`http://localhost:8090/v1` for embeddings 可在 embedding_client 中配置）
|
||
3. 实现 `config/node_schema.json`。
|
||
4. 实现 `pipeline/router.py`（含 intents/entities 提取与 Fast-Path 短路 + 冲突处理）。
|
||
5. 实现 `tools/geo.py`（仅作为 fallback 静态坐标表）。
|
||
6. 实现 `rag/*`（embedding_client, vector_store, ingestion, retriever）。
|
||
7. 实现 `pipeline/composer.py` 和 `pipeline/planner.py`（加入 rag_context）。
|
||
8. 实现 `execution/nodes.py` 和 `execution/tree_wrapper.py`。
|
||
9. 实现 `api/routes.py` 和 `main.py`。
|
||
10. 最后补充简单的 `tests/` 或手动 curl 示例。
|
||
|
||
请从目录结构 + 模块职责开始规划，确认后再逐步生成代码。
|
||
``` |