外部知识库 API

作者： Allen。 Dify Technical Writer。

端点

POST <your-endpoint>/retrieval

请求头

该 API 用于连接团队内独立维护的知识库，如需了解更多操作指引，请参考阅读 连接外部知识库。你可以在 HTTP 请求头的 Authorization 字段中使用 API-Key 来验证权限。身份验证逻辑由你在检索 API 中定义，如下所示：

Authorization: Bearer {API_KEY}

请求体元素

请求接受以下 JSON 格式的数据。

属性	是否必需	类型	描述	示例值
knowledge_id	是	字符串	知识库唯一 ID	AAA-BBB-CCC
query	是	字符串	用户的查询	Dify 是什么？
retrieval_setting	是	对象	知识检索参数	见下文
metadata_condition	否	对象	原数组筛选	见下文

retrieval_setting 属性是一个包含以下键的对象：

属性	是否必需	类型	描述	示例值
top_k	是	整数	检索结果的最大数量	5
score_threshold	是	浮点数	结果与查询相关性的分数限制，范围：0~1	0.5

metadata_condition 属性是一个包含以下键的对象：

属性	是否必需	类型	描述	示例值
logical_operator	否	字符串	逻辑操作符，取值为 and 或 or，默认 and	and
conditions	是	数组（对象）	条件列表	见下文

conditions 数组中的每个对象包含以下键：

属性	是否必需	类型	描述	示例值
name	是	数组（字符串）	需要筛选的 metadata 名称	["category", "tag"]
comparison_operator	是	字符串	比较操作符	contains
value	否	字符串	对比值，当操作符为 empty、not empty、null、not null 时可省略	"AI"

支持的 comparison_operator 操作符：

• contains：包含某个值

• not contains：不包含某个值

• start with：以某个值开头

• end with：以某个值结尾

• is：等于某个值

• is not：不等于某个值

• empty：为空

• not empty：不为空

• =：等于

• ≠：不等于

• >：大于

• <：小于

• ≥：大于等于

• ≤：小于等于

• before：在某个日期之前

• after：在某个日期之后

请求语法

POST <your-endpoint>/retrieval HTTP/1.1
-- 请求头
Content-Type: application/json
Authorization: Bearer your-api-key
-- 数据
{
    "knowledge_id": "your-knowledge-id",
    "query": "你的问题",
    "retrieval_setting":{
        "top_k": 2,
        "score_threshold": 0.5
    }
}

响应元素

如果操作成功，服务将返回 HTTP 200 响应。服务以 JSON 格式返回以下数据。

属性	是否必需	类型	描述	示例值
records	是	对象列表	从知识库查询的记录列表	见下文

records 属性是一个包含以下键的对象列表：

属性	是否必需	类型	描述	示例值
content	是	字符串	包含知识库中数据源的文本块	Dify：GenAI 应用程序的创新引擎
score	是	浮点数	结果与查询的相关性分数，范围：0~1	0.5
title	是	字符串	文档标题	Dify 简介
metadata	否	json	包含数据源中文档的元数据属性及其值	见示例

响应语法

HTTP/1.1 200
Content-type: application/json
{
    "records": [{
                    "metadata": {
                            "path": "s3://dify/knowledge.txt",
                            "description": "dify 知识文档"
                    },
                    "score": 0.98,
                    "title": "knowledge.txt",
                    "content": "这是外部知识的文档。"
            },
            {
                    "metadata": {
                            "path": "s3://dify/introduce.txt",
                            "description": "dify 介绍"
                    },
                    "score": 0.66,
                    "title": "introduce.txt",
                    "content": "GenAI 应用程序的创新引擎"
            }
    ]
}

错误

如果操作失败，服务将返回以下错误信息（JSON 格式）：

属性	是否必需	类型	描述	示例值
error_code	是	整数	错误代码	1001
error_msg	是	字符串	API 异常描述	无效的 Authorization 头格式。预期格式为 'Bearer '。

error_code 属性有以下类型：

代码	描述
1001	无效的 Authorization 头格式
1002	授权失败
2001	知识库不存在

HTTP 状态码

AccessDeniedException 由于缺少访问权限，请求被拒绝。请检查你的权限并重试。 HTTP 状态码：403

InternalServerException 发生内部服务器错误。请重试你的请求。 HTTP 状态码：500

开发示例

你可以通过以下视频了解如何开发外部知识库插件 —— 以 Llamacloud 为例。

如需了解功能原理，请参考插件 GitHub 地址。