DeepRAG - 企业级 RAG 知识库系统

基于 FastAPI + Vue 3 的前后端分离 RAG（检索增强生成）系统，支持 Milvus/FAISS 向量存储、BM25 混合检索、Reranker 重排，以及多租户隔离。

核心特性

混合检索：向量检索 + BM25 融合，MMR 多样性采样
智能重排：可选 FlagEmbedding Reranker 提升相关性
查询改写：多种策略优化检索效果
- 查询扩展 - 生成同义词和相关表达
- 查询分解 - 将复杂查询拆分为子查询
- HyDE - 假设性文档嵌入
- 智能分析 - 自动推荐最佳策略
灵活存储：Milvus 云原生 / FAISS 本地，自动回退
多租户：命名空间隔离 + API Key 鉴权
深度文档理解：
- 支持 .txt, .md, .pdf, .docx, .xlsx
- PDF 表格自动提取和解析
- OCR 图片文字识别（可选）
- 智能分块保持语义边界
精确引用溯源：记录页码信息，支持精确定位
多轮对话管理：上下文感知的对话历史
现代前端：Vue 3 + Vite，组件化架构，代码高亮，原生暗黑模式
可观测性：结构化日志、健康检查、监控指标
易部署：Docker Compose 一键启动
模型可选：设置里卡片式选择 DeepSeek / Qwen 等兼容模型
联网搜索（可选）：可将实时搜索结果并入上下文（Serper / DuckDuckGo）

架构

┌─────────────────┐         ┌──────────────────┐
│   Vue 3 前端    │ ------- │  FastAPI 后端    │
│  (Vite 5173)    │  HTTP   │   (uvicorn 8000) │
└─────────────────┘         └──────────┬───────┘
                                       │
                       ┌────────────────┼────────────────┐
                       │                │                │
                  ┌────▼────┐     ┌────▼────┐     ┌────▼────┐
                  │ Milvus  │     │ OpenAI  │     │ BM25    │
                  │ /FAISS  │     │  兼容   │     │ Rerank  │
                  └─────────┘     └─────────┘     └─────────┘

核心链路（默认组合与兜底）

默认问答链路（POST /ask）：

文档解析与分块：上传/入库时完成（PDF/Docx/Xlsx/Text → split_text）。
检索：向量检索（Milvus 或 FAISS） + BM25（可选）进行候选召回。
融合：将向量相似度与 BM25 分数归一化后加权融合（RAG_VEC_WEIGHT / RAG_BM25_WEIGHT）。
多样化：对候选进行 MMR 下采样（RAG_MMR_LAMBDA）。
重排（可选）：若启用 reranker，则先扩大候选池后重排，并保留 max(top_k, top_n) 的上下文窗口。
生成：把上下文片段拼接到 prompt 中调用 OpenAI 兼容模型生成答案。

失败兜底（Best-effort）：

Milvus 不可用：自动回退到 FAISS。
Reranker 不可用/报错：跳过重排，仅用融合检索结果。
解析器缺失：对应格式回退到更基础的解析方案（例如 PDF 回退到 pdfminer）。

排障建议：

先看响应头 X-Request-Id，再查后端日志同 request_id 的检索/重排过程。
同时检查 X-RAG-Vector-Backend 与 X-RAG-Vector-Fallback，确认是否发生 Milvus→FAISS 回退。
如果效果波动：先固定模型与检索参数（RAG_*）再逐项开关（BM25/MMR/Rerank/改写）。
如需更细的排查信息：设置 RAG_TRACE=true，将输出每次请求的检索/重排/提示词构建/LLM 耗时与候选数量（不记录原始问题，仅记录 hash）。

快速开始

环境要求

Python 3.10–3.11（CI 覆盖；推荐）
Node.js 20+ (前端)
Conda (推荐，用于 FAISS)
Tesseract OCR (可选，用于图片文字识别)

1. 安装依赖

# 后端（推荐使用 conda 环境）
conda create -n rag-env python=3.10 -y
conda activate rag-env
pip install -r backend/requirements.txt

# 说明：必须先激活环境再安装依赖
# 如果是非交互/脚本环境，可用：
# conda run -n rag-env python -m pip install -r backend/requirements.txt

