知识检索 - Agent Studio

POST

/api/v1/indices/knowledge/search

cURL

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": "推荐一件适合秋冬的运动夹克",
    "images": [],
    "kb_search_configs": [
      {
        "id": "kb_product_001",
        "search_filters": [
          {"tags": ["秋冬", "运动"]}
        ]
      }
    ]
  }'

{
  "code": "Success",
  "status_code": 200,
  "data": {
    "total": 5,
    "nodes": [
      {
        "score": 0.9201360940933228,
        "metadata": {
          "_rc_v_score": 0.9662528038024902,
          "image_url": [
            "https://example.com/image.jpeg"
          ],
          "_score": 0.9201360940933228,
          "doc_id": "table_xxxxxxxxxxxx_10034682_5780",
          "_score_with_weight": 0.9201360940933228,
          "_rank_weight": 1,
          "doc_name": "商品图库",
          "pipeline_id": "your_kb_id",
          "_id": "llm-xxxxxxxxxxxx_your_kb_id_table_xxxxxxxxxxxx_10034682_5780",
          "media_url": "https://example.com/image.jpeg",
          "update_date": "2023-11-4 0:03",
          "product_id": "SKU-001",
          "product_name": "运动夹克示例",
          "category": "服装",
          "_knowledge_type": "image",
          "_knowledge_scene": "image_qa"
        },
        "text": "media_url: https://example.com/image.jpeg\nupdate_date: 2023-11-4 0:03\nproduct_id: SKU-001\nproduct_name: 运动夹克示例\ncategory: 服装"
      }
    ],
    "cost_time": 2629
  },
  "success": true,
  "message": "success",
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "SUCCESS"
}

跨多个知识库执行联合语义检索，返回按相关性排序的切片。检索策略预先在控制台配置进 agent 实例并发布，调用方传入检索意图（query / images）与 agent_id，还可通过 kb_search_configs 为每个知识库指定文档/标签过滤条件。

调用前必须先在控制台发布知识检索服务（agent），否则返回 Agent 未发布错误。

参数分类

请求面保持最小。所有参数按角色分为两类：

分类	含义	归属	是否进请求
A 类 · agent 策略	属于 agent 属性的检索策略	锁进 `agent_config`，控制台配置并发布	否
B 类 · 调用意图	仅本次调用时才知道的输入	请求体	是

A 类示例：dense_similarity_top_k、sparse_similarity_top_k、rerank、rerank_top_n、rerank_min_score、hybrid_rerank、enable_kb_router、kb_search_configs[].weight、enable_rewrite、enable_nl2sql 等，全部在 agent_config 中管理，请求不可覆盖。 B 类示例：query、images、kb_search_configs[].id、kb_search_configs[].search_filters。

kb_search_configs

通过 kb_search_configs 可在请求中为每个知识库指定文档/标签过滤条件，实现运行时动态过滤。该字段为数组，每个元素对应一个知识库。

kb_search_configs[].id 必须是 agent 离线配置中已绑定的知识库 ID，不能查询未绑定的知识库。
同一请求中 id 不能重复。
每个 kb_search_configs 元素必须包含 id 字段。
search_filters 总字节数不超过 80,000 bytes。非结构化知识库仅允许 tags 和 meta 两种 key，数组长度不超过 1,000。
可过滤字段须在该知识库入卷时声明于 index_config.fields，否则过滤不生效。

Show search_filters 语法详情

search_filters 是一个 JSON 数组，每个元素是一个独立的过滤条件对象。支持三种过滤维度，每种维度用独立的 JSON 对象传入：

"search_filters": [
  // 按文档 ID 过滤（支持多值 IN）
  { "doc_id": "file_abc_123" },
  { "doc_id": ["file_abc_123", "file_def_456"] },

  // 按标签过滤
  { "tags": ["合同", "2024年"] },

  // 按自定义 Meta 字段过滤
  { "custom_field": "value" },

  // 高级：操作符（gte / lte / like 等）
  { "price": { "gte": 100, "lte": 500 } },
  { "name": { "like": "张%" } },

  // 高级：嵌套 OR 分组
  {
    "_operator": "OR",
    "_conditions": [
      { "status": "active" },
      { "priority": { "gte": 5 } }
    ]
  }
]

合并策略：当 agent 离线配置中已有 search_filters，请求中传入的会追加到离线 filters 数组末尾，两者同时生效（AND 关系），而非替换。如果需要"只用在线条件"，离线配置中不要设置 search_filters。

响应

响应 data 包含 total（命中切片总数）、nodes（结果列表）、cost_time（耗时毫秒）。每个 node 含 score、text、metadata，具体字段见上方参数表。

以 _ 开头的 metadata 字段是内部打分用，版本间可能变，不要写进业务逻辑。表格型知识库还会额外返回用户表格里的业务字段（字段名因表结构而异）。

错误处理

