知识检索 - Agent Studio

跨多个知识库执行联合语义检索，返回按相关性排序的切片。

接口说明

权限要求：调用本接口需提供阿里云百炼 API Key 及业务空间。在控制台 API Key 页面及业务空间管理获取。
调用方式：HTTP REST，POST + application/json。Base URL 为 https://{workspaceId}.cn-beijing.maas.aliyuncs.com，其中 {workspaceId} 为业务空间 ID。
前置条件：调用前须在百炼控制台知识检索服务页面创建并发布知识检索服务，获取服务 ID（agent_id）。检索策略（多库权重、知识路由、混排模型等）预先在控制台配置进服务实例并发布，调用方只需传入检索意图（query / images）与 agent_id。
限流：默认用户维度 25 QPS。如遇限流，请稍后重试。

请求语法

POST /api/v1/indices/knowledge/search HTTP/1.1
Host: {workspaceId}.cn-beijing.maas.aliyuncs.com
Authorization: Bearer <API-Key>
Content-Type: application/json

请求参数

调用方仅需传入检索意图与 agent_id，其余检索策略配置在 agent_config，不在请求中暴露。

名称	类型	必填	描述	示例
agent_id	string	是	知识检索服务（agent）实例 ID。服务端据此加载已发布的 `agent_config`（含全部检索策略）。在控制台知识检索页面创建并发布后获取。	aid-xxxxxxxxxxxxxxxx
query	string	条件必填	文本检索意图。与 `images` 至少传入一个；纯图搜时可传空串；非纯图搜场景下必填。	推荐一件适合秋冬的运动夹克
images	array<string>	条件必填	图片检索意图，元素为图片 URL（须公网可访问）。与 `query` 至少传入一个，可同时传入实现多模态检索。	[]
agent_version	string	否	agent 版本。

响应参数

响应顶层是统一结构，data 里包含三部分：total 是命中的切片总数，nodes 是结果列表，cost_time 是本次检索耗时（毫秒）。建议以 success 字段判断成功与否，用 request_id 关联日志排查。

名称	类型	描述
code	string	业务状态码，`Success` 表示成功；失败时为对应错误码字符串。
status_code	integer	语义状态码，成功为 200。
status	string	状态枚举，成功 `SUCCESS`，失败 `ERROR`。
success	boolean	是否成功。调用方以此字段作为主判定。
message	string	状态描述。
request_id	string	请求唯一标识，排查问题时请提供此 ID。
data.total	integer	命中结果总数。
data.nodes	array<object>	检索结果节点列表，按相关性排序。结构见下表。
data.cost_time	integer	本次检索耗时（毫秒）。

data.nodes[] 结构

名称	类型	描述
score	float	相关性评分。
text	string	切片文本内容。
metadata	object	切片元数据信息。

请求示例

curl -X POST "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "agent_id": "aid-xxxxxxxxxxxxxxxx",
    "query": "推荐一件适合秋冬的运动夹克"
}'

错误码

如果调用失败并返回报错信息，请参阅错误码文档进行解决。

​接口说明

​请求语法

​请求参数

​响应参数

​data.nodes[] 结构

​请求示例