DocMind

DocMind

为什么选择 DocMind

项目功能

RAG 引擎

三档处理模式

# 绕过 ainsert() 的 KG 阶段,直接操作 LightRAG 的存储层
chunks = lightrag.chunking(text_content) # 1. 分块
embeddings = await lightrag.embedding_func(chunks) # 2. Embedding(1 次 API 调用)
for chunk, vec in zip(chunks, embeddings): # 3. 批量 upsert(无 KG)
 await lightrag.chunks_vdb.upsert(chunk_id, vec, {...})

五模式查询

自适应检索(RF-Mem 启发)

Agentic 检索(PageIndex 风格)

上下文管理(ContextManager v2)

MCP 集成

暴露的能力

传输协议

客户端配置

{
 "mcpServers": {
 "docmind": {
 "url": "http://localhost:8000/mcp"
 }
 }
}

{
 "mcp.servers": {
 "docmind": {
 "url": "http://localhost:8000/mcp"
 }
 }
}

快速开始

环境要求

1. 克隆项目

git clone https://github.com/lxcshine/DocMind.git
cd DocMind

2. 后端配置

cd backend
# 创建虚拟环境
conda create -n docmind python=3.11
conda activate docmind
# 安装依赖
pip install -r requirements.txt
# 配置环境变量
cp .env.example .env
# 编辑 .env,填写以下必填项:
# GEMINI_API_KEY=your_api_key
# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
# GEMINI_MODEL=gemini-2.5-flash
# MYSQL_HOST=localhost
# MYSQL_PASSWORD=your_password

3. 启动后端

cd backend
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

4. 启动前端

cd frontend
npm install
npm run dev

5. 访问

Docker部署

# 确保 backend/.env 已配置
docker compose up -d
# 查看状态
docker compose ps
# 查看日志
docker compose logs -f backend

Kubernetes部署

前置条件

目录结构

k8s/
├── deploy.sh # 一键部署脚本
├── base/
│ ├── kustomization.yaml # Kustomize 基础入口
│ ├── namespace.yaml # Namespace 定义
│ ├── configmap.yaml # 非敏感配置
│ ├── secret.yaml # 敏感配置 (API Keys, 密码)
│ ├── pvc.yaml # 持久化卷声明
│ ├── mysql.yaml # MySQL StatefulSet + Service
│ ├── backend.yaml # Backend Deployment + Service + PDB
│ ├── frontend.yaml # Frontend Deployment + Service + PDB
│ ├── ingress.yaml # Ingress (TLS + SSE 支持)
│ ├── hpa.yaml # HPA 自动扩缩容
│ └── networkpolicy.yaml # 网络安全策略
└── overlays/
 └── production/
 └── kustomization.yaml # 生产环境 Overlay

快速部署

stringData:
 GEMINI_API_KEY: "your-actual-api-key"
 VISION_API_KEY: "your-actual-api-key"
 EMBEDDING_API_KEY: "your-actual-api-key"
 MYSQL_ROOT_PASSWORD: "your-strong-root-password"
 MYSQL_PASSWORD: "your-strong-user-password"

# 构建镜像
docker build -t your-registry/docmind-backend:v1.0.0 ./backend
docker build -t your-registry/docmind-frontend:v1.0.0 ./frontend
# 推送到镜像仓库
docker push your-registry/docmind-backend:v1.0.0
docker push your-registry/docmind-frontend:v1.0.0

images:
 - name: docmind-backend
 newName: your-registry/docmind-backend
 newTag: v2.0.0
 - name: docmind-frontend
 newName: your-registry/docmind-frontend
 newTag: v2.0.0

# 开发环境
kubectl apply -k k8s/base/
# 生产环境(更多副本、更大资源、cert-manager TLS)
kubectl apply -k k8s/overlays/production/
# 或使用部署脚本
chmod +x k8s/deploy.sh
./k8s/deploy.sh deploy dev # 开发环境
./k8s/deploy.sh deploy prod # 生产环境

kubectl get all -n docmind
kubectl logs -f deployment/backend -n docmind

