DronePlanningV2/README.md

无人机行为规划后端系统

从自然语言指令到行为树 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. 克隆与依赖

cd DronePlanningV2
pip install -e .
# 或
pip install -r requirements.txt

2. 配置 LLM 服务

确保 Chat 和 Embedding 服务已启动。可通过环境变量覆盖默认地址：

export LLM_CHAT_BASE_URL="http://localhost:8081/v1"
export LLM_EMBEDDING_BASE_URL="http://localhost:8090/v1"
export OPENAI_API_KEY="not-needed"   # 本地部署通常不需要

可选：开启模型思考模式（默认关闭以降低延迟）：

export ENABLE_THINKING=true

3. RAG 知识库灌入

必须先启动 Embedding 服务（默认 http://localhost:8090/v1）。灌入会向该地址请求向量；未启动会出现 Connection refused。可与 Chat 一并启动：

bash run_api.sh   # 含 8081 Chat + 8090 Embedding，待终端出现 listening 后再灌入

包位于 src/ 下，灌入命令任选其一：

# 方式 A：已执行 pip install -e . 时
python -m drone_planning.rag.ingestion

# 方式 B：未安装包时，需指定 PYTHONPATH（与 run_api.sh 一致）
PYTHONPATH=src python -m drone_planning.rag.ingestion

Embedding 地址可通过环境变量覆盖：export LLM_EMBEDDING_BASE_URL=http://主机:端口/v1

知识库文件位于 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 服务

项目根目录下需让 Python 能找到 src/drone_planning（已 pip install -e . 可省略）：

PYTHONPATH=src python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

5. 启动 Playground 测试台

streamlit run playground.py

使用方式

API 调用

# 复杂任务（走完整流水线）
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）：

{
  "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

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