如何使用语义检索 - 智能媒体管理

IMM语义检索是采用向量检索方式，根据特定内容语义对多媒体数据进行搜索的过程，本文介绍如何使用语义检索。

功能简介

传统的标量检索是根据文件携带的元数据信息进行检索，例如文件名称、文件创建时间、文件格式等。与标量检索不同的是，语义检索采用向量检索的方式，可以根据文件内容进行检索，例如“俯瞰森林”、“雪中城市”、“去年夏天的草原”等文件内容。您可以利用 IMM 语义检索能力对您对象存储 OSS 中的文件进行检索，也可以对网盘与相册服务 PDS 中的文件进行检索。

应用场景

个人及企业办公场景

语义检索功能可以通过特定语义内容直接对办公文件进行搜索，例如直接搜索“ERP 系统使用方式”、“IT 维修流程”“2024 年经营情况分析”等关键词，以实现文件搜索方式的便捷化，从而提升办公效率。

多媒体社交场景

在多媒体社交场景中，您可以利用IMM语义检索能力，为您的用户提供特定内容和多媒体数据检索功能。例如，在某款社交应用程序中，用户上传了大量图片数据。通过语义检索，用户可以直接根据内容进行图片搜索，比如直接搜索内容为“去年郊外春游”、“春节团聚”、“我见过的大海”等照片，从而为应用程序增加实用性和趣味性。

网盘场景

在网盘场景中，目前大多数提供基于标量检索的文件搜索功能，例如按文件名称、创建时间或文件后缀进行搜索。网盘通常应用于个人或企业场景，用户可以利用IMM语义检索功能，对网盘中的特定内容进行搜索，比如相关文档或相册中的相关图片。

视频监控场景

针对视频监控存储的数据，企业可以利用 IMM 语义检索能力对监控数据中的部分文件进行搜索。比如输入“昨天的雪天户外监控”、“晴天中的果园”等关键词，即可对相应文件进行检索。

使用限制

重要

目前仅支持对图片和文档进行语义检索。
该功能当前仅支持华北2（北京）地域。
该功能支持的图片格式：JPG、PNG、BMP、GIF、WebP、TIFF、HEIC、AVIF。
原图大小不超过 20MB，且对应的原图高或者宽不能超过30,000 px和总像素不能超过2.5亿 px。动态图片（例如GIF图片）的总像素计算方式为宽*高*图片帧数；非动态图片（例如PNG图片）的总像素计算方式为宽*高。
文档大小不得超过30万字符，超过限制将会被截断。
数据索引与分析是一个异步过程。在使用诸如 IndexFileMeta 等 API 接口添加文件索引后，需要通过回调消息通知来确认分析完成。这通常需要几秒或者几分钟的时间，具体等待时间取决于您提交的文件类型和大小，分析的复杂程度以及所需的时间也会有所不同。在分析完成后，由于存储引擎需要构建索引，通常需要等待几秒的时间，之后您就可以开始检索这些文件。

前提条件

已根据使用场景为文件建立元数据索引。具体操作，请参见建立元数据索引。
数据集选择“Official:CognitionImageManagement” 或者 “Official:CognitionDocumentManagement” 模板，分别对应“图片语义检索”和“文档语义检索”功能。

重要

当您不再需要进行语义检索时，请及时删除数据集。未删除的IMM 数据集将持续自动抽取 OSS 元数据，该过程会导致 IMM 持续产生数据请求费用。

计费说明

IMM 费用：使用 IMM 语义检索功能，将会产生“元数据管理”相关接口的调用费用，详情请参见IMM计费项概述。

说明

在您使用语义检索时，您需要为您的数据集选择“Official:CognitionImageManagement” 或者 “Official:CognitionDocumentManagement” 模板，分别对应“图片语义检索”和“文档语义检索”功能。模板中包含了多种算子，其中语义检索算子为免费提供，其余算子为收费状态，关于模板与算子的对应关系，请查看工作流模板与算子。

OSS 费用：详情请参见 OSS计费概述。

语义检索

调用 SemanticQuery - 自然语言查询接口对项目test-project下test-dataset数据集中的元数据进行基于语义的查询搜索。

图片语义检索