# 可选：安装 Tesseract OCR（用于图片识别）
# Windows: 下载安装 https://github.com/UB-Mannheim/tesseract/wiki
# macOS: brew install tesseract tesseract-lang
# Linux: sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim

# 前端
cd frontend
npm install

文档解析依赖与平台差异（建议统一版本）：

能力	Python 依赖	系统依赖	备注
PDF 文本解析	`pdfplumber`, `pdfminer.six`	无必需	`pdfplumber` 失败会回退 `pdfminer`
PDF 表格抽取	`pdfplumber`	无必需	复杂扫描件表格可能抽取不完整
DOCX 解析	`python-docx`	无必需	保留段落与表格内容
XLSX 解析	`openpyxl`	无必需	按 sheet 展开为文本
OCR（可选）	`pytesseract`, `Pillow`	`tesseract` 可执行程序	缺失时仅跳过 OCR，不影响文本型文档摄取

可复现建议：

锁定 Python 3.10–3.11，并固定 backend/requirements.txt 版本。
生产环境优先使用 Docker 镜像，避免本机依赖差异导致解析结果漂移。
如需精确页码引用，建议固定解析器版本并对核心文档做回归对比。

2. 配置环境变量

在项目根目录创建 .env 文件：

# 大模型配置（OpenAI 兼容）
OPENAI_API_KEY=sk-your-key
OPENAI_BASE_URL=https://api.deepseek.com/v1  # 或其他兼容服务

# 可用模型（逗号分隔），前端将用来渲染模型卡片
AVAILABLE_MODELS=deepseek-chat,qwen-turbo,qwen-plus,qwen-max

# Qwen 兼容配置（可选，若使用阿里灵积）
QWEN_API_KEY=sk-your-qwen-key
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# 向量存储（auto 自动选择 Milvus/FAISS）
VECTOR_BACKEND=auto
MILVUS_HOST=127.0.0.1
MILVUS_PORT=19530

# 检索参数（推荐默认）
RAG_TOP_K=8
RAG_BM25_ENABLED=true
RAG_BM25_WEIGHT=0.4
RAG_VEC_WEIGHT=0.6
RAG_MMR_LAMBDA=0.7
RAG_RERANKER_ENABLED=false
RAG_TRACE=false  # 可观测性：输出检索链路 trace 日志（建议排障时开启）
RAG_AUTO_INGEST_ON_STARTUP=false  # 默认关闭：避免冷启动阻塞与误入库（需要时手动执行入库/建索引）
RAG_DISABLE_LEGACY_ROUTES=false  # 默认保留历史路径兼容；设为 true 后仅允许 /v1 与 /admin
RAG_LEGACY_ROUTES_SUNSET_DATE=2026-12-31  # 历史路径下线目标日期（用于响应头提示）
RAG_AUDIT_LOG_ENABLED=true  # 审计日志开关：记录管理/写接口操作（脱敏 key + request_id + namespace）

# 联网搜索（可选）
RAG_WEB_SEARCH_ENABLED=false
SERPER_API_KEY=

# 多租户与鉴权
RAG_NAMESPACE=default
RAG_NAMESPACE_WHITELIST=default  # 允许的命名空间（逗号分隔，可选）
RAG_API_KEY_NAMESPACE=default  # API key 绑定命名空间（可选）
RAG_API_KEY=  # 可选，设置后需请求头 X-API-Key
RAG_READ_API_KEYS=  # 可选，读权限 key 列表（逗号分隔）；与 RAG_API_KEY 兼容
RAG_READ_KEY_NAMESPACES=  # 可选，读 key 的命名空间授权映射：key1=nsA|nsB;key2=nsC
RAG_API_KEY_REQUIRED=false  # 是否强制鉴权（true/false）

# 管理员接口（强烈建议公网部署开启）
RAG_ADMIN_API_KEY=
RAG_ADMIN_API_KEYS=  # 可选，管理员 key 列表（逗号分隔）；与 RAG_ADMIN_API_KEY 兼容
RAG_ADMIN_KEY_NAMESPACES=  # 可选，管理员 key 的命名空间授权映射：adm1=nsA|nsB
RAG_ADMIN_API_KEY_REQUIRED=true
RAG_ADMIN_API_KEY_FALLBACK_TO_API_KEY=false  # 默认 false，更严格；仅兼容迁移时才建议开启

