ai_agent/CHANGELOG.md

# 项目修改日志 (Changelog)

本文档记录了项目的主要功能修改和代码变更。

## 修改日期
2025-11-24

---

## 一、模型服务器 (Models Server) 修改

### 1.1 文件：`scripts/ai_agent/models/models_server.py`

#### 修改内容：

**1. 配置解析改进**
- **位置**：`get_model_server()` 函数
- **修改**：
  - 修正配置文件路径，使用 `project_root` 变量
  - 添加配置文件读取错误检查（`read_json_file()` 返回 `None` 的情况）
  - 支持 `models_server` 配置为列表或字典两种格式
  - 修复 `global _process_instance` 声明位置（必须在函数开始处）

**2. 消息构建逻辑修复**
- **位置**：`_build_message()` 方法
- **修改**：
  - 修复纯文本和多模态消息格式不一致的问题
  - 纯文本推理：`system_prompt` 和 `user_prompt` 的 `content` 字段为字符串
  - 多模态推理：`system_prompt` 和 `user_prompt` 的 `content` 字段为列表（包含文本和图像对象）
  - 解决了 `TypeError: can only concatenate str (not "list") to str` 错误

**3. JSON Schema 支持**
- **位置**：`text_inference()`, `multimodal_inference()`, `model_inference()` 方法
- **修改**：
  - 添加 `response_format` 参数支持，用于约束模型输出格式
  - 当 `request.json_schema` 存在时，构建 `response_format` 对象传递给 `create_chat_completion`
  - 格式：`{"type": "json_object", "schema": request.json_schema}`

**4. 错误处理增强**
- **位置**：`text_inference()` 方法
- **修改**：
  - 添加 `messages` 为 `None` 的检查
  - 显式设置 `image_data=None` 用于纯文本请求
  - 改进错误日志，使用 `exc_info=True` 记录完整堆栈信息

**5. GPU 日志增强**
- **位置**：`init_vlm_llamacpp()` 方法
- **修改**：
  - 当 `n_gpu_layers > 0` 时，设置 `verbose=True` 以输出 GPU 使用信息
  - 添加 GPU 层数日志输出

**6. 主函数启用**
- **位置**：`main()` 函数
- **修改**：
  - 取消注释 `uvicorn.run()` 调用，使模型服务器可以独立启动

---

### 1.2 文件：`scripts/ai_agent/models/model_definition.py`

#### 修改内容：

**JSON Schema 字段添加**
- **位置**：`TextInferenceRequest` 和 `InferenceRequest` 类
- **修改**：
  - 添加 `json_schema: Optional[Dict[str, Any]] = None` 字段
  - 用于在推理请求中传递 JSON Schema，约束模型输出格式

---

### 1.3 文件：`scripts/ai_agent/models/models_client.py`

#### 修改内容：

**Pydantic 兼容性改进**
- **位置**：`text_inference()` 和 `multimodal_inference()` 方法
- **修改**：
  - 添加 Pydantic v1/v2 兼容的 JSON 序列化逻辑
  - 优先使用 `model_dump_json()` (Pydantic v2)
  - 降级使用 `json()` (Pydantic v1)
  - 最后使用 `dict()`/`model_dump()` + `json.dumps()` 作为兜底方案
  - 解决了 `Object of type TextInferenceRequest is not JSON serializable` 错误

**服务器等待逻辑改进**
- **位置**：`wait_for_server()` 方法
- **修改**：
  - 接受 "loading" 状态作为有效状态
  - 增强连接失败时的错误消息

---

## 二、后端服务 (Backend Service) 修改

### 2.1 文件：`scripts/ai_agent/groundcontrol/backend_service/src/main.py`

#### 修改内容：

**子进程输出处理改进**
- **位置**：`start_model_server()` 函数
- **修改**：
  - 使用线程实时输出模型服务器的 stdout 和 stderr
  - 移除 `bufsize=1` 参数（二进制模式下不支持行缓冲）
  - 解决了 `RuntimeWarning: line buffering (buffering=1) isn't supported in binary mode` 警告

---

### 2.2 文件：`scripts/ai_agent/groundcontrol/backend_service/src/py_tree_generator.py`

#### 修改内容：

**1. RAG 初始化改进**
- **位置**：`__init__()` 方法
- **修改**：
  - 从 `rag_config.json` 读取 RAG 配置
  - 计算 `ai_agent_root` 路径（相对于 `base_dir` 向上三级）
  - 使用配置中的 `vectorstore_persist_directory` 和 `collection_name`
  - 添加向量数据库加载状态日志

