AI 助理
文档备案控制台
官方文档
首页

新版 MetaQuery 功能概览

更新时间：
复制 MD 格式
产品详情
我的收藏

当一个 Bucket 内积累了多条业务、多个设备或多个场景的文件后，旧版 MetaQuery 只有一个隐含的元数据库，所有文件共用同一套 AI 处理配置，难以按业务隔离管理和检索。新版 MetaQuery 引入 Dataset，让您在同一个 Bucket 内按业务、设备或场景把文件分组：每个 Dataset 拥有独立的元数据、独立的 AI 内容感知配置（DatasetConfig）和独立的查询入口，从而实现「一个 Bucket、多套业务、互不干扰」的精细化元数据管理与语义检索。

重要

本文档中的多 Dataset、Dataset CRUD、SmartCluster CRUD 等能力当前处于邀测阶段，仅支持华东1（杭州）、新加坡地域。使用前请确保目标 Bucket 位于上述地域，并联系技术支持申请开通新版 MetaQuery 邀测能力。

应用场景

  • 多设备/多业务混存的精细化检索：一个 Bucket 同时存放入口摄像头、仓库摄像头、办公区摄像头的视频，或多个应用的图片。为每类来源建独立 Dataset，查询时只在目标 Dataset 内检索，互不干扰。

  • 跨语言内容理解与检索：为不同业务的 Dataset 配置不同的 Insights 输出语言（如中文、英文），让 AI 生成的内容描述与业务语言一致，便于跨语言检索与展示。

  • 自定义事件侦测：为安防、巡检等业务的 Dataset 配置自定义事件标签（如「有人摔倒」），视频入库时自动打标，后续直接按标签检索命中事件的文件。

  • 智能分组（SmartCluster）：在 Dataset 内对人脸、图片等进行自动聚类分组，支撑相册、媒资库等场景。

工作原理

新版 MetaQuery 以 Dataset 为核心组织元数据与 AI 处理，整体流程如下：

  1. 开启与路由：以 semantic 模式为 Bucket 开启 MetaQuery。如需多 Dataset，开启时配置 RouteRule，指定用哪个 OSS Object Tag 把文件路由到不同 Dataset。

  2. 按 Dataset 处理：文件根据 Tag 进入对应 Dataset，并按该 Dataset 的 DatasetConfig 进行 AI 内容感知（如图片/视频内容描述、Insights 语言、自定义事件标签等），处理结果写入该 Dataset 的元数据。

  3. Dataset 级查询：文件索引完成后，通过 SimpleQuery（结构化查询）或 SemanticQuery（自然语言语义检索）在指定 Dataset 内检索，结果只来自该 Dataset。

  4. 智能分组（可选）：在 Dataset 内通过 SmartCluster 对文件做自动聚类分组。

说明

文件索引为异步执行，开启功能或上传文件后，需要等待一段时间索引才会完成；在此之前文件可能查询不到。如需感知索引完成，可在开启 MetaQuery 时配置 MNS 通知。

新版与旧版的区别

对比项

旧版

新版

数据组织

每个 Bucket 只有一个隐含元数据库

同一 Bucket 可拥有多个 Dataset

文件路由

文件统一进入隐含元数据库

可通过 OSS Object Tag 将文件路由到指定 Dataset

处理配置

Bucket 级统一配置

每个 Dataset 可独立配置 DatasetConfig

查询接口

通过 DoMetaQuery 查询默认元数据库

可通过 SimpleQuery、SemanticQuery 指定 Dataset 查询

智能分组

不支持独立管理

可在 Dataset 内创建和管理 SmartCluster

说明

不配置 RouteRule 时，所有文件进入系统默认 Dataset（通常命名为 oss_{uid}_{bucket}），使用方式等价于旧版单库语义。

使用限制

RouteRule 仅在 mode=semantic 时生效，且在开启 MetaQuery 时确定；开启后如需变更，需要先调用 CloseMetaQuery 再重新 OpenMetaQuery，该操作会清空已索引的元数据。

1. 开启 MetaQuery

以 semantic 模式为目标 Bucket 开启 MetaQuery。运行前请通过环境变量 OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET 配置访问凭证，并将 examplebucket 替换为您的 Bucket 名称。

