跳至主要內容

Dify-4-知识库与工具

程序员李某某大约 34 分钟

Dify-4-知识库与工具

知识库

支持的文本

  • 长文本内容（TXT、Markdown、DOCX、HTML、JSONL 甚至是 PDF 文件）
  • 结构化数据（CSV、Excel 等）

另外，我们正在逐步支持从诸多数据源同步数据至数据集，包括：

  • 网页
  • Notion
  • Github
  • 数据库

在 Dify 中，知识库（Knowledge）是一些文档（Documents）的集合。一个知识库可以被整体集成至一个应用中作为检索上下文使用。文档可以由开发者或运营人员上传，或由其它数据源同步（通常对应数据源中的一个文件单位）。

创建知识库

创建

在 Dify 主导航栏中点击知识库，在该页面你可以看到已有的知识库。你可以点击 创建知识库 进入创建向导：

  • 如果你已经准备好了文件，可以从上传文件开始;
  • 如果你还没有准备好文档，可以先创建一个空数据集;

如果你在创建数据集时选择了使用外部数据源，该知识库的类型不可更改。这是为了防止单一知识库存在多数据源而造成的管理困难。如果你需要使用多个数据源，建议创建多个知识库。

上传文档

知识库内上传文档的步骤：

  1. 从本地选择你需要上传的文档；
  2. 分段与清洗，预览效果；
  3. 选择及配置索引和检索策略；
  4. 等待分段嵌入；
  5. 完成上传，可以在应用中使用了🎉

上传文档的限制：

  • 单文档的上传大小限制为 15MB；
  • 单次批量上传文件个数上限为 20 个；
  • SaaS 版本的不同订阅计划open in new window限定了批量上传个数、文档上传总数、向量存储；

分段与清洗

分段：大语言模型存在有限的上下文窗口，通常需要将整段文本进行分段处理后，将与用户问题关联度最高的几个段落召回，即分段 TopK 召回模式。此外，在用户问题与文本分段进行语义匹配时，合适的分段大小将有助于匹配关联性最高的文本内容，减少信息噪音。

清洗： 为了保证文本召回的效果，通常需要在将数据传入模型之前对其进行清理。例如，如果输出中存在不需要的字符或者空行，可能会影响问题回复的质量。为了帮助用户解决这个问题， Dify 提供了多种清洗方法，可以帮助用户在将输出发送到下游应用程序之前对其进行清理。

分段与清洗支持两种配置策略

  • 自动模式（即将下线）
  • 自定义模式

在自定义模式下，用户可以根据不同的文档格式和场景要求来配置文本的分段和清洗策略。

分段规则：

  • 分段标识符，设置标识符如“\n”，系统将在文本中出现该标识符时分段；
  • 分段最大长度，根据分段的文本字符数最大上限来进行分段，超出该长度时将强制分段；
  • 分段重叠长度，设置分段间的重叠字符数，建议设置为分段长度的 10-25%，有助于保留分段之间的语义相关性，在多分段召回时提高召回效果。

预处理规则：

  • 替换连续的空格、换行符和制表符；
  • 删除所有 URL 和电子邮件地址；

ETL 可选配置

在 RAG 的生产级应用中，为了获得更好的数据召回效果，需要对多源数据进行预处理和清洗，即 ETL （extract, transform, load）。为了增强非结构化/半结构化数据的预处理能力，Dify 支持了可选的 ETL 方案：Dify ETL 和open in new windowUnstructured ETL open in new window。

Unstructured 能够高效地提取并转换您的数据为干净的数据用于后续的步骤。

Dify 各版本的 ETL 方案选择：

  • SaaS 版不可选，默认使用 Unstructured ETL；
  • 社区版可选，默认使用 Dify ETL ，可通过环境变量open in new window开启 Unstructured ETL；

文件解析支持格式的差异：

DIFY ETLUnstructured ETL
txt、markdown、md、pdf、html、htm、xlsx、xls、docx、csvtxt、markdown、md、pdf、html、htm、xlsx、xls、docx、csv、eml、msg、pptx、ppt、xml、epub

不同的 ETL 方案在文件提取效果的方面也会存在差异，想了解更多关于 Unstructured ETL 的数据处理方式，请参考官方文档open in new window。

索引方式

你需要选择文本的索引方式来指定数据的匹配方式，索引策略往往与检索方式相关，你需要根据场景需求来选择合适的索引方式。

高质量模式： 将调用 OpenAI 的嵌入接口进行处理，以在用户查询时提供更高的准确度。

