RAG-core

RAG-core 是一个可公开的多模态文档 RAG demo，保留了上传、页面转图、ColPali + MUVERA 两阶段检索、证据页展示和可选的多模态答案生成主链路。

这个仓库默认可以在不配置任何私有 API key 的情况下启动。未配置 LLM provider 时，系统会运行在 retrieval-only 模式：照常返回证据页，但不自动生成自然语言答案。配置好 openai 或可选的 doubao provider 后，聊天接口会恢复答案生成能力。

功能概览

• 支持 PDF、图片、PPTX 上传与异步建索引
• 使用 ColPali 多向量 + MUVERA FDE + Qdrant 实现视觉检索
• 支持 two_stage、colpali_only、muvera_only 三种检索模式
• 提供前端证据卡片、SSE 流式输出和多轮追问能力
• 默认支持 retrieval-only 降级，便于公开演示与二次开发

目录结构

RAG-core/
├── backend/
├── docs/
├── frontend/
├── src/
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

环境要求

• Python 3.11+
• Poppler：用于 PDF 转图片
• LibreOffice：仅在需要上传 PPTX 时需要
• Qdrant：推荐使用 Docker 运行；如果 QDRANT_URL 不可达，后端会回退到本地 data/qdrant embedded 存储

macOS 可用如下命令安装系统依赖：

brew install poppler
brew install --cask libreoffice

快速开始

1. 创建虚拟环境并安装依赖

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. 复制环境变量模板

cp .env.example .env

3. 可选：启动 Qdrant Docker

docker run -p 6333:6333 -p 6334:6334 \
  -v $(pwd)/data/qdrant:/qdrant/storage:z \
  qdrant/qdrant

4. 启动后端服务

uvicorn backend.main:app --reload

5. 打开浏览器访问 http://127.0.0.1:8000

LLM 配置说明

Retrieval-only 模式

默认推荐公开演示使用：

LLM_PROVIDER=none

此时系统仍可完成上传、建索引、检索和证据页展示，但不会自动生成自然语言答案。

OpenAI 模式

LLM_PROVIDER=openai
OPENAI_API_KEY=your_key
OPENAI_MODEL_NAME=gpt-4o-mini

可选 Doubao / ARK 模式

LLM_PROVIDER=doubao
ARK_API_KEY=your_key
ARK_API_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
DOUBAO_MODEL_NAME=doubao-seed-2-0-pro-260215

支持的文件格式

• PDF
• PNG / JPG / JPEG / WEBP
• PPTX
• 纯文本文件会被渲染成页面图后进入检索流程

说明

• 更详细的运行流程见 docs/system_workflow.md
• colpali-engine 目前仍使用上游 feature branch，以保持与当前 ColPali/MUVERA 管线兼容