Java SDK

import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.dataprocess.OSSDataProcessClient;
import com.aliyun.sdk.service.oss2.dataprocess.models.*;

public class OpenMetaQuerySample {
    public static void main(String[] args) throws Exception {
        try (OSSDataProcessClient client = OSSDataProcessClient.newBuilder()
                .region("cn-hangzhou")
                .credentialsProvider(new EnvironmentVariableCredentialsProvider())
                .build()) {
            client.openMetaQuery(OpenMetaQueryRequest.newBuilder()
                    .bucket("examplebucket")
                    .mode("semantic")
                    .build());
            System.out.println("open meta query success");
        }
    }
}

如需把不同文件路由到不同 Dataset，请在开启时配置 RouteRule。以下 RouteRule 表示：读取文件的 routing-dataset 标签，将文件路由到同名 Dataset，Dataset 不存在时自动创建。

<RouteRule>
  <Type>OSSTag</Type>
  <OSSTagKey>routing-dataset</OSSTagKey>
  <AutoCreateDataset>True</AutoCreateDataset>
</RouteRule>

2. 创建 Dataset 并配置 DatasetConfig

Dataset 是新版 MetaQuery 的元数据逻辑分组单元。您可以显式创建 Dataset，也可以在配置 RouteRule.AutoCreateDataset=True 后由系统按 Tag 值自动创建。多 Dataset 路由规则如下：

配置

文件索引行为

不配置 RouteRule

文件进入默认 Dataset

配置 RouteRule + AutoCreateDataset=False

仅携带有效路由 Tag 且 Dataset 已存在的文件会被索引

配置 RouteRule + AutoCreateDataset=True

携带路由 Tag 的文件会进入同名 Dataset，Dataset 不存在时自动创建

DatasetConfig 是 AI 内容感知和智能分组的统一配置入口。以下创建 photos-en 这个 Dataset，并让它生成的图片内容描述（Insights）以英文输出。

说明

WorkflowParameters 仍保留用于兼容旧版基础开关，例如 ImageInsightEnable、VideoInsightEnable、UserDefinedLabelsEnable。后续新能力主要通过 DatasetConfig 演进，新接入建议优先使用 DatasetConfig。

配置方式建议如下：

场景

推荐配置方式

新接入 AI 内容感知、多语言 Insights、自定义事件侦测或自动智能分组

使用 DatasetConfig

存量业务继续使用图片或视频内容感知基础开关

可继续使用 WorkflowParameters

同一 Bucket 内不同业务使用不同语言、标签规则或聚类策略

为不同 Dataset 显式配置不同 DatasetConfig

Java SDK

import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.dataprocess.OSSDataProcessClient;
import com.aliyun.sdk.service.oss2.dataprocess.models.*;

public class CreateDatasetSample {
    public static void main(String[] args) throws Exception {
        try (OSSDataProcessClient client = OSSDataProcessClient.newBuilder()
                .region("cn-hangzhou")
                .credentialsProvider(new EnvironmentVariableCredentialsProvider())
                .build()) {
            DatasetConfig config = DatasetConfig.newBuilder()
                    .insights(InsightsConfig.newBuilder()
                            .language("en")
                            .image(InsightsImageConfig.newBuilder()
                                    .caption(InsightsCaptionConfig.newBuilder()
                                            .enable("true")
                                            .build())
                                    .build())
                            .build())
                    .build();

            client.createDataset(CreateDatasetRequest.newBuilder()
                    .bucket("examplebucket")
                    .datasetName("photos-en")
                    .datasetConfig(config)
                    .build());
            System.out.println("create dataset success");
        }
    }
}
说明

通过 OpenMetaQuery 配置的 DatasetConfig 可作为默认处理配置；自动创建的 Dataset 可能在运行时使用该默认配置，但该继承值不一定持久化到 Dataset 记录中。如需配置可被 GetDataset 查询和维护，请在 CreateDataset 或 UpdateDataset 时显式写入 datasetConfig。

3. 上传文件并路由到 Dataset

配置 RouteRule 后，上传文件时设置对应的 OSS Object Tag，文件即进入目标 Dataset。以下把 photos/snow.jpg 路由到 photos-en。

