Dify 知识库检索 API 指的是其外部知识库检索接口。当您在 Dify 中添加 RAGFlow、ThinkDoc 等外部知识库时，Dify 会通过此标准接口 /retrieval来获取内容。
以下是该接口的详细参数说明与调用示例。
🔌 API 基本信息
-
请求方式:
POST -
请求路径: 您在 Dify 中配置的外部知识库 API 地址，例如
http://your-kg-host/api/v1/dify/retrieval。 -
请求头 (Headers) :
Content-Type:application/jsonAuthorization:Bearer <your_api_key>(由您在外部知识库处创建的 API Key 填充)
-
核心功能: 根据
query查询指定knowledge_id的知识库，并返回按相关性排序的文本片段及其元数据。
📦 请求体 (Request Body) 参数
请求体为 JSON 格式，包含以下字段：
| 参数 | 类型 | 是否必需 | 说明 |
|---|---|---|---|
knowledge_id | string | 是 | 要检索的知识库唯一 ID，由 Dify 在“召回测试”时传入。 |
query | string | 是 | 用户的检索问题或关键词。 |
retrieval_setting | object | 是 | 检索控制参数，包含 top_k和 score_threshold。 |
retrieval_setting.top_k | integer | 是 | 返回的最相关结果数量上限。 |
retrieval_setting.score_threshold | number (0-1) | 是 | 相关性分数阈值，低于此值的结果将被过滤。 |
metadata_filter | object | 否 | 元数据过滤条件，用于实现多关键词 AND 等复杂查询。 |
rerank | object | 否 | 重排序模型配置，部分外部知识库支持，用于优化结果顺序。 |
query_type | string | 否 | 检索类型，部分外部知识库支持，如 hybrid(混合检索)。 |
注意：metadata_filter、rerank、query_type等高级参数是特定外部知识库（如 ThinkDoc）的扩展功能，Dify 核心规范主要定义了前四个字段。
📄 响应体 (Response Body) 结构
接口返回 JSON 格式数据，核心结构如下：
json
{
"records": [
{
"content": "这里是知识库中的一段文本内容……",
"score": 0.87,
"title": "文档标题或来源文件名",
"metadata": {
"doc_id": "内部文档 ID",
"source": "文件路径或 URL",
"author": "作者",
"chunk_index": 3,
"upload_time": "2025-03-01T12:00:00Z"
}
}
// ... 更多记录
]
}
records: 检索结果列表，按相关性分数从高到低排序。content: 知识库中的文本片段，是 RAG 的核心上下文。score: 相关性分数，范围通常在 0-1 之间，越高越相关。title: 文档的标题或来源文件名。metadata: 文档的元数据，可用于实现基于来源、时间、标签的过滤和展示。
💻 调用示例
1. cURL 示例
bash
curl -X POST 'http://your-kg-host/api/v1/dify/retrieval' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ragflow-xxxxxx' \
-d '{
"knowledge_id": "0ed8508e8f7311ef801500155d1e64cf",
"query": "如何克服恐惧？",
"retrieval_setting": {
"top_k": 3,
"score_threshold": 0.5
}
}'
2. Python 示例
python
import requests
url = "http://your-kg-host/api/v1/dify/retrieval"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer ragflow-xxxxxx"
}
payload = {
"knowledge_id": "0ed8508e8f7311ef801500155d1e64cf",
"query": "如何克服恐惧？",
"retrieval_setting": {
"top_k": 3,
"score_threshold": 0.5
}
}
resp = requests.post(url, json=payload, headers=headers)
data = resp.json()
print("检索到 {} 条结果：".format(len(data.get("records", []))))
for rec in data.get("records", []):
print(f"--- 分数: {rec['score']:.2f} | 标题: {rec['title']}")
print(f"内容: {rec['content'][:100]}...")
print(f"元数据: {rec['metadata']}\n")
3. ThinkDoc 扩展参数示例
若您的外部知识库是 ThinkDoc，可使用其扩展参数实现混合检索和重排序：
json
{
"query": "流程有哪些特征？",
"kb_ids": ["6781xxxxxxxx"],
"retrieval_setting": {
"top_k": 10,
"score_threshold": 0.1
},
"query_type": "hybrid",
"rerank": true,
"top_n": 3
}
💡 结合“多关键词 AND 检索”的应用
您之前提到的“多关键词 AND 检索”问题，可以通过 metadata_filter参数在调用此 API 时实现。
思路：在将文档接入外部知识库时，预先将关键词（如 doc_type, mine_type, keyword）存入文档的 metadata。检索时，通过 metadata_filter传入多个 AND条件，即可实现硬性过滤。
示例：检索“安全规程”类型下，同时包含“露天矿”和“爆破”关键词的文档。
json
{
"knowledge_id": "your-knowledge-id",
"query": "露天矿爆破作业粉尘浓度标准",
"retrieval_setting": {
"top_k": 5,
"score_threshold": 0.5
},
"metadata_filter": {
"doc_type": "安全规程",
"mine_type": "露天矿",
"keyword": "爆破"
}
}
注意：此方案的前提是您的外部知识库支持 metadata_filter参数。Dify 核心 API 规范本身不强制要求实现此字段，具体需参考您所使用的外部知识库文档。
