🐍 Venom: Scientific Paper CRAG Agent

Venom 是一个面向学术论文的纠正式检索增强生成（CRAG）Agent。支持将双栏学术 PDF 注入本地 Milvus 向量数据库，进行带引用的精准问答。当本地知识库不足时，系统会自动 fallback 到 Semantic Scholar 进行学术检索。

支持用户注册/登录、对话历史持久化和基于 LLM 的长期记忆功能，所有数据存储在 PostgreSQL 中。

📁 项目结构

MelivusCrag/
├── app.py                  # Streamlit 入口：登录/注册页
├── pages/
│   ├── 1_chat.py           # 主聊天页（对话历史 + 聊天窗口）
│   └── 2_upload.py         # 论文入库页（PDF 上传）
├── main.py                 # FastAPI 后端（API 网关）
├── CragFlow.py             # LangGraph CRAG 流水线 + 长期记忆注入
├── CeleryWorker.py         # Celery 异步入库 Worker
├── Parser.py               # PDF 解析 (MinerU) + 智能分块
├── services/
│   ├── database.py         # SQLAlchemy ORM 模型（用户/对话/消息/记忆）
│   ├── auth.py             # JWT 认证（密码哈希 + Token 签发验证）
│   ├── embedding.py        # BGE-M3 向量化服务
│   └── constants.py        # Milvus 字段名常量
├── docker-compose.yml      # Redis + etcd + MinIO + Milvus + PostgreSQL
├── requirements.txt        # Python 依赖
└── .env.example            # 环境变量模板

🚀 快速启动指南

1. 环境准备

推荐使用 Python 3.10 或 3.11。克隆项目后，创建并激活虚拟环境：

git clone <your-repo-url>
cd MelivusCrag

python -m venv .venv
# Windows 激活
.venv\Scripts\Activate.ps1
# macOS/Linux 激活
source .venv/bin/activate

安装核心依赖：

pip install -r requirements.txt

2. 启动基础架构 (Docker)

项目依赖 Milvus (>=2.4.5)、Redis 和 PostgreSQL。在项目根目录下运行：

docker compose up -d

使用 docker compose ps 确保 etcd, minio, milvus, redis, postgres 均处于 healthy/running 状态。

3. 环境配置

复制环境变量模板：

# Windows
copy .env.example .env  
# macOS/Linux
cp .env.example .env

在 .env 中填入你的 API 密钥和 JWT 密钥：

# 必填：你的 LLM API Key
api_key=sk-xxxxxxxxxxxxxxxx

# 必填：JWT 签名密钥（随意填写一串随机字符串即可）
JWT_SECRET_KEY=my-random-secret-key-2026

# 选填：Semantic Scholar API Key（用于外网学术搜索 fallback）
SEMANTIC_SCHOLAR_API_KEY=your_key_here

其余配置项（DATABASE_URL、MILVUS_HOST 等）若使用本机 Docker 运行，保持默认值即可。 建议填写 SEMANTIC_SCHOLAR_API_KEY，否则外网学术检索更容易触发频率限制。

4. PDF 解析模型配置 (MinerU)

在用户主目录（如 C:\Users\你的用户名\）下创建 magic-pdf.json：

{
    "models-dir": "D:\\magic-pdf-models\\models",
    "layoutreader-model-dir": "D:\\magic-pdf-models\\models\\ReadingOrder\\layout_reader",
    "device-mode": "cuda",
    "table-config": { "model": "rapid_table", "enable": false, "max_time": 400 },
    "formula-config": { "mfd_model": "yolo_v8_mfd", "mfr_model": "unimernet_small", "enable": false },
    "layout-config": { "model": "doclayout_yolo" }
}

注：请确保 models-dir 指向你本地的 PDF-Extract-Kit 模型路径。若无 GPU，将 device-mode 改为 cpu。

5. 启动系统进程

请在项目根目录打开三个独立的终端（确保都激活了虚拟环境），依次启动：

终端 1：向量入库队列 (Celery)

celery -A CeleryWorker worker --loglevel=info --pool=solo

(注：Windows 系统必须加 --pool=solo 参数)

终端 2：核心大模型 API (FastAPI)

python run.py

注：Windows 下必须使用 run.py 启动，它会在 Uvicorn 之前设置正确的事件循环策略。 启动时应看到日志：PostgreSQL tables initialized. 和 CRAG agent with PostgresSaver initialized.

终端 3：交互界面 (Streamlit)

streamlit run app.py

6. 使用

启动完成后，浏览器自动打开 http://localhost:8501：

1. 注册账号 — 首次使用需在登录页点击「注册」创建账号
2. 开始对话 — 登录后进入聊天页，点击左侧「新建对话」开始提问
3. 论文入库 — 在左侧导航栏切换到「论文入库」页面上传 PDF
4. 历史对话 — 左侧边栏列出所有历史对话，点击即可切换/继续
5. 长期记忆 — 系统自动从对话中提取用户偏好和研究方向，跨对话记忆

🔧 技术笔记

1. BGE-M3 只负责嵌入，将文本转换为稀疏与稠密向量，向量余弦相似度的查询是在 Milvus 里进行的；
2. 语义鸿沟：问题的向量与答案的向量可能存在差距，BGE-M3 在训练时就完成了映射；还有一种办法是 HyDE 假设性文档嵌入，即让 LLM 提前将问题转换为文档。