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

图片检索 API 用于在图片库中搜索相似图片。支持以图搜图（Base64 图片输入）和以文搜图（文本描述输入），可通过 tag_filter 叠加标签过滤条件。

接口总览

说明：所有接口统一前缀为 /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": "in", "value": ["red", "blue"]},
      {"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，越高越相似。通常 0.9 以上表示高度相似，0.7~0.9 表示中等相似。
`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": "white",
          "season": "summer"
        }
      },
      {
        "image_id": "img002",
        "image_uri": "https://example.com/tops/img002.jpg",
        "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
        "score": 0.891,
        "tags": {
          "color": "blue",
          "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": {
          "color": "white",
          "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 / OR）等能力。

条件对象

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

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

字段	类型	是否必选	默认值	说明
`field`	string	是	无	tags 中的字段名。
`op`	string	是	无	操作符，见下方操作符表。
`value`	string / list	是	无	匹配值。`in` / `not in` 时为数组，其余为字符串。

操作符

op	含义	value 类型	示例
`=`	精确匹配	string	`{"field": "color", "op": "=", "value": "red"}`
`!=`	精确排除	string	`{"field": "color", "op": "!=", "value": "black"}`
`>`	大于	string / number	`{"field": "score", "op": ">", "value": 0.5}`
`>=`	大于等于	string / number	`{"field": "score", "op": ">=", "value": 0.9}`
`<`	小于	string / number	`{"field": "score", "op": "<", "value": 1.0}`
`<=`	小于等于	string / number	`{"field": "score", "op": "<=", "value": 0.95}`
`like`	包含子串	string	`{"field": "color", "op": "like", "value": "re"}`
`not like`	不包含子串	string	`{"field": "color", "op": "not like", "value": "dark"}`
`in`	多值任一匹配	list	`{"field": "color", "op": "in", "value": ["red", "blue"]}`
`not in`	多值全排除	list	`{"field": "color", "op": "not in", "value": ["black", "grey"]}`

逻辑组合

数组 = AND：数组中的条件之间为 AND 关系。
{"or": [...]} = OR：数组中的条件之间为 OR 关系。
支持嵌套组合。

示例

AND 组合（最常用，直接用数组）

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

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

跨字段 OR

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

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

AND + OR 嵌套

[
  {"field": "category", "op": "!=", "value": "pants"},
  {
    "or": [
      {"field": "color", "op": "=", "value": "red"},
      {"field": "season", "op": "=", "value": "summer"}
    ]
  }
]

含义：category != "pants" AND (color = "red" OR season = "summer")

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

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

含义：category = "T恤" AND color IN ["白色", "米色"] AND price >= 50 AND price <= 200