调用 CreateSmartCluster 接口在指定 Dataset 内创建一个 SmartCluster(智能聚类),用于对 Dataset 中已索引的素材按规则做向量化聚类。常见用法包括基于参考人脸图片的人脸聚类、基于关键词的语义聚类。
注意事项
阿里云账号默认拥有创建 SmartCluster 的权限。如需通过 RAM 用户创建,请确保 RAM 用户拥有
oss:MetaQuery权限。本接口仅在 OpenMetaQuery 时配置了
RouteRule启用多 Dataset 路由的场景下可用。同一 Dataset 内 SmartCluster 的
name必须唯一,否则返回SmartClusterAlreadyExist(HTTP 409)。创建后聚类计算是异步进行的,接口返回 200 仅表示请求已被接收。聚类结果通常需要数分钟才能就绪,可通过 GetSmartCluster 查询当前进度。
rules参数为聚类规则数组,通过 URL Query String 传递时需 JSON 序列化并 URL 编码。其中BaseURIs指向用于训练聚类规则的参考素材。例如人脸聚类需要给定数张参考人脸图片,且BaseURIs指向的 Object 必须真实存在。配置
notification时,需要预先为 RAM 角色授予访问指定 MNS 主题的权限。
请求语法
POST /?metaQuery&action=createSmartCluster&datasetName=DatasetName&name=ClusterName&clusterType=ClusterType&rules=Rules HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue请求头
此接口仅涉及公共请求头。更多信息,请参见公共请求头(Common Request Headers)。
请求元素
名称 | 类型 | 是否必选 | 示例值 | 描述 |
datasetName | 字符串 | 是 | photos-2026 | SmartCluster 所在的 Dataset 名。 |
name | 字符串 | 是 | face-cluster-alice | SmartCluster 名,Dataset 内唯一,长度最长 128 字符。 |
description | 字符串 | 否 | Cluster faces matching Alice | 描述文本,长度最长 128 字符。 |
clusterType | 字符串 | 是 | figure | 聚类类型。取值如下:
|
rules | SmartClusterRule 数组 | 是 | [{"RuleType":"face","BaseURIs":["oss://examplebucket/refs/alice.jpg"]}] | 聚类规则数组。通过 URL Query String 传递时需 JSON 序列化并 URL 编码。 子节点:SmartClusterRule |
SmartClusterRule | 容器 | 是 | 不涉及 | 单条聚类规则。 子节点:RuleType、BaseURIs、Keywords、Sensitivity 父节点:rules |
RuleType | 字符串 | 是 | face | 聚类规则类型。取值如下:
父节点:SmartClusterRule |
BaseURIs | 字符串数组 | 否 | ["oss://examplebucket/refs/alice.jpg"] | 参考素材 OSS URI 列表,格式 父节点:SmartClusterRule |
Keywords | 字符串数组 | 否 | ["人物","车辆","建筑"] | 聚类关键词列表,RuleType 为 keywords 时必填。 父节点:SmartClusterRule |
Sensitivity | 浮点型 | 否 | 0.7 | 聚类灵敏度,取值范围 [0, 1],值越大匹配越严格。 父节点:SmartClusterRule |
notification | Notification 对象 | 否 | {"MNS":{"TopicName":"imm-cluster-notification"}} | MNS 消息通知配置,用于聚类任务完成时推送消息。通过 URL Query String 传递时需 JSON 序列化并 URL 编码。 子节点:Notification |
Notification | 容器 | 否 | 不涉及 | 聚类任务消息通知配置。 子节点:MNS 父节点:notification |
MNS | 容器 | 否 | 不涉及 | MNS 通知配置。 子节点:TopicName 父节点:Notification |
TopicName | 字符串 | 否 | imm-cluster-notification | MNS 主题名称。 父节点:MNS |
响应头
此接口仅涉及公共响应头。更多信息,请参见公共响应头(Common Response Headers)。
响应元素
名称 | 类型 | 是否必选 | 示例值 | 描述 |
CreateSmartClusterResponse | 容器 | 是 | 不涉及 | 响应根元素。 子节点:ObjectId |
ObjectId | 字符串 | 是 | cluster-abc123def456 | 系统为新建 SmartCluster 分配的唯一 ID,后续的查询、更新、删除均使用此 ID。 父节点:CreateSmartClusterResponse |
示例
请求示例
POST /?metaQuery&action=createSmartCluster&datasetName=photos-2026&name=face-cluster-alice&clusterType=figure&rules=%5B%7B%22RuleType%22%3A%22face%22%2C%22BaseURIs%22%3A%5B%22oss%3A%2F%2Fexamplebucket%2Frefs%2Falice.jpg%22%5D%7D%5D&description=Cluster%20faces%20matching%20Alice HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 11:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e返回示例
HTTP/1.1 200 OK
x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7F6
Date: Wed, 20 May 2026 11:00:01 GMT
Content-Type: application/xml
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<CreateSmartClusterResponse>
<ObjectId>cluster-abc123def456</ObjectId>
</CreateSmartClusterResponse>