MimirQ
可观察、可替换、可回归的企业 RAG 基础设施
中文优先 · 从文档解析到证据引用，每一步都能检查输入、输出与版本
项目定位 · 产品界面 · 快速开始 · 平台对比 · 800 题实测 · 完整文档
为什么做 MimirQ
企业知识库真正难的，不是把文档向量化，而是让错误可定位、策略可替换、质量可回归。
| 可检查 | 可替换 | 可回归 |
|---|---|---|
| 查看解析、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 init
make 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 运行基础设施 |
方式一：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 配置。
方式二：本地源码运行（Python venv + pip + pnpm）
这是常见的本地开发方式，无需 Conda。FastAPI 运行在 Python .venv 中，Next.js 由 pnpm 启动；Docker 只运行 PostgreSQL、Redis、Milvus 等基础设施：
make setup-host
make 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 步骤见开发文档，可选政务示例见插件说明。
Dify 接入
MimirQ 可作为 Dify 的可治理 RAG 层接入现有应用，不重复实现工作流画布。当前支持两种方式：
- External Knowledge API：Dify 负责编排与生成，MimirQ 负责文档治理、检索、重排、权限过滤和证据返回。
- Workflow HTTP 节点：Dify 负责自定义路由与参数，MimirQ 按指定知识范围返回证据和 Trace。
Workflow HTTP 节点
真实 Dify HTTP 子链（已脱敏）：安全构造 JSON 请求 → HTTP 节点调用 MimirQ retrieval endpoint → 转换结果 → 合并知识证据。
External Knowledge API
真实 Dify Chatflow（已脱敏）：绿色知识检索节点通过 External Knowledge API 调用 MimirQ，再统一合并证据；点击查看原图。
图中的地区路由来自可选示例插件；MimirQ 核心不内置地区、事项或行业规则。
Dify 标准外部知识库端点为 POST /api/v1/integrations/dify/retrieval；可选用 `POST /api/v1/integrations/dify/conversation-t