AI重构

tools/rag/README.md

@@ -1,39 +1,62 @@
-# RAG & Map Tools
+# RAG 工具说明
 
-该目录包含了地图构建、知识库生成和向量数据库管理的相关工具。
+该目录负责知识构建与向量入库。
 
 ## 目录结构
 
-- **knowledge_base/**: 存放源文档数据。
-  - 支持格式: `.txt`, `.md`, `.pdf`
-  - 生成格式: `.json`, `.ndjson` (由 `build_knowledge_base.py` 生成)
-  
-- **map/**: 存放地图原始数据。
-  - `.osm` (OpenStreetMap 数据)
-  - `.world` (Gazebo 仿真环境数据)
-  
-- **vector_store/**: ChromaDB 向量数据库的持久化存储目录。
-
-## 脚本说明
-
-### 1. `build_knowledge_base.py`
-**功能**: 处理 `map/` 目录下的地图文件，提取地理信息和语义描述，生成知识库文件到 `knowledge_base/` 目录。
-**使用方法**:
-```bash
-python build_knowledge_base.py
+```text
+tools/rag/
+├── map/                     # 原始地图数据
+├── knowledge_base/
+│   ├── location/            # 地点知识（可选分目录）
+│   ├── pattern/             # 模式知识（任务模板）
+│   ├── rules/               # 规则知识
+│   └── *.ndjson
+├── vector_store/            # Chroma 持久化目录
+├── build_knowledge_base.py  # 从 map 构建 ndjson
+└── ingest.py                # 入库到 Chroma（多集合 + 兼容集合）
 ```
 
-### 2. `ingest.py`
-**功能**: 读取 `knowledge_base/` 中的所有文档，调用嵌入模型（Embedding Model）将其向量化，并存入 `vector_store/` 中的 ChromaDB 数据库。
-**使用方法**:
+## 运行前准备
+
 ```bash
-python ingest.py
+cd /home/huangfukk/DronePlanning
+source backend_service/venv/bin/activate
+export ORIN_IP="localhost"
 ```
-**依赖**: 需要确保后端嵌入服务（如 `llama-server`）已启动，或者配置正确的 `ORIN_IP` 环境变量。
 
-## 工作流
-1. 将地图文件放入 `map/`。
-2. 运行 `build_knowledge_base.py` 生成文本描述。
-3. 将其他补充文档放入 `knowledge_base/`。
-4. 运行 `ingest.py` 构建向量索引。
+并确保 embedding 服务可用（默认 `8090`）：
+
+```bash
+curl -s http://localhost:8090/v1/embeddings \
+  -H "Content-Type: application/json" \
+  -d '{"input":["test"]}'
+```
+
+## 完整流程（可直接执行）
+
+```bash
+cd /home/huangfukk/DronePlanning
+source backend_service/venv/bin/activate
+
+# 1) 由 map 构建知识文本
+python tools/rag/build_knowledge_base.py
+
+# 2) 入库
+python tools/rag/ingest.py
+```
+
+## 入库结果
+
+`ingest.py` 会同时写入：
+
+- 兼容集合：`drone_docs`
+- 新集合：`location_kb`、`pattern_kb`、`rules_kb`
+
+并在 metadata 中写入 `kb_type`，支持检索时按知识域筛选。
+
+## 常见问题
+
+- **Chroma 初始化异常**：先确认使用的是项目 venv，再检查 `tools/rag/vector_store/` 是否损坏（备份后重建）。
+- **连接 embedding 失败**：检查 `ORIN_IP`、端口 8090、以及模型服务是否已启动。