RAG 知识库 (rag-knowledge-base)

本地模块化 RAG 知识库应用 — Chainlit + ChromaDB + DeepSeek。

功能

• 多知识库管理，每个知识库对应独立 ChromaDB collection
• 支持文档列表、删除、重新索引和知识库创建/切换/删除（聊天命令 + 内嵌按钮）
• 同名文档重新上传自动作为新版本入库，成功后替换旧版本；失败保留旧版
• 文件哈希去重；上传失败自动清理向量与文件
• 支持 PDF / DOCX / Markdown 文档上传
• PDF 自动分流：文字型 → PyMuPDF，扫描/图片型 → PaddleOCR（CPU）
• BAAI/bge-base-zh-v1.5 中文 Embedding（GPU）
• 检索结果精确引用到文件名 + 页码 + chunk；证据不足时明确拒答
• DeepSeek 流式回答；网络/超时/限流/认证错误显示中文友好提示
• AGPL-3.0-or-later

环境要求

• Python 3.12
• NVIDIA GPU + CUDA 12.6（Embedding）
• DeepSeek API Key

快速开始

# 激活虚拟环境
.\.venv\Scripts\Activate.ps1

# 配置 API Key（编辑 .env 填入真实密钥）
# DEEPSEEK_API_KEY=sk-xxx

# 安装依赖
uv sync

# 修复 Windows SSL 证书问题（仅首次）
python -m pip install pip-system-certs

# 启动应用
$env:PYTHONPATH = "D:\RAG"
chainlit run app/main.py --port 8000

# 质量检查
ruff check app tests && mypy app && pytest -q

注意：启动前必须设置 $env:PYTHONPATH 指向项目根目录，否则 Chainlit 无法加载 app 包。

使用指南

启动后打开浏览器访问 http://127.0.0.1:8000：

命令	说明
/文档	查看当前知识库的文档列表（每篇附删除 / 重新索引按钮）
/知识库	查看全部知识库（附切换 / 删除按钮，删除需二次确认）
/新建知识库 <名称>	创建并切换到新知识库
/切换 <名称>	切换到指定知识库
/帮助	显示全部命令

• 直接拖入文件即可上传入库（首次上传自动创建「默认知识库」）。
• 上传同名文件且内容不同时，自动作为新版本入库；新版本成功后替换旧版本。
• 重新索引从已保存的原始文件重建全部向量，适用于调整分块参数或修复失败状态。
• 问答基于当前知识库，回答随生成过程流式显示，引用附在回答之后。

配置项（.env / 环境变量）

常用可调配置（其余见 app/core/config.py）：

DEEPSEEK_API_KEY=            # 必填
DEEPSEEK_MODEL=deepseek-v4-flash
RETRIEVAL_TOP_K=10           # 检索候选数量
MIN_RELEVANCE_SCORE=0.45     # 低于该相关性的片段被过滤
CHUNK_SIZE=512               # 分块大小（字符近似 token）
CHUNK_OVERLAP=64             # 分块重叠（必须小于 CHUNK_SIZE）
EMBEDDING_DEVICE=cuda        # Embedding 设备（OCR 固定使用 CPU）

升级提示：若存在旧版本创建的 Chroma collection（距离度量不是 cosine）， 请删除 data/chroma 下对应目录并重新索引，否则相关性分数含义不一致。

项目结构

app/
├── core/              # 配置、领域模型、协议接口、启动检查
├── parsers/           # PDF / DOCX / Markdown 解析 + OCR 分流
├── embedding/         # BGE Sentence-Transformer
├── storage/           # ChromaDB 向量存储 + 文件存储
├── llm/               # DeepSeek OpenAI 兼容客户端（重试 + 流式 + 错误映射）
├── repositories/      # SQLite 元数据仓库
├── services/          # 入库管线 + 检索问答编排 + 删除/重索引
└── chainlit_handlers/ # Chainlit 事件处理 + 管理命令
data/
├── uploads/           # 上传文档
├── chroma/            # ChromaDB 向量数据
└── metadata.db        # SQLite 元数据
models/                # 模型缓存（HuggingFace / PaddleOCR）
tests/                 # 测试（pytest -q 运行，含 slow 标记的模型加载测试）

开发

ruff check app tests && mypy app && pytest -q