推理知识库（树索引 RAG）

INFO

推理知识库（Tree-RAG）将文档构建为层级树索引，由 LLM 沿树逐层推理导航检索，作为 AI 回答的上下文。相比传统向量检索的"一次匹配"，推理知识库对长文档、PPT、网页等结构化内容定位更精准，支持 PDF、Word、PPT、Excel、HTML、图片、TXT、Markdown 等多种格式，开箱即用无需配置模型。

WARNING

旧版向量知识库采用"一次向量匹配"检索，对长文档定位粗糙，现已下线，控制台入口已移除。如需使用知识库，请直接使用推理知识库。

1. 基本原理

小智Pro 服务端通过 HTTP 调用 Tree-RAG 服务完成文档建树与检索，设备端检索采用 异步消息转发 模式，整体流程如下：

小智设备 ──(语音提问)──> 小智Pro服务端 ──(检索)──> 推理知识库
        │                                              │
        │<──────────("正在检索，请稍候")────────────────│
        │                                              │
小智设备 <──(下发通知)── 小智Pro服务端 <──(知识库检索结果)─┘
        │
        └──(取回结果)──> AI 组织回答

1.1 文档建树

上传文档后，Tree-RAG 服务自动执行：

解析清洗：提取文档正文（PDF/Word/PPT 等转 Markdown，URL 抓取网页清洗）
标题切分：按 Markdown 标题层级提取节点，构建嵌套树结构
空根合并：内容过短的空根节点自动合并到下一节点，减少 LLM 摘要调用
逐层摘要：LLM 为每个节点生成摘要，消耗的 tokens 记录到文档
状态更新：建树完成，文档状态变为「就绪」即可检索

1.2 异步检索

检索耗时较长，为避免设备连接超时采用异步流程：

发起检索后服务端立即返回"正在检索，请稍候";
后台沿文档树推理检索；
完成后通知设备，AI 取回结果组织回答。

1.3 关键设计

特性	说明
树索引检索	LLM 沿文档树逐层推理导航，定位精准，支持长文档
异步响应	发起检索后立即返回，不阻塞设备对话
智能推送	检索完成后根据设备状态（空闲/说话中）选择合适时机通知取结果
结果去重	检索结果读取后即删，避免重复消费
多格式支持	PDF/Word/PPT/Excel/HTML/图片/TXT/Markdown，URL 自动抓取清洗
开箱即用	无需配置 Agent / LLM 模型，平台内置

2. 操作指南

2.0 前置准备

已在小智Pro 控制台绑定设备
设备固件版本需为 v2.4.0.1 以上：https://github.com/hougeai/xiaozhiPro/releases

2.1 创建知识库

进入小智Pro 控制台，点击左侧菜单 推理知识库，点击右上角「创建知识库」按钮：

填写知识库名称（必填）
填写描述（可选，简要说明知识库用途）
点击确认，完成创建

每个用户可创建的知识库数量受账号等级配额限制，在列表顶部可查看当前用量/配额。

2.2 上传文档

点击知识库卡片进入详情页，支持两种上传方式：

1. 文件上传

点击「添加文档」按钮，选择本地文件上传，支持格式：

PDF · Word(.docx) · PPT(.pptx) · Excel(.xlsx)
HTML(.html/.htm) · Markdown(.md/.markdown) · TXT
图片(.jpg/.jpeg/.png/.gif/.webp/.bmp/.tiff)

单个文件上传大小限制 30MB。

2. URL 上传

切换到 URL 标签页，粘贴网页链接（如博客、文档站点等公开网页），服务端提取干净标题作为文档名。

上传后文档状态为「索引中」，建树完成后变为「就绪」即可检索。可在文档卡片查看文件类型、文件大小、tokens 消耗等信息。

2.3 检索测试

在知识库详情页点击「检索」按钮，打开检索测试弹窗：

输入问题，点击「检索」
查看命中节点数、检索耗时
结果按文档分组展示，每个节点显示来源文档、节点标题与完整内容

检索测试用于在控制台验证检索效果，不影响设备端使用。

2.4 统计数据

点击「统计」按钮查看检索统计：

总检索次数：该知识库累计被检索的次数
缓存命中率：命中缓存的检索占比
平均耗时：单次检索的平均耗时
热门问题：近 30 天的检索问题列表

支持一键清空所有检索统计数据。

2.5 查看文档树

点击文档的「树结构」进入「文档树」视图：

左侧树结构：展示 LLM 提炼的层级标题，点击节点跳转
右侧详情：展示选中节点的摘要、完整内容
Markdown 预览：支持切换查看 Markdown 格式文档

通过文档树可直观了解文档如何被切分索引，便于排查检索效果。

2.6 设为设备知识库

在知识库列表，每个卡片底部有「设为设备知识库」按钮（上箭头图标）：

点击后该库设为设备的默认检索库
已设为默认的库显示绿色「设备知识库」标签
设备端语音问答时，AI 会自动调用该库检索上下文

每个用户只有一个默认知识库，所有设备共享。

2.7 编辑与删除

编辑：点击卡片底部的编辑按钮，可修改知识库名称和描述
删除：点击删除按钮（需二次确认），删除后不可恢复，同时扣减配额

2.8 通过设备语音操控

WARNING

设备固件版本需为 v2.2.6.2 以上：https://github.com/hougeai/xiaozhiPro/releases

将知识库设为设备默认库后，你可以直接对小智说：

- '你知道xx么'
- '帮我查查xx'
- '调用知识库，帮我查查xx'

成功调用后，屏幕或日志中会看到 self.kb.query 工具调用，检索完成后，小智基于检索结果组织回答。

3. 常见问题

检索一直返回"知识库检索中"？

检索是异步流程，Agent 沿文档树推理需要时间（通常 5-30 秒）
确认设备固件版本为 v2.4.0.1 以上，旧版固件可能不支持异步检索
检查知识库中是否有「就绪」状态的文档，未索引完成无法检索

上传文档后状态一直"索引中"？

建树需要调用 LLM 生成摘要，大文档耗时较长

文件存储配额已满？

文件存储配额按账号等级限制所有文档原始文件总大小
URL 上传的网页也会按清洗后的 HTML 大小计入配额
可在知识库列表顶部查看当前用量，删除不需要的文档释放空间

URL 上传失败？

确认 URL 公网可访问，且不是需要登录的页面
部分网站有反爬机制，可能导致抓取失败

检索结果不准确？

检查文档是否已正常建树（状态为「就绪」）
在文档树视图查看节点结构是否合理
尝试用更精确的关键词或换一种问法
短内容页可能被合并到相邻节点，检索结果会包含合并节点的完整内容

推理知识库（树索引 RAG） ​

1. 基本原理 ​

1.1 文档建树 ​

1.2 异步检索 ​

1.3 关键设计 ​

2. 操作指南 ​

2.0 前置准备 ​

2.1 创建知识库 ​

2.2 上传文档 ​

2.3 检索测试 ​

2.4 统计数据 ​

2.5 查看文档树 ​

2.6 设为设备知识库 ​

2.7 编辑与删除 ​

2.8 通过设备语音操控 ​

3. 常见问题 ​

检索一直返回"知识库检索中"？ ​

上传文档后状态一直"索引中"？ ​

文件存储配额已满？ ​

URL 上传失败？ ​

检索结果不准确？ ​