ColPali + MUVERA + Qdrant 驱动的多模态文档检索与问答系统。上传 PDF、图片或 PPTX 文件后，系统会将每页统一渲染为图像并建立视觉索引；当前网页端默认沿用 MUVERA 单向量 FDE Prefetch + ColPali 多向量 Rerank 的两阶段检索路径，再由豆包多模态大模型生成答案，并附上原页截图供溯源。最新 20 题 benchmark 显示：两阶段路径在当前小规模语料上能够稳定取得 90% final page Hit@3 与 0.7667 final page MRR，也体现出“轻量召回 + 精排复核”的双路检索设计思路；但单向量 MUVERA FDE 在本轮检索消融中取得了更高的 raw Hit@3 和 MRR。因此，两阶段路径更适合表述为具备工程扩展潜力的检索架构，而不是已被当前实验充分证明的最优默认策略。
- 视觉文档支持：PDF / PNG / JPG / JPEG / WEBP / PPTX，统一渲染为页面图像进入索引
- 可切换检索架构：支持
two_stage（MUVERA 单向量 FDE Prefetch + ColPali Rerank）、colpali_only和muvera_only三种模式；当前网页端默认走two_stage，其主要价值在于把轻量召回与视觉精排解耦，为更大规模语料预留扩展空间；在最新同进程 20 题 benchmark 上，two_stage与colpali_only检索质量持平，而muvera_only的 raw Hit@3 更高、平均检索延迟更低 - 归一化相关性得分：MaxSim 原始分除以查询 token 数，得分落在 0–1 区间；默认采用
score >= 0.60作为正式证据阈值，并补入少量 near-threshold 页面，减少 final evidence 丢页 - 复合问题支持：对以强分隔符拆出的多个子问题分别检索，再合并证据页，减少多问合并时只覆盖单一主题的问题
- 多文档作用域查询：Scope Bar 支持同时选中多个文档进行对话，也可切回全库检索
- 原页图片溯源：每条回答附带匹配页面缩略图网格（最多 5 列自适应），点击大图查看；卡片显示文档名、页码与相关性得分
- 现代化 UI：欢迎页 → 聊天页平滑过渡，暗色模式，Markdown 渲染，一键复制回答
| 层次 | 技术 |
|---|---|
| 视觉嵌入模型 | ColPali v1.3（vidore/colpali-v1.3），128-D 多向量 |
| 加速检索 | MUVERA 固定维度单向量 FDE（fastembed，当前参数 30720-D），Prefetch 倍率 10× |
| 向量数据库 | Qdrant（本地 Docker 或云端），单向量 FDE 检索 + ColPali MaxSim 多向量精排 |
| 大语言模型 | 豆包 Seed 2.0 Pro（doubao-seed-2-0-pro-260215），Volcengine ARK API |
| 后端框架 | FastAPI + uvicorn |
| 前端 | 原生 HTML/JS + Tailwind CSS CDN + marked.js |
| PDF 解析 | pdf2image + Poppler |
| 文档转图 | pdf2image + Poppler；PPTX 通过 LibreOffice soffice 先转 PDF |
| 图像处理 | Pillow（图片缓存与标准化） |
RAG/
├── backend/ # FastAPI 后端
│ ├── main.py # 应用入口，挂载静态前端
│ └── api/routes/
│ ├── health.py # 健康检查
│ └── rag.py # 上传、对话、文件管理接口
├── benchmarks/ # benchmark 定义与样本文档
│ ├── README.md
│ ├── rag_eval_small_draft.json
│ └── sample-documents/
├── data/ # 本地运行产物（默认忽略）
│ ├── eval_runs/ # 评测结果输出
│ └── qdrant/ # embedded Qdrant 数据与原始上传文件
├── docs/ # 项目说明文档
│ ├── system_workflow.md # 系统流程、性能耗时与 API
│ ├── evaluation_guide.md # 评测指标、脚本与 faithfulness 说明
│ └── project_pitch.md # benchmark 结果与项目介绍表述
├── frontend/ # 前端客户端
│ ├── index.html # 单页 HTML（Tailwind 样式）
│ └── app.js # 所有交互逻辑
├── scripts/ # benchmark 起草与评测脚本
│ ├── bootstrap_rag_benchmark.py
│ ├── build_retrieval_ablation_summary.py
│ └── run_rag_eval.py
├── src/ # AI 核心逻辑
│ ├── config.py # 环境变量、运行目录与模型配置
│ ├── llm_generator.py # 调用豆包视觉 LLM 生成答案
│ ├── doc_processor.py # 视觉文档 → 页面图像缓存（PDF/图片/PPTX）
│ └── vector_store.py # ColPali + MUVERA + Qdrant 封装
├── tests/ # 回归测试
├── assets/ # README 配图等静态资源
├── README.md
└── requirements.txt
从这一版开始，仓库会把持久化运行数据统一放到 data/ 下；如果根目录里还残留旧的 qdrant_local/ 或 eval_runs/，首次运行配置或评测脚本时会自动迁移到新位置。
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtmacOS 需要安装 Poppler 和 LibreOffice：
brew install poppler brew install --cask libreofficePPTX 支持依赖 LibreOffice 提供的
soffice转换能力；如果本机没有该命令，上传 PPTX 会直接返回可操作的错误提示。
在项目根目录创建 .env 文件（或直接在 src/config.py 中设置）：
ARK_API_KEY=your_volcengine_ark_api_key
DOUBAO_MODEL_NAME=doubao-seed-2-0-pro-260215
QDRANT_URL=http://localhost:6333
COLLECTION_NAME=colpali-rag-collectiondocker run -p 6333:6333 -p 6334:6334 \
-v $(pwd)/data/qdrant:/qdrant/storage:z \
qdrant/qdrant推荐把 Docker 版 Qdrant 作为默认运行路径。若 QDRANT_URL 不可达，后端会自动回退到仓库内的 data/qdrant/ embedded 存储，方便本地开发或离线调试；但做 benchmark 时，建议先确认当前实例实际连接的是 Docker 暴露的 6333 端口。
python -m uvicorn backend.main:app --reload --port 8000打开浏览器访问 http://localhost:8000
- 上传文件：点击左侧上传按钮，支持 PDF、PNG、JPG、WEBP、PPTX 格式
- 多文档管理：点击右上角文件图标查看已加载文档，可下载原文件或删除
- 作用域选择：上传 2 个及以上文档后，输入框上方出现 Scope Bar，可点击选中特定文档进行对话
- 提问：在输入框输入问题，回车或点击发送；回答下方附有相关页面截图，点击可全屏查看
README 现在只保留项目入口信息；系统流程、评测细节和项目表述拆到了 docs/ 下：
- docs/system_workflow.md：系统运行流程、性能耗时拆解与完整 API 表。
- docs/evaluation_guide.md：证据质量分数、benchmark 指标、评测脚本与
automatic_faithfulness解释。 - docs/project_pitch.md：当前 20 题 benchmark 结果、检索消融结论和中英文项目介绍表述。
- 上传后端会把 PDF / 图片 / PPTX 统一转换为页面图像；PPTX 会先转成 PDF，再复用 PDF 转页图链路。
- 每页会同时写入 ColPali 原始多向量和 MUVERA 固定维度单向量 FDE，便于支持
two_stage、colpali_only、muvera_only三种检索模式。 - 当前网页端默认走
two_stage：先用 MUVERA FDE 做 Prefetch，再用 ColPali 多向量 MaxSim 精排；当前小规模 benchmark 尚未证明该路径优于另外两种模式。 - 对话链路包含轻量 guard、复合问题拆分、多轮上下文桥接、阈值证据筛选、near-threshold 补偿和 top-1 fallback。
- 完整端到端流程、性能拆解和 API 表见 docs/system_workflow.md。
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/api/rag/upload |
上传文件并立即返回 task_id，后台异步索引 |
GET |
/api/rag/jobs/{task_id}/events |
通过 SSE 订阅上传任务进度 |
POST |
/api/rag/chat |
发起对话查询 |
完整 API 列表见 docs/system_workflow.md。
- 当前正式 benchmark 为 20 题，覆盖 3 份真实 PDF / PPTX 文档。
- 默认
two_stage最近一轮完整结果：final_page_hit_at_3 = 0.90、final_page_mrr = 0.7667、citation_has_gold_evidence_rate = 0.90、answer_contains_gold_answer_rate = 0.85、automatic_faithfulness_avg = 1.00。 automatic_faithfulness = 1.00只表示回答能被返回证据页直接支撑，不代表系统整体事实正确率 100%。- 最新同进程检索消融显示：
two_stage与colpali_only的 raw Hit@3 / MRR 持平，muvera_only的 raw Hit@3、MRR 和平均检索延迟最好。 - 详细指标定义、评测命令和输出文件说明见 docs/evaluation_guide.md；当前结果和简历表述见 docs/project_pitch.md。