PlantAI-rag/docs/plans/PROJECT_RECORD.md

Gene Family MAS - RAG 模块项目记录

最后更新: 2026-03-06 项目状态: RAG核心功能可用，LLM对话已修复

---

📌 项目概述

项目目标: 构建基因家族分析 RAG 系统，从"文献检索工具"升级为"具备领域推理能力的虚拟合作者"。

核心技术栈:

• 嵌入模型: BGE-M3 (本地模型)
• LLM: 多提供商 (GLM, Kimi, MiniMax, DeepSeek) + Ollama (本地 qwen3:0.6b)
• 向量存储: FAISS + 自定义存储
• 前端: Vue 3 + Element Plus

数据资源:

• 当前文献: 87 篇 (已索引)
• Chunk 数量: 5,107
• 待处理文献: 12,483 篇 Q1 论文

---

✅ 2026-03-06 更新日志

修复内容

问题	原因	解决方案	状态
BGE-M3 模型加载失败	PyTorch 输出大量进度日志导致 IO 瓶颈	添加环境变量抑制 (TF_CPP_MIN_LOG_LEVEL, TRANSFORMERS_VERBOSITY)	✅
/chat 返回空结果	1) BM25 索引返回空 2) 无 fallback 机制 3) 默认 LLM 无 API Key	1) 添加 substring fallback 2) 改用 Ollama 本地模型	✅

技术细节

1. BGE-M3 模型加载问题

• 现象: 模型加载时输出大量 "Loading weights: xx%" 进度日志
• 原因: 不是缺库，而是 PyTorch 加载 2GB 模型权重时输出大量日志
• 解决: 在 rag_api.py 开头添加:

import os
os.environ['TF_CPP_MIN_LOG_LEVEL'] = '3'
os.environ['TOKENIZERS_PARALLELISM'] = 'false'
os.environ['TRANSFORMERS_VERBOSITY'] = 'error'
os.environ['HF_HOME'] = '/tmp/hf_home'

2. 搜索 fallback 机制

• 问题: /chat 默认使用 normal 模式调用 hybrid_search，依赖 BM25 索引，但 BM25 返回空结果时直接失败
• 解决: 修改 hybrid_retriever.py 的 search() 方法，添加失败自动切换逻辑:

if mode == "normal":
    results = await self._hybrid_search(query, top_k, alpha)
    if results:
        return results
    # Fallback to substring if hybrid fails
    return await self._substring_search(query, top_k)

3. LLM 配置

• 问题: 默认使用 GLM 但没有 API Key
• 解决: 修改 config/llm.yaml，将默认 provider 改为 Ollama:

default:
  provider: "ollama"
  model: "qwen3:0.6b"

测试结果

查询	状态
SPL gene	✅ 返回苦荞 FtSPL 相关文献
MYB	✅ 返回葫芦科相关文献
WRKY	✅ 返回甜橙 WRKY 相关文献
What is SPL gene?	❌ 分数太低，无结果
我应该怎么做	❌ 无匹配内容

当前限制

1. 长句/复杂问句匹配差 - 检索基于关键词匹配，不是语义理解
2. 需要关键词触发 - 查询需要包含基因家族名称 (SPL, MYB, WRKY 等)
3. 知识库有限 - 当前仅 87 篇论文，缺少分析方法论文献

---

✅ 第一阶段：基础设施搭建 (已完成)

1.1 核心模块修复

任务	文件	状态	备注
RAG API 修复	scripts/rag_api.py	✅	添加 /chat 端点支持 RAG+LLM
PDF 提取器修复	src/rag/pdf_extractor.py	✅	添加 Unicode 清理，处理中文 PDF
Ollama 提供商修复	src/llm/providers/ollama.py	✅	修复 async/sync 问题
前端语法修复	frontend/index.html	✅	修复 JSON.stringify 语法错误
BGE-M3 加载修复	src/rag/embeddings.py	✅	添加日志抑制
检索 fallback	src/rag/hybrid_retriever.py	✅	添加失败自动切换
LLM 配置	config/llm.yaml	✅	改用 Ollama

1.2 索引构建

指标	数值
PDF 数量	87 篇
Chunk 数量	5,107
索引大小	~98 MB (chunks + embeddings)

---

🔬 第二阶段：技术调研结论

2.1 切块方法对比

方法	优点	缺点	结论
Fixed-Size	简单、快	可能切断语义	✅ 当前使用 (50词+30重叠=60%)
Recursive	平衡好	仍可能切断专业术语	备选
Semantic	语义完整	2-3x 嵌入成本	非必须

2.2 检索方式对比

方法	精度提升	复杂度	结论
纯向量	基准	低	✅ 当前使用
混合检索 (BM25+向量+RRF)	+20-35%	高	后续可升级

---

🧬 基因家族 RAG 需求分析

核心模块 (已完成)

模块	状态
向量检索基础	✅
PDF 提取	✅
LLM 集成	✅
实体提取	✅
外部链接	✅

待开发模块

模块	实现方式	难度
物种识别	正则 + 物种数据库校验	⭐
Pfam 提取	正则匹配 PFxxxxx	⭐
基因名提取	正则 + 物种基因名数据库	⭐⭐
数据集编号	正则匹配 GSE/SRA/PRJNA	⭐

---

📋 后续优化方向

2026-03-19 更新：开源项目对比结论

项目	建议	优先级
Mem0	✅ 优先集成，解决跨对话记忆	P0
Qdrant	✅ 完全迁移，支持持久化	P1
Unstructured	⚠️ 可选，PyMuPDF 目前够用	P2
LlamaIndex/LangChain	❌ 不建议，会丢失技能化架构	-

核心结论: 不需要迁移到 LlamaIndex/LangChain，只需在现有编排器上加 Mem0 记忆层。详见 memory/2026-03-19.md

原有优化方向

1. 降低检索阈值 - 让更多结果通过，增加 LLM 可用上下文
2. 添加系统提示 - 让 LLM 根据少量内容生成完整回答
3. 扩展知识库 - 添加基因家族分析方法论文献
4. 意图识别 - 区分查询类型 (是什么/怎么做/有多少)

---

📁 相关文件路径

类型	路径
主项目	/home/xia-lab/gene-family-mas/
RAG API	/home/xia-lab/gene-family-mas/scripts/rag_api.py
嵌入模型	/home/xia-lab/wutx/00test/bbav2/scripts/bge-m3-model
索引数据	/home/xia-lab/gene-family-mas/data/rag_index/
实体数据库	/home/xia-lab/gene-family-mas/data/rag/entities.db

---

记录人: Sisyphus AI Agent 最后更新: 2026-03-19