Initial commit: 无人机行为规划后端系统
Made-with: Cursor
This commit is contained in:
181
README.md
Normal file
181
README.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# 无人机行为规划后端系统
|
||||
|
||||
从自然语言指令到行为树 JSON 的四层流水线系统，支持 RAG 检索、Function Calling 坐标计算、Fast-Path 短路等能力。
|
||||
|
||||
## 功能概览
|
||||
|
||||
- **Layer 1 (Router)**：意图分类与实体抽取，支持原子指令（起飞/降落/悬停）Fast-Path 短路
|
||||
- **RAG 检索**：地图基准点坐标、规则约束、Few-shot 示例（不负责相对坐标计算）
|
||||
- **Layer 2 (Composer)**：根据意图裁剪 schema，组装精简 System Prompt
|
||||
- **Layer 3 (Planner)**：LLM 生成行为树 JSON，**仅 LLM 通过 mcp 工具计算坐标**（绝对地点用 base_location_coords，相对位置必须调用工具，禁止心算）
|
||||
- **Layer 4 (Execution)**：解析 JSON 为 py_trees，根据 `is_in_air` 自动插入起飞逻辑
|
||||
|
||||
## 环境要求
|
||||
|
||||
- Python 3.10+
|
||||
- 本地 LLM 服务（llama-server 或兼容 OpenAI API 的服务）：
|
||||
- **Chat**：默认 `http://localhost:8081/v1`
|
||||
- **Embedding**：默认 `http://localhost:8090/v1`（RAG 用）
|
||||
|
||||
## 快速部署
|
||||
|
||||
### 1. 克隆与依赖
|
||||
|
||||
```bash
|
||||
cd DronePlanningV2
|
||||
pip install -e .
|
||||
# 或
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. 配置 LLM 服务
|
||||
|
||||
确保 Chat 和 Embedding 服务已启动。可通过环境变量覆盖默认地址：
|
||||
|
||||
```bash
|
||||
export LLM_CHAT_BASE_URL="http://localhost:8081/v1"
|
||||
export LLM_EMBEDDING_BASE_URL="http://localhost:8090/v1"
|
||||
export OPENAI_API_KEY="not-needed" # 本地部署通常不需要
|
||||
```
|
||||
|
||||
可选：开启模型思考模式（默认关闭以降低延迟）：
|
||||
|
||||
```bash
|
||||
export ENABLE_THINKING=true
|
||||
```
|
||||
|
||||
### 3. RAG 知识库灌入
|
||||
|
||||
首次使用或更新知识库后需执行灌入：
|
||||
|
||||
```bash
|
||||
python -m drone_planning.rag.ingestion
|
||||
```
|
||||
|
||||
知识库文件位于 `data/knowledge/`：
|
||||
|
||||
- `map_db.jsonl`：地点坐标（location, x, y, z）
|
||||
- `rule_db.jsonl`：规则约束（intent, document）
|
||||
- `few_shot_db.jsonl`：Few-shot 示例（instruction, tree_json）
|
||||
|
||||
### 4. 启动 API 服务
|
||||
|
||||
```bash
|
||||
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
### 5. 启动 Playground 测试台
|
||||
|
||||
```bash
|
||||
streamlit run playground.py
|
||||
```
|
||||
|
||||
## 使用方式
|
||||
|
||||
### API 调用
|
||||
|
||||
```bash
|
||||
# 复杂任务（走完整流水线）
|
||||
curl -X POST http://localhost:8000/api/plan \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"text": "飞到大门然后拍照"}'
|
||||
|
||||
# 原子指令（Fast-Path 短路）
|
||||
curl -X POST http://localhost:8000/api/plan \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"text": "起飞"}'
|
||||
|
||||
# 相对描述（RAG 提供基准点，LLM 调用 mcp 计算）
|
||||
curl -X POST http://localhost:8000/api/plan \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"text": "飞到广场东边500米"}'
|
||||
```
|
||||
|
||||
响应示例（含各环节耗时 `timing_ms`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"fast_path": false,
|
||||
"intents": ["fly_task", "photo_task"],
|
||||
"entities": {"locations": ["大门"], "targets": []},
|
||||
"rag_context": {...},
|
||||
"tool_call_log": [...],
|
||||
"tree_json": {"root": {...}},
|
||||
"tree_ascii": "...",
|
||||
"timing_ms": {
|
||||
"Layer1_Router": 120,
|
||||
"RAG_检索": 45,
|
||||
"Layer2_Composer": 2,
|
||||
"Layer3_Planner": 3500,
|
||||
"Layer4_Execution": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Playground 测试
|
||||
|
||||
1. 打开 `http://localhost:8501`
|
||||
2. 左侧边栏：切换「是否在空中」模拟起飞状态
|
||||
3. 主界面：输入自然语言指令，点击「执行规划」
|
||||
4. 查看：各环节耗时、Layer 1~4 输出、RAG 检索结果、LLM Tool Call 日志（坐标仅由 LLM 通过 mcp 计算）
|
||||
|
||||
### 命令行测试 Router
|
||||
|
||||
```bash
|
||||
python -m drone_planning.pipeline.router "飞到大门然后拍照"
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
DronePlanningV2/
|
||||
├── config/
|
||||
│ └── node_schema.json # 行为树节点定义
|
||||
├── data/
|
||||
│ └── knowledge/ # RAG 知识库 jsonl
|
||||
│ ├── map_db.jsonl
|
||||
│ ├── rule_db.jsonl
|
||||
│ └── few_shot_db.jsonl
|
||||
├── src/drone_planning/
|
||||
│ ├── api/ # FastAPI 路由
|
||||
│ ├── core/ # Blackboard 黑板
|
||||
│ ├── execution/ # py_trees 解析与包装
|
||||
│ ├── llm_client/ # Chat / Embedding 客户端
|
||||
│ ├── pipeline/ # Router / Composer / Planner
|
||||
│ ├── rag/ # 向量存储、检索、灌入
|
||||
│ └── tools/ # mcp_calc 坐标计算
|
||||
├── main.py # API 入口
|
||||
├── playground.py # Streamlit 测试台
|
||||
├── requirements.txt
|
||||
└── pyproject.toml
|
||||
```
|
||||
|
||||
## 环境变量汇总
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `LLM_CHAT_BASE_URL` | `http://localhost:8081/v1` | Chat API 地址 |
|
||||
| `LLM_EMBEDDING_BASE_URL` | `http://localhost:8090/v1` | Embedding API 地址 |
|
||||
| `OPENAI_API_KEY` | `not-needed` | API Key |
|
||||
| `ENABLE_THINKING` | `false` | 是否开启模型思考模式 |
|
||||
| `CHROMA_PERSIST_PATH` | `./data/chroma` | ChromaDB 持久化路径 |
|
||||
| `EMBEDDING_MODEL` | `qwen3-embedding` | Embedding 模型名 |
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q: ChromaDB 报错？**
|
||||
A: 确保已安装 `chromadb>=0.4.0`，首次运行需执行 `python -m drone_planning.rag.ingestion`。
|
||||
|
||||
**Q: LLM 调用超时？**
|
||||
A: 检查 `LLM_CHAT_BASE_URL` 是否可达，模型是否支持 `json_schema` / `tools`。
|
||||
|
||||
**Q: 相对坐标未计算？**
|
||||
A: 确保 `map_db.jsonl` 中有基准点（如「广场」），Router 正确抽取 `direction`、`distance`，且 LLM 支持 Function Calling 调用 `calculate_relative_coordinate`。
|
||||
|
||||
**Q: 如何扩展知识库？**
|
||||
A: 编辑 `data/knowledge/*.jsonl` 后重新执行 `python -m drone_planning.rag.ingestion`。
|
||||
|
||||
## 详细流程文档
|
||||
|
||||
完整项目流程、各 Stage 对应代码、RAG 调用、工具调用、提示词组织等详见：[docs/项目流程详解.md](docs/项目流程详解.md)
|
||||
Reference in New Issue
Block a user