# 路径/命名空间安全（可选，建议多租户开启）
# 开启后文档会以 `<namespace>/<path>` 作为逻辑 key 存储，避免跨命名空间误读/误删
RAG_ENFORCE_NAMESPACE_PATH_PREFIX=true

# CORS 配置
RAG_CORS_ALLOW_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
RAG_CORS_ALLOW_CREDENTIALS=true
RAG_CORS_ALLOW_METHODS=*
RAG_CORS_ALLOW_HEADERS=*

4. 启动服务

# 后端（终端 1，从项目根目录运行）
python -m uvicorn backend.server:app --host 0.0.0.0 --port 8000 --reload

# 前端（终端 2）
cd frontend
npm run dev  # 访问 http://localhost:5173

Docker 部署（Milvus）

生产（不挂载源码）：

docker compose -f deploy/docker-compose.yml up --build

开发（挂载源码，方便调试）：

docker compose -f deploy/docker-compose.dev.yml up --build

5. 最小 Smoke Test（推荐）

服务启动后，用 curl 快速验证基础链路是否正常：

curl -sS http://localhost:8000/healthz
curl -sS http://localhost:8000/models
curl -sS http://localhost:8000/ask \
  -H "Content-Type: application/json" \
  -d "{\"question\":\"用一句话说明这个系统做什么？\"}"

如开启了鉴权（RAG_API_KEY_REQUIRED=true），需要加请求头 X-API-Key: <your_key>。

API 文档

启动后访问 http://localhost:8000/docs 查看 Swagger 交互式文档。

评测（可复现）

项目内置评测接口与离线 CLI。推荐先准备测试用例 JSON（示例：backend/eval_cases.example.json），然后运行：

# 检索评测（不依赖大模型）
python -m backend.eval_cli --cases backend/eval_cases.example.json --mode retrieval --top_k 10 --out data/evaluation/retrieval.txt

# 完整评测（包含答案质量；需要配置 OPENAI_API_KEY 等）
python -m backend.eval_cli --cases backend/eval_cases.example.json --mode benchmark --top_k 10 --out data/evaluation/benchmark.txt

批量实验矩阵（自动对比不同检索参数）：

python -m backend.eval_matrix_cli \
  --cases backend/eval_cases.example.json \
  --matrix backend/eval_matrix.example.json \
  --mode retrieval \
  --top_k 10 \
  --out data/evaluation/matrix_report.json

主要端点

稳定端点（建议新接入优先使用）：

POST /v1/ask
POST /v1/ask_stream
GET /v1/models
GET /v1/healthz
GET /v1/docs/paths
GET /v1/docs/preview?path=...
GET /v1/export?path=...

管理端点（需 admin key）：

POST /admin/docs, DELETE /admin/docs
POST /admin/import
POST /admin/namespaces/create, POST /admin/namespaces/clear, DELETE /admin/namespaces
POST /admin/cache/clear
POST /admin/metrics/export, POST /admin/metrics/clear
POST /admin/documents/metadata
POST /admin/documents/{path}/tags, DELETE /admin/documents/{path}/tags

历史路径继续保留兼容（如 /ask、/docs 等），后续会逐步收敛到 /v1 与 /admin。

历史路径治理策略：

访问历史路径时，响应头会包含 Deprecation: true、Sunset、Link（指向 successor route）。
如需提前强制收敛，可设置 RAG_DISABLE_LEGACY_ROUTES=true，历史路径将返回 410 Gone。

问答相关

POST /ask - 基础问答
POST /ask_stream - 流式问答（SSE）
说明：sources 中的 score_fused 为融合分，score_rerank 为重排分（启用 reranker 时才有）。
POST /ask_with_rewriting - 使用查询改写增强检索
POST /analyze_query - 分析查询并推荐策略
POST /explain_retrieval - 解释检索结果（评分+高亮）
POST /advanced_search - 高级检索（过滤+权重+聚合）
POST /optimize_weights - 权重优化测试
GET /models - 返回可用大模型列表

文档管理