经济模式： 会使用关键词索引方式，降低了准确度但无需花费 Token。

Q&A 模式（仅社区版支持）： Q&A 分段模式功能，与上述普通的「Q to P」（问题匹配文本段落）匹配模式不同，它是采用「Q to Q」（问题匹配问题）匹配工作，在文档经过分段后，经过总结为每一个分段生成 Q&A 匹配对，当用户提问时，系统会找出与之最相似的问题，然后返回对应的分段作为答案。这种方式更加精确，因为它直接针对用户问题进行匹配，可以更准确地获取用户真正需要的信息。

在知识库上传文档时，系统将对文本进行分段，使得用户的提问（输入）能匹配到相关的文本段落（Q to P），最后输出结果。

问题文本是具有完整语法结构的自然语言，而不是文档检索任务中的一些关键字，所以 Q to Q （问题匹配问题）的模式会令语意和匹配更加清晰，并同时满足一些高频和高相似度问题的提问场景。

检索设置

在高质量索引模式下，Dify 提供了 3 种检索方案：

  • 向量检索，通过生成查询嵌入并查询与其向量表示最相似的文本分段。
  • 全文检索，索引文档中的所有词汇，从而允许用户查询任意词汇，并返回包含这些词汇的文本片段。
  • 混合检索，同时执行全文检索和向量检索，并附加重排序步骤，从两类查询结果中选择匹配用户问题的最佳结果，需配置 Rerank 模型 API。

三种检索方式的具体配置如下：

向量检索

定义：通过生成查询嵌入并查询与其向量表示最相似的文本分段。

TopK：用于筛选与用户问题相似度最高的文本片段。系统同时会根据选用模型上下文窗口大小动态调整片段数量。系统默认值为 3 。数值越高，预期被召回的文本分段数量越多。

Score 阈值：用于设置文本片段筛选的相似度阈值，即：只召回超过设置分数的文本片段。系统默认关闭该设置，即不会对召回的文本片段相似值过滤。打开后默认值为 0.5。数值越高，预期被召回的文本数量越少。

Rerank 模型：你可以在“模型供应商”页面配置 Rerank 模型的 API 秘钥之后，在检索设置中打开“Rerank 模型”，系统会在语义检索后对已召回的文档结果再一次进行语义重排序，优化排序结果。设置 Rerank 模型后，TopK 和 Score 阈值设置仅在 Rerank 步骤生效。

全文检索

定义：索引文档中的所有词汇，从而允许用户查询任意词汇，并返回包含这些词汇的文本片段。

TopK：用于筛选与用户问题相似度最高的文本片段。系统同时会根据选用模型上下文窗口大小动态调整片段数量。系统默认值为 3 。数值越高，预期被召回的文本分段数量越多。

Score 阈值：用于设置文本片段筛选的相似度阈值，即：只召回超过设置分数的文本片段。系统默认关闭该设置，即不会对召回的文本片段相似值过滤。打开后默认值为 0.5。数值越高，预期被召回的文本数量越少。

Rerank 模型：你可以在“模型供应商”页面配置 Rerank 模型的 API 秘钥之后，在检索设置中打开“Rerank 模型”，系统会在全文检索后对已召回的文档结果再一次进行语义重排序，优化排序结果。设置 Rerank 模型后，TopK 和 Score 阈值设置仅在 Rerank 步骤生效。

混合检索

定义：同时执行全文检索和向量检索，并应用重排序步骤，从两类查询结果中选择匹配用户问题的最佳结果。在此模式下可以指定“权重设置”（无需配置 Rerank 模型 API）或选择 Rerank 模型进行检索。

权重设置：允许用户赋予语义优先和关键词优先自定义的权重。关键词检索指的是在知识库内进行全文检索（Full Text Search），语义检索指的是在知识库内进行向量检索（Vector Search）。

  • 语义值为 1

    仅启用语义检索模式。借助 Embedding 模型，即便知识库中没有出现查询中的确切词汇，也能通过计算向量距离的方式提高搜索的深度，返回正确内容。此外，当需要处理多语言内容时，语义检索能够捕捉不同语言之间的意义转换，提供更加准确的跨语言搜索结果。

    语义检索指的是比对用户问题与知识库内容中的向量距离。距离越近，匹配的概率越大。参考阅读：《Dify：Embedding 技术与 Dify 数据集设计/规划》open in new window。

  • 关键词值为 1

    仅启用关键词检索模式。通过用户输入的信息文本在知识库全文匹配，适用于用户知道确切的信息或术语的场景。该方法所消耗的计算资源较低，适合在大量文档的知识库内快速检索。

  • 自定义关键词和语义权重

    除了仅启用语义检索或关键词检索模式，我们还提供了灵活的自定义权重设置。你可以通过不断调试二者的权重，找到符合业务场景的最佳权重比例。

