企业知识库真正难的，不是把文档向量化，而是让错误可定位、策略可替换、质量可回归。
| 可检查 | 可替换 | 可回归 |
|---|---|---|
| 查看解析、Chunk、召回、重排与引用证据 | 按文档和场景切换解析器、索引、检索与模型 | 用 Golden 题集、质量门禁和 Trace 守住版本质量 |
MimirQ 起源于真实的政务知识库交付。回答出错时，团队需要快速判断问题究竟来自解析、治理、切块、召回、重排，还是生成偏离引用。把整条链路藏在一个“上传并开始问答”的按钮后面，原型很快，长期交付却难以估算、验收和治理。
一条可控的企业知识流水线
数据评估→场景化解析→清洗治理→业务切块
→向量 / 全文索引→混合召回→重排与引用→Golden 回归
真实项目应先抽样评估数据，再按材料选择解析器：复杂版式或扫描件可比较 MinerU / DeepDoc，公式、表格与版面结构密集的资料可评估 Docling，数字原生 Office 或纯文本可从 MarkItDown 等轻量路径开始。高风险资料仍需人工校验。
解析结果经脚本、规则 DSL 或插件治理后，再按标题、章节、业务记录或父子关系切块，而不是统一套用固定长度和重叠窗口。索引层可使用 Milvus 等向量库，并组合 BM25、向量检索与重排；上层应用可以是 Dify、LangGraph、PydanticAI 或一个简单 API 服务。
| 你的目标 | 更合适的选择 |
|---|---|
| 业务简单、流程稳定、低代码优先 | Dify、FastGPT 等应用平台通常更快 |
| 一体化使用 DeepDoc 与 GraphRAG | RAGFlow 是成熟选择 |
| 知识链路需要按业务替换、审计和回归 | 使用 MimirQ，或把它作为 Dify 的外部知识层 |
当前仓库覆盖 30 个解析后端、86 种切块策略、13 类重排器，并保留固定 800 题的实测证据。数字只是实现广度，核心是每一步都能检查输入输出、追溯引用与版本，并用 Golden 题集守住发布质量。完整方法见企业知识流水线设计准则。
以下界面使用仓库内公开的政务插件演示样例生成，不含生产知识库数据。
知识图谱 在同一画布中检索和分析实体、事件与关系。 |
|
知识库管理 集中查看数据集、文档、Chunk 与入库状态。 |
数据治理 在同一工作台完成文档预览、质量检测、清洗与标注。 |
入库执行监控 按数据集观察解析、切块、治理、导出和失败重试状态。 |
Golden 回归评测 标准问答、运行记录与 Recall / MRR 等指标同屏可查。 |
更多界面与完整操作流程见用户指南。
- Docker 20.10+ 与 Docker Compose 2.0+
- GNU Make；Docker 一键启动另需 Python 3.9+ 生成配置
- 源码开发模式另需 Python 3.11+、Node.js 20+ 与 pnpm 10.26
- 至少 4 核 CPU / 16 GB RAM / 50 GB 磁盘
git clone --depth 1 --single-branch https://github.com/skygazer42/MimirQ.git
cd MimirQ
make initmake init 只创建缺失的 .env 和 web/.env.local，不会覆盖已有配置。编辑 .env，按部署场景填写：
- 默认模型调用：
LLM_API_KEY（必填） - 自定义 LLM：
LLM_API_BASE、LLM_MODEL - 独立 Embedding：
EMBEDDING_API_BASE、EMBEDDING_API_KEY、EMBEDDING_MODEL - 启用 Reranker：
ENABLE_RERANKER、RERANKER_API_BASE、RERANKER_API_KEY、RERANKER_MODEL - 自动创建首个管理员：
INITIAL_ADMIN_EMAIL、INITIAL_ADMIN_USERNAME、INITIAL_ADMIN_PASSWORD
字段取值、独立模型服务和管理员初始化规则见模型服务与首次管理员配置。
启动后如何创建数据集、上传解析、检查切块、验证检索和引用，以及后续治理、评测、Dify 与运维，见完整操作指南。
| 启动方式 | 适用场景 | 应用运行位置 |
|---|---|---|
| Docker 一键启动（推荐） | 首次体验、服务器部署 | 前端、API、Worker 与依赖服务均在容器中 |
| 源码开发模式 | 前后端开发、热更新调试 | .venv + pip 运行 API，pnpm 运行 Web；Docker 运行基础设施 |
make up-web
make api-ping启动后访问 http://localhost:3000；未预置管理员时，在页面注册首个账户。首次构建、代理、生产凭据和网络配置见 Docker Compose 部署指南。
停止使用 make down；清空持久化数据使用 make docker-reset；连同本项目服务镜像删除使用 make docker-purge。MimirQ 固定使用独立的 mimirq Compose 项目名，不会把同机 Dify 当成本项目；后两项不可恢复。Windows PowerShell、容器归属检查、旧版数据迁移、误删恢复和精确删除范围见 Docker Compose 部署指南。
默认使用内置 DeepDoc。其他解析器仅在业务需要时启动：
| 文档场景 | 建议解析器 | 额外要求 | 启动命令 |
|---|---|---|---|
| 常规 PDF / Office / 文本 | 内置 DeepDoc | 无 | 无需额外容器 |
| 表格、公式与复杂版式，多格式 CPU 解析 | Docling Serve | CPU；独立重型镜像，不进入 MimirQ 主镜像 | make up-docling |
| 表格、公式、OCR 与复杂版式 GPU 解析 | Docling Serve CUDA | NVIDIA GPU；默认 CUDA 12.8 | make up-docling-gpu |
| PDF 转 Markdown，服务器无 GPU | Marker | CPU | make up-marker |
| 版面、表格与图片混合文档 | ETL4LLM | CPU | make up-etl4llm |
| 扫描件、OCR、复杂版面 | PaddleOCR-VL | NVIDIA GPU，建议预留 10 GiB | make up-paddlevl |
| 表格、公式与图片较多的 PDF | MinerU pipeline | NVIDIA GPU、首次下载模型 | make up-mineru |
| VLM 复杂 PDF | MinerU VLM | NVIDIA GPU，资源占用较高 | make up-mineru-vlm |
| 高精度 PDF OCR | olmOCR | NVIDIA GPU，建议 48 GiB 级显存 | make up-olmocr |
| 公式 / 表格 PDF 转 Markdown | MagicPDF | NVIDIA GPU | make up-magicpdf |
| PDF / 图片走外部视觉 OCR | Qianfan-OCR | 上游 URL 与 API Key，本地无需 GPU | make up-qianfanocr |
Docling 说明：重依赖与模型只存在于独立容器；CPU / GPU profile 共享 5001 端口，不能同时启动。GPU 镜像约 11.13 GB；本仓库已在 RTX 3070 Ti 8 GiB 上验证 PDF、DOCX、Markdown 表格和
ParserFactory无回退链路。源码开发命令、实测边界与 CUDA 配置见 Docling Serve 配置。
这是常见的本地开发方式，无需 Conda。FastAPI 运行在 Python .venv 中，Next.js 由 pnpm 启动；Docker 只运行 PostgreSQL、Redis、Milvus 等基础设施：
make setup-hostmake setup-host 会创建 .venv、执行 pip 与 pnpm 依赖安装、准备解析模型并启动 Docker 基础设施。默认使用 API 进程内后台任务，只需打开两个终端：
# 终端 1：FastAPI（热更新）
make backend
# 终端 2：Next.js（热更新）
make web启用独立 Worker 的配置见模型服务与首次管理员配置。验证主机前后端：
make api-ping结束主机进程后，执行 make infra-down 停止依赖服务。
| 服务 | 地址 |
|---|---|
| 前端 UI | http://localhost:3000 |
| API 文档 | http://localhost:8000/docs |
低资源模式可使用
make up-lite，它用 Chroma/FAISS 替代 Milvus、免 MinIO，默认不含前端；适合验证 APIready与make core-e2e最小闭环。需要 UI 时另运行make web，或改用make up-web。外部 LLM/Embedding 调用仍需对应模型供应商密钥。
高级模型、解析器和代理配置见 .env.example。更换 Embedding 模型后必须重建已有知识库索引；更多平台与 Windows 步骤见开发文档，可选政务示例见插件说明。
MimirQ 可作为 Dify 的可治理 RAG 层接入现有应用，不重复实现工作流画布。当前支持两种方式：
- External Knowledge API：Dify 负责编排与生成，MimirQ 负责文档治理、检索、重排、权限过滤和证据返回。
- Workflow HTTP 节点：Dify 负责自定义路由与参数，MimirQ 按指定知识范围返回证据和 Trace。
真实 Dify HTTP 子链（已脱敏）：安全构造 JSON 请求 → HTTP 节点调用 MimirQ retrieval endpoint → 转换结果 → 合并知识证据。
真实 Dify Chatflow（已脱敏）：绿色知识检索节点通过 External Knowledge API 调用 MimirQ，再统一合并证据；点击查看原图。
图中的地区路由来自可选示例插件；MimirQ 核心不内置地区、事项或行业规则。
Dify 标准外部知识库端点为 POST /api/v1/integrations/dify/retrieval；可选用 POST /api/v1/integrations/dify/conversation-turns 回传答案、引用与会话标识。knowledge_id 默认必须显式配置在 DIFY_EXTERNAL_KNOWLEDGE_MAP_JSON 中。配置见 .env.example，部署前校验见 readiness gate，实测结果见真实场景验证。
| 功能维度 | MimirQ | Dify | RAGFlow | FastGPT | AnythingLLM | LangChain |
|---|---|---|---|---|---|---|
| 文档解析 | 30 种解析后端：PDF、OCR、版式、表格、公式、VLM | Knowledge Pipeline；PDF、PPT 等常见格式 | DeepDoc；复杂版式、扫描件、MinerU / Docling | PDF、扫描件、表格、公式转 Markdown | PDF、TXT、DOCX 等文档管道 | Document Loaders 与第三方解析器集成 |
| 切块能力 | 86 种策略：递归、语义、父子、RAPTOR、Late Chunking；可视化预览 | 通用、父子、Q&A 与可编排处理 | 模板化切块；支持可视化人工干预 | 自动、手工、Q&A 与增强处理 | 文档管道自动分块 | Text Splitters；由应用代码组合 |
| 检索 / 重排 | Milvus / FAISS / Chroma + BM25 / SPLADE / ColBERT / LTR / RRF；13 种重排器 | 语义、全文、混合检索；可配置 rerank | 多路召回 + 融合重排 | 语义、全文、混合检索 + RRF + rerank | 多种向量库检索 + 来源引用 | Retriever / reranker 组件；自行编排 |
| 知识图谱 | 实体、关系、事件抽取；实体消解、社区发现与多跳检索 | 通过工作流、插件或外部服务接入 | 内建 GraphRAG | 通过工作流或外部服务接入 | 通过 Agent / Tool 外接 | 图数据库集成与自定义链路 |
| Agent / MCP | LangGraph Agent、Self-RAG / CRAG / FLARE；MCP client / server | Function Calling / ReAct Agent、工具与 MCP | Agentic Workflow、MCP、代码执行器 | Agent V2、工具、MCP 与 VM 执行 | No-code Agent Builder、MCP、定时任务 | Agents / LangGraph / MCP；代码优先 |
| 可视化工作流 | 无通用节点画布；专注 RAG 调试、治理页面与 API | 核心能力：应用 / Agent 节点编排 | Agent 与入库 Pipeline 编排 | 核心能力：Flow 节点编排 | No-code Agent Builder | 无内建产品 UI；由应用实现 |
| 评测 / 治理闭环 | RAGAS、回归门禁、Leaderboard、显著性检验、证据审计 | 运行日志、观测与人工标注 | 检索测试、切块检查与引用追溯 | 运行详情、检索调试与日志 | 来源引用；无内建 RAG 回归门禁 | 需另接 LangSmith 或自建评测 |
| 安全 Guard | InputGuard / OutputGuard、PII / Secret 脱敏、SSRF 逐跳校验 | 内容审查节点与工作流规则 | 代码执行沙箱；业务 Guard 需配置 | 工作流内容审查与 VM 沙箱 | Local-first、Agent 工具权限 | 由应用中间件与部署边界实现 |
| 企业权限 / 合规 | 文档 ACL + Security Trimming、RBAC、SCIM / SSO / SAML、审计 | Workspace 权限；企业版组织与 SSO | 账号与 API 鉴权；细粒度合规需按部署建设 | ABAC + RBAC；团队、群组与资源权限 | Docker 版多用户与权限控制 | 框架本身不提供；由应用实现 |
| RAG 调试可视化 | 切块预览、检索 Trace、重排过程、逐句引用、KG、评测看板 | Dataset 测试、Workflow Trace 与应用日志 | 切块可视化、命中片段与引用 | 知识库测试、Workflow 运行详情 | Workspace、来源引用与聊天 UI | 无内建 UI；可另接观测平台 |
| Dify 外部知识库 | 原生兼容 Dify External Knowledge API | 原生消费外部知识库 | 需通过 API 适配 | 需通过 API 适配 | 需通过 API 适配 | 自行实现适配器 |
| 开箱方式 | Docker Compose / Helm；完整企业 RAG 栈 | Docker Compose / Cloud | Docker Compose；官方建议 4C / 16 GB / 50 GB | Docker / Cloud | Desktop / Docker | Python / JS 库；需自行组装应用 |
对比基于各项目公开版本与官方文档（2026-07），描述的是仓库直接提供的能力表面，不是统一 benchmark。插件、商业版和后续版本可能改变结果。
MimirQ 已用于市级政务智能问答助手，覆盖 7 个区域级 + 1 个市级知识库。2026-07-27 使用同一固定 800 题和真实自托管模型复测，五条链路最终均无失败：
| 链路 | 成功执行 | 准确 / 部分准确 / 证据不足 |
准确率 / 可用率 | 证据覆盖 | 平均 / P50 / P95 |
|---|---|---|---|---|---|
| MimirQ 检索直连 | 800 / 800 | 791 / 9 / 0 | 98.9% / 100% | 99.5% | 3.64s / 2.02s / 12.58s |
| 真实 Embedding + Reranker + LLM | 800 / 800 | 727 / 73 / 0 | 90.9% / 100% | 99.7% | 2.59s / 1.53s / 8.15s |
| Dify HTTP → MimirQ | 800 / 800 | 514 / 223 / 63 | 64.3% / 92.1% | 96.3% | 13.15s / 12.93s / 17.33s |
| Dify External → MimirQ | 800 / 800 | 502 / 232 / 66 | 62.7% / 91.7% | 99.7% | 12.14s / 11.17s / 23.49s |
| Dify 原生知识库 | 800 / 800 | 309 / 287 / 204 | 38.6% / 74.5% | 83.8% | 13.67s / 11.34s / 29.55s |
直连输出检索证据，其他链路输出生成答案，因此准确率与延迟不是严格同任务横比。Dify HTTP / External 的证据覆盖为 96.3% / 99.7%，答案条款覆盖仅为 83.6% / 83.8%，主要损失在 Dify 生成编排而不是 MimirQ 召回；Dify 原生知识库不经过 MimirQ。
并发 5 直连首轮触发 15 次配置化 admission backpressure，降至并发 3 仅重试失败题后恢复为 800 / 800。MimirQ 没有加入地区、事项或题目特判；不同 Embedding runtime 的多库请求由通用检索层分片处理。
完整方法、指标解释与历史复测 · Dify 接入方式与真实工作流
支持以下部署方式：
| 方式 | 命令 | 说明 |
|---|---|---|
| 标准部署 | make up |
完整栈：Postgres + Milvus + Etcd + MinIO + Redis + API + Worker |
| 标准 + 前端 | make up-web |
推荐首次启动；自动初始化本地配置并启动完整 Web 栈 |
| 轻量模式 | make up-lite |
Chroma/FAISS 替代 Milvus，无需 MinIO，适合快速体验 |
| 开发模式 | make infra-up |
仅基础设施，后端/前端本地运行 |
| Helm / K8s | helm install |
生产级部署，含 HPA、PDB、CronJob、PrometheusRule |
| 解析器扩展 | Docker Compose 指南 | 按需启动 CPU / GPU profile |
生产配置和升级顺序见 Docker Compose 指南、Helm 部署文档 和 运维手册。
| 指南 | 说明 |
|---|---|
| 切片预览 | 可视化文档分块效果与参数调整 |
| 知识图谱 | KG 抽取、可视化与 RAG 增强 |
| 文档 ACL | 文档级访问控制与 Security Trimming |
| URL 导入 | 远程 URL 抓取与批量导入 |
| 文档版本 | Pipeline 版本管理与回滚 |
| 稀疏检索 | SPLADE 稀疏检索通道 |
| ColBERT 重排 | ColBERT 晚交互重排序 |
| RAG 优化 | 检索效果与回答质量优化 |
| 检索排障 | 检索问题诊断 |
| SAML SSO | SAML 单点登录集成 |
| 快速开始 | 从源码开发部署 |
| 运维手册 | 生产运维与排障 |
提交前建议运行一键自检（后端 + 前端），与 CI 保持一致：
# 完整自检（后端 lint/test + 前端 lint/test）
make enterprise-checks
# 仅后端
make verify && make test
# 仅前端
cd web && pnpm lint && pnpm test
# 浏览器核心路径（上传/解析/对话 UI + 前端到真实后端）
make test-core-browser-smoke任一部署方式启动并在网页注册账号后，可将该账号写入本地 .env 的 MIMIRQ_SMOKE_IDENTIFIER 与 MIMIRQ_SMOKE_PASSWORD，再运行同一套知识库核心闭环门禁。它验证就绪、入库、解析与检索证据，不依赖 LLM，并在成功后删除临时数据集。不要在需要人工注册的环境中使用 CORE_E2E_BOOTSTRAP_REGISTER=1，因为首个管理员创建后会关闭公开注册：
make core-e2e
# 远程或非默认端口：CORE_E2E_BASE_URL=http://host:8000 make core-e2e已有同请求量的串行与并发负载报告时，可验证并发是否真正提高批量吞吐，而不只是客户端同时发起请求：
RAG_CONCURRENCY_BASELINE=/tmp/c1.json \
RAG_CONCURRENCY_CANDIDATE=/tmp/cN.json \
make rag-concurrency-gate已交付能力见上方对比表。近期计划：
- RAG 专用调试编排（非通用 Agent 画布）
- 更多数据源连接器（Confluence / S3 / Notion）
- 跨语言检索
- 统一 LLM-as-Judge（G-Eval + Self-Consistency）
路线图、功能请求与投票通过 GitHub Issues 管理。
贡献代码、报告问题或提交功能建议前，请阅读 CONTRIBUTING.md。本地开发流程见快速开始，提交前运行 make enterprise-checks。
本项目采用 Apache License 2.0。第三方组件（含 vendored 自 RAGFlow/DeepDoc 的代码及构建时下载的模型权重）的归属声明见 NOTICE。
PyMuPDF (AGPL-3.0) 说明：默认 PDF 解析可能使用 PyMuPDF，其协议为 AGPL-3.0 / 商业双授权。以 SaaS 形式提供服务时，AGPL 网络条款可能要求公开整个组合作品的源码。需要避免该约束时，请改用宽松协议的解析后端（pypdf / pdfplumber）。详见 NOTICE。
MimirQ 构建于优秀的开源生态之上，感谢以下项目：
Dify · RAGFlow · FastAPI · LangChain · LangGraph · Milvus · Next.js · PostgreSQL · RAGAS · PyMuPDF · MinerU · Tailwind CSS · shadcn/ui