SemanticQuery-对象存储(OSS)-阿里云帮助中心

调用 SemanticQuery 接口在指定 Dataset 内做自然语言语义检索。功能与 DoMetaQuery 的向量检索等价,但需要在请求中显式指定 datasetName,适用于在 Bucket 含有多个 Dataset 时精确查询某一个 Dataset。以图搜图相关参数作为预留参数保留,当前尚未支持。

注意事项

调用本接口的 RAM 用户需要 oss:MetaQuery 权限。
仅当 OpenMetaQuery 时设置向量检索后可用。
要查询的 Dataset 需具备对应媒体类型的 AI 内容感知配置。新接入推荐通过 CreateDataset 或 UpdateDataset 的 datasetConfig 配置内容感知细项。
本接口的所有参数都通过 URL Query String 传递,不接受 HTTP body。
语义检索结果按相关度降序返回,不支持分页(响应无 NextToken),也不支持聚合。
本接口每次只查询 datasetName 指定的单个 Dataset,当前不支持跨 Dataset 检索。如需查询多个 Dataset,请分别调用本接口。
当前仅支持通过 query 传入自然语言文本进行检索。sourceURI 为以图搜图预留参数,当前尚未支持。

请求语法

POST /?metaQuery&action=semanticQuery&datasetName=DatasetName&query=Query&mediaTypes=MediaTypes&simpleQuery=SimpleQuery&withFields=WithFields&maxResults=MaxResults HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

请求头

此接口仅涉及公共请求头。更多信息,请参见公共请求头(Common Request Headers)。

请求元素

名称	类型	是否必选	示例值	描述
datasetName	字符串	是	photos-2026	要查询的 Dataset 名。
query	字符串	是	海边日落	自然语言搜索语句,需 URL 编码后传入,长度 1 到 1024。
sourceURI	字符串	否	不涉及	以图搜图预留参数,格式为 `oss://{bucket}/{object-key}`。当前尚未支持,请使用 `query` 传入自然语言文本进行检索。
mediaTypes	字符串数组	否	["image"]	目标媒体类型。通过 URL Query String 传递时需 JSON 序列化并 URL 编码。子节点:MediaType
MediaType	字符串	否	image	目标媒体类型。取值如下: image：图片 video：视频 audio：音频 document：文档父节点:mediaTypes
simpleQuery	Query 对象	否	{"Field":"Size","Operation":"gt","Value":"102400"}	附加的结构化过滤条件。通过 URL Query String 传递时需 JSON 序列化并 URL 编码,用于在语义检索结果上进一步过滤。支持的过滤字段以及操作符，请参见附录：向量检索的字段和操作符列表。子节点:Field、Operation、Value、SubQueries
Field	字符串	否	Size	字段名称。常用字段包括 `Size`、`Filename`、`FileModifiedTime`、`ObjectACL`、`OSSStorageClass`、`OSSTagging.<key>`、`OSSUserMeta.<key>`、`Labels.LabelName`。父节点:simpleQuery
Operation	字符串	是	gt	操作符。取值范围: eq、gt、gte、lt、lte、match、prefix、and、or、not。父节点:simpleQuery
Value	字符串	否	102400	字段值。比较、匹配、前缀查询等操作符需要设置。父节点:simpleQuery
SubQueries	Query 数组	否	[{"Field":"Size","Operation":"gt","Value":"102400"}]	子查询条件列表。仅当 `Operation` 为 `and`、`or`、`not` 时设置。数组元素为 Query 对象(结构同 simpleQuery,可递归嵌套) 父节点:simpleQuery
withFields	字符串数组	否	["URI","Insights"]	投影字段列表。通过 URL Query String 传递时需 JSON 序列化并 URL 编码。子节点:WithField
WithField	字符串	否	Insights	单个投影字段名,如 `URI` / `Size` / `FileModifiedTime` / `Insights` 等。父节点:withFields
maxResults	整型	否	100	单次返回的最大结果数,取值范围 1 到 100,默认 100。

响应头

此接口仅涉及公共响应头。更多信息,请参见公共响应头(Common Response Headers)。

响应元素

名称	类型	是否必选	示例值	描述
MetaQuery	容器	是	不涉及	检索结果的根容器。子节点:Files
Files	容器	否	不涉及	命中的文件列表容器。按相关度降序排列。子节点:File 父节点:MetaQuery
File	容器	否	不涉及	单个文件的元数据。完整字段见 File 数据结构。父节点:Files

示例

请求示例

按自然语言"海边日落"在 photos-2026 Dataset 中检索图片:

POST /?metaQuery&action=semanticQuery&datasetName=photos-2026&query=%E6%B5%B7%E8%BE%B9%E6%97%A5%E8%90%BD&mediaTypes=%5B%22image%22%5D&maxResults=20 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 09:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

URL 中参数解码后为:query=海边日落、mediaTypes=["image"]。

按"雪景"在 Size 大于 100 KB 的图片范围内做语义检索:

POST /?metaQuery&action=semanticQuery&datasetName=photos-2026&query=%E9%9B%AA%E6%99%AF&mediaTypes=%5B%22image%22%5D&simpleQuery=%7B%22Field%22%3A%22Size%22%2C%22Operation%22%3A%22gt%22%2C%22Value%22%3A%22102400%22%7D&maxResults=20 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 09:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

URL 中参数解码后为:

query=雪景
mediaTypes=["image"]
simpleQuery={"Field":"Size","Operation":"gt","Value":"102400"}

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7F9
Date: Wed, 20 May 2026 09:00:01 GMT
Content-Type: application/xml
Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
  <Files>
    <File>
      <Filename>photos/snow-mountain.jpg</Filename>
      <Size>3145728</Size>
      <FileModifiedTime>2026-05-18T10:00:00.000+08:00</FileModifiedTime>
      <ContentType>image/jpeg</ContentType>
      <MediaType>image</MediaType>
      <ImageWidth>4032</ImageWidth>
      <ImageHeight>3024</ImageHeight>
      <Insights>
        <Image>
          <Caption>白雪覆盖的山脉,阳光从云层中透出。</Caption>
        </Image>
      </Insights>
      <Labels>
        <Label>
          <LabelName>雪山</LabelName>
          <LabelConfidence>0.99</LabelConfidence>
        </Label>
      </Labels>
    </File>
  </Files>
</MetaQuery>