AI内容感知_对象存储(OSS)-阿里云帮助中心

当存储在对象存储（OSS）中积累了海量的图片、视频、文档等非结构化数据后，传统的基于文件名或手动标签的检索方式变得效率低下，且无法理解文件内容的深层语义。OSS 利用多模态 AI 模型，自动为存储在 Bucket 中的文件提取语义描述与精简摘要，并构建为可检索的索引。使得可通过自然语言直接搜索文件内容，实现“以文搜图”、“以文搜视频”等高级检索功能，从而显著提升数据检索的准确性与效率，并为构建智能问答（RAG）等上层应用提供坚实基础。

应用场景

IP Camera (IPC) 场景的智能搜索：面向智能安防场景，支持回放视频的语义检索、监控事件推送、App 热词推荐等。例如终端用户查看回放时，自动生成“今日热词推荐”。
RAG 检索增强知识库：基于 OSS 海量数据和内容感知能力构建 RAG 外挂知识库，当用户提问时，可以利用OSS的内容感知能力进行RAG检索增强，为大模型提供更精准、更相关的上下文信息，从而生成更高质量的回答。
知识存储与管理平台：基于 OSS 数据索引和内容感知的知识内容，构建知识管理平台、媒资管理平台、企业智能办公平台等。OSS 数据索引和内容感知可以获取多媒体文件的近 70 项元数据，客户可以基于这些元数据进行云端知识管理平台的构建。

工作原理

AI 内容感知功能的核心是语义检索，通过理解用户的自然语言，将查询与文件的多媒体内容匹配，而非依赖传统的关键词匹配。整体流程如下：

开启功能与首次索引：当为 Bucket 开启该功能后，系统会触发一次性存量扫描，对 Bucket 内所有受支持的文件进行异步处理。
特征提取与描述生成：系统使用大模型为每个文件提取核心语义特征，并生成两类内容感知描述文本：内容详细描述（约 100 字）与精简摘要（20 字内）。
向量化与索引构建：将文件的语义特征与感知描述向量化，构建向量索引库，支撑大规模高性能检索。
语义检索与精排：用户发起查询时，系统将查询语句向量化，在向量索引中召回最相似的文件；随后结合向量表示与内容感知描述进行联合精排，提升准确率与召回率，精准识别海量数据中的关键信息，实现增强型语义检索。
结果返回与应用：检索结果会返回通过内容感知能力生成的内容详细描述和精简摘要，用户可直接获取要点信息，并据此构建上层应用，如“检索热词”“每日总结”等功能。

首次索引是异步执行的，根据 Bucket 内文件数量和大小，可能需要数分钟到数小时不等。在此期间，存量文件无法被搜到。对于新上传或更新的文件，系统会自动触发增量式的索引更新。

使用限制

在开始之前，请确保您的Bucket位于以下支持AI内容感知的地域：华北2（北京）、华北3（张家口）、华东1（杭州）、华东2（上海）、华南1（深圳）、西南1（成都）地域的 Bucket支持使用 AI 内容感知功能。

1. 创建Bucket并上传文件

登录OSS管理控制台。
进入Bucket列表页面，并点击创建Bucket。
在创建Bucket页面，填写Bucket名称（建议使用业务相关的名称，如videos-oss-metaquery），其余参数可保持默认配置。
单击完成创建，在创建成功的页面，点击进入Bucket。
在文件列表页面，点击上传文件 > 扫描文件，选择待上传的视频文件（如视频A.mp4、视频B.mp4和视频C.mp4），其余参数保留默认配置，点击上传文件。

2. 开启 AI 内容感知

您需要为Bucket在 OSS 数据索引-向量检索功能中开启 OSS AI 内容感知，开启后，使用数据索引的查询接口进行语义检索和查询即可。

在左侧导航栏，选择文件管理 > 数据索引。
在数据索引页面，首次使用数据索引功能时，需要按指引完成对 AliyunMetaQueryDefaultRole 角色的授权，以便 OSS 服务能管理 Bucket 中的数据。授权后，单击开启数据索引。
选择向量检索，在 AI内容感知 选项中，可根据需要勾选 图片内容感知 或 视频内容感知。
（可选）文件过滤规则：配置此项仅对符合特定规则的文件进行 AI 分析。最多可设置 5 条文件过滤规则。支持根据前缀、文件大小、LastModifiedTime、ObjectTag过滤。示例：添加一条前缀规则，值为 videos/，表示仅处理 videos 目录下的文件。
说明
如果开启文件过滤，那么只根据过滤后的文件数量收取数据索引-向量检索费用和内容感知费用。
单击确认开启。