高可用设计

零停机滚动更新

strategy:
 type: RollingUpdate
 rollingUpdate:
 maxSurge: 1 # 先创建 1 个新 Pod
 maxUnavailable: 0 # 始终不低于期望副本数

数据持久化

自动扩缩容(HPA)

# 查看 HPA 状态
kubectl get hpa -n docmind
# 查看扩缩事件
kubectl describe hpa backend-hpa -n docmind

网络安全(NetworkPolicy)

安全加固

灾难恢复

# 手动备份
kubectl exec mysql-0 -n docmind -- \
 mysqldump -u root -p$MYSQL_ROOT_PASSWORD \
 --single-transaction --routines --triggers docmind > backup.sql
# 使用部署脚本
./k8s/deploy.sh backup

# 安装 Velero
velero install --provider aws --bucket velero-backups --secret-file ./credentials
# 创建定时备份
velero schedule create docmind-daily \
 --schedule="0 2 * * *" \
 --include-namespaces docmind \
 --ttl 720h
# 灾难恢复
velero restore create --from-schedule docmind-daily

Kustomize Overlay 说明

常用运维命令

# 查看所有资源状态
kubectl get all,pvc,hpa,ingress -n docmind
# 查看滚动更新状态
kubectl rollout status deployment/backend -n docmind
# 查看特定 Pod 日志
kubectl logs -f deployment/backend -n docmind --tail=200
# 进入 Backend Pod 调试
kubectl exec -it deployment/backend -n docmind -- /bin/bash
# 手动扩缩容
kubectl scale deployment/backend --replicas=4 -n docmind
# 回滚到上一版本
kubectl rollout undo deployment/backend -n docmind
# 查看事件(排查调度问题)
kubectl get events -n docmind --sort-by='.lastTimestamp'
# 检查 PVC 绑定状态
kubectl get pvc -n docmind -o wide

项目结构