TopK：用于筛选与用户问题相似度最高的文本片段。系统同时会根据选用模型上下文窗口大小动态调整片段数量。系统默认值为 3 。数值越高，预期被召回的文本分段数量越多。

Score 阈值：用于设置文本片段筛选的相似度阈值，即：只召回超过设置分数的文本片段。系统默认关闭该设置，即不会对召回的文本片段相似值过滤。打开后默认值为 0.5。数值越高，预期被召回的文本数量越少。

Rerank 模型：你可以在“模型供应商”页面配置 Rerank 模型的 API 秘钥之后，在检索设置中打开“Rerank 模型”，系统会在混合检索后对已召回的文档结果再一次进行语义重排序，优化排序结果。设置 Rerank 模型后，TopK 和 Score 阈值设置仅在 Rerank 步骤生效。

文档维护

查看文本分段

知识库内已上传的每个文档都会以文本分段（Chunks）的形式进行存储，你可以在分段列表内查看每一个分段的具体文本内容。

检查分段质量

文档分段对于知识库应用的问答效果有明显影响，在将知识库与应用关联之前，建议人工检查分段质量。

通过字符长度、标识符或者 NLP 语义分段等机器自动化的分段方式虽然能够显著减少大规模文本分段的工作量，但分段质量与不同文档格式的文本结构、前后文的语义联系都有关系，通过人工检查和订正可以有效弥补机器分段在语义识别方面的缺点。

检查分段质量时，一般需要关注以下几种情况：

  • 过短的文本分段，导致语义缺失；

  • 过长的文本分段，导致语义噪音影响匹配准确性；

  • 明显的语义截断，在使用最大分段长度限制时会出现强制性的语义截断，导致召回时缺失内容；

添加文本分段

在分段列表内点击 「 添加分段 」 ，可以在文档内自行添加一个或批量添加多个自定义分段。

批量添加分段时，你需要先下载 CSV 格式的分段上传模板，并按照模板格式在 Excel 内编辑所有的分段内容，再将 CSV 文件保存后上传。

编辑文本分段

在分段列表内，你可以对已添加的分段内容直接进行编辑修改。包括分段的文本内容和关键词。

元数据管理

除了用于标记不同来源文档的元数据信息，例如网页数据的标题、网址、关键词、描述等。元数据将被用于知识库的分段召回过程中，作为结构化字段参与召回过滤或者显示引用来源。

添加文档

在「 知识库 > 文档列表 」 点击 「 添加文件 」，可以在已创建的知识库内上传新的文档或者 Notion 页面open in new window。

知识库（Knowledge）是一些文档（Documents）的集合。文档可以由开发者或运营人员上传，或由其它数据源同步（通常对应数据源中的一个文件单位）。

文档禁用和归档

禁用：数据集支持将暂时不想被索引的文档或分段进行禁用，在数据集文档列表，点击禁用按钮，则文档被禁用；也可以在文档详情，点击禁用按钮，禁用整个文档或某个分段，禁用的文档将不会被索引。禁用的文档点击启用，可以取消禁用。

归档：一些不再使用的旧文档数据，如果不想删除可以将它进行归档，归档后的数据就只能查看或删除，不可以进行编辑。在数据集文档列表，点击归档按钮，则文档被归档，也可以在文档详情，归档文档。归档的文档将不会被索引。归档的文档也可以点击撤销归档。

知识库设置

在知识库的左侧导航中点击设置，你可以改变知识库的以下设置项：

知识库名称，定义一个名称用于识别一个知识库。

知识库描述，用于描述知识库内文档代表的信息

在知识库召回模式为 N 选 1 时，知识库作为工具提供给 LLM 进行推理调用，推理依据是知识库的描述，如果描述为空则会使用 Dify 的自动索引策略

可见权限，可选择 「 只有我 」 或 「 所有团队成员 」，不具有权限的人将无法查阅和编辑数据集。

索引模式

**Embedding 模型，**修改知识库的嵌入模型，修改 Embedding 模型将对知识库内的所有文档重新嵌入，原先的嵌入将会被删除。

检索设置

知识库 API 管理