Java SDK

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.PutObjectRequest;
import com.aliyun.sdk.service.oss2.transport.BinaryData;
import java.nio.file.Files;
import java.nio.file.Paths;

public class PutObjectSample {
    public static void main(String[] args) throws Exception {
        try (OSSClient client = OSSClient.newBuilder()
                .region("cn-hangzhou")
                .credentialsProvider(new EnvironmentVariableCredentialsProvider())
                .build()) {
            // 通过 Object Tag 把文件路由到 photos-en 这个 Dataset。
            client.putObject(PutObjectRequest.newBuilder()
                    .bucket("examplebucket")
                    .key("photos/snow.jpg")
                    .tagging("routing-dataset=photos-en")
                    .body(BinaryData.fromStream(Files.newInputStream(Paths.get("/local/path/snow.jpg"))))
                    .build());
            System.out.println("put object success");
        }
    }
}
说明

如果开启 MetaQuery 时配置了 RouteRule，但上传文件未携带路由 Tag，该文件不会进入任何 Dataset。

4. 在 Dataset 内查询

索引完成后，通过 Dataset 级查询接口在指定 Dataset 内检索。以下用 SimpleQuery 做结构化查询；如需自然语言语义检索，可改用 SemanticQuery。

Java SDK

import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.dataprocess.OSSDataProcessClient;
import com.aliyun.sdk.service.oss2.dataprocess.models.File;
import com.aliyun.sdk.service.oss2.dataprocess.models.Label;
import com.aliyun.sdk.service.oss2.dataprocess.models.SimpleQuery;
import com.aliyun.sdk.service.oss2.dataprocess.models.SimpleQueryRequest;
import com.aliyun.sdk.service.oss2.dataprocess.models.SimpleQueryResult;
import java.util.Arrays;

public class SimpleQueryLabelSample {
    public static void main(String[] args) throws Exception {
        try (OSSDataProcessClient client = OSSDataProcessClient.newBuilder()
                .region("cn-hangzhou")
                .credentialsProvider(new EnvironmentVariableCredentialsProvider())
                .build()) {
            SimpleQueryResult result = client.simpleQuery(SimpleQueryRequest.newBuilder()
                    .bucket("examplebucket")
                    .datasetName("security-events")
                    .query(SimpleQuery.newBuilder()
                            .field("Labels.LabelName")
                            .value("有人摔倒")
                            .operation("eq")
                            .build())
                    .withFields(Arrays.asList("Filename", "URI", "Labels"))
                    .maxResults(20)
                    .build());
            for (File file : result.files()) {
                StringBuilder names = new StringBuilder();
                if (file.labels() != null) {
                    for (Label label : file.labels()) {
                        names.append(label.labelName()).append(" ");
                    }
                }
                System.out.println(file.filename() + " -> " + names);
            }
        }
    }
}

相关 API

新版 MetaQuery 在保留 OpenMetaQuery、GetMetaQueryStatus、CloseMetaQuery、DoMetaQuery 的基础上，新增以下接口。

分类

接口

说明

Dataset 管理

CreateDataset

创建 Dataset

Dataset 管理

GetDataset

查询 Dataset 信息和配置

Dataset 管理

UpdateDataset

更新 Dataset 配置

Dataset 管理

DeleteDataset

删除 Dataset

Dataset 管理

ListDatasets

列出 Bucket 下的 Dataset

Dataset 级查询

SimpleQuery

在指定 Dataset 内发起结构化查询

Dataset 级查询

SemanticQuery

在指定 Dataset 内发起语义检索

SmartCluster 管理

CreateSmartCluster

创建智能分组

SmartCluster 管理

GetSmartCluster

查询智能分组详情

SmartCluster 管理

UpdateSmartCluster

更新智能分组配置

SmartCluster 管理

DeleteSmartCluster

删除智能分组

SmartCluster 管理

ListSmartClusters

列出 Dataset 下的智能分组

元数据管理

DeleteFileMeta

删除指定文件在 Dataset 中的元数据

上一篇：新版 MetaQuery（邀测）下一篇：OpenMetaQuery