Dify 检索与数据库查询
本页补充第三方知识检索适配与已接入数据库表的查询接口。请求统一使用 JSON，并按 API 鉴权 在服务端配置平台 API Key。
Dify 外部知识库检索
| 方法与路径 | 行为 |
|---|---|
POST /openapi/paas/dify/v1/retrieval | 知识分片检索，平台密钥模块 knowledge_search=READ |
POST /openapi/paas/dify/v2/retrieval | 先进行知识地图检索限定文档，再检索分片；需部署方启用并准备相应知识地图能力 |
不要根据日志中的历史简称省略路径的 paas。V2 依赖知识地图数据，接入前应确认目标环境的功能和授权配置。
| 请求字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
knowledge_id | string | 是 | 知识库 code，必填 |
query | string | 是 | 非空查询文本 |
retrieval_setting | object | 否 | 可选检索设置 |
retrieval_setting.top_k | integer | 否 | 默认 5，使用正整数 |
retrieval_setting.score_threshold | number | 否 | 默认 0.5，相关性阈值 |
{
"knowledge_id": "partner_kb_001",
"query": "产品部署要求",
"retrieval_setting": {
"top_k": 5,
"score_threshold": 0.5
}
}
请求模型保留 metadata_condition，但当前检索实现未应用该字段。需要元数据过滤时，使用 知识检索 的 metadataFilter。
请求示例
curl --request POST "${BASE_URL}/openapi/paas/dify/v1/retrieval" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--header "Content-Type: application/json" \
--data '{"knowledge_id":"partner_kb_001","query":"产品部署要求","retrieval_setting":{"top_k":5,"score_threshold":0.5}}'
调用 V2 时仅将路径中的 v1 改为 v2，字段与响应结构相同；V2 没有知识地图候选文档时可直接返回空 records。请使用在当前环境已具备地图数据的知识库联调。
响应字段
| 字段 | JSON 类型 | 说明 |
|---|---|---|
records | array[object] | 命中片段列表，无命中可为空 |
records[].title | string | 来源标题/文件名 |
records[].content | string | 命中片段文本 |
records[].score | number | 相关分数，依检索模型计算，不是置信度百分比 |
records[].metadata | object | 引用元数据，字段随来源变化，允许空对象 |
响应示例
成功直接返回 records，无 Result 包装：
{
"records": [
{
"title": "产品白皮书.pdf",
"content": "产品部署要求说明。",
"score": 0.91,
"metadata": {}
}
]
}
metadata 为引用元数据，字段随知识来源变化。无命中可返回空 records；模型未配置或嵌入调用失败也可能返回空 records，因此持续空结果需同时排查模型与索引配置。
已接入数据库表的 SQL 查询
POST /openapi/paas/v1/knowledge/sql/execute
平台密钥要求 knowledge_sql_execute=READ。只支持 SELECT 查询，目标表必须已经在当前租户接入。
| 字段 | 类型 | 说明 |
|---|---|---|
items | array[object] | 查询项列表，调用时提供非空列表 |
items[].tableCode | string | 已接入数据库表的业务编码 |
items[].sqls | array[string] | SELECT 语句列表 |
{
"items": [
{
"tableCode": "REPLACE_WITH_TABLE_CODE",
"sqls": ["SELECT product_name FROM product_catalog LIMIT 10"]
}
]
}
示例 SQL 必须替换为实际数据源的表名、字段和方言。成功返回 Result<string>，data 是查询结果拼接的文本，不是结构化行数组。空结果也可能来自底层查询失败，应结合实际数据源检查。
该接口没有提供任意外部数据库连接参数；连接与表定义由 AIS 中已配置的数据源决定。
请求示例
curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/sql/execute" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--header "Content-Type: application/json" \
--data '{"items":[{"tableCode":"REPLACE_WITH_TABLE_CODE","sqls":["SELECT product_name FROM product_catalog LIMIT 10"]}]}'
响应字段
| 字段 | JSON 类型 | 说明 |
|---|---|---|
code | integer | 8200 表示外层请求正常返回 |
message | string | 提示信息 |
data | string | 各查询结果拼接的文本；不是行数组、JSON 对象或总行数 |
无可用结果时的响应结构示例：
{
"code": 8200,
"message": "SUCCESS",
"data": ""
}
有数据时 data 包含查询结果文本；其排版不作为机器读取结构契约，不建议依赖固定分隔符解析业务行。底层查询失败也可能产生空文本，持续空结果时核对数据源连接、tableCode、SQL 方言与查询日志。
安全与失败处理
对接服务端应使用已审核的只读 SQL，限定查询范围和行数，不把客户端任意输入直接拼接到 SQL。接口不支持通过请求临时指定数据库连接，也不应尝试写入语句。普通业务错误见 错误编码；Dify 的空列表与 SQL 的空字符串分别按各自语义处理。