Dify 知识库提供整套标准 API ，开发者通过 API 调用对知识库内的文档、分段进行增删改查等日常管理维护操作，请参考知识库 API 文档open in new window。

应用集成

在应用内引用知识库

知识库可以作为外部知识提供给大语言模型用于精确回复用户问题，你可以在 Dify 的所有应用类型内关联已创建的知识库。

以聊天助手为例，使用流程如下：

  1. 进入 工作室 -- 创建应用 --创建聊天助手
  2. 进入 上下文设置 点击 添加 选择已创建的知识库
  3. 在 上下文设置 -- 参数设置 内配置召回策略
  4. 在 添加功能 内打开 引用和归属
  5. 在 调试与预览 内输入与知识库相关的用户问题进行调试
  6. 调试完成之后保存并发布为一个 AI 知识库问答类应用

关联知识库并指定召回模式

如果当前应用的上下文涉及多个知识库，需要设置召回模式以使得检索的内容更加精确。进入 上下文 -- 参数设置 -- 召回设置，选择知识库的召回模式。

N 选 1 召回（Legacy）

N 选 1 召回由 Function Call/ReAct 进行驱动，每一个关联的知识库作为工具函数，LLM 会自主选择与用户问题最匹配的 1 个知识库来进行查询，推理依据为用户问题与知识库描述的语义的匹配程度。

举例：A 应用的上下文关联了 K1、K2、K3 三个知识库。使用 N 选 1 召回策略后，用户在应用内输入问题后，LLM 将检索这三个知识库的描述，匹配某个最适合的知识库并使用其中的内容进行检索。

虽然此方法无需配置 Rerankopen in new window 模型，但该召回策略仅匹配单个知识库，且匹配的目标知识库严重依赖于 LLM 对于知识库描述的理解，检索匹配知识库时可能会存在不合理的判断，导致检索到的结果可能不全面、不准确，从而无法提供高质量的查询结果。

自 9 月份后，该策略将会被自动替换为多路召回，请提前进行修改。

在 N 选 1 模式下，召回效果主要受三个因素影响：

  • 系统推理模型的能力 部分模型对于 Function Call/ReAct 的指令遵循程度不稳定
  • 知识库描述是否清晰 描述内容会影响 LLM 对用户问题与相关知识库的推理
  • 知识库的个数 知识库过多会影响 LLM 的推理精确性，同时可能会超出推理模型的上下文窗口长度。

提升 N 选 1 模式推荐效果的方法：

  • 选择效果更好的系统推理模型，关联尽量少的知识库，提供精确的知识库描述。
  • 在知识库内上传文档内容时，系统推理模型将自动为知识库生成一个摘要描述。为了在该模式下获得最佳的召回效果，你可以在 “知识库->设置->知识库描述” 中查看到系统默认创建的摘要描述，并检查该内容是否可以清晰的概括知识库的内容。
多路召回（推荐）

在多路召回模式下，检索器会在所有与应用关联的知识库中去检索与用户问题相关的文本内容，并将多路召回的相关文档结果合并，以下是多路召回模式的技术流程图：

根据用户意图同时检索所有添加至 “上下文” 的知识库，在多个知识库内查询相关文本片段，选择所有和用户问题相匹配的内容，最后通过 Rerank 策略找到最适合的内容并回答用户。该方法的检索原理更为科学。

举例：A 应用的上下文关联了 K1、K2、K3 三个知识库，当用户输入问题后，将在三个知识库内检索并汇总多条内容。为确保能找到最匹配的内容，需要通过 Rerank 策略确定与用户问题最相关的内容，确保结果更加精准与可信。

在实际问答场景中，每个知识库的内容来源和检索方式可能都有所差异。针对检索返回的多条混合内容，Rerank 策略open in new window是一个更加科学的内容排序机制。它可以帮助确认候选内容列表与用户问题的匹配度，改进多个知识间排序的结果以找到最匹配的内容，提高回答质量和用户体验。

考虑到 Rerank 的使用成本和业务需求，多路召回模式提供了以下两种 Rerank 设置：

权重设置

