通过API以图搜图或以文搜图的方式检索图片-云原生数据仓库AnalyticDB(AnalyticDB)-阿里云帮助中心

接口总览

说明：所有接口统一前缀为 /api/v1/operators/image-search。

接口名称	方法	路径
在指定图片库中以图搜图	POST	`/api/v1/operators/image-search/search/by-image`
在指定图片库中以文搜图	POST	`/api/v1/operators/image-search/search/by-text`

1. 以图搜图

请求方法：POST

请求路径：/api/v1/operators/image-search/search/by-image

接口说明：以图片为查询输入，在指定图片库中检索相似图片。仅支持 Base64 编码方式传入查询图片。

请求参数

参数名	类型	是否必选	默认值	参数含义
`library_name`	string	是	无	目标图片库名称。
`image_base64`	string	是	无	查询图片的 Base64 编码字符串。
`top_k`	int	否	`10`	返回的最大结果数量。
`tag_filter`	list [object]	否	无	标签过滤条件，语法请参见tag_filter 过滤语法。
`return_frame`	bool	否	`true`	是否在结果中返回图片的 Base64 编码内容。设为 `false` 可减少传输量。

请求示例

curl -X POST 'http://localhost:8000/api/v1/operators/image-search/search/by-image' \
  -H 'Content-Type: application/json' \
  -d '{
    "library_name": "shop_a_tops",
    "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
    "top_k": 5,
    "tag_filter": [
      {"field": "color", "op": "=", "value": "red"},
      {"field": "season", "op": "=", "value": "summer"}
    ]
  }'

响应说明

HTTP 状态码

状态码	含义
200	检索成功（结果可能为空列表）。
400	请求参数错误。
404	图片库不存在。
500	服务器内部错误。

data 字段

字段名	类型	说明
`results`	list[object]	检索结果列表，按相似度降序排列。未检索到结果时为空列表。
`results[].image_id`	string	图片唯一标识。
`results[].image_uri`	string	图片资源标识（导入时传入的原始值）。
`results[].image_base64`	string / null	图片 Base64 编码内容。当 `return_frame=false` 或图片库中未存储时返回 `null`。
`results[].score`	float	相似度分数，取值范围 0~1，越高越相似。
`results[].tags`	object	该图片的自定义标签。

响应示例（有结果）

{
  "status": "SUCCESS",
  "message": null,
  "data": {
    "results": [
      {
        "image_id": "img001",
        "image_uri": "https://example.com/tops/img001.jpg",
        "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
        "score": 0.962,
        "tags": {
          "color": "red",
          "season": "summer"
        }
      },
      {
        "image_id": "img002",
        "image_uri": "https://example.com/tops/img002.jpg",
        "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
        "score": 0.891,
        "tags": {
          "color": "red",
          "season": "summer"
        }
      }
    ]
  }
}

响应示例（无结果，如 item_search 模式未识别到物品）

{
  "status": "SUCCESS",
  "message": null,
  "data": {
    "results": []
  }
}

2. 以文搜图

请求方法：POST

请求路径：/api/v1/operators/image-search/search/by-text

接口说明：以文本描述为查询输入，在指定图片库中检索语义匹配的图片。

支持多语言输入，在中国内地区域部署时，服务端会自动将输入文本翻译为中文后再执行检索。

说明：以文搜图仅在 general_search（通用搜索）模式的图片库中可用。其他模式调用将返回 HTTP 400。

请求参数

参数名	类型	是否必选	默认值	参数含义
`library_name`	string	是	无	目标图片库名称（须为 `general_search` 模式）。
`query_text`	string	是	无	搜索文本描述，如 `白色短袖T恤`、`a white short-sleeve T-shirt`。
`top_k`	int	否	`10`	返回的最大结果数量。
`tag_filter`	list [object]	否	无	标签过滤条件，语法请参见tag_filter 过滤语法。
`return_frame`	bool	否	`true`	是否在结果中返回图片的 Base64 编码内容。设为 `false` 可减少传输量。

请求示例

curl -X POST 'http://localhost:8000/api/v1/operators/image-search/search/by-text' \
  -H 'Content-Type: application/json' \
  -d '{
    "library_name": "general_clothing",
    "query_text": "a white short-sleeve T-shirt",
    "top_k": 10,
    "tag_filter": [
      {"field": "season", "op": "=", "value": "summer"},
      {"field": "category", "op": "=", "value": "pants"}
    ]
  }'

响应说明

HTTP 状态码

状态码	含义
200	检索成功（结果可能为空列表）。
400	请求参数错误（或图片库模式不支持文搜图，非 general_search 模式）。
404	图片库不存在。
500	服务器内部错误。

data 字段结构与以图搜图相同，参见上方 data 字段说明。

响应示例

{
  "status": "SUCCESS",
  "message": null,
  "data": {
    "results": [
      {
        "image_id": "img001",
        "image_uri": "https://example.com/tops/img001.jpg",
        "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
        "score": 0.943,
        "tags": {
          "category": "pants",
          "season": "summer"
        }
      }
    ]
  }
}

失败响应示例（HTTP 400）

{
  "status": "MODE_NOT_SUPPORTED",
  "message": "Image library 'shop_a_tops' is in item_search mode and does not support text-to-image search.",
  "data": null
}

tag_filter 过滤语法

检索接口支持通过 tag_filter 对结果进行标签过滤。tag_filter 采用结构化条件表达式，支持精确匹配，以及数值字段的范围过滤。多个过滤条件之间按 AND 关系组合。实际过滤效果与标签字段的取值分布和查询条件有关。

条件对象

每个过滤条件为一个结构化 JSON 对象：

{"field": "color", "op": "=", "value": "red"}

字段	类型	是否必选	默认值	说明
`field`	string	是	无	tags 中的字段名。
`op`	string	是	无	操作符，见下方操作符表。
`value`	string / number	是	无	匹配值。字符串类型用于精确匹配，数值类型可用于精确匹配或范围过滤。

操作符

op	含义	value 类型	示例
`=`	精确匹配	string/number	`{"field": "color", "op": "=", "value": "red"}`
`>`	大于	number	`{"field": "score", "op": ">", "value": 0.5}`
`>=`	大于等于	number	`{"field": "score", "op": ">=", "value": 0.9}`
`<`	小于	number	`{"field": "score", "op": "<", "value": 1.0}`
`<=`	小于等于	number	`{"field": "score", "op": "<=", "value": 0.95}`

逻辑组合

tag_filter 为一个 JSON 数组，数组中的所有条件之间为 AND 关系，即所有条件必须同时满足。

示例

多条件 AND 组合

[
  {"field": "color", "op": "=", "value": "red"},
  {"field": "season", "op": "=", "value": "summer"}
]

含义：color = "red" AND season = "summer"

电商场景示例（按品类 + 颜色 + 价格范围筛选）

[
  {"field": "category", "op": "=", "value": "T恤"},
  {"field": "color", "op": "=", "value": "白色"},
  {"field": "price", "op": ">=", "value": 50},
  {"field": "price", "op": "<=", "value": 200}
]

含义：category = "T恤" AND color = "白色" AND price >= 50 AND price <= 200