失败时 success 为 false、status 为 ERROR、status_code 为对应语义码、code 为错误码字符串、message 为描述，request_id 必返回。始终校验 success，而非仅依赖 HTTP 状态码；排查问题提供 request_id。

场景	错误码	错误信息
`agent_id` 缺失	`InvalidParameter`	`agent_id is required`
`query` 缺失	`InvalidParameter`	`query is required`
kb_id 不属于 agent 绑定的知识库	`InvalidParameter`	`kb not bound to agent: {id}`
kb_id 重复	`InvalidParameter`	`duplicate kb id in kb_search_configs: {id}`
kb_id 为空	`InvalidParameter`	`kb_search_configs[{i}].id is required`
search_filters 总字节数超限	`InvalidParameter`	`search_filters total bytes must less than 80000`
非结构化 filter 包含非法 key	`InvalidParameter`	`search_filters[{i}] contains invalid key '{key}'. Only 'tags' and 'meta' are allowed for unstructured data`
非结构化 tags/meta 数组超限	`InvalidParameter`	`search_filters[{i}].tags array size must not exceed 1000`

多种参数错误都返回同一个错误码 InvalidParameter，仅凭错误码无法精准定位错误原因，请参照 message 字段。

Authorizations

string

header

required

DashScope API Key，在控制台 API Key 页面（https://agent.console.aliyun.com/settings/apikey）获取。

Body

application/json

string

required

知识检索服务（agent）实例 ID。服务端据此加载已发布的 agent_config（含全部 A 类检索策略）。在控制台知识检索页面创建并发布后获取。

string

default""

文本检索意图。与 images 至少传入一个；纯图搜时可传空串；非纯图搜场景（未传 images）下必填，否则返回 InvalidParameter。

string[]

default[]

图片检索意图，元素为图片 URL（须公网可访问）。与 query 至少传入一个，可同时传入实现多模态检索。

string

agent 版本。标准接口仅暴露 agent_id / agent_version / query / images / kb_search_configs，其余检索策略一律走 agent_config，不在请求中暴露。

object[]

知识库过滤配置数组。每个元素对应一个知识库，可指定文档/标签过滤条件。id 必须属于 agent 已绑定的知识库，同一请求中不可重复。

Show child attributes

string

required

知识库 ID（pipeline_id），必须属于 agent 已绑定的知识库。

object[]

过滤条件数组，每个元素是一个 JSON 对象。支持按 doc_id、tags、自定义 meta 字段过滤。在线传入的 search_filters 会追加到离线配置的 search_filters 末尾（AND 关系），而非替换。总字节数不超过 80,000。非结构化知识库仅允许 tags 和 meta 两种 key，数组长度不超过 1,000。

Response

200-application/json

string

业务状态码，Success 表示成功；失败时为对应错误码字符串。

integer

语义状态码，成功为 200。

string

状态枚举，成功 SUCCESS，失败 ERROR。

boolean

是否成功。调用方以此字段作为主判定。

string

状态描述。

string

请求唯一标识，排查问题时请提供此 ID。

object

Show child attributes

integer

命中结果总数。

object[]

检索结果节点列表，按相关性排序。

Show child attributes

number

切片与查询的相关性分数，0 到 1 之间，越大越相关。

string

拼接好的切片文本，按 字段名: 值 逐行拼成，默认包含文档名、标题、正文。

object

切片的元数据。字段不是固定的，会随知识库类型变化，按用途分为几组：业务内容（doc_id / doc_name / title / hier_title / content / image_url / audio_url / video_url）、知识库信息（_knowledge_type / _knowledge_scene / pipeline_id / workspace_id）、切片信息（_id / nid / page_number / doc_url）、内部打分（以 _ 开头，版本间可能变，不建议依赖）、结构化业务字段（只在表格型知识库出现，字段名随你的表结构而定，如 product_id / product_name / category / update_date）。

Show child attributes

string

文档/数据行唯一 ID，如 table_..._10034682_5780。

string

文档名称。

string

切片标题。

string

层级标题，按 > 分隔的标题路径。

string

切片原始正文内容。

string[]

切片包含的图片地址列表。

string[]

切片包含的音频地址列表。

string[]

切片包含的视频地址列表。

string

知识类型，如 document、image。

string

知识场景，如 basic_document_qa、image_qa。

string

所属知识库 ID。

string

所属业务空间 ID。

string

切片 ID。

string

文档解析 layout ID。

integer[]

切片所属页码列表。

string

原始文档 URL。

number

切片的相关性分数，0 到 1 之间（内部字段，不稳定）。

number

向量匹配分数（内部，不稳定）。

number

关键词匹配分数（内部，不稳定）。

number

加权后的相关性分数（内部字段，不稳定）。

number

加权排序权重（内部，不稳定）。

integer

本次检索耗时（毫秒）。

​参数分类

​kb_search_configs

​响应

​错误处理

Authorizations

Body

Response

参数分类

kb_search_configs

响应

错误处理