**2. JSON Schema 支持**
- **位置**：`generate()` 方法
- **修改**：
  - 分类请求：传递 `classifier_schema` 约束输出格式
  - 生成请求：根据模式（simple/complex）传递对应的 schema（`self.schema` 或 `self.simple_schema`）
  - 确保模型输出符合预期的 JSON 结构

**3. RAG 检索调用更新**
- **位置**：`_retrieve_context()` 方法
- **修改**：
  - 将 `score_threshold=0.6` 改为 `score_threshold=None`
  - 使用自适应阈值，自动适应 L2 距离（ChromaDB 默认使用 L2 距离）

**4. 正则表达式修复**
- **位置**：`_parse_allowed_nodes_from_prompt()` 函数
- **修改**：
  - 修复正则表达式，正确匹配 "可用节点定义" 部分
  - 解决了 `ERROR - 在系统提示词中未找到'可用节点定义'部分的JSON代码块` 错误

---

## 三、RAG 系统 (Retrieval Augmented Generation) 修改

### 3.1 文件：`scripts/ai_agent/tools/memory_mag/rag/rag.py`

#### 修改内容：

**1. 向量数据库加载改进**
- **位置**：`load_vector_database()` 函数
- **修改**：
  - 添加集合存在性检查（使用 ChromaDB 客户端）
  - 列出所有可用集合及其文档数量
  - 检查目标集合是否有数据
  - 自动检测并提示有数据的集合
  - 即使集合为空也返回数据库对象（允许后续添加数据）
  - 添加详细的日志输出，包括集合信息和文档数量

**2. 检索逻辑优化**
- **位置**：`retrieve_relevant_info()` 函数
- **修改**：
  - 将 `score_threshold` 默认值改为 `None`，支持自适应阈值
  - 自适应阈值逻辑：
    - 取前 k 个结果中的最高分数
    - 乘以 1.5 作为阈值（确保包含所有前 k 个结果）
    - 自动适应 L2 距离（分数范围通常在 10000-20000）
  - 修复日志格式化错误（`score_threshold` 可能为 `None`）
  - 添加相似度分数范围日志输出
  - 解决了阈值过小（0.6）导致所有结果被过滤的问题

**3. 嵌入模型配置容错**
- **位置**：`set_embeddings()` 函数
- **修改**：
  - 使用 `.get()` 方法访问 `model_config` 参数，提供默认值
  - 支持的参数：`n_ctx`, `n_threads`, `n_gpu_layers`, `n_seq_max`, `n_threads_batch`, `flash_attn`, `verbose`
  - 解决了 `KeyError: 'n_threads_batch'` 等配置缺失错误

---

### 3.2 文件：`scripts/ai_agent/config/rag_config.json`

#### 修改内容：

**配置更新**
- **修改项**：
  1. `vectorstore_persist_directory`：更新为 `/home/huangfukk/AI_Agent/scripts/ai_agent/memory/knowledge_base/map/vector_store/osm_map1`
  2. `embedding_model_path`：更新为 `/home/huangfukk/models/gguf/Qwen/Qwen3-Embedding-4B/Qwen3-Embedding-4B-Q4_K_M.gguf`
  3. `collection_name`：从 `"osm_map_docs"` 改为 `"drone_docs"`（使用有数据的集合）
  4. `model_config_llamacpp`：添加 `n_threads_batch: 4` 字段

---

### 3.3 文件：`scripts/ai_agent/config/model_config.json`

#### 修改内容：

**模型配置更新**
- **修改项**：
  1. `verbose`：从 `0` 改为 `1`（启用详细日志）
  2. `n_gpu_layers`：设置为 `40`（启用 GPU 加速）

---

## 四、主要问题修复总结

### 4.1 已修复的错误

1. **模型服务器启动超时**
   - **原因**：`main()` 函数被注释，服务器无法启动
   - **修复**：取消注释 `uvicorn.run()` 调用

2. **配置解析 KeyError**
   - **原因**：`models_server` 配置格式不一致（列表 vs 字典）
   - **修复**：添加格式判断，支持两种格式

3. **消息格式类型错误**
   - **原因**：纯文本和多模态消息格式混用
   - **修复**：区分纯文本（字符串）和多模态（列表）格式

4. **JSON 序列化错误**
   - **原因**：Pydantic 模型直接序列化失败
   - **修复**：添加 Pydantic v1/v2 兼容的序列化逻辑

5. **RAG 检索返回空结果**
   - **原因**：
     - 集合名称不匹配（`osm_map_docs` 为空，`drone_docs` 有数据）
     - 相似度阈值过小（0.6），而 L2 距离分数通常在 10000+ 范围
   - **修复**：
     - 更新集合名称为 `drone_docs`
     - 实现自适应阈值机制

