外部知识库 API

本文档由 AI 自动翻译。如有任何不准确之处，请参考英文原版。

本页定义了外部知识服务必须实现的 API 协议，以便 Dify 从中检索内容。API 准备就绪后，详见连接外部知识库在 Dify 中完成注册。

认证

Dify 在每个请求中将你配置的 API Key 作为 Bearer 令牌发送：

Authorization: Bearer {API_KEY}

认证逻辑由你自行定义。Dify 仅传递密钥，不会对其进行验证。

请求

POST {your-endpoint}/retrieval
Content-Type: application/json
Authorization: Bearer {API_KEY}

Dify 在你配置的端点 URL 后追加 /retrieval。如果注册的地址为 https://your-service.com，Dify 将请求发送至 https://your-service.com/retrieval。

请求体

属性	必填	类型	说明
`knowledge_id`	是	string	外部系统中知识源的标识符，即连接时填写的外部知识库 ID 字段的值，用于将查询路由到正确的知识源。
`query`	是	string	用户的搜索查询。
`retrieval_setting`	是	object	检索参数。详见下文。
`metadata_condition`	否	object	元数据筛选条件。详见下文。

`retrieval_setting`

属性	必填	类型	说明
`top_k`	是	int	返回结果的最大数量。
`score_threshold`	是	float	最低相似度分数（0-1）。在 Dify 中禁用分数阈值时，此值为 `0.0`。

`metadata_condition`

Dify 将元数据条件传递给你的 API，但目前未提供供用户配置的界面。此参数仅用于程序化调用。

属性	必填	类型	说明
`logical_operator`	否	string	`and` 或 `or`。默认值：`and`。
`conditions`	是	array[object]	筛选条件列表。

conditions 中每个对象的结构：

属性	必填	类型	说明
`name`	是	string	要筛选的元数据字段名称。
`comparison_operator`	是	string	比较运算符。支持的值见下文。
`value`	否	string、number 或 array[string]	比较值。使用 `empty` 或 `not empty` 时可省略。

支持的比较运算符

运算符	说明
`contains`	包含某个值
`not contains`	不包含某个值
`start with`	以某个值开头
`end with`	以某个值结尾
`is`	等于某个值
`is not`	不等于某个值
`in`	匹配列表中的任意值
`not in`	不匹配列表中的任意值
`empty`	为空
`not empty`	不为空
`=`	等于（数值）
`≠`	不等于（数值）
`>`	大于
`<`	小于
`≥`	大于或等于
`≤`	小于或等于
`before`	在某个日期之前
`after`	在某个日期之后

请求示例

{
    "knowledge_id": "your-knowledge-id",
    "query": "Dify 是什么？",
    "retrieval_setting": {
        "top_k": 3,
        "score_threshold": 0.5
    }
}

响应

返回 HTTP 200，响应体为包含 records 数组的 JSON。如果没有匹配结果，返回空数组：{"records": []}。

`records`

属性	类型	说明
`content`	string	检索到的文本分段。Dify 将其作为传递给 LLM 的上下文。
`score`	float	相似度分数（0-1）。用于分数阈值过滤和结果排序。
`title`	string	源文档标题。
`metadata`	object	由 Dify 保留的任意键值对。

Dify 不会拒绝缺少字段的记录，但缺少 content 或 score 将导致结果不完整或无法排序。

记录中的 metadata 必须是对象（{}），不能为 null。null 值将导致 Dify 检索流程出错。

响应示例

{
    "records": [
        {
            "content": "这是外部知识库的文档。",
            "score": 0.98,
            "title": "knowledge.txt",
            "metadata": {
                "path": "s3://dify/knowledge.txt",
                "description": "dify 知识文档"
            }
        },
        {
            "content": "GenAI 应用的创新引擎",
            "score": 0.66,
            "title": "introduce.txt",
            "metadata": {}
        }
    ]
}

错误处理

Dify 检查响应的 HTTP 状态码。非 200 状态码将触发错误并展示给用户。可选择在 JSON 中返回结构化的错误信息：

属性	类型	说明
`error_code`	int	自定义的应用级错误码。
`error_msg`	string	可读的错误描述。

以下是建议的错误码，仅为约定，Dify 不强制要求：

错误码	建议用途
1001	无效的 Authorization 请求头格式
1002	认证失败
2001	知识库不存在

错误响应示例

{
    "error_code": 1002,
    "error_msg": "Authorization failed. Please check your API key."
}

编排

发布

监控

知识库

集成

工作空间

外部知识库 API

认证

请求

请求体

`retrieval_setting`

`metadata_condition`

请求示例

响应

`records`

响应示例

错误处理

错误响应示例

​认证

​请求

​请求体

​retrieval_setting

​metadata_condition

​请求示例

​响应

​records

​响应示例

​错误处理

​错误响应示例

认证

请求

请求体

`retrieval_setting`

`metadata_condition`

请求示例

响应

`records`

响应示例

错误处理

错误响应示例