知识库是做什么的
模型只知道训练时学到的东西。知识库把你自己的内容交给应用，比如帮助中心、内部制度或产品目录。问题进来时，Dify 找出最相关的段落，连同问题一起交给模型，答案就能用上你的内容。这就是检索增强生成，RAG 教程从零搭了一个。
Dify Cloud 有两种知识库。在经典知识库里，内容怎样分块、索引和搜索由你决定。智能体知识库还在测试阶段，会自己整理并建立全部索引。自托管文档只介绍经典这一种，所以本课大部分讲它，最后一节再讲智能体这一种。
| 对比项 | 经典知识库 | 智能体知识库（测试中） |
|---|---|---|
| 能用它的应用 | Chatbot、Text Generator、旧版 Agent、Workflow 和 Chatflow | Workflow 和 Chatflow，以及新版 Agent |
| 内容来源 | 上传文件、网站抓取和 Notion，另有 Knowledge Pipeline 或外部知识库 | 上传文件、网站抓取、在线文档和在线网盘 |
| 要配置什么 | 分块模式和长度、索引方式、搜索方式和 Top K | 模型和检索深度，再加 Top K |
| 质量测试 | 检索测试 | 检索测试、黄金问题、评估和问题案例 |
创建知识库并上传文件
经典知识库归结为三个决定：文件怎样分块，块怎样索引，结果怎样搜索。先从上传开始。自托管安装的上传限制是环境设置：UPLOAD_FILE_BATCH_LIMIT 管每次上传的文件数，UPLOAD_FILE_SIZE_LIMIT 管文件大小。
图片会多一道处理。Word 和 Excel 文件里的图片，或者任何文件里用 Markdown 图片语法链接的图片，只要是 2 MB 以下的 JPG、PNG 或 GIF，就会被提取出来，作为对应块的附件。检索时，它们会和各自的块一起返回。
- 点“Knowledge”>“Create”>“Create a ready-to-use knowledge base”。
- 数据源选“Import from file”，然后上传文件。
- 选好分块模式和它的设置，再点“Preview”，看内容会怎样拆分。
- 选择索引方式和检索设置，下面几节会讲。
知识库创建之后，数据源就不能再改。分块模式同样不能改，不过分隔符和最大块长度随时可以调整。
分块设置
分块是把每份文档拆成更小的片段，叫作块。有人提问时，Dify 在这些块里搜索，把相关的块交给模型当上下文，因为每次查询都读整份文档会很慢。分块那一课讲了通用的分块策略。
两个设置在所有模式里都适用。分隔符是文本被切开的位置，比如用连续两个换行表示段落。最大块长度以字符计，超出的文本会被强制切开。分隔符在分块时会被删掉，所以用 A 作分隔符，CBACD 会变成 CB 和 CD。文档建议选一个不会出现在你内容里的字符。
通用模式多一个块重叠设置，让上一块的结尾在下一块的开头再出现一次。重叠 50 个字符时，一个块的结尾会在下一个块的开头再出现一次。在父子模式里，父块可以是“Paragraph”或“Full Doc”，而 Full Doc 只处理前 10,000 个 token。
拆分之前，你可以替换连续的空格、换行和制表符，还可以删除所有网址和邮箱地址，不过 Full Doc 模式会忽略后一个选项。Summary Auto-Gen 为每个块生成摘要，摘要也会建索引，所以摘要匹配了问题，它对应的块也会一起返回。
| 对比项 | 通用 | 父子 |
|---|---|---|
| 分块方式 | 单层：所有块用同一套设置 | 双层：父块和子块各有设置 |
| 检索方式 | 匹配到的块直接返回 | 子块用来匹配查询，返回的是父块，提供更多上下文 |
| 索引方式 | High Quality 或 Economical | 只能用 High Quality |
| 适合 | 内容自成一体，比如术语表或常见问题 | 信息密集的文档，比如技术手册或研究论文 |
索引方式和搜索设置
High Quality 索引用嵌入模型把每个块变成向量，所以搜索能匹配含义，而不只是原词。嵌入那一课解释了这个思路。Economical 索引每个块保留 10 个关键词，不消耗 token，检索精度较低，用的是倒排索引，也就是网页搜索引擎用的关键词查找结构。它只支持 Top K。Economical 的知识库可以在设置里升级到 High Quality，反过来，High Quality 的不能切回去。
High Quality 有三种搜索方式：向量搜索、全文搜索和混合搜索。混合搜索两种一起跑，再重新排序。在混合模式里，权重设置不需要重排序模型。语义值为 1 只用向量搜索，关键词值为 1 只用关键词搜索，介于两者之间就是混合。文档建议，用户清楚知道确切词汇时偏重关键词，内容里没有这些词或者查询跨语言时偏重语义。
重排序模型默认关闭。打开后，会由第三方模型把搜索返回的块重新排序。要先在“Integrations”>“Model Provider”里添加它的 API 密钥，因为它会消耗重排序模型的 token。Top K 是返回多少个块，Score Threshold 是块至少要达到的相似度，文档说这两项在重排序阶段才生效，所以要先打开重排序模型。之后更换嵌入模型，会把所有块重新嵌入一遍。
自托管文档里还有 Q&A 模式，它为每个片段生成问答对，让用户的问题去匹配问题，而不是匹配段落。文档把它用在常见问题类的文档上。
应用使用之前先测试检索
在知识库里点左侧边栏的“Retrieval Testing”图标，像你的用户那样输入问题，看返回哪些块。想要数字而不只是看一眼，评估 RAG讲了怎样给这类结果打分。你在这个页面改的设置是临时的，只对当前这次测试有效，要保留的设置，请改到知识库自己的设置里。
“Records”部分记录每一次检索：你测试的问题，以及关联应用发来的请求，无论是测试运行还是线上运行。测试检索和正常检索用的是同一个 API 端点。
在对话流里使用
Chatflow 通过 Knowledge Retrieval 节点用到知识库。User Input 节点收集问题，Knowledge Retrieval 搜索选定的知识库，输出一个由块组成的 result 列表，LLM 节点根据问题和这些块回答，Answer 节点返回回复。LLM 节点页面给了下面这个传递上下文的提示词。
Chatbot 应用的路径更简单。打开“Context”，点“Add”选一个知识库，设置“Retrieval Setting”，在“Add Features”里打开“Citation and Attribution”，在“Debug and Preview”里试一试，然后发布。关联多个知识库时，Dify 会同时搜索它们，再由重排序步骤挑出最好的块。Weighted Score 不需要额外的模型，但只有每个知识库都用 High Quality 索引、并且嵌入模型相同时才能用。
Answer using only this context:
{{knowledge_retrieval.result}}
Question: {{user_question}}- 按前面几节的做法，创建一个现成可用的知识库并上传文件。
- 在 Studio 里创建一个 Chatflow，在 User Input 后面添加 Knowledge Retrieval 节点。
- 在节点里，把“Query Text”设为存放用户消息的变量，文档里的例子是
userinput.query。添加你的知识库，再打开“Retrieval Setting”，选择重排序设置、Top K 和 Score Threshold。 - 在 LLM 节点里，把 Knowledge Retrieval 的输出连到上下文输入，使用上面的提示词，并把
{{user_question}}换成用户消息的变量。 - 添加一个 Answer 节点，返回 LLM 的回复。Dify 会自动记录引用，用户能看到信息的出处。
- 点“Preview”，问一个文档能回答的问题，再问一个文档回答不了的。
Cloud 上的智能体知识库
智能体这一种没有分块模式和索引方式可选。推理模型读取并整理每份文档，嵌入模型让它可以被搜索，你要选的是内容、检索深度和 Top K。它的内容可以从网站、在线文档或网盘同步，周期从 1 小时到 30 天，也可以手动同步。Cloud 文档说，新项目应该从这里开始。
Chatbot、旧版 Agent 和 Text Generator 应用搜不了智能体知识库，它也不能转回经典知识库。它的页面只在 Cloud 文档里有。
测试时，在它的 Retrieval Test 页面运行问题。某次运行返回了正确的块，就把它保存为黄金问题，之后每次改动设置或模型，都到“Quality”下运行一次评估，确认所有黄金问题仍然通过。块缺失或排名太低时，把它标记为问题案例。每次只改一个设置，再重新测试。
| 检索深度 | 它做什么 | 适合 |
|---|---|---|
| Fast | 按含义和关键词匹配，是最快的深度 | 大多数直接的问题，从这里开始 |
| Deep | 范围比 Fast 更广，顺着知识图谱找到相关主题的块，速度更慢 | Fast 总是漏掉、答案涉及相关主题的情况 |
| Research | 把复杂问题拆成子问题，各自广泛搜索，是最慢的一档，消耗的模型 token 也最多 | 需要多次搜索才能回答的问题 |
常见错误
- 把分块模式当成以后再改的默认值。创建之后它不能改，只有分隔符和最大长度可以改。
- 选了 High Quality，又指望以后切回 Economical 省 token。文档只允许反方向。
- 用了会出现在你文本里的分隔符。分隔符本身在分块时会被删掉，它出现的每个位置都会变成一处切口，这个字符也会从你的块里消失。
- 调高了 Top K 或 Score Threshold 却看不到变化。这两项在重排序阶段才生效，所以重排序模型必须打开。
- 打开了重排序，却发现它没有任何作用，因为从没给那个模型添加过密钥。
- 在嵌入模型不同或用 Economical 索引的知识库之间选 Weighted Score。Dify 会报错，或者不显示这个选项。解决办法是用重排序模型，或者统一设置。
- 把智能体知识库关联到 Chatbot 应用，而它搜不了。
自己试一试
- 上传一份文档，先在通用模式下点“Preview”，再在父子模式下点一次，比较两种分块。
- 在 Retrieval Testing 页面，用向量搜索和混合搜索各问同一个问题，看哪些块变了。
- 把 Score Threshold 调高，直到原本能答的问题什么也返回不了，再调回去。
下一课
第 4 课搭一个会调用工具的智能体应用，再把它发布成网页应用、API 和嵌入组件，并查看它的日志。知识库可以成为这个智能体的工具之一。
自测一下
哪种分块模式只能配合 High Quality 索引方式使用？
查看答案
B. 父子 文档写明，通用模式兼容 High Quality 和 Economical，父子模式只能用 High Quality。
你给知识库设置了 Top K 和 Score Threshold，却看不到变化。文档说该检查什么？
查看答案
A. 重排序模型是否已打开，因为这两项在重排序阶段才生效 索引方式页面说，Top K 和 Score Threshold 只在重排序阶段有效，所以要先添加并启用重排序模型。
一个知识库用 High Quality 索引方式创建。之后哪件事做不到？
查看答案
C. 切换到 Economical 备注说，知识库一旦用 High Quality 创建，就不能再切换到 Economical。Economical 的可以升级。
Chatflow 怎样把检索到的块交给模型？
查看答案
B. Knowledge Retrieval 节点输出 result 列表，LLM 节点把它当作上下文 Knowledge Retrieval 节点输出 result 变量，LLM 节点页面让你把它连到上下文输入，并在提示词里引用。
常见问题
怎样让 Dify 根据我自己的文档回答？
先把文档放进知识库，再把这个知识库连接到应用。Chatbot 在“Context”下连接，Chatflow 则用放在 LLM 节点前面的 Knowledge Retrieval 节点。Dify 会自己记录引用，读者能看到回答依据了哪些文档。
Dify 知识库的文件最大能有多大？
自托管安装的默认值是每个文件 15 MB，Dify Cloud 上的智能体知识库同样最大 15 MB。Cloud 上的经典知识库，在 Professional 和 Team 套餐上可到 50 MB。自托管时，文件大小和每次上传的文件数都是环境设置。
Dify 里的嵌入模型和重排序模型有什么区别？
嵌入发生在建索引的时候，只做一次，决定哪些块和问题看起来相似。重排序发生在查询时，对已经找到的块逐个打分、排序。重排序默认关闭，还需要另一个模型和它自己的 API 密钥。
Dify 检索出错误的块，该怎么办？
在知识库的 Retrieval Testing 里重现这个问题，每两次运行之间只调整一个设置。块缺失时，Cloud 文档的建议是先检查文档是怎样建索引的，再用更大的 Top K 或更低的 Score Threshold 扩大搜索。块排名太低时，换一个重排序模型试试。
编程智能体能读取 Dify 知识库吗？
在 Cloud 上可以。通过 Dify CLI，Claude Code 或 Codex 这样的编程智能体，可以像浏览文件夹里的文件一样浏览智能体知识库的文档，并搜索确切的词。它不能修改里面的任何内容。
资料来源
- Dify Docs (GitHub): Upload Local Files https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/create-knowledge/import-text-data/readme.mdx
- Dify Docs (GitHub): Configure the Chunk Settings https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/create-knowledge/chunking-and-cleaning-text.mdx
- Dify Docs (GitHub): Index Method and Retrieval Settings https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/create-knowledge/setting-indexing-methods.mdx
- Dify Docs (GitHub): Test Knowledge Retrieval https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/test-retrieval.mdx
- Dify Docs (GitHub): Manage Knowledge Settings https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/manage-knowledge/introduction.mdx
- Dify Docs (GitHub): Integrate Knowledge within Apps https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/knowledge/integrate-knowledge-within-application.mdx
- Dify Docs (GitHub): Knowledge Retrieval node https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/nodes/knowledge-retrieval.mdx
- Dify Docs (GitHub): LLM node https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/nodes/llm.mdx
- Dify Cloud Docs (GitHub): Knowledge https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge/overview.mdx
- Dify Cloud Docs (GitHub): Agent Knowledge Base https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge-base/overview.mdx
- Dify Cloud Docs (GitHub): Create an Agent Knowledge Base https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge-base/create-knowledge-base.mdx
- Dify Cloud Docs (GitHub): Retrieval Settings https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge-base/retrieval-settings.mdx
- Dify Cloud Docs (GitHub): Test and Tune Retrieval https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge-base/test-and-tune.mdx
- Dify Cloud Docs (GitHub): Connect to Apps, Agents, and Code https://github.com/langgenius/dify-docs/blob/main/en/cloud/use-dify/knowledge-base/use-knowledge-in-apps.mdx