本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。不经过 Dify 控制台，直接在自己的代码中构建和维护 知识库：创建知识库、导入文档和分段、用元数据和标签组织内容，并可直接调用检索接口用于搜索或 RAG。
单个知识库 API 密钥可访问创建该密钥的账户下所有可见的知识库，妥善保管密钥，避免数据意外泄露。
获取 API 端点和密钥
在 知识库 页面右上角点击 服务 API，打开 API 配置面板，可在此：- 复制服务 API 端点，这是所有知识库 API 请求的基础 URL。
- 点击 API 密钥 创建和管理密钥。
管理知识库的 API 访问权限
默认情况下，每个知识库都可通过 API 访问。如需限制某个知识库的访问，打开该知识库，点击左下角的 访问 API，关闭开关即可。创建和管理知识库
- 创建空知识库：创建一个还没有文档的知识库。
- 获取知识库列表：返回分页列表，支持按关键词或标签筛选。
- 获取知识库详情：返回单个知识库的嵌入模型、检索配置和文档统计信息。
- 更新知识库：修改名称、权限、嵌入模型或检索设置，只更新请求中提供的字段。
- 删除知识库：永久删除知识库及其中的所有文档。
- 从知识库检索分段 / 测试检索：搜索知识库并返回最相关的分段，生产检索和召回测试共用同一个接口。
添加和更新文档
文档创建是异步的，需要先创建文档，再轮询等待索引完成：创建知识库
调用 创建空知识库，也可直接使用已有的知识库。
轮询索引状态
使用
batch ID 轮询 获取文档嵌入状态（进度），直到 indexing_status 变为 completed 或 error，期间会依次经过 waiting、parsing、cleaning、splitting、indexing 几个阶段。- 获取知识库的文档列表：返回分页列表，支持按关键词或索引状态筛选。
- 获取文档详情：返回文档的索引状态、元数据和处理统计信息，
metadata查询参数控制响应包含、省略还是仅返回元数据字段。 - 下载文档：返回文档原始上传文件的签名下载 URL。
- 批量下载文档（ZIP）：最多可将 100 个通过文件上传的文档打包为一个压缩包。
- 更新文档：上传新文件替换文档内容并重新触发索引，是基于文件更新文档的标准方式。
- 用文本更新文档：直接更新文档的文本内容、名称或处理配置，内容变更时将重新触发索引。
- 用文件更新文档：已废弃的别名接口，用于上传替换文件，改用「更新文档」。
- 批量更新文档状态：一次性启用、禁用、归档或取消归档多个文档。
- 删除文档：永久删除文档及其中的所有分段。
管理分段与子分段
- 向文档添加分段：手动为文档添加分段（上传的内容在索引时已自动分段）。每个分段都需要
content，问答模式的文档还需要answer。 - 从文档获取分段：返回分页列表，支持按关键词或状态筛选。
- 获取文档中的分段详情：返回单个分段的内容、关键词和索引状态。
- 更新文档中的分段：修改分段的内容、关键词或答案，并为该分段重新触发索引。
- 删除文档中的分段：永久删除该分段。
hierarchical_model）的文档，子分段挂在父分段下。通过 API 创建或更新的子分段，其 type 始终为 customized，区别于索引流程自动生成的 automatic 子分段。
管理元数据字段
元数据字段为文档附加结构化信息，检索时可据此过滤：- 创建元数据字段：为知识库添加自定义字段，类型可为
string、number或time。 - 获取元数据字段列表：返回全部字段（包括自定义和内置字段），并给出每个字段的使用文档数。
- 更新元数据字段：重命名自定义字段。
- 删除元数据字段：删除自定义字段，文档会随之丢失该字段的取值。
- 获取内置元数据字段：返回系统内置字段，如
document_name、uploader、upload_date。 - 更新内置元数据字段：为知识库启用或禁用内置字段。
- 批量更新文档元数据：在一次调用中为多个文档设置元数据键值对。
用标签组织知识库
标签在工作空间层面管理，不依附于某个具体知识库：- 创建知识库标签：创建用于组织知识库的标签。
- 获取知识库标签列表：返回工作空间内的全部标签。
- 修改知识库标签：重命名标签。
- 删除知识库标签：将标签从所有绑定的知识库上移除，但不会删除这些知识库。
- 绑定标签到知识库：为知识库绑定一个或多个标签，一个知识库可同时绑定多个标签。
- 解除标签与知识库的绑定：从知识库上移除标签。
- 获取知识库绑定的标签：返回某个知识库当前绑定的标签。
查询可用模型
- 获取可用模型：返回指定
model_type下的可用模型。配置知识库时，可查询text-embedding获取嵌入模型，或查询rerank获取重排序模型。