该设置无需配置外部 Rerank 模型，重排序内容无需额外花费。可以通过调整语义或关键词的权重比例条，选择最适合的内容匹配策略。

  • 语义值为 1

    仅启用语义检索模式。借助 Embedding 模型，即便知识库中没有出现查询中的确切词汇，也能通过计算向量距离的方式提高搜索的深度，返回正确内容。此外，当需要处理多语言内容时，语义检索能够捕捉不同语言之间的意义转换，提供更加准确的跨语言搜索结果。

    语义检索指的是比对用户问题与知识库内容中的向量距离。距离越近，匹配的概率越大。参考阅读：《Dify：Embedding 技术与 Dify 数据集设计/规划》open in new window。

  • 关键词值为 1

    仅启用关键词检索模式。通过用户输入的信息文本在知识库全文匹配，适用于用户知道确切的信息或术语的场景。该方法所消耗的计算资源较低，适合在大量文档的知识库内快速检索。

  • 自定义关键词和语义权重

    除了仅启用语义检索或关键词检索模式，我们还提供了灵活的自定义权重设置。你可以通过不断调试二者的权重，找到符合业务场景的最佳权重比例。

Rerank 模型

Rerank 模型是一种外部评分系统，它会计算用户问题与给定的每个候选文档之间的相关性分数，从而改进语义排序的结果，并按相关性返回从高到低排序的文档列表。

虽然此方法会产生一定的额外花费，但是更加擅长处理知识库内容来源复杂的情况，例如混合了语义查询和关键词匹配的内容，或返回内容存在多语言的情况。

点击了解更多重排序open in new window机制。

Dify 目前支持多个 Rerank 模型，进入 “模型供应商” 页填入 Rerank 模型（例如 Cohere、Jina 等模型）的 API Key。

可调参数

  • TopK

    用于筛选与用户问题相似度最高的文本片段。系统同时会根据选用模型上下文窗口大小，动态调整分段数量。数值越高，预期被召回的文本分段数量越多。

  • Score 阈值

    用于设置文本片段筛选的相似度阈值。向量检索的相似度分数需要超过设置的分数后才会被召回，数值越高，预期被召回的文本数量越少。

多路召回模式在多知识库检索时能够获得质量更高的召回效果，因此更推荐将召回模式设置为多路召回。

常见问题

如何选择多路召回中的 Rerank 设置？

如果用户知道确切的信息或术语，可以通过关键词检索精确发挥匹配结果，那么请将 “权重设置” 中的关键词设置为 1。

如果知识库内并未出现确切词汇，或者存在跨语言查询的情况，那么推荐使用 “权重设置” 中的语义设置为 1。

如果业务人员对于用户的实际提问场景比较熟悉，想要主动调整语义或关键词的比值，那么推荐自行调整 “权重设置” 里的比值。

如果知识库内容较为复杂，无法通过语义或关键词等简单条件进行匹配，同时要求较为精准的回答，愿意支付额外的费用，那么推荐使用 Rerank 模型 进行内容检索。

为什么会出现找不到 “权重设置” 或要求必须配置 Rerank 模型等情况，应该如何处理？

以下是知识库检索方式对多路召回的影响情况：

image
image

引用多个知识库时，无法调整 “权重设置”，提示错误应如何处理？

出现此问题是因为上下文内所引用的多个知识库内所使用的嵌入模型（Embedding）不一致，为避免检索内容冲突而出现此提示。推荐设置在“模型供应商”内设置并启用 Rerank 模型，或者统一知识库的检索设置。

为什么在多路召回模式下找不到“权重设置”选项，只能看到 Rerank 模型？

请检查你的知识库是否使用了“经济”型索引模式。如果是，那么将其切换为“高质量”索引模式。

召回测试/引用归属

召回测试

Dify 知识库内提供了文本召回测试的功能，用于调试不同检索方式及参数配置下的召回效果。你可以在 源文本 输入框输入常见的用户问题，点击 测试 并在右侧的 召回段落 查看召回结果。在 最近查询 内可以查看到历史的查询记录；若知识库已关联至应用内，由应用内触发的知识库查询也可以在此查看记录。

点击源文本输入框右上角的图标可以更换当前知识库的检索方式和具体参数，保存之后仅在召回测试的调试过程中生效。在召回测试完成调试并确认更改知识库的检索参数时，需要在 知识库设置 > 检索设置open in new window 中进行更改。

召回测试建议步骤：

  1. 设计和整理覆盖常见用户问题的测试用例/测试问题集；
  2. 选择合适的检索策略：向量检索/全文检索/混合检索，不同检索方式的优缺点，请参考扩展阅读检索增强生成（RAG）open in new window；
  3. 调试召回分段数量（TopK）和召回分数阈值（Score），需根据应用场景、包括文档本身的质量来选择合适的参数组合。