例如：某个相册中包含大量旅游拍摄的图片，其中一些照片是2020年7月份在成都熊猫基地拍摄的熊猫，若需通过语义检索找到这些图片，可以创建一个数据集为相册中的照片建立元数据索引，之后使用关键字”2020年7月成都的熊猫“来进行检索。

如下以查询项目test-project下，test-dataset数据集中包含2020年7月成都的熊猫的文件为例：

请求示例

{
    "ProjectName": "test-project",
    "DatasetName": "test-dataset",
    "Query": "2020年7月成都的熊猫"
}

返回示例

{
    "RequestId": "645FB6D9-5EA0-02C9-B253-****",
    "Files": [
        {
            "ProduceTime": "2020-07-19T17:11:11+08:00",
            "ObjectACL": "default",
            "ContentType": "image/jpeg",
            "ProjectName": "test-project",
            "Size": 22868,
            "URI": "oss://test-bucket/test-object.jpg",
            "Addresses": [
                {
                    "Language": "zh-Hans",
                    "Township": "三河街道",
                    "AddressLine": "四川省成都市新都区三河街道成都大熊猫繁育研究基地",
                    "Country": "中国",
                    "City": "成都市",
                    "District": "新都区",
                    "Province": "四川省"
                }
            ],
            "ObjectType": "file",
            "OwnerId": "****",
            "FileModifiedTime": "2021-05-13T10:22:44+08:00",
            "ImageWidth": 270,
            "OSSStorageClass": "Standard",
            "MediaType": "image",
            "ObjectId": "****",
            "CreateTime": "2022-07-06T07:10:18.497753661+08:00",
            "Filename": "1.jpg",
            "Labels": [
                {
                    "CentricScore": 0.757,
                    "Language": "zh-Hans",
                    "LabelConfidence": 0.946,
                    "LabelName": "熊猫",
                    "LabelLevel": 2,
                    "ParentLabelName": "野生动物"
                },
                ...
            ],
            "Orientation": 1,
            "EXIF": "...",
            "ContentMd5": "HZwoCnxPZ/fvhz4oRJ****",
            "ImageHeight": 270,
            "ImageScore": {
                "OverallQualityScore": 0.719
            },
            "ETag": "\"1D9C280A7C4F67F7EF873E28449D****\"",
            "DatasetName": "test-dataset",
            "FileHash": "\"1D9C280A7C4F67F7EF873E2****\"",
            "UpdateTime": "2022-07-06T07:10:18.497753661+08:00",
            "OSSCRC64": "5634447745650079669",
            "OSSTaggingCount": 0,
            "LatLong": "34.000000,119.000000",
            "OSSObjectType": "Normal"
        }
    ]
}

示例代码（以1.27.3版本的Python SDK为例）

# -*- coding: utf-8 -*-

import os
from alibabacloud_imm20200930.client import Client as imm20200930Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_imm20200930 import models as imm_20200930_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient


class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client(
        access_key_id: str,
        access_key_secret: str,
    ) -> imm20200930Client:
        """
        使用AccessKey ID&AccessKey Secret初始化账号Client。
        @param access_key_id:
        @param access_key_secret:
        @return: Client
        @throws Exception
        """
        config = open_api_models.Config(
            access_key_id=access_key_id,
            access_key_secret=access_key_secret
        )
        config.endpoint = f'imm.cn-beijing.aliyuncs.com'
        return imm20200930Client(config)

    @staticmethod
    def main() -> None:
        # 阿里云账号AccessKey拥有所有API的访问权限，建议您使用RAM用户进行API访问或日常运维。
        # 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里，否则可能导致AccessKey泄露，威胁您账号下所有资源的安全。
        # 本示例通过从环境变量中读取AccessKey，来实现API访问的身份验证。如何配置环境变量，请参见https://help.aliyun.com/document_detail/2361894.html。
        imm_access_key_id = os.getenv("AccessKeyId")
        imm_access_key_secret = os.getenv("AccessKeySecret")
        client = Sample.create_client(imm_access_key_id, imm_access_key_secret)
        semantic_query_request = imm_20200930_models.SemanticQueryRequest(
            query='2020年7月成都的熊猫',
            project_name='test-project',
            dataset_name='test-dataset',
            max_results=100
        )
        runtime = util_models.RuntimeOptions()
        try:
            # 打印API的返回值。
            response = client.semantic_query_with_options(semantic_query_request, runtime)
            print(response.body.to_map())
        except Exception as error:
            # 如有需要，请打印错误信息。
            UtilClient.assert_as_string(error.message)
            print(error)


