10分钟看懂Knowhere：文档摄取、层级记忆与检索系统全流程解析

10分钟看懂Knowhere文档摄取、层级记忆与检索系统全流程解析【免费下载链接】knowhereKnowhere extracts, parses, and outputs structured chunks ready for AI Agents and RAG.项目地址: https://gitcode.com/gh_mirrors/know/knowhereKnowhere 是一个面向 AI Agent 与 RAG 的文档解析和检索系统它把你手里的 PDF、Word、Excel、图片等杂乱文件摄取Ingestion成带层级、带引用、可导航的结构化记忆再让任何 Agent 像人一样翻查、检索、引用。这篇文章带你用 10 分钟走完全流程文档摄取 → 双轨解析 → 层级记忆构建 → Agent 原生检索并附完整上手步骤。一、Knowhere 解决什么问题传统 RAG 的痛点是扁平把文档切成一段段 chunk做向量检索返回孤立的片段。Agent 拿到片段后缺乏上下文不知道它出自哪一章、哪一页也不知道文档之间有什么关系。Knowhere 的思路是构建文档记忆基础设施Document Memory Infrastructure它做三件事摄取与解析把非结构化文件变成结构化数据文本、表格、图片、页面层级记忆每个内容都挂在章节树上保留文档路径、页码、摘要、实体Agent 原生检索提供大纲、精确搜索、模糊召回、全文阅读、资产读取、跨文档关联等一组工具由 Agent 自己决定怎么查。官方数据很直接在相同的 Agent RAG 任务上接入 Knowhere 的 Agent首次回答准确率提升 36%、召回率提升 11%且 token 消耗更少。二、第 1 步文档摄取与双轨解析整个系统分两个进程协作API 服务apps/api/接收上传请求、创建 Job任务、做配额校验、发布检索可见的文档Worker 服务apps/worker/执行真正的解析工作。一次典型摄取流程上传文件 → 创建 Job通过认证、限流、配额检查→ Worker 从 S3 拉取源文件 →格式路由选择解析器 → 输出统一 Schema 的 chunk → 打包结果 →发布Publication成 Document/Section/Chunk 三层记录。核心代码位于 apps/api/app/services/document_ingestion/service.py解析编排入口在 apps/worker/app/services/document_parser/parse_service.py。双轨解析Text Track 与 Vision Track这是 Knowhere 2.0 的核心设计——不同格式走不同轨道但产出同一套数据契约轨道适用格式做法Text Track.docx.xlsx.md.txt.html保留原生文本结构与精确层级Vision Track.pdf.pptx用前沿视觉模型整页理解不依赖逐元素 OCR 完美重建为什么 PDF 要走视觉轨道因为脏 PDF 的阅读顺序、表格、隐藏文本层很容易让逐元素 OCR 出错错误会累积成不可靠的上下文。Vision Track 让视觉模型把页面作为整体来理解——即使某个元素没被完美提取页面依然可以被检索到、被读懂。两种轨道最终都收敛到同一个 Schema层级 节点 图下游存储、检索、引用完全格式无关。三、第 2 步构建层级记忆Page Memory解析完成后Knowhere 把结果构建成一棵可导航的章节树。用官方数据模型表述Namespace检索命名空间 └─ Document文档记录 parse_track └─ Section章节节点section_path 路径、层级、摘要、实体 └─ Chunk检索单元text / page / image / tableSection章节节点来自标题层级推断。以 NVIDIA 财报演示数据为例doc_nav.jsonItem 1. Financial Statements 是 Level 1 节点其下的a) Condensed Consolidated Statements of Income 是 Level 2 子节点每个节点都带摘要由 VLM 生成和chunk_count。Page Chunk页面块Vision Track 产出的以页面为单位的块每一页都是一个可检索、可引用的节点。跨文档 Graph基于页面提取的实体与关键词在不同文档的关联区块之间建立related边让 Agent 能顺着关系走。下面是一张财报页面资产截图这类渲染页会被保留为视觉证据检索结果可以精确回指到哪个文档、哪条路径、第几页 层级重建标题推断的实现见 apps/worker/app/services/document_parser/structure/heading_hierarchy.py页面级记忆构建在 apps/worker/app/services/page_memory/。关键区别在于传统 RAG 返回断线的 chunkKnowhere 返回带文档路径、页码、摘要、关联资产的可导航节点。四、第 3 步Agent 原生检索检索时Knowhere 只做两件事提供语料底座一套 Schema 一组工具让 Agent 自由探索。内置工具集工具定义在 packages/shared-python/shared/services/retrieval/agent_tools/Agent 面对语料时手上有工具作用outline查看文档章节大纲先定位再深入grep/recall精确搜索 / 模糊召回read全文阅读指定章节assets/query_table读取图片资产 / 查询表格neighbors沿跨文档关系图找关联内容node_filter按章节路径与摘要做结构过滤list_documents列出命名空间内的文档这套工具契约是Agent 中立的——内置检索、MCP 客户端、Cursor/Claude Code 等外部 Agent 都能用同一套接口。工具调用返回的证据引用会被解析为可追溯的文档、章节、页码和资产即Page-grounded Citations页面级引用。经典检索确定性 top-K 依然可用如果不想让 Agent 自由发挥也可以走传统确定性 top-K 检索路径。为保证优化不改变结果项目用语义对等Semantic Parity契约约束 serving index 检索同一次请求在新旧路径上必须选中相同的 chunk 顺序与分数——详见架构决策记录 docs/adr/README.md。五、10 分钟上手本地跑起来前置条件Python 3.11、uv、Docker含 docker compose。# 1. 同步依赖 uv sync --all-packages # 2. 复制环境变量模板 cp apps/api/.env.example apps/api/.env cp apps/worker/.env.example apps/worker/.env # 3. 填入数据库/Redis/S3 连接至少一个 LLM Key如 DS_KEY / GPT_API_KEY # 4. 启动本地基础设施PostgreSQL / Redis / LocalStack ./deploy/local-dev/start-dev.sh # 5. 两个终端分别启动 API 与 Worker cd apps/api uv run alembic upgrade heads uv run main.py cd apps/worker uv run worker.pyAPI 运行在http://localhost:5005OpenAPI 文档在/docs。本地开发编排文件位于 deploy/local-dev/docker-compose.dev.yml。不需要本地部署官方也提供托管版 Knowhere Cloud 和 Python/Node SDK仓库还内置了 20 份演示文档财报、论文、技术手册可通过 Demo API 一键物化到命名空间直接体验检索。六、支持格式与适用场景✅ 已支持.pdf.pptxVision 轨道、.doc.docx.xls.xlsx、.jpg.png、.md.txt.html.json⏳ 即将支持.epub.xml、音视频它特别适合企业知识库 RAG财务、法务等长文档需要可追溯引用超长 PDF300~500 页与图册类文档解析流水线可处理并路由到布局感知解析器多文档交叉问答跨文档实体图谱让 Agent 能顺藤摸瓜。七、总结用一张表回顾 Knowhere 全流程阶段输入输出关键模块① 摄取原始文件Job 解析结果包apps/apiapps/worker② 层级记忆解析 chunkDocument → Section → Chunk 树 文档图谱shared/services/retrieval/③ 检索用户问题带页码引用的证据 Agent 探索工具agent_tools MCPKnowhere 的定位一句话概括它不是下一个 MinerU解析器而是让 Agent 真正能读得动、查得到、引得准的文档记忆基础设施。如果你想深入建议按 CONTRIBUTING.md 的指引从good first issue入手——添加一个解析器就是很棒的第一个贡献。【免费下载链接】knowhereKnowhere extracts, parses, and outputs structured chunks ready for AI Agents and RAG.项目地址: https://gitcode.com/gh_mirrors/know/knowhere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考