POST /docs - 上传文档（支持 PDF/Word/Excel）
DELETE /docs?path=xxx - 删除文档
GET /docs/paths - 列出已入库路径
GET /docs/preview?path=xxx - 预览文档分块
POST /visualize_chunks - 可视化文档分块详情
GET /export?path=xxx - 导出文档分块
POST /documents/metadata - 更新文档元数据（标签/分类/描述）
GET /documents/metadata/{path} - 获取文档元数据
GET /documents/list - 列出文档（支持按分类/标签过滤）
GET /documents/tags - 获取所有标签
GET /documents/categories - 获取所有分类
GET /documents/statistics - 获取文档统计信息
POST /documents/{path}/tags - 添加文档标签
DELETE /documents/{path}/tags - 移除文档标签

对话管理

POST /conversations - 创建新对话
GET /conversations - 列出对话列表
GET /conversations/{id} - 获取对话详情
DELETE /conversations/{id} - 删除对话
POST /conversations/{id}/messages - 添加消息

系统管理

POST /namespaces/create - 创建命名空间
GET /healthz - 健康检查
GET /cache/stats - 缓存统计
GET /cache/analyze - 缓存性能分析
POST /cache/prewarm - 缓存预热
GET /cache/smart_stats - 智能缓存统计
POST /cache/optimize - 缓存配置优化

性能监控

GET /metrics/statistics - 性能统计信息
GET /metrics/hot_queries - 热门查询排行
GET /metrics/recent_requests - 最近请求记录
GET /metrics/time_series - 时间序列数据
POST /metrics/export - 导出性能指标
POST /metrics/clear - 清空监控数据

安全说明（重要）

建议将接口分为两类：

读接口：问答/检索/预览/导出等（使用 RAG_API_KEY，或内网环境可关闭）
管理接口：写入/删除/清理/导入/指标导出等（使用 RAG_ADMIN_API_KEY）

默认已加硬的管理接口（需要 admin key）：

POST /docs, DELETE /docs, POST /import
POST /namespaces/create, POST /namespaces/clear, DELETE /namespaces
POST /cache/clear
POST /metrics/export, POST /metrics/clear
POST /documents/metadata, POST /documents/{path}/tags, DELETE /documents/{path}/tags

管理员鉴权策略：

默认 RAG_ADMIN_API_KEY_FALLBACK_TO_API_KEY=false，admin 接口不会自动退化到普通 API key。
仅在历史兼容迁移期可开启 RAG_ADMIN_API_KEY_FALLBACK_TO_API_KEY=true。

RBAC（第一阶段）：

通过 RAG_READ_API_KEYS 与 RAG_ADMIN_API_KEYS 实现角色级 key 管理（逗号分隔）。
read 接口接受 read/admin key；admin 接口仅接受 admin key。
单 key 变量（RAG_API_KEY / RAG_ADMIN_API_KEY）仍兼容，可与多 key 变量混用。
支持 namespace 级授权映射：RAG_READ_KEY_NAMESPACES / RAG_ADMIN_KEY_NAMESPACES。

审计日志：

开启 RAG_AUDIT_LOG_ENABLED=true 后，会为管理/写接口输出 audit ... 日志（包含 request_id、method、path、status、namespace、actor_key 哈希前缀）。
审计日志不记录原始 API key 与请求正文，默认写入 logs/rag.log（若文件不可写则仅输出控制台）。

路径与命名空间：

所有 path 参数会做规范化并拒绝 ..、绝对路径/盘符等输入。
建议多租户场景开启 RAG_ENFORCE_NAMESPACE_PATH_PREFIX=true，使文档以 <namespace>/<path> 作为逻辑 key 存储。

检索优化

说明：以下接口用于实验/调参，建议视为 Experimental API。
POST /retrieval/analyze - 分析检索质量并提供优化建议
POST /retrieval/suggest_weights - 根据查询类型建议最佳权重
POST /retrieval/grid_search - 网格搜索最佳权重组合
POST /retrieval/compare_strategies - 比较不同检索策略效果

查询意图识别

说明：以下接口用于实验/调参，建议视为 Experimental API。
POST /query/analyze_intent - 分析查询意图并提供优化建议
POST /query/smart_search - 基于意图识别的智能检索
POST /query/batch_analyze - 批量分析查询意图

评估测试

说明：以下接口用于离线评估流程，建议视为 Experimental API。
POST /evaluation/run_benchmark - 运行基准测试
POST /evaluation/test_retrieval - 测试检索质量
POST /evaluation/test_answer - 测试答案质量
POST /evaluation/save_test_cases - 保存测试用例
GET /evaluation/load_test_cases - 加载测试用例