DocMind/
├── backend/ # 后端 (FastAPI)
│ ├── main.py # 应用入口:FastAPI 实例、中间件栈、路由注册、MCP 挂载
│ ├── api/ # API 层
│ │ ├── chat.py # 对话 API:KB/Direct 模式、SSE 流式、多会话管理
│ │ ├── documents.py # 文档管理 API:上传、处理进度、列表、删除
│ │ ├── memory.py # 记忆 API:CRUD、开关、知识提取配置
│ │ ├── ocr.py # OCR API:PDF/图片/PPT → Tesseract + LLM 纠错
│ │ └── search.py # 搜索 API:多引擎搜索 → 深度抓取 → LLM 综合
│ ├── core/ # 核心业务层
│ │ ├── raganything.py # RAG-Anything 封装:文档解析 + 多模态 + 查询
│ │ ├── context_manager.py # 上下文管理器 v2:分层摘要 + 指令持久化 + 去重
│ │ ├── agentic_retrieve.py # Agentic 检索:PageIndex 风格工具调用 Agent
│ │ ├── tree_index.py # 树形文档索引:层级结构树,按页/按节点检索
│ │ ├── adaptive_retrieval.py # 自适应检索:RF-Mem 熟悉度评估 + 双路径切换
│ │ ├── mcp_server.py # MCP Server:7 Tools + 2 Resources + 1 Prompt
│ │ ├── doc_handler.py # 文档处理器:Upload → MinerU → LightRAG 管道
│ │ ├── batch_processor.py # 批量处理器:Semaphore 并发 + 进度追踪 + 重试
│ │ ├── chat_history.py # 对话历史:aiomysql 异步连接池
│ │ ├── memory.py # 记忆服务:LLM 知识提取 + 语义索引 + SQLite
│ │ ├── meta_store.py # 元数据存储:SQLite WAL 模式
│ │ ├── context_extractor.py # 上下文提取器:页级/块级上下文窗口
│ │ ├── modal_processors.py # 多模态处理器:图片/表格/公式 VLM 分析
│ │ ├── ocr_handler.py # OCR 处理器:Tesseract + LLM 纠错管道
│ │ ├── parser.py # 文档解析器:PyMuPDF + LLM TOC 检测
│ │ ├── progress.py # 进度追踪器:SQLite 持久化
│ │ ├── prompt_templates.py # Prompt 模板注册中心
│ │ └── web_scraper.py # 网页抓取引擎:多引擎策略 + 自动降级
│ ├── infrastructure/ # 基础设施层
│ │ ├── llm_client.py # LLM 客户端:Tenacity 重试 + Fallback + Token 计费
│ │ ├── reranker.py # Cross-Encoder 重排序 + 三明治重排
│ │ ├── token_counter.py # Token 计数器:tiktoken 精确 + 字符启发式
│ │ ├── tracing.py # 链路追踪:OpenTelemetry 风格 Trace/Span
│ │ ├── state_db.py # SQLite 持久化状态层
│ │ ├── errors.py # 全局异常处理 + Correlation ID
│ │ ├── logging.py # 结构化 JSON 日志
│ │ ├── response.py # 标准化 API 响应
│ │ ├── security.py # 安全中间件:API Key + 响应头 + IP 白/黑名单
│ │ └── validation.py # 请求验证 + 滑动窗口限流
│ ├── config/
│ │ └── settings.py # 全局配置:LLM、数据库、存储路径、MCP
│ ├── Dockerfile # 后端容器构建
│ └── .env.example # 环境变量模板
│
├── frontend/ # 前端 (React 18 + Ant Design 5)
│ ├── src/
│ │ ├── main.tsx # 入口:BrowserRouter + Ant Design 中文国际化
│ │ ├── App.tsx # 路由定义:5 个页面
│ │ ├── index.css # 设计系统 v2:CSS 变量体系 + Ant Design 覆盖
│ │ ├── layouts/
│ │ │ ├── MainLayout.tsx # 主布局:可折叠 Sider + Header + Content
│ │ │ └── MainLayout.css # 布局样式
│ │ ├── pages/
│ │ │ ├── Chat/ # 智能对话:KB/Direct 模式、SSE 流式、Markdown+KaTeX
│ │ │ ├── KnowledgeBase/ # 知识库管理:上传、3 种处理模式、批量导入
│ │ │ ├── Search/ # 深度搜索:多引擎 → 抓取 → AI 分析
│ │ │ ├── Memory/ # 记忆管理:4 种类型、开关、配置
│ │ │ └── OCR/ # OCR 识别:Tesseract + LLM 纠错
│ │ ├── components/ # 共享组件
│ │ │ ├── BatchImportModal.tsx# 批量导入弹窗:5 步向导
│ │ │ ├── ErrorBoundary.tsx # 错误边界
│ │ │ ├── StatusTag.tsx # 状态标签
│ │ │ ├── EmptyState.tsx # 空状态占位
│ │ │ └── LoadingSpinner.tsx # 加载指示器
│ │ ├── services/
│ │ │ └── api.ts # API 客户端:类型安全 + Correlation ID + SSE 解析
│ │ └── types/
│ │ └── api.ts # TypeScript 类型定义(与后端 Pydantic 对齐)
│ ├── Dockerfile # 前端多阶段构建:node:20 → nginx
│ ├── nginx.conf # Nginx 配置:gzip + SPA fallback + API 代理
│ ├── vite.config.ts # Vite 构建配置
│ └── tailwind.config.js # Tailwind CSS 配置
│
├── docker-compose.yml # 全栈部署编排
└── README.md # 本文件

API 参考

文档管理

对话

搜索

记忆

OCR

MCP

环境变量

部署指南

本地开发

# 后端(热重载)
cd backend && uvicorn main:app --reload --port 8000
# 前端(热重载)
cd frontend && npm run dev

Docker Compose(推荐生产部署)

docker compose up -d

可选:本地 Ollama

技术栈

设计决策

为什么不用 ChromaDB?

为什么 MCP 用 Streamable HTTP 而不是 stdio?

为什么 ContextManager 不直接扩到 128k?

License

致谢

RAG-Anything

LightRAG