TopK 值和召回阈值（Score ）如何配置

  • TopK 代表按相似分数倒排时召回分段的最大个数。TopK 值调小，将会召回更少分段，可能导致召回的相关文本不全；TopK 值调大，将召回更多分段，可能导致召回语义相关性较低的分段使得 LLM 回复质量降低。
  • **召回阈值（Score）代表允许召回分段的最低相似分数。**召回分数调小，将会召回更多分段，可能导致召回相关度较低的分段；召回分数阈值调大，将会召回更少分段，过大时将会导致丢失相关分段。

引用与归属

在应用内测试知识库效果时，你可以进入 工作室 -- 添加功能 -- 引用归属，打开引用归属功能。

开启功能后，当 LLM 引用知识库内容来回答问题时，可以在回复内容下面查看到具体的引用段落信息，包括原始分段文本、分段序号、匹配度等。点击引用分段上方的 **跳转至知识库 ，**可以快捷访问该分段所在的知识库分段列表，方便开发者进行调试编辑。

从 Notion 导入数据

Dify 知识库支持从 Notion 导入，并设置 同步 使得数据在 Notion 更新后便自动同步到 Dify。

授权验证

  1. 在创建数据集，选择数据源时，点击 同步自 Notion 内容-- 去绑定，根据提示完成授权验证。
  2. 你也可以：进入 设置 -- 数据来源 -- 添加数据源 中点击 Notion 来源 绑定 ，完成授权验证。

导入 Notion 数据

完成验证授权后，进入创建数据集页面，点击 **同步自 Notion 内容 ，**选择需要的授权页面进行导入。

进行分段和清洗

接下来，选择你的分段设置和索引方式，保存并处理。等待 Dify 为你处理这些数据，通常该步骤在 LLM 供应商中需要消耗 Token。Dify 不仅支持普通类型页面导入，并且会将 database 类型下的页面属性进行汇总保存。

请注意：图片和文件暂不支持导入，表格类数据会被转换为文本展示。

同步 Notion 数据

如果您的 Notion 内容有修改，您可以直接在 Dify 数据集 文档列表页中点击 同步 即可进行数据一键同步，该步骤是需要消耗 Token。

社区版 Notion 的集成配置方法

Notion集成分为内部集成（internal integration）和外部集成（public integration）两种方式。可按需在 Dify 里配置。两种集成方式的具体区别请参阅 Notion 官方文档open in new window。

使用 internal 集成方式

首先，在集成的设置页面中创建集成open in new window。默认情况下，所有集成都以内部集成开始；内部集成将与您选择的工作区相关联，因此您需要是工作区所有者才能创建集成。

具体操作步骤：

点击“New integration”按钮，类型默认是 Internal（不可修改），选择关联的空间，输入集成名称并上传 logo 后，点击“Submit”，集成创建成功。

创建集成后，您可以根据需要在 Capabilities 选项卡下更新其设置，并在 Secrets 下点击 “Show” 按钮然后复制 Secrets。

复制后回到 Dify 源代码下，在 .env 文件里配置相关环境变量，环境变量如下：

NOTION_INTEGRATION_TYPE = internal or NOTION_INTEGRATION_TYPE = public

NOTION_INTERNAL_SECRET=you-internal-secret

使用 Public 集成方式

需要将 internal 集成升级为 public 集成，导航到集成的 Distribution 页面，然后切换开关以公开集成。将开关切换到公共设置，您需要在下面的 Organization Information 表单中填写其他信息，包括您的公司名称、网站和重定向 URL 等信息，然后点击“Submit”按钮。

在集成的设置页面中成功公开集成后，您将能够在密钥选项卡中访问集成的密钥：

回到 Dify 源代码下，在 .env 文件里配置相关环境变量，环境变量如下：

NOTION_INTEGRATION_TYPE=public

NOTION_CLIENT_SECRET=you-client-secret

NOTION_CLIENT_ID=you-client-id

配置完成后，即可在数据集中操作 Notion 的数据导入及同步功能。

从网页导入数据

Dify 知识库通过集成 Firecrawl ，支持网页抓取并解析为 Markdown 导入至知识库。

Firecrawl open in new window是一个开源的网页解析工具，它能将网页将其转换为干净并且方便 LLM 识别的 Markdown 格式文本，它同时提供了易于使用的 API 服务。

配置

首先需要在 DataSource 页面内配置 Firecrawl 的凭据。

登录 Firecrawl 官网open in new window 完成注册，获取 API Key 后填入并保存。

在知识库创建页选择 Sync from website，填入需要抓取的网页 URL。