说明

构建元数据索引需要等待一定的时间，具体等待时长取决于Bucket中Object的数量。若开启时间过久可通过刷新来查看开启状态。

3. 执行查询

索引构建完成后，您可以通过控制台、SDK或命令行工具执行语义检索。只需输入一段描述性文字，例如停着车的院子，系统便会返回与描述相符的关键文件及其内容摘要。且直接基于该接口或 SDK 进行开发即可，无需关系底层资源的弹性、无需关系向量化过程、无需关心索引构建和索引存储，完全 serverless 化使用。

控制台

在Bucket 列表页面，点击您的 Bucket名称。
在文件列表页面，确认视频已上传。
在左侧导航栏，选择文件管理 > 数据索引。
在数据索引页面，检索内容中输入停着车的院子，在多媒体类型中勾选视频，点击立即查询，检索到符合描述的视频且返回内容摘要。

SDK

Java

仅Java SDK 3.18.2及以上版本支持使用向量检索功能，更多用法见向量检索（Java SDK）。

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.*;
import java.util.ArrayList;
import java.util.List;

public class DoMetaQuery {
    public static void main(String[] args) throws Exception {
        // Endpoint以华东1（杭州）为例，其它Region请按实际情况填写。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 填写Bucket名称，例如examplebucket。
        String bucketName = "examplebucket";
        // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为cn-hangzhou。
        String region = "cn-hangzhou";

        // 创建OSSClient实例。
        // 当OSSClient实例不再使用时，调用shutdown方法以释放资源。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            int maxResults = 20;
            List<String> mediaTypes = new ArrayList<String>();
            mediaTypes.add("image");
            String query = "Snow";
            String simpleQuery = "{\"Operation\":\"gt\", \"Field\": \"Size\", \"Value\": \"30\"}";
            String sort = "Size";
            DoMetaQueryRequest doMetaQueryRequest = new DoMetaQueryRequest(bucketName, maxResults, query, sort, MetaQueryMode.SEMANTIC, mediaTypes, simpleQuery);
            DoMetaQueryResult doMetaQueryResult = ossClient.doMetaQuery(doMetaQueryRequest);
        } catch (OSSException oe) {
            System.out.println("Error Message: " + oe.getErrorMessage());
            System.out.println("Error Code:       " + oe.getErrorCode());
            System.out.println("Request ID:      " + oe.getRequestId());
            System.out.println("Host ID:           " + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Error Message: " + ce.getMessage());
        } finally {
            if(ossClient != null){
                ossClient.shutdown();
            }
        }
    }
}

Python

更多用法见向量检索。

import argparse
import alibabacloud_oss_v2 as oss

# 创建命令行参数解析器，用于处理命令行输入
parser = argparse.ArgumentParser(description="do meta query semantic sample")
# 添加必要的命令行参数
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)  # 存储空间所在地域
parser.add_argument('--bucket', help='The name of the bucket.', required=True)  # 存储空间名称
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')  # OSS访问域名，可选

def main():
    # 解析命令行参数
    args = parser.parse_args()

    # 从环境变量中加载访问凭证
    # 运行前需要设置环境变量：OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 加载SDK默认配置
    cfg = oss.config.load_default()
    # 设置凭证提供者
    cfg.credentials_provider = credentials_provider
    # 设置区域
    cfg.region = args.region
    # 如果提供了endpoint，则更新配置中的endpoint
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 创建OSS客户端实例
    client = oss.Client(cfg)

    # 发起元数据查询请求 - 向量检索模式
    result = client.do_meta_query(oss.DoMetaQueryRequest(
            bucket=args.bucket,
            mode='semantic',
            meta_query=oss.MetaQuery(
                max_results=1000,
                query='俯瞰白雪覆盖的森林',
                order='desc',
                media_types=oss.MetaQueryMediaTypes(
                    media_type=['image']
                ),
                simple_query='{"Operation":"gt", "Field": "Size", "Value": "30"}',
            ),
    ))

    # 打印检索结果
    print(vars(result))

if __name__ == "__main__":
    main()

Go

更多用法见向量检索（Go SDK V2）。

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

var (
	region     string
	bucketName string
)

