huangfu/ai_agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6acda6238069d6b52cf8a1cc536f91b0a2df0e5c
ai_agent/CHANGELOG.md
huangfu 12cfcc2681 first commit
2025-11-24 20:10:33 +08:00

12 KiB
Raw Blame History

项目修改日志 (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. 模型服务器启动测试

    cd scripts/ai_agent/models
python models_server.py

  2. RAG 检索测试

    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

使用方法：

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