设置中的配置项包括：是否抓取子页面、抓取页面数量上限、页面抓取深度、排除页面、仅抓取页面、提取内容。完成配置后点击 Run，预览已解析的页面。

导入网页解析的文本后存储至知识库的文档中，查看导入结果。点击 Add URL 可以继续导入新的网页。

通过 API 维护知识库

鉴权、调用方式与应用 Service API 保持一致，不同的是一个数据集 API token 可操作所有数据集

使用数据集API的优势

  • 将您的数据系统同步至 Dify 数据集，创建强大的工作流程。
  • 提供数据集列表，文档列表及详情查询，方便构建您自己的数据管理页。
  • 同时支持纯文本和文件两种上传和更新文档的接口，并支持分段级的批量新增和修改，便捷您的同步方式。
  • 减少文档手动处理同步的时间,提高您对 Dify 的软件和服务的可见性。

使用

进入数据集页面，你可以在左侧的导航中切换至 API 页面。在该页面中你可以查看 Dify 提供的数据集 API 文档，并可以在 API 密钥 中管理可访问数据集 API 的凭据。

API 调用示例

创建空数据集

仅用来创建空数据集

curl --location --request POST 'https://api.dify.ai/v1/datasets' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{"name": "name"}'
数据集列表
curl --location --request GET 'https://api.dify.ai/v1/datasets?page=1&limit=20' \
--header 'Authorization: Bearer {api_key}'
通过文本创建文档
curl --location --request POST '<https://api.dify.ai/v1/datasets/<uuid:dataset_id>/document/create_by_text>' \\
--header 'Authorization: Bearer {api_key}' \\
--header 'Content-Type: application/json' \\
--data-raw '{
    "name": "Dify",
    "text": "Dify means Do it for you...",
    "indexing_technique": "high_quality",
    "process_rule": {
        "rules": {
                "pre_processing_rules": [{
                        "id": "remove_extra_spaces",
                        "enabled": true
                }, {
                        "id": "remove_urls_emails",
                        "enabled": true
                }],
                "segmentation": {
                        "separator": "###",
                        "max_tokens": 500
                }
        },
        "mode": "custom"
    }
}'
通过文件创建文档
curl --location POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create_by_file' \
--header 'Authorization: Bearer {api_key}' \
--form 'data="{
	"name": "Dify",
	"indexing_technique": "high_quality",
	"process_rule": {
		"rules": {
			"pre_processing_rules": [{
				"id": "remove_extra_spaces",
				"enabled": true
			}, {
				"id": "remove_urls_emails",
				"enabled": true
			}],
			"segmentation": {
				"separator": "###",
				"max_tokens": 500
			}
		},
		"mode": "custom"
	}
    }";
    type=text/plain' \
--form 'file=@"/path/to/file"'
获取文档嵌入状态（进度）
curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{batch}/indexing-status' \
--header 'Authorization: Bearer {api_key}'
删除文档
curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}' \
--header 'Authorization: Bearer {api_key}'
数据集文档列表
curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents' \
--header 'Authorization: Bearer {api_key}'
新增分段
curl 'https://api.dify.ai/v1/datasets/aac47674-31a8-4f12-aab2-9603964c4789/documents/2034e0c1-1b75-4532-849e-24e72666595b/segment' \
  --header 'Authorization: Bearer {api_key}' \
  --header 'Content-Type: application/json' \
  --data-raw $'"chunks":[
  {"content":"Dify means Do it for you",
  "keywords":["Dify","Do"]
  }
  ]'
  --compressed

错误信息

  • document_indexing，文档索引失败
  • provider_not_initialize， Embedding 模型未配置
  • not_found，文档不存在
  • dataset_name_duplicate ，数据集名称重复
  • provider_quota_exceeded，模型额度超过限制
  • dataset_not_initialized，数据集还未初始化
  • unsupported_file_type，不支持的文件类型
    • 目前只支持：txt, markdown, md, pdf, html, htm, xlsx, docx, csv
  • too_many_files，文件数量过多，暂时只支持单一文件上传
  • file_too_large，文件太大，支持15M以下

外部数据工具

功能介绍

此前 功能允许开发者可以直接上传各类格式的长文本、结构化数据来构建数据集，使 AI 应用基于用户上传的最新上下文进行对话。

而本次更新的外部数据工具赋能开发者可以使用自有的搜索能力或内部知识库等外部数据作为 LLM 的上下文，通过 API 扩展的方式实现外部数据的获取并嵌入提示词。