if __name__ == '__main__':
    Sample.main()

文档语义搜索

例如：在网盘场景中，该网盘存储了各种类型的文件。若要利用语义搜索找到包含“IT服务流程”内容的文件，可以创建一个数据集来为网盘中的文件建立元数据索引，之后使用关键词“IT服务流程”进行检索。

如下以查询项目test-project下，test-dataset数据集中包含“IT服务流程”的文件为例，请求参数如下。

请求示例

{
    "ProjectName": "test-project",
    "DatasetName": "test-dataset",
    "MediaTypes": ["document"],  
    "Query": "IT服务流程"
}

返回示例

{
  "RequestId": "CD870E69-D2E8-031B-BD3E-****",
  "Files": [
    {
      "ObjectACL": "default",
      "ContentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "ProjectName": "test-project",
      "ObjectId": "2f66ba6e902e5ad42341a9e7365b19f6130d4a077e4f57150450e281d0b7afd9",
      "Size": 28340,
      "CreateTime": "2024-03-08T10:13:19.569053164+08:00",
      "Filename": "3839a9a0-c630-420d-ae69-ea24792412fd.docx",
      "URI": "oss://test-bucket/test-object.docx",
      "ObjectType": "file",
      "ContentMd5": "Y7SmYa831Hq1qryuRyl6mg==",
      "OwnerId": "****",
      "FileModifiedTime": "2024-01-10T16:18:31+08:00",
      "ETag": "\"63B4A661AF37D47AB5AABCAE47297A9A\"",
      "DatasetName": "test-dataset",
      "FileHash": "63B4A661AF37D47AB5AABCAE47297A9A",
      "UpdateTime": "2024-03-08T10:13:19.569053164+08:00",
      "OSSStorageClass": "Standard",
      "MediaType": "document",
      "OSSCRC64": "6833019149643646551",
      "OSSTaggingCount": 0,
      "OSSObjectType": "Normal"
    }
  ]
}

示例代码（以1.27.3版本的Python SDK为例）

# -*- coding: utf-8 -*-

import os
from alibabacloud_imm20200930.client import Client as imm20200930Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_imm20200930 import models as imm_20200930_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient


class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client(
        access_key_id: str,
        access_key_secret: str,
    ) -> imm20200930Client:
        """
        使用AccessKey ID&AccessKey Secret初始化账号Client。
        @param access_key_id:
        @param access_key_secret:
        @return: Client
        @throws Exception
        """
        config = open_api_models.Config(
            access_key_id=access_key_id,
            access_key_secret=access_key_secret
        )
        config.endpoint = f'imm.cn-beijing.aliyuncs.com'
        return imm20200930Client(config)

    @staticmethod
    def main() -> None:
        # 阿里云账号AccessKey拥有所有API的访问权限，建议您使用RAM用户进行API访问或日常运维。
        # 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里，否则可能导致AccessKey泄露，威胁您账号下所有资源的安全。
        # 本示例通过从环境变量中读取AccessKey，来实现API访问的身份验证。如何配置环境变量，请参见https://help.aliyun.com/document_detail/2361894.html。
        imm_access_key_id = os.getenv("AccessKeyId")
        imm_access_key_secret = os.getenv("AccessKeySecret")
        client = Sample.create_client(imm_access_key_id, imm_access_key_secret)
        semantic_query_request = imm_20200930_models.SemanticQueryRequest(
            query='IT服务流程',
            project_name='test-project',
            dataset_name='test-dataset',
          	media_types=['document'],
            max_results=100
        )
        runtime = util_models.RuntimeOptions()
        try:
            # 打印API的返回值。
            response = client.semantic_query_with_options(semantic_query_request, runtime)
            print(response.body.to_map())
        except Exception as error:
            # 如有需要，请打印错误信息。
            UtilClient.assert_as_string(error.message)
            print(error)


if __name__ == '__main__':
    Sample.main()