知识图谱

说明：以下接口用于知识图谱实验能力，建议视为 Experimental API。
POST /kg/build - 构建知识图谱
GET /kg/statistics - 获取图谱统计信息
GET /kg/entity/{name} - 获取实体信息
GET /kg/subgraph/{name} - 获取实体子图
GET /kg/search - 搜索实体
GET /kg/path - 查找实体路径
POST /kg/enhanced_search - 图谱增强检索
POST /kg/export - 导出知识图谱
POST /kg/import - 导入知识图谱

Docker 部署

快速开始

# 1. 进入部署目录
cd deploy

# 2. 复制环境变量模板
cp .env.example ../.env

# 3. 编辑 .env 文件，填入你的 API Key
vim ../.env

# 4. 一键启动（推荐）
./start.sh

# 或手动启动
docker-compose up -d

服务访问

前端界面: http://localhost:5173
后端 API: http://localhost:8000
API 文档: http://localhost:8000/docs

常用命令

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f backend

# 停止服务
./stop.sh
# 或
docker-compose down

# 重启服务
docker-compose restart

详细部署文档请查看 deploy/README.md

使用示例

Python SDK

import requests

response = requests.post(
    "http://localhost:8000/v1/ask_stream",
    json={
        "question": "什么是 RAG？",
        "top_k": 8,
        "model": "deepseek-chat",          # 可选
        "system_prompt": "请用清晰小节回答：\n{context}\n问题：{question}",
        "web_enabled": True,                 # 可选
        "web_top_k": 3
    },
    headers={"X-API-Key": "your-key"},  # 可选
    stream=True
)

for line in response.iter_lines():
    if line.startswith(b"data: "):
        print(line.decode()[6:], end="")

cURL

curl -X POST http://localhost:8000/v1/ask_stream \
  -H "Content-Type: application/json" \
  -d '{
    "question": "介绍一下系统功能",
    "top_k": 8,
    "model": "qwen-plus",
    "system_prompt": "{context}\n\n请基于以上内容回答：{question}",
    "web_enabled": True,
    "web_top_k": 3
  }'

高级配置

BM25 混合检索

RAG_BM25_ENABLED=true
RAG_BM25_WEIGHT=0.35
RAG_VEC_WEIGHT=0.65
RAG_MMR_LAMBDA=0.5  # 多样性权衡

Reranker 重排

RAG_RERANKER_ENABLED=true
RAG_RERANKER_MODEL=BAAI/bge-reranker-base
RAG_RERANKER_TOP_N=4

Milvus 云端部署

VECTOR_BACKEND=milvus
MILVUS_HOST=your-milvus.cloud
MILVUS_PORT=19530
MILVUS_USER=xxx
MILVUS_PASSWORD=xxx
MILVUS_SECURE=true

贡献指南

欢迎贡献！请先 Fork 本仓库，然后：

创建特性分支：git checkout -b feature/amazing-feature
提交改动：git commit -m 'feat: add amazing feature'
推送分支：git push origin feature/amazing-feature
提交 Pull Request

分支规范

main - 生产稳定版本
dev - 开发集成分支
feature/* - 新功能开发
hotfix/* - 紧急修复

开发路线图

许可证

本项目采用 MIT License 开源。

致谢

FastAPI - 现代高性能 Web 框架
Milvus - 云原生向量数据库
Sentence Transformers - 语义向量模型
Vue.js - 渐进式前端框架

Name		Name	Last commit message	Last commit date
Latest commit History 113 Commits
.github		.github
backend		backend
data/docs		data/docs
deploy		deploy
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

DeepRAG - 企业级 RAG 知识库系统

核心特性

架构

核心链路（默认组合与兜底）

快速开始

环境要求

1. 安装依赖

2. 配置环境变量

4. 启动服务

Docker 部署（Milvus）

5. 最小 Smoke Test（推荐）

API 文档

评测（可复现）

主要端点

安全说明（重要）

Docker 部署

快速开始

服务访问

常用命令

使用示例

Python SDK

cURL

高级配置

BM25 混合检索

Reranker 重排

Milvus 云端部署

贡献指南

分支规范

开发路线图

许可证

致谢

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages