Dify 知识库 API 操作指南

写在前面

如果你已经在 Dify 的界面上手动建过知识库、传过文档、做过检索测试，那你对知识库的构建流程应该不陌生了。但一旦数据量上来，或者你想把知识库接入自己的业务系统，手动操作就不够用了——这时候就需要用到知识库 API。

这篇笔记会以”搭建一个个人学习资料库”为线索，从创建空知识库开始，一路走到添加文档、管理分段、检索内容、更新删除，把常用 API 串成一条完整的链路。所有例子都围绕同一个场景展开，方便你对照着一步步操作。

参考来源：Dify 官方 API 文档-https://docs.dify.ai/api-reference

一、先搞懂三层结构：知识库、文档、分段

在动手调 API 之前，必须先理清 Dify 知识库的三层结构，否则后面的接口路径会把你绕晕。

打个比方，Dify 的知识库就像一个书架：

  • 知识库（Dataset） 就是书架本身。你给书架起个名字，比如”我的学习资料库”，它是一个容器。
  • 文档（Document） 就是书架上的一本本书。每本书有自己的名字和内容，比如《Python 基础笔记》《机器学习入门》。
  • 分段（Segment / Chunk） 就是每本书里的一个个章节。Dify 会把一本书的内容切成若干小段，检索的时候是按段来匹配的，而不是整本书。

这三层是包含关系：书架里有书，书里有章节。API 的路径也严格对应这个层级：

1
2
3
/datasets                                              -> 操作书架
/datasets/{dataset_id}/documents                       -> 操作某书架里的书
/datasets/{dataset_id}/documents/{document_id}/segments -> 操作某本书里的章节

记住这个”书架-书-章节”的比喻，后面所有的接口路径你都能对上号。

二、认证：所有请求都要带的一把钥匙

Dify 知识库 API 用 API Key 做认证，同 Dify 的工作流调用方式一样，每个请求的 HTTP Header 里加上：

1
Authorization: Bearer {你的API_KEY}

这把钥匙怎么拿？在 Dify 界面上，进入”知识库”页面，左侧切到”API 访问”（API ACCESS），就能看到 API 文档和 API Key 管理入口，在那里面创建一个 Key 就行。

有两点要特别注意：

第一，知识库的 API Key 和应用的 API Key 不是一回事。应用 API Key 只能操作对应的应用（比如聊天助手），而知识库 API Key 可以操作你账号下所有的知识库。所以这把钥匙权限更大，务必保管好，别放到前端代码里泄露出去。

第二，一个知识库 API Key 能操作所有可见的知识库，不需要为每个知识库单独生成 Key。这既是方便，也是风险点，调用时要确认好 dataset_id 别写错。

三、第一步：创建一个空知识库

现在开始我们的主线任务：用 API 搭建一个”个人学习资料库”。

创建知识库的接口是 POST /datasets，它会创建一个空的书架，里面还没有任何书。

来个实际的调用例子：

1
2
3
4
5
6
7
8
9
10
11
12
13
curl --request POST \
  --url https://api.dify.ai/v1/datasets \
  --header 'Authorization: Bearer {你的API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "个人学习资料库",
    "description": "存放我学习过程中的笔记和资料",
    "indexing_technique": "high_quality",
    "permission": "only_me",
    "provider": "vendor",
    "embedding_model": "text-embedding-3-small",
    "embedding_model_provider": "openai"
  }'

请求成功后，返回里最重要的就是知识库的 id，类似这样：

1
2
3
4
5
6
7
{
  "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
  "name": "个人学习资料库",
  "indexing_technique": "high_quality",
  "document_count": 0,
  "embedding_model": "text-embedding-3-small",
}

把这个 id 记下来，后面所有的操作都要用到它。在我们的例子里，假设它是 c42e2a6e-40b3-4330-96f8-f1e4d768e8c9。

几个容易搞混的参数解释

indexing_technique（索引方式） 有两个选项：high_quality 和 economy。

用买书来打比方：high_quality 就像给每本书都做了一个精装版索引，用嵌入模型把内容转成向量，检索时能理解语义，找得准但费资源；economy 就像一个简装版目录，只做关键词倒排索引，找得快但只认字面匹配，理解不了同义词。

学习资料库建议用 high_quality，因为学习笔记里经常有”梯度下降”和”gradient descent”这种同一概念不同写法的情况，语义检索能帮你都找到。

permission（权限） 控制谁能看到这个知识库：only_me 只有自己能用，all_team_members 团队所有人能用，partial_members 指定部分成员。个人资料库选 only_me 就行。

provider 填 vendor 表示用 Dify 内部的知识库，填 external 表示接外部知识库（比如你已经有一个向量数据库了）。我们用 vendor。

embedding_model 和 embedding_model_provider 只有在选了 high_quality 时才需要指定，告诉 Dify 用哪个嵌入模型把文本转向量。上面的例子用的是 OpenAI 的 text-embedding-3-small。具体有哪些模型可选，可以在 Dify 界面的模型供应商页面查看。

四、第二步：看看我有哪些知识库

创建完之后，想确认一下或者查看所有知识库列表，用 GET /datasets：

1
2
3
curl --request GET \
  --url 'https://api.dify.ai/v1/datasets?page=1&limit=20' \
  --header 'Authorization: Bearer {你的API_KEY}'

支持分页，page 是页码，limit 是每页条数。还可以用 keyword 参数按名字搜索，比如 ?keyword=学习 就能筛出名字里带”学习”的知识库。

返回的是一个数组，每个元素就是一个知识库的信息，包含 id、名字、文档数量、词数等等。从返回里找到你刚创建的”个人学习资料库”，确认它的 id。

五、第三步：往知识库里添加文档

书架建好了，现在要往里面放书。添加文档有两种方式：通过文本和通过文件。

方式一：通过文本创建文档

如果你手里就是一段纯文本内容，比如你手写的学习笔记，可以直接用文本接口：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl --request POST \
  --url https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9/document/create-by-text \
  --header 'Authorization: Bearer {你的API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Python基础笔记",
    "text": "Python 是一种解释型、高级编程语言。它的设计哲学强调代码的可读性。Python 支持多种编程范式，包括面向对象、命令式、函数式和过程式编程。\n\n变量是存储数据的容器。在 Python 中，不需要提前声明变量类型，直接赋值即可。例如：x = 10 就创建了一个整数变量。",
    "indexing_technique": "high_quality",
    "doc_form": "text_model",
    "doc_language": "Chinese",
    "process_rule": {
      "mode": "automatic"
    }
  }'

返回里有两个关键信息：

1
2
3
4
5
6
7
8
9
{
  "document": {
    "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
    "name": "Python基础笔记",
    "indexing_status": "indexing",
    ...
  },
  "batch": "20250306150245647595"
}

document.id 是这本”书”的编号，后面管理这本”书”要用。batch 是一个批次号，用来查处理进度的，相当于快递单号——文档添加后是异步处理的，你得拿这个单号去查”包裹到哪了”。

假设我们的文档 id 是 a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac，batch 是 20250306150245647595。

方式二：通过文件创建文档

如果你有一个 PDF、Word、TXT 等文件，用文件接口上传：

1
2
3
4
5
curl --request POST \
  --url https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9/document/create-by-file \
  --header 'Authorization: Bearer {你的API_KEY}' \
  --form 'data="{"indexing_technique":"high_quality","process_rule":{"mode":"automatic"}}";type=text/plain' \
  --form 'file=@"/path/to/机器学习入门.pdf"'

注意文件接口的参数是通过 form-data 传的，data 字段里放 JSON 配置，file 字段放文件本身。

几个关键参数解释

doc_form（文档形式） 决定了 Dify 怎么切分和处理文档，有三个选项，用记笔记的方式来比喻：

  • text_model（文本模式）：就像普通记笔记，把内容按段落切开，每段是一块。最常用，适合大多数文档。
  • hierarchical_model（父子模式）：就像写笔记时先写大纲再写细节，切出来有”父块”和”子块”两层结构。检索时先定位子块，再返回父块提供更多上下文，适合长文档。
  • qa_model（问答模式）：就像做复习卡片，每块内容是一问一答的形式。适合 FAQ 类资料。

学习笔记一般用 text_model 就够了。

process_rule（处理规则） 控制文档怎么被清洗和分段：

  • mode: "automatic" 是自动模式，Dify 用默认规则帮你切，省心。
  • mode: "custom" 是自定义模式，你可以指定分隔符和每段最大长度，像这样：
1
2
3
4
5
6
7
8
9
10
11
12
13
"process_rule": {
  "mode": "custom",
  "rules": {
    "pre_processing_rules": [
      {"id": "remove_extra_spaces", "enabled": true},
      {"id": "remove_urls_emails", "enabled": true}
    ],
    "segmentation": {
      "separator": "\n\n",
      "max_tokens": 500
    }
  }
}

用切蛋糕来比喻：automatic 就是让厨师帮你切，你不用管；custom 就是你自己指定刀怎么下——先去掉奶油（预处理），再按特定间距切（分段），每块不超过多大（max_tokens）。

预处理规则有两个：remove_extra_spaces 清理多余空格和换行，remove_urls_emails 去掉 URL 和邮箱地址。分段规则里 separator 是分隔符，max_tokens 是每段最大 token 数。

六、第四步：查一下文档处理好了没

前面说过，添加文档是异步的——你提交了请求，Dify 说”收到了，正在处理”，但不会等你。那怎么知道处理完了？

用 batch 号查进度，接口是 GET /datasets/{dataset_id}/documents/{batch}/indexing-status：

1
2
3
curl --request GET \
  --url https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9/documents/20250306150245647595/indexing-status \
  --header 'Authorization: Bearer {你的API_KEY}'

返回类似这样：

1
2
3
4
5
6
7
8
9
10
{
  "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
  "indexing_status": "completed",
  "processing_started_at": 1741267200,
  "parsing_completed_at": 1741267210,
  "indexing_completed_at": 1741267220,
  "completed_segments": 3,
  "total_segments": 3,
  "error": null
}

indexing_status 会有几种状态：waiting（排队中）、parsing（解析中）、indexing（索引中）、completed（完成了）、error（出错了）。等状态变成 completed 就可以检索了。

这就像你寄快递后查物流：下单了显示”已揽收”（waiting），运输中显示”运输中”（indexing），到了显示”已签收”（completed）。

七、第五步：看看知识库里有哪些文档

想列出某个知识库下的所有文档，用 GET /datasets/{dataset_id}/documents：

1
2
3
curl --request GET \
  --url 'https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9/documents?page=1&limit=20' \
  --header 'Authorization: Bearer {你的API_KEY}'

返回一个文档数组，每个文档包含 id、名字、字数、状态、是否启用等信息。你可以从这里找到某本文档的 id，后续操作要用。

八、第六步：管理文档分段（章节）

前面说过，文档会被切成一个个分段（章节）。有时候你想手动加一个分段，或者修改、删除某个分段，这就需要分段管理 API。

新增一个分段

比如你想给”Python基础笔记”补充一段关于列表的内容：

1
2
3
4
5
6
7
8
9
10
11
12
curl --request POST \
  --url https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9/documents/a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac/segments \
  --header 'Authorization: Bearer {你的API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "segments": [
      {
        "content": "列表是 Python 中最常用的数据结构之一。用方括号创建，元素之间用逗号分隔。例如：nums = [1, 2, 3] 创建了一个包含三个整数的列表。列表支持增删改查，常用方法有 append、remove、sort 等。",
        "keywords": ["列表", "list", "数据结构"]
      }
    ]
  }'

keywords 是可选的，给分段加上关键词能帮助检索时更精准地命中。就像给书里的章节贴上标签，方便以后查找。

查看文档的所有分段

1
2
3
curl --request GET \
  --url 'https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9/documents/a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac/segments' \
  --header 'Authorization: Bearer {你的API_KEY}'

返回这个文档下所有分段，每个分段有 id、位置、内容、词数、命中次数等。假设我们刚加的分段 id 是 f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1。

更新一个分段

发现之前写的列表内容有误，想改一下：

1
2
3
4
5
6
7
8
9
10
11
curl --request POST \
  --url https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9/documents/a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac/segments/f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1 \
  --header 'Authorization: Bearer {你的API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "segment": {
      "content": "列表是 Python 中最常用的数据结构之一。用方括号创建，元素之间用逗号分隔。例如：nums = [1, 2, 3] 创建了一个包含三个整数的列表。列表是可变序列，支持 append、extend、insert、remove、pop、sort、reverse 等方法。",
      "keywords": ["列表", "list", "数据结构", "可变序列"],
      "enabled": true
    }
  }'

enabled 控制这个分段是否参与检索，设成 false 就相当于暂时把这个章节”下架”，检索时不会命中它，但内容还在。

删除一个分段

1
2
3
curl --request DELETE \
  --url https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9/documents/a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac/segments/f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1 \
  --header 'Authorization: Bearer {你的API_KEY}'

删除后这个分段就彻底没了，检索也不会再命中。操作前确认好，删除不可恢复。

九、第七步：检索知识库——最核心的功能

前面建书架、放书、管章节，最终目的都是为了检索。检索接口是 POST /datasets/{dataset_id}/retrieve，它会根据你的问题，从知识库里找出最相关的分段。

来个实际例子，比如我想查”Python 里怎么存多个数据”：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl --request POST \
  --url https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9/retrieve \
  --header 'Authorization: Bearer {你的API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "Python 里怎么存多个数据",
    "retrieval_model": {
      "search_method": "hybrid_search",
      "top_k": 3,
      "score_threshold_enabled": true,
      "score_threshold": 0.5,
      "reranking_enable": false
    }
  }'

返回里 records 是命中的分段列表，每条包含分段内容和匹配分数：

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "query": {"content": "Python 里怎么存多个数据"},
  "records": [
    {
      "segment": {
        "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
        "content": "列表是 Python 中最常用的数据结构之一...",
        "document": {"name": "Python基础笔记"}
      },
      "score": 0.85
    }
  ]
}

检索参数详解

search_method（搜索方式） 是最容易搞混的，用去图书馆找书来比喻：

  • semantic_search（语义搜索）：就像你跟图书管理员说”我想找讲 Python 数据结构的书”，管理员理解你的意思后帮你找。它用向量相似度匹配，能理解同义词和语义，但需要嵌入模型支持。
  • full_text_search（全文搜索）：就像你用图书馆的电脑搜”列表”这个关键词，只认字面匹配。速度快，但”数组”和”列表”这种同义但不同字的情况找不到。
  • hybrid_search（混合搜索）：两者结合，既理解语义又认关键词，通常效果最好。推荐用这个。

top_k 控制返回几条结果。比如 top_k: 3 就是只要最相关的 3 条。就像你问图书管理员要推荐，他说”给你挑 3 本最好的”。

score_threshold_enabled 和 score_threshold 控制质量门槛。开启后，只有匹配分数超过阈值的分段才会返回。用招聘来比喻：top_k 是”最多面试 3 个人”，score_threshold 是”但分数低于 60 的不要”——两个条件同时生效，可能返回不足 3 条。

reranking_enable（重排序） 开启后，会用一个专门的重排序模型对初步检索结果做二次排序。用图书管理员来比喻：第一次检索像实习生帮你粗筛了一堆书，重排序像资深馆员再帮你精排一遍，把最相关的排到最前面。重排序能提升精度，但会增加一次模型调用，耗时更长。

开启重排序时需要配置 reranking_model，指定重排序模型的供应商和名称：

1
2
3
4
5
6
7
8
9
10
"retrieval_model": {
  "search_method": "hybrid_search",
  "top_k": 5,
  "reranking_enable": true,
  "reranking_mode": "reranking_model",
  "reranking_model": {
    "reranking_provider_name": "cohere",
    "reranking_model_name": "rerank-multilingual-v3.0"
  }
}

检索结果怎么用

检索返回的 records 里每条都有 segment.content（分段内容）和 score（匹配分数）。在实际应用中，你通常会把检索到的内容拼到 LLM 的提示词里，让 LLM 基于这些内容回答用户问题——这就是 RAG（检索增强生成）的核心流程。

十、第八步：更新和删除文档

更新文档内容

如果你的学习笔记有更新，想替换整篇内容，用更新接口。和创建一样分文本和文件两种：

通过文本更新：

1
2
3
4
5
6
7
8
9
curl --request POST \
  --url https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9/documents/a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac/update-by-text \
  --header 'Authorization: Bearer {你的API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Python基础笔记（修订版）",
    "text": "Python 是一种解释型、高级编程语言。它由 Guido van Rossum 于 1991 年发布...",
    "process_rule": {"mode": "automatic"}
  }'

更新后 Dify 会重新处理文档（重新切分、重新索引），返回一个新的 batch 号，同样可以用来查进度。

删除文档

某篇笔记不要了，可以删除：

1
2
3
curl --request DELETE \
  --url https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9/documents/a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac \
  --header 'Authorization: Bearer {你的API_KEY}'

删除文档会连同它下面的所有分段一起删掉，不可恢复，操作前想清楚。

十一、第九步：删除知识库

最后，如果整个知识库都不要了，可以删掉整个”书架”：

1
2
3
curl --request DELETE \
  --url https://api.dify.ai/v1/datasets/c42e2a6e-40b3-4330-96f8-f1e4d768e8c9 \
  --header 'Authorization: Bearer {你的API_KEY}'

这会删除知识库及其下所有文档和分段，是一个不可逆的操作，谨慎使用。

十二、完整流程回顾

把前面所有步骤串起来，用 API 管理一个知识库的完整流程是这样的：

第一步，POST /datasets 创建一个空知识库，拿到 dataset_id。

第二步，GET /datasets 查看知识库列表，确认创建成功。

第三步，POST /datasets/{dataset_id}/document/create-by-text（或 create-by-file）往知识库里添加文档，拿到 document_id 和 batch。

第四步，GET /datasets/{dataset_id}/documents/{batch}/indexing-status 查文档处理进度，等状态变成 completed。

第五步，GET /datasets/{dataset_id}/documents 查看知识库里的文档列表。

第六步，用分段 API 管理文档的章节：POST .../segments 新增、GET .../segments 查看、POST .../segments/{segment_id} 更新、DELETE .../segments/{segment_id} 删除。

第七步，POST /datasets/{dataset_id}/retrieve 检索知识库，这是最常用的功能。

第八步，需要时用 POST .../update-by-text 更新文档，或 DELETE .../documents/{document_id} 删除文档。

第九步，整个知识库不要了，DELETE /datasets/{dataset_id} 删除。

十三、几个实用小贴士

关于异步处理：除了检索和查询类接口，创建、更新文档都是异步的。调用后返回的 batch 号一定要存下来，配合 indexing-status 接口轮询，确认处理完成后再进行后续操作。不然文档还没处理完就去检索，是搜不到内容的。

关于错误码：常见的几个错误要心里有数。返回 400 通常是参数有问题；401 是 API Key 不对或过期；404 是 dataset_id 或 document_id 写错了；413 是文件太大超限了。遇到问题先看 HTTP 状态码和返回的 error 信息。

关于生产环境：如果你要把这些 API 用到生产环境，建议做好几件事——API Key 存在后端别暴露给前端；调用时做好重试和超时处理；批量添加文档时控制并发，别一次性塞太多把服务压垮；定期用检索接口测试知识库效果，确保数据质量。

关于 API 地址：文中的例子用的是 Dify 云端的地址 https://api.dify.ai。如果你是本地部署的 Dify，要换成你自己的服务地址，比如 http://localhost/v1 或 http://你的服务器IP/v1，注意路径里的 /v1 不能少。

写在最后

Dify 的知识库 API 本质上就是围绕”书架-书-章节”三层结构做增删改查，再加上一个检索功能。只要理清了层级关系，记住每个接口对应的路径规律，用起来并不复杂。

建议你照着这篇笔记，用自己的 API Key 把流程跑一遍：建个知识库，传篇笔记，查查进度，检索一下，改改分段。亲手操作一遍，比看十遍文档都管用。

如果遇到接口参数不确定的情况，最权威的参考永远是官方文档 ，不同版本的 Dify 接口可能有细微差异，以你实际使用的版本为准。