func init() {
	// 设置命令行参数来指定region，默认为空字符串
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	// 设置命令行参数来指定bucket名称，默认为空字符串
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	flag.Parse() // 解析命令行参数

	// 检查是否提供了存储空间名称，如果没有提供，则输出默认参数并退出程序
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// 检查是否提供了区域信息，如果没有提供，则输出默认参数并退出程序
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// 创建客户端配置，并使用环境变量作为凭证提供者和指定的区域
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg) // 使用配置创建一个新的OSS客户端实例

	// 执行向量检索操作
	request := &oss.DoMetaQueryRequest{
		Bucket: oss.Ptr(bucketName),
		Mode:   oss.Ptr("semantic"),
		MetaQuery: &oss.MetaQuery{
			MaxResults:  oss.Ptr(int64(99)),
			Query:       oss.Ptr("Overlook the snow-covered forest"), // 输入语义内容检索，此处为示例文本
			MediaType:   oss.Ptr("image"),                            // 指定检索的媒体类型，此处为图像类型
			SimpleQuery: oss.Ptr(`{"Operation":"gt", "Field": "Size", "Value": "30"}`),
		},
	}
	result, err := client.DoMetaQuery(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to do meta query %v", err)
	}

	log.Printf("do meta query result:%#v\n", result)
}

PHP

更多用法见向量检索（PHP SDK V2）。

<?php

// 引入自动加载文件，确保依赖库能够正确加载
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// 定义命令行参数的描述信息
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // Bucket所在的地域（必填）
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // 访问域名（可选）
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // Bucket名称（必填）
];

// 将参数描述转换为getopt所需的长选项格式
// 每个参数后面加上":"表示该参数需要值
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// 解析命令行参数
$options = getopt("", $longopts);

// 验证必填参数是否存在
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // 获取参数的帮助信息
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // 如果必填参数缺失，则退出程序
    }
}

// 从解析的参数中提取值
$region = $options["region"]; // Bucket所在的地域
$bucket = $options["bucket"]; // Bucket名称

// 加载环境变量中的凭证信息
// 使用EnvironmentVariableCredentialsProvider从环境变量中读取Access Key ID和Access Key Secret
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// 使用SDK的默认配置
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 设置凭证提供者
$cfg->setRegion($region); // 设置Bucket所在的地域
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // 如果提供了访问域名，则设置endpoint
}

// 创建OSS客户端实例
$client = new Oss\Client($cfg);

// 执行向量检索查询满足指定条件的对象
$request = new Oss\Models\DoMetaQueryRequest($bucket, new Oss\Models\MetaQuery(
    maxResults: 99,
    query: "Overlook the snow-covered forest",
    mediaTypes: new Oss\Models\MetaQueryMediaTypes('image'),
    simpleQuery: '{"Operation":"gt", "Field": "Size", "Value": "30"}',
), 'semantic');

$result = $client->doMetaQuery($request);
printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId . PHP_EOL .
    'result:' . var_export($result, true)
);

ossutil

以下示例展示了如何查询存储空间examplebucket中满足指定条件的文件。

ossutil api do-meta-query --bucket examplebucket --meta-query "{\"Query\":\"Overlooking the snow covered forest\",\"MediaTypes\":{\"MediaType\":\"video\"},\"SimpleQuery\":\"{\\\"Operation\\\":\\\"gt\\\", \\\"Field\\\": \\\"Size\\\", \\\"Value\\\": \\\"1\\\"}\"}" --meta-query-mode semantic

关于该命令的更多信息，请参见do-meta-query。

计费说明

使用 AI 内容感知功能会产生以下费用：

数据索引费用：需要在数据索引-向量检索模式中开启 AI 内容感知，因此会产生数据索引-向量检索相关的费用。
AI内容感知费用：包括图片内容感知和视频内容感知费用，根据处理的文件类型和用量计费。开启 AI 内容感知后，OSS 会自动扫描该 Bucket 中的存量图片/视频文件。同时，一旦有新的图片/视频文件上传，OSS 会自动触发 AI 内容感知，新上传的图片/视频文件也会产生 AI 内容感知费用，请您及时关注账单变化。

API请求费用：在存量文件索引构建期间和增量文件索引更新期间会产生API请求费用，按API调用次数收费。涉及的API请求如下：

操作	API
扫描Bucket中的文件	ListObjects
为Bucket中的文件构建索引	HeadObject和GetObject
Bucket中文件存在Tag	GetObjectTag
Bucket中文件携带自定义Meta	GetObjectMeta
Bucket中存在软链接文件	GetSymlink

如需停止相关计费，请及时关闭向量检索。