6. **配置缺失 KeyError**
   - **原因**：`rag_config.json` 缺少 `n_threads_batch` 字段
   - **修复**：添加字段，并在代码中使用 `.get()` 提供默认值

---

## 五、新增功能

### 5.1 JSON Schema 约束输出

- **功能描述**：支持在推理请求中传递 JSON Schema，约束模型输出格式
- **应用场景**：
  - 分类任务：确保输出符合 `{"mode": "simple"|"complex"}` 格式
  - 生成任务：确保输出符合 Pytree JSON 结构
- **实现位置**：
  - `model_definition.py`：添加 `json_schema` 字段
  - `models_server.py`：构建 `response_format` 参数
  - `py_tree_generator.py`：传递动态生成的 schema

### 5.2 自适应相似度阈值

- **功能描述**：根据检索结果自动调整相似度阈值
- **优势**：
  - 自动适应不同的距离度量（L2、余弦距离等）
  - 无需手动调整阈值参数
  - 确保返回前 k 个最相关的结果
- **实现位置**：`rag.py` 的 `retrieve_relevant_info()` 函数

### 5.3 向量数据库诊断功能

- **功能描述**：加载向量数据库时自动检查集合状态
- **功能**：
  - 列出所有可用集合
  - 显示每个集合的文档数量
  - 提示有数据的集合
  - 诊断集合不存在或为空的情况
- **实现位置**：`rag.py` 的 `load_vector_database()` 函数

---

## 六、配置变更

### 6.1 必须更新的配置

1. **`rag_config.json`**
   - 更新 `vectorstore_persist_directory` 路径
   - 更新 `embedding_model_path` 路径
   - 更新 `collection_name` 为有数据的集合
   - 确保 `model_config_llamacpp` 包含所有必需字段

2. **`model_config.json`**
   - 根据需求调整 `n_gpu_layers`（GPU 加速层数）
   - 根据需求调整 `verbose`（日志详细程度）

---

## 七、测试建议

### 7.1 功能测试

1. **模型服务器启动测试**
   ```bash
   cd scripts/ai_agent/models
   python models_server.py
   ```

2. **RAG 检索测试**
   ```python
   from tools.memory_mag.rag.rag import set_embeddings, load_vector_database, retrieve_relevant_info
   # 测试检索功能
   ```

3. **JSON Schema 约束测试**
   - 发送分类请求，验证输出格式
   - 发送生成请求，验证 Pytree JSON 结构

### 7.2 集成测试

1. **端到端测试**
   - 启动后端服务
   - 发送 "起飞，飞到匡亚明学院" 请求
   - 验证 RAG 检索是否返回地点信息
   - 验证生成的 Pytree 是否包含正确的地点坐标

---

## 八、注意事项

1. **向量数据库集合**
   - 确保使用有数据的集合（当前为 `drone_docs`）
   - 如果更换集合，需要更新 `rag_config.json` 中的 `collection_name`

2. **嵌入模型路径**
   - 确保嵌入模型路径正确
   - 嵌入模型必须与向量数据库创建时使用的模型一致

3. **GPU 配置**
   - 根据硬件配置调整 `n_gpu_layers`
   - 如果使用 CPU，设置 `n_gpu_layers=0`

4. **日志级别**
   - 生产环境建议设置 `verbose=0`
   - 调试时可以使用 `verbose=1` 查看详细信息

---

## 九、后续优化建议

1. **性能优化**
   - 考虑缓存嵌入模型实例
   - 优化向量数据库查询性能

2. **错误处理**
   - 添加更细粒度的错误分类
   - 提供更友好的错误消息

3. **配置管理**
   - 考虑使用环境变量覆盖配置
   - 添加配置验证逻辑

4. **文档完善**
   - 添加 API 文档
   - 添加部署指南

---

## 十、启动脚本

### 10.1 后端服务启动脚本

**文件**：`scripts/ai_agent/groundcontrol/backend_service/start_backend.sh`

**功能**：
- 提供便捷的后端服务启动方式
- 自动设置工作目录和 Python 路径
- 启动 FastAPI 后端服务，监听 `0.0.0.0:8001`

**使用方法**：
```bash
cd scripts/ai_agent/groundcontrol/backend_service
./start_backend.sh
```

**脚本内容**：
- 自动切换到脚本所在目录
- 设置 Python 路径
- 使用 uvicorn 启动 FastAPI 应用：`python -m uvicorn src.main:app --host 0.0.0.0 --port 8001`

---

**文档版本**：1.1  
**最后更新**：2025-11-24