Knowledge Search

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"
}

Perform federated semantic search across multiple knowledge bases and return slices ranked by relevance. The search strategy is pre-configured in the console for an agent instance and published. Callers provide the search intent (query / images) and agent_id. Additionally, they may specify document/tag filtering conditions per knowledge base via kb_search_configs.

Before calling this API, you must first publish the Knowledge Search service (agent) in the console; otherwise, an “Agent not published” error will be returned.

Parameter Categories

The request surface is kept minimal. All parameters are categorized into two groups by role:

Category	Meaning	Belongs to	Included in Request?
Category A · Agent Strategy	Search strategies defined as agent properties	Locked in `agent_config`, configured and published in the console	No
Category B · Invocation Intent	Inputs known only at call time	Request body	Yes

Examples of Category A parameters: 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, etc. All are managed exclusively within agent_config and cannot be overridden in the request. Examples of Category B parameters: query, images, kb_search_configs[].id, kb_search_configs[].search_filters.

kb_search_configs

The kb_search_configs field allows specifying document/tag filtering conditions per knowledge base at runtime, enabling dynamic filtering. This field is an array where each element corresponds to one knowledge base.

kb_search_configs[].id must be a knowledge base ID already bound to the agent in offline configuration; querying unbound knowledge bases is not allowed.
Within the same request, id values must be unique.
Each kb_search_configs element must include the id field.
Total byte size of search_filters must not exceed 80,000 bytes. For unstructured knowledge bases, only tags and meta keys are permitted, and their arrays must not exceed 1,000 elements.
Filterable fields must have been declared in index_config.fields during knowledge base ingestion; otherwise, filtering has no effect.

Show search_filters Syntax Details

search_filters is a JSON array, where each element is an independent filter condition object. Three filtering dimensions are supported, each passed as a separate JSON object:

"search_filters": [
  // Filter by document ID (supports multi-value IN)
  { "doc_id": "file_abc_123" },
  { "doc_id": ["file_abc_123", "file_def_456"] },

  // Filter by tags
  { "tags": ["Contract", "2024"] },

  // Filter by custom Meta fields
  { "custom_field": "value" },

  // Advanced: Operators (e.g., gte / lte / like)
  { "price": { "gte": 100, "lte": 500 } },
  { "name": { "like": "Zhang%" } },

  // Advanced: Nested OR grouping
  {
    "_operator": "OR",
    "_conditions": [
      { "status": "active" },
      { "priority": { "gte": 5 } }
    ]
  }
]

Merging Strategy: If search_filters are already defined in the agent’s offline configuration, those from the request are appended to the end of the offline filters array. Both sets apply simultaneously (logical AND), rather than replacing the offline ones. To use only the runtime filters, ensure no search_filters are set in the offline configuration.

Response

The response data includes total (total number of matched slices), nodes (list of results), and cost_time (execution time in milliseconds). Each node contains score, text, and metadata; see the parameter table above for details.

Metadata fields prefixed with _ are internal scoring fields whose names may change across versions—do not rely on them in business logic. Tabular knowledge bases also return additional business fields from the user-defined table schema (field names vary depending on table structure).

Error Handling

On failure, success is false, status is ERROR, status_code is the corresponding semantic code, code is the error code string, message is the description, and request_id is always present. Always check success, not just the HTTP status code; when troubleshooting, provide the request_id.

Scenario	Error Code	Error Message
`agent_id` missing	`InvalidParameter`	`agent_id is required`
`query` missing	`InvalidParameter`	`query is required`
`kb_id` not bound to the agent	`InvalidParameter`	`kb not bound to agent: {id}`
Duplicate `kb_id` in `kb_search_configs`	`InvalidParameter`	`duplicate kb id in kb_search_configs: {id}`
`kb_search_configs[{i}].id` empty	`InvalidParameter`	`kb_search_configs[{i}].id is required`
`search_filters` total byte size exceeds limit	`InvalidParameter`	`search_filters total bytes must less than 80000`
Unstructured `search_filters` contains invalid key	`InvalidParameter`	`search_filters[{i}] contains invalid key '{key}'. Only 'tags' and 'meta' are allowed for unstructured data`
Unstructured `tags`/`meta` array exceeds size limit	`InvalidParameter`	`search_filters[{i}].tags array size must not exceed 1000`

Multiple parameter-related errors all return the same error code InvalidParameter. Rely on the message field—not just the error code—to precisely identify the root cause.

Authorizations

string

header

required

DashScope API Key，在控制台 API Key 页面获取。

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

切片元数据，字段随知识库类型变化，按用途分组，详见 metadata 字段分组

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

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

boolean

该切片内容是否用于展示。

integer

本次检索耗时（毫秒）。

​Parameter Categories

​kb_search_configs

​Response

​Error Handling

Authorizations

Body

Response

Parameter Categories

kb_search_configs

Response

Error Handling