跳转到主要内容
⚠️ 本文档由 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否stringand 或 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

属性类型说明
contentstring检索到的文本分段。Dify 将其作为传递给 LLM 的上下文。
scorefloat相似度分数（0-1）。用于分数阈值过滤和结果排序。
titlestring源文档标题。
metadataobject由 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_codeint自定义的应用级错误码。
error_msgstring可读的错误描述。
以下是建议的错误码，仅为约定，Dify 不强制要求：
错误码建议用途
1001无效的 Authorization 请求头格式
1002认证失败
2001知识库不存在

​
错误响应示例

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