企业官网建设流程全解析

如何让AI Agent像人一样读文档？Knowhere Agentic Retrieval与MCP工具完整指南

【免费下载链接】knowhereKnowhere extracts, parses, and outputs structured chunks ready for AI Agents and RAG.项目地址: https://gitcode.com/gh_mirrors/know/knowhere

Knowhere 是一个开源的文档解析与检索系统，能把 PDF、PPT、Word、Excel 等"脏"文件解析成 AI Agent 可直接导航的持久化"文档记忆"。本文将带你完整了解它的核心能力Agentic Retrieval（智能体式检索）：为什么 Agent 读文档应该像人一样"先翻目录、再定位、后精读"，以及它内置的MCP 工具如何让你的 Agent（Cursor、Claude 等）直接接入这份文档记忆，并返回可溯源到页码的证据。

一、传统 RAG 的痛点：Agent 在"搜索"，而不是在"阅读" 📖

传统 RAG 做的是扁平的向量查找：把一个几十页的 PDF 切成碎片、做向量检索、返回几个孤立的段落。Agent 拿到的碎片缺少上下文，既不知道这段来自哪一章，也不知道文档的整体结构。

Knowhere 的思路完全不同——它先为文档构建一棵可导航的层级树：

• Namespace（命名空间）→ Document（文档）→ Section（章节）→ Chunk（检索单元）
• 每个章节都保留完整的文档路径、页码范围、摘要、实体和关联的图片/表格
• Agent 可以像人一样：先看目录 → 判断哪一章相关 → 精读该章 → 顺藤摸瓜引用图表

官方基准测试显示：基于 Knowhere 记忆的 Agent 比直接读取原始文档或 Markitdown、Unstructured、MinerU 输出的 Agent首次回答准确率提升 36%、召回率提升 11%，且有反馈时准确率可达 79%。更少的循环、更少的 token、更短的时间。

二、双轨解析：先给 Agent 一份"读得懂"的记忆 🧠

Knowhere 2.0 采用**视觉轨（Vision Track）+ 文本轨（Text Track）**双轨解析：

• 文本轨：对 DOCX、XLSX、MD 等文本原生文档，保留精确的标题层级和原生结构
• 视觉轨：对复杂 PDF 和 PPT，直接用前沿视觉模型"整页看懂"，不依赖脆弱的逐元素 OCR

两条轨道最终汇聚到同一套记忆 schema，下游的检索引擎和引用模型无需关心文档原始格式。

这套"面向 Agent 的语料 schema"是检索的地基，其唯一定义在 CORPUS_SCHEMA.md 中，设计说明见 docs/design/agent-corpus-schema.md。

三、Agentic Retrieval：Agent 读文档的完整工作流 🔍

这是整个项目的灵魂。Knowhere 不强制 Agent 走固定的检索流水线，而是提供一套层级感知的探索工具，由 Agent 自己决定调用哪些工具、按什么顺序、钻多深：

9 个 corpus.* 工具速查表

典型检索路径

一次自然的人类式阅读流程大致是：

1. outline看目录，圈定候选章节
2. grep（已知精确词）或recall（模糊问题）定位
3. read精读正文——它会自动解析跨页引用、展开关联的图表
4. 遇到大表格用query_table做只读 SQL 查询
5. 顺带用neighbors找相关文档，交叉验证

每一步返回的结果都携带可溯源引用：文档 ID、章节路径、页码，以及渲染好的页面截图作为视觉证据。

四、MCP 工具接入：三步让你的 Agent 读文档 🔌

Knowhere API 内置了一个MCP（Model Context Protocol）服务端点，挂载在/mcp路径上（无状态 HTTP 传输），任何支持 MCP 的客户端都可以直接接入。实现见 apps/api/app/mcp/retrieval_server.py。

接入步骤

第 1 步：启动 Knowhere 本地服务

# 克隆仓库 git clone https://gitcode.com/gh_mirrors/know/knowhere cd knowhere # 安装依赖并启动本地基础设施（PostgreSQL / Redis / LocalStack） uv sync --all-packages ./deploy/local-dev/start-dev.sh # 分别启动 API 和 Worker cd apps/api && uv run main.py cd apps/worker && uv run worker.py

第 2 步：创建 API 用户与密钥

cd apps/api uv run scripts/init_user.py --email you@example.com

第 3 步：在 MCP 客户端中配置

在你的 MCP 客户端（如 Cursor、Claude Desktop）中，将端点指向http://localhost:5005/mcp，并通过 HTTP 头传递认证信息：

• Authorization: 你的 API 密钥
• x-knowhere-namespace: 可选，指定检索的命名空间（多租户隔离用）

MCP 端点会自动注册两类工具（见 apps/api/app/mcp/dynamic_tools.py）：

• corpus.*系列（推荐）：上面表格中的 9 个探索工具，schema 与内置 Agent 完全一致
• retrieval.query：一键式兼容检索，适合只需要"问一句、拿证据"的简单场景，返回 evidence（组合证据）、referenced_chunks（引用元数据）和 decision_trace（导航决策轨迹）

五、给新手的 3 条实用建议 💡

1. 能用grep就别用recall：已知精确字符串（编号、术语、数字）时，grep更快更准；recall留给真正模糊的问题。
2. 先定位、后精读：先用outline/node_filter缩小范围，再read正文，可以大幅节省 token 预算。
3. 看引用，别只看文字：结果里的页码截图和章节路径是可验证的证据，回答用户时带上它们，可信度会显著提升。

六、延伸阅读 📚

• 检索的文档作用域规则：docs/retrieval-document-scope.md
• 架构决策记录（ADR）：docs/adr/README.md
• 检索设计文档：docs/design/
• 想参与贡献？从 CONTRIBUTING.md 开始，添加新格式解析器是很好的第一个 PR。

总结：Knowhere 没有再造一个更强的"解析器"，而是构建了一层 Agent 真正能用的文档记忆基础设施——层级化记忆 + 中立工具契约 + MCP 接入。你的 Agent 负责思考"怎么找"，Knowhere 负责保证"每一步都可溯源"。这正是 AI Agent 像人一样读文档的答案。

【免费下载链接】knowhereKnowhere extracts, parses, and outputs structured chunks ready for AI Agents and RAG.项目地址: https://gitcode.com/gh_mirrors/know/knowhere