导读
导读
KnowledgeHub 是一套单机自部署的多租户知识库服务,服务于一个具体的问题:办公文档、聊天记录、照片散落在各处,想「问一句话就定位到原文某页某段」。它把素材收进统一的库,切块、建四路索引(dense / sparse / trgm / visual,行文中统称四条腿),检索结果每条都带引用坐标,可以点回 PDF 的原始页与扫描页的页图。支持带引用的问答(SSE),并向 AI 客户端与别的 Agent 暴露 MCP 与 A2A 接口。
三条不能让步的需求构成了全部设计的约束:
| 需求 | 落地方式 |
|---|---|
| 可核验 | 引用做三级坐标(文档 → 页 → 归一化 bbox),前端乘回页图像素画框 |
| 不外传 | 生成层默认抽取式,答案句子全部摘自原文;接外部 LLM 必须显式配置,失败退回抽取式 |
| 可运维 | Postgres 任务表、一条巡检命令、备份只备事实、索引靠重建 |
明确不做:OCR(扫描件走视觉召回)、对象存储、Redis 或消息队列、k8s、细粒度 RBAC、多实例横向扩展。
亮点速览
- 四路混合检索 + 可解释降级:任一条腿不可用返回
skipped与原因,检索仍 200。调试面板摊开每一路的条数、耗时与跳过原因。skipped(没跑)与null(跑了零命中)是两个不同的值。 - 租户隔离收口:可见性判定全部在
services/common/auth.py。Qdrant 过滤与 PG 谓词同源。无权限与不存在同码(KB_NOT_FOUND)。 - L3 引用坐标:
bbox归一化 0~1,前端乘回页图像素画框。表格 chunk 带row/col,高亮到单元格。 - 六种切分策略 + 表格结构化:定长 / 递归 / 语义 / 父子块 / Late / Contextual。表格除 Markdown 外另存一份结构化网格(
table_json),前端渲染成真表格。 - 任务终态与进度:
jobs.progress是进度条的唯一来源。worker 在成功与失败两条路径上都结算文档状态。 - 契约治理:82 个端点声明、81 个实现、1 个决议不做。
eval/contract_check.py三向对账。1335 项 pytest 为门禁。
三条主链路
写入:上传 → 同步校验 → 内容寻址存储 → ingest 任务 → 解析 → 切分 → 嵌入 → 写两条文本腿 → 视觉任务与预览任务 → ready。
读取:检索 → 四条腿并发 → RRF 融合 → 软删过滤 → 路由偏好 → 精排 → 证据组装 → 生成 → 引用校验 → 落库。问答走 SSE,帧序固定 sources → delta* → done。
对外:HTTP、MCP、A2A 三个入口调用同一套 engine.search 与 ask.prepare + stream_answer。权限都读 UserContext.readable_kb_ids,没有第二套检索实现。
目录与常用命令
services/
api/ FastAPI 入口、19 个路由模块、前端托管
common/ 模型、认证、任务、存储、Qdrant、对账
ingest/ 解析、切分、PII、坐标、版本、清理
retrieval/ 四条腿、融合、路由、精排、问答
worker/ 主循环、文档终态、八种 handler
mcp/ JSON-RPC 协议层与四个工具
visual_service/ 只做编码的常驻进程
web/ React 19 + Vite + Tailwind v4
migrations/ 23 个迁移
eval/ 契约对账、三套 HTTP 验收、检索评测
deploy/ 起停、巡检、备份、恢复、蓝绿迁移
tests/ 1335 项 pytest| 命令 | 用途 |
|---|---|
bash deploy/dev.sh start | 起 API + worker + 视觉服务(另有 restart、stop) |
bash deploy/visual.sh status | 视觉服务单独管理 |
uv run python -m services.api.scripts.create_user | 建账号(自助注册默认开,对外部署应关 ALLOW_REGISTER) |
uv run python deploy/seed_photos.py | 造一个含照片库的演示账号 |
uv run python deploy/monitor.py | 十四项巡检(跳过不算健康) |
bash deploy/backup.sh | 备份并自检 |
bash deploy/restore.sh --scratch <dir> | 恢复到临时库并逐表对账 |
bash deploy/ci.sh | CI 与本地共用的门禁 |
uv run python eval/contract_check.py | 82 / 81 / 1 的契约对账 |
cd web && npm run build | 改前端后需要重新构建;dev.sh 不代构建 |
dev.sh 只有 start / restart / stop 三个子命令,没有 status / logs。状态与排障见《运维与验收》的排障一节。
快速导航
| 你要做的事 | 去哪 |
|---|---|
| 补检索机制(BM25、RRF、MaxSim、点 ID) | 《小白概念指南》 |
| 理解三进程、内存与并发预算 | 《架构总览》 |
| 加文件格式、改切分策略 | 《文档摄取》 |
| 调检索效果、加腿、改精排 | 《检索与问答》 |
| 索引点数对不上、重建 | 《数据与一致性》 |
| 判断谁看得到哪个库 | 《多租户与权限》 |
| 接 MCP 客户端 / 调 A2A | 《对外接口》 |
| 巡检、备份、排障、CI | 《运维与验收》 |
| 准备面试话术 | 《面试准备指南》 |
阅读顺序:小白概念指南 → 架构总览 → 文档摄取 → 检索与问答 → 数据与一致性 → 多租户与权限 → 对外接口 → 运维与验收 → 面试准备指南。只想快速浏览的读者可选架构总览(对应数据平面)、检索与问答(对应核心机制)、运维与验收(对应交付门禁)。
已知限制
| 限制 | 具体表现 |
|---|---|
| 默认不归纳 | 抽取式输出原句;归纳需要外部 LLM,配置后原文会离开本机 |
| 文档可写作日期缺失 | 文件名大多是编号或修订年份,mtime 是拷贝时刻;事件日期依赖 EXIF 或文件名,抽不到留空 |
| Late Chunking 有 512 token 上限 | 超限内容进入截断后的 span |
| Contextual Chunking 需要外部 LLM | 默认抽取式不外传,该策略不生效,只留一条 note |
| 表格结构化覆盖有限 | 仅 PDF / CSV / XLSX 结构化;DOCX / HTML / PPTX 表格按纯文本处理 |
| 新增字段有重摄取欠账 | table_json / updated_at 仅对之后摄取的文档生效 |
| 外部 LLM 不可用会降级 | 401 / 超时 / 5xx 退回抽取式,原因写在 done.degraded,该轮无归纳 |
| 视觉服务无鉴权 | 只能绑 127.0.0.1(威胁模型见《运维与验收》) |
| 不做 OCR | 扫描件交给视觉召回,不进 tesseract |
| 外部 LLM 仅实测一个厂商 | 一家 OpenAI 兼容网关(含自定义请求头场景) |
| 存储仅本地盘 | blobs.storage_path 没有代码读取做分发 |
| PII 掩码以 chunk 为单位 | 跨 chunk 边界的号码会漏检 |
| 并发受连接池约束 | 一次 hybrid 占 4 条 Postgres 连接,池大小按并发检索数 × 4 估 |
| 20 人以上团队不适合直接上线 | 无 RBAC、视觉无鉴权、存储仅本地盘,均为显式不做 |
下一章: 小白概念指南