# 无人机自然语言控制项目 (DronePlanning)

本项目提供一个基于 `FastAPI + LLM + RAG` 的无人机任务规划后端。输入自然语言指令，输出严格 JSON 的行为树计划（`py_tree`）。

> 当前版本已与 ROS2 解耦。  
> 推荐直接使用 `start_all.sh` / `start_all_vllm.sh` 启动。

## 1. 当前代码结构

```text
backend_service/src/
├── main.py
├── py_tree_generator.py
├── models.py
├── websocket_manager.py
├── pipeline/        # 编排层（stage1~stage4）
├── llm/             # 模型网关/响应解析/工具运行时
├── retrieval/       # 多知识库检索（Location/Pattern/Rules）
├── prompting/       # prompt manifest + 动态注入
├── validation/      # schema provider + validator
├── prompts/
└── tools/
```

## 2. 环境准备（完整命令）

在项目根目录执行：

```bash
cd /home/huangfukk/DronePlanning

# 1) 创建并激活 venv
python3 -m venv backend_service/venv
source backend_service/venv/bin/activate

# 2) 安装依赖
pip install -r backend_service/requirements.txt

# 3) 可选：设置设备地址（本地默认 localhost）
export ORIN_IP="localhost"
```

## 3. 启动服务（推荐）

### 3.1 llama.cpp 路线

```bash
cd /home/huangfukk/DronePlanning
./start_all.sh start
```

常用命令：

```bash
./start_all.sh stop
./start_all.sh restart
./start_all.sh vl
./start_all.sh restart-vl
./start_all.sh status
```

### 3.2 vLLM 路线

```bash
cd /home/huangfukk/DronePlanning
./start_all_vllm.sh start
```

常用命令：

```bash
./start_all_vllm.sh stop
./start_all_vllm.sh restart
./start_all_vllm.sh status
```

## 4. 构建与入库（RAG）

```bash
cd /home/huangfukk/DronePlanning
source backend_service/venv/bin/activate

# 1) 从 map 生成知识文本（可选，已有知识可跳过）
python tools/rag/build_knowledge_base.py

# 2) 入库到 ChromaDB（Location/Pattern/Rules + 兼容集合）
python tools/rag/ingest.py
```

> 运行 `ingest.py` 前，请确保 embedding 服务（8090）已启动。

## 5. 快速接口验证

```bash
cd /home/huangfukk/DronePlanning

# 健康检查
curl -s http://localhost:8000/docs >/dev/null && echo "fastapi ok"
curl -s http://localhost:8081/v1/models && echo "llm ok"

# 生成计划
curl -s http://localhost:8000/generate_plan \
  -H "Content-Type: application/json" \
  -d '{"user_prompt":"无人机当前在地面，到广场查找绿色公交车，找到就拍照"}'
```

## 6. 测试命令

```bash
cd /home/huangfukk/DronePlanning
source backend_service/venv/bin/activate

# API 回归
python tools/test_api.py

# 直接测试 8081 的 OpenAI 兼容推理接口
python tools/test_llama_server.py \
  --system-file backend_service/src/prompts/system_prompt_vllm.txt \
  --user "起飞到10米然后降落" \
  --base-url "http://127.0.0.1:8081/v1" \
  --verbose

# 交互式/批量验证
python tools/test_validate/run_tests.py
```

## 7. 关键 API

- `POST /generate_plan`
- `POST /execute_mission`（当前返回 execution_disabled）
- `WS /ws/status`
- `GET /static/py_tree.png`

## 8. 日志与排障

```bash
cd /home/huangfukk/DronePlanning
tail -f logs/*.log
```

常见日志：

- `logs/inference_model.log`（llama.cpp 推理）
- `logs/vllm_inference_model.log`（vLLM 推理）
- `logs/embedding_model.log`
- `logs/fastapi.log`

如果 `tools/rag/ingest.py` 在 Chroma 初始化时报错，优先确认：

1. 是否使用项目 venv 运行  
2. `tools/rag/vector_store/` 是否损坏（可备份后重建）  
3. embedding 服务是否可访问（`http://localhost:8090/v1/embeddings`）