相比在云端上传数据集，使用外部数据工具可以在保障私有数据安全，自定义搜索，获取实时数据等方面有显著优势。

具体实现

当终端用户向对话系统提出请求时，平台后端会触发外部数据工具（即调用自己的 API），它会查询用户问题相关的外部信息，如员工资料、实时记录等，

通过 API 返回与当前请求相关的部分，平台后端会将返回的结果组装成文本作为上下文注入到提示词中，以输出更加个性化和符合用户需求的回复内容。

操作说明

在使用外部数据工具之前，你需要准备一个 API 和用于鉴权的 API Key

Dify 提供了集中式的 API 管理，在设置界面统一添加 API 扩展配置后，即可在 Dify 上的各类应用中直接使用。

工具

概念

工具可以扩展 LLM 的能力，比如联网搜索、科学计算或绘制图片，赋予并增强了 LLM 连接外部世界的能力。Dify 提供了两种工具类型：第一方工具和自定义工具。

你可以直接使用 Dify 生态提供的第一方内置工具，或者轻松导入自定义的 API 工具（目前支持 OpenAPI / Swagger 和 OpenAI Plugin 规范）。

工具的作用：

  1. 工具使用户可以在 Dify 上创建更强大的 AI 应用，如你可以为智能助理型应用（Agent）编排合适的工具，它可以通过任务推理、步骤拆解、调用工具完成复杂任务。
  2. 方便将你的应用与其他系统或服务连接，与外部环境交互，如代码执行、对专属信息源的访问等。

官方工具

Dify 目前已支持：

工具工具描述
谷歌搜索用于执行 Google SERP 搜索并提取片段和网页的工具。输入应该是一个搜索查询
维基百科用于执行维基百科搜索并提取片段和网页的工具。
DALL-E 绘画用于通过自然语言输入生成高质量图片
网页抓取用于爬取网页数据的工具
WolframAlpha一个强大的计算知识引擎，能根据问题直接给出标准化答案，同时具有强大的数学计算功能
图表生成用于生成可视化图表的工具，你可以通过它来生成柱状图、折线图、饼图等各类图表
当前时间用于查询当前时间的工具
雅虎财经获取并整理出最新的新闻、股票报价等一切你想要的财经信息。
Stable Diffusion一个可以在本地部署的图片生成的工具，您可以使用 stable-diffusion-webui 来部署它
Vectorizer一个将 PNG 和 JPG 图像快速轻松地转换为 SVG 矢量图的工具。
YouTube一个用于获取油管频道视频统计数据的工具

欢迎您为 Dify 贡献自己开发的工具，关于如何贡献的具体方法请查看 Dify 开发贡献文档open in new window，您的任何支持对我们都是极为宝贵的。

若你需要直接使用 Dify 生态提供的第一方内置工具，你需要在使用前配置相应的凭据。

凭据校验成功后工具会显示“已授权”状态。配置凭据后，工作区中的所有成员都可以在编排应用程序时使用此工具。

自定义工具

你可以在“工具-自定义工具”内导入自定义的 API 工具，目前支持 OpenAPI / Swagger 和 ChatGPT Plugin 规范。你可以将 OpenAPI schema 内容直接粘贴或从 URL 内导入。关于 OpenAPI / Swagger 规范您可以查看官方文档说明open in new window。

工具目前支持两种鉴权方式：无鉴权 和 API Key。

在导入 Schema 内容后系统会主动解析文件内的参数，并可预览工具具体的参数、 方法、路径。您也可以在此对工具参数进行测试。

完成自定义工具创建之后，工作区中的所有成员都可以在“工作室”内编排应用程序时使用此工具。

已添加自定义工具

Cloudflare Workers

您也可以使用 dify-tools-workeropen in new window 来快速部署自定义工具。该工具提供了：

  • 可以导入 Dify 的路由 https://difytoolsworker.yourname.workers.dev/doc, 提供了 OpenAPI 兼容的接口文档
  • API 的实现代码，可以直接部署到 Cloudflare Workers

应用内使用工具

目前，您可以在“工作室”中创建智能助手型应用时，将已配置好凭据的工具在其中使用。

在财务分析应用内添加工具后，智能助手将在需要时自主调用工具，从工具中查询财务报告数据，并将数据分析后完成与用户之间的对话。

接入工具

快速接入工具open in new window

高级接入工具open in new window

工具配置open in new window

上次编辑于:
贡献者: 李元昊
Copyright © 2025 程序员李某某