一个面向中型软件企业内部知识场景的、可迁移的 RAG 检索脚手架。 把文档摄取、权限、版本、混合检索、证据门控、引用校验和评测闭环一次搭好，未来替换业务文档即可复用。
作者主页：qq1069730908
DocMind 不是一个虚构的“已经服务某企业”的产品案例，也不是只展示聊天页面的 Demo。它是我的个人可迁移后端基线：以后遇到企业制度、研发手册、售后知识库、项目文档等具体业务，只需替换数据源、权限配置和模型端点，就能在现有工程骨架上继续开发，避免每次从零重写 RAG 基础设施。
当前项目适合描述为：
核心功能和工程骨架已完成，具备受控试生产基础；尚未通过正式企业生产发布验收。
质量结论和边界均以 项目交接总览 为准。
仓库提供一个可公开复现的软件企业知识助手场景：使用许可证明确的 PostHog Handbook 作为制度与 SOP 参考语料，模拟员工查询入职、协作、会议、远程办公等内部规则。
这个场景只用于验证工程链路，不冒充真实客户资料、真实员工或生产用户。换成其他企业场景时，核心代码无需重写：
公开/客户授权文档
|
v
目录或 Git 快照导入 -> 解析/分块 -> Embedding -> Qdrant
|
v
员工问题 -> 混合检索 -> 证据门控 -> 生成答案 -> [S1] 引用校验
导入示例见 scenarios/software-handbook。
- Dense + Sparse 混合检索，使用 RRF 融合，再进行 Rerank。
- 检索结果严格绑定 kb_id 和 PostgreSQL 中的 Active Revision，避免召回错误知识库或失效版本。
- 无证据时不调用生成模型；最多进行一次受限查询改写，仍无证据则拒答。
- 生成回答必须带行内 [S1] 形式来源；非法引用会被标记为未验证，而不是静默放行。
- 文档正文被当作不可信证据，不执行其中的指令，降低 Prompt Injection 风险。
- 解析器、存储、向量库、Embedding、Reranker 和 LLM 通过模块边界隔离。
- 使用 source_key、不可变 Revision、SHA-256 和 source_metadata 保留文档身份与来源追溯。
- 目录/Git 快照导入支持增量识别新增、变更和待人工确认的删除。
- Docker Compose 适合单企业单机私有化部署；后续可替换为对象存储、外部身份系统或分布式 Worker。
- 提供公开年报数据集、问题集、引用复核队列和检索阶段诊断脚本。
- 评测结果绑定数据集版本、模型配置和代码版本，历史结果不被覆盖。
- v0.3 诊断定位出主要损失来自 Reranker Top-K 的文档拥挤，而非简单归因于“模型不够强”。
| 领域 | 已实现能力 |
|---|---|
| 身份认证 | 本地账号、Argon2 密码散列、短期 JWT、HttpOnly Refresh Cookie、轮换、登录限速、管理员 TOTP 基础能力 |
| 权限 | System Administrator、Knowledge Base Owner、Contributor、Reader；用户直授和部门继承；最后一个 Owner 保护 |
| 文档 | PDF、DOCX、PPTX、Markdown、TXT 文本优先解析；流式上传、SHA-256、异步摄取、状态和进度 |
| 版本 | Revision 不可变；只有成功处理的版本才会成为 Active Revision；失败版本不会替换线上版本 |
| RAG | BGE-M3 Dense、BM25 Sparse、Qdrant RRF、BGE Reranker、语义缓存、有界 LangGraph 工作流 |
| 对话 | 同步问答、SSE 流式输出、会话、反馈、来源片段展示 |
| 运维 | PostgreSQL、Redis、Qdrant、Celery、Alembic、健康检查、审计、备份/恢复脚本 |
| 前端 | React 18 + TypeScript，覆盖登录、知识库、文档、问答和设置页面 |
flowchart LR
A[用户问题] --> B[权限过滤]
B --> C[Dense 检索]
B --> D[Sparse 检索]
C --> E[RRF 融合]
D --> E
E --> F[Rerank]
F --> G{证据门控}
G -- 无证据 --> H[拒答]
G -- 有证据 --> I{已改写?}
I -- 否 --> J[最多一次查询改写]
J --> C
I -- 是 --> K[受约束生成]
K --> L[引用校验]
L --> M[答案 + 来源]
关键不变量：
- 检索范围同时受知识库权限和 Active Revision 约束。
- 没有可验证证据时，系统不得生成看似完整的答案。
- 查询改写是有界步骤，不会演化成开放式 Agent 循环。
- 引用必须指向本次检索结果中的来源，引用失败会降级为未验证来源。
flowchart TB
U[浏览器] --> F[Caddy + React]
F --> A[FastAPI API]
A --> P[(PostgreSQL)]
A --> R[(Redis)]
A --> Q[(Qdrant)]
A --> V[/uploads volume/]
W[Celery Worker] --> P
W --> R
W --> Q
W --> V
S[Celery Scheduler] --> R
| 层 | 选型 |
|---|---|
| API | Python 3.11、FastAPI、Pydantic v2 |
| 业务数据 | PostgreSQL 15、SQLModel、SQLAlchemy Async、Alembic |
| 异步任务 | Celery、Redis DB 0 |
| 缓存/会话 | Redis DB 1，noeviction |
| 向量检索 | Qdrant 1.10、BGE-M3、Jieba + BM25、RRF、BGE Reranker |
| 工作流 | LangGraph、LangChain Core、OpenAI-compatible 客户端 |
| 解析 | PyMuPDF、python-docx、python-pptx |
| 前端 | React 18、TypeScript、Vite、TanStack Query、Zustand |
| 入口 | Caddy，反向代理、TLS 和安全响应头 |
Copy-Item .env.example .env至少设置数据库密码、32 字符以上的 SECRET_KEY、管理员引导信息，以及实际使用的 LLM、Embedding 和 Reranker 端点。生产 HTTPS 部署还应设置 APP_ENV=production、AUTH_COOKIE_SECURE=true 和正式域名。
docker compose up -d --build
docker compose ps访问 Caddy 暴露的地址：
- Web UI：http://localhost/
- OpenAPI：http://localhost/docs
- 健康检查：http://localhost/api/v1/health
首次启动会执行 Alembic 迁移并创建引导管理员。确认管理员已创建后，应从 .env 删除 BOOTSTRAP_ADMIN_PASSWORD。
git clone --depth 1 https://github.com/PostHog/posthog.com.git .data/posthog.com
$env:DOCMIND_ACCESS_TOKEN = "<contributor access token>"
python scripts/import_directory.py --config scenarios/software-handbook/posthog.json --root .data/posthog.com --kb-id <knowledge-base-id> --dry-run先检查 dry-run 报告，再正式导入。导入器不会自动删除远端文件，只会生成 remove? 待确认项。
截至 2026-08-06，当前基线已验证：
| 门禁 | 结果 |
|---|---|
| 单元测试 | 52 passed |
| 真实 Qdrant RAG pipeline | 1 passed |
| 真实 PostgreSQL/Redis/Qdrant API 集成 | 29 passed |
| Alembic 空库迁移 | 0001 -> 0004 通过 |
| alembic check | No new upgrade operations detected |
| Ruff | python -m ruff check app tests scripts 通过 |
| Python 编译检查 | compileall 通过 |
| 前端构建 | npm run build 通过 |
| Compose | docker compose config --quiet、API 镜像构建通过 |
公开评测和历史结果见 evaluation。其中 v0.3 的公开年报集 Recall@5 为 86.99%，无答案正确拒答率为 100%；自动引用支持率为 56.09%，低于正式生产门槛，因此项目不会把自己包装成“已通过企业生产验收”。
python -m compileall -q app tests migrations
python -m pytest tests/unit -q
python -m pytest tests/integration -q -m integration
npm --prefix frontend run build
docker compose config --quiet
alembic check集成测试应使用名称以 _test 结尾的独立数据库，避免污染开发或生产数据。
app/modules/identity/ 用户、部门、认证
app/modules/knowledge/ 知识库、授权、文档和版本
app/modules/ingestion/ 解析、分块、索引任务
app/modules/retrieval/ 混合检索、Rerank、有界工作流、诊断
app/modules/conversation/ 会话、问答、缓存、反馈
app/modules/system/ 健康、指标、审计、维护
app/infrastructure/ 数据库、Redis、Qdrant、存储、AI 客户端
app/workers/ Celery Worker 和 Scheduler
frontend/ React 应用与 Caddy 镜像
scripts/ 导入、评测、诊断、备份恢复
tests/ 单元测试与真实基础设施集成测试
docs/adr/ 架构决策记录
当前版本有意保持轻量，不包含：
- SaaS 多租户隔离、OIDC/LDAP/Keycloak；
- Neo4j、GraphRAG、知识图谱、多 Agent 和外部工具执行；
- Kubernetes、自动故障切换、横向扩展和强制对象存储；
- 扫描件 OCR、复杂图表理解和机密数据外发的生产保证。
这些不是遗漏，而是单企业单机私有化基线的范围控制。扩展前应先补 ADR、容量测试、安全测试和迁移方案。
已实现并验证：核心身份、知识库权限、文档版本、文本摄取、混合检索、有界问答、引用门禁、Docker 基线和主要测试门禁。
已实现但仍需部署验证：部分生产降级、完整审计覆盖、管理员控制台、引用原文重新鉴权、备份加密与恢复演练。
正式发布前必须完成：第二位人工引用复核、v0.4 全量评测、并发性能、干净主机恢复、一版本回退、Prompt Injection 回归和模型供应商数据治理。
- 项目交接总览：当前真实状态、风险和接手清单
- 架构说明：模块边界和运行拓扑
- RAG 质量验收：指标、失败分析和门禁
- API 概览：认证、知识库、文档、检索和对话入口
- 部署与恢复：Compose、备份、恢复和发布约束
- 开发与测试：本地开发、测试和集成环境
- 作品集定位：岗位能力映射和可验证简历表述
- 场景导入：公开 handbook 数据源和导入命令
- 前后端交接：新窗口前端工作入口、API 契约和验收标准
简历或面试中可以这样描述：
独立设计并实现可迁移的单企业 RAG 检索脚手架，覆盖文档版本化摄取、知识库 RBAC、Dense/Sparse 混合检索、Rerank、证据门控、引用校验、SSE 问答和公开数据集评测；通过真实 PostgreSQL/Redis/Qdrant 集成测试验证核心链路，并保留失败样本和质量边界。
不要写成已有真实企业客户、真实用户规模、生产节省成本或正式生产上线，除非后续取得可公开的真实证据。
当前仓库尚未声明开源许可证。若公开发布，请先补充许可证和第三方语料归属说明。