# 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` 开头添加:
```python
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()` 方法，添加失败自动切换逻辑:
```python
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:
```yaml
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*