全部產品
Search

搜尋本產品

    Object Storage Service：使用向量檢索通過語義內容及多媒體特性快速尋找檔案

    文件中心

    Object Storage Service：使用向量檢索通過語義內容及多媒體特性快速尋找檔案

    更新時間：Sep 23, 2025

    通過OSS向量檢索，您可以基於語義內容、OSS中繼資料、多媒體中繼資料、對象ETag及標籤和自訂中繼資料等條件，快速定位海量Object中的目標檔案，最佳化檢索效率。

    使用情境

    個人及企業辦公情境

    向量檢索可以通過特定語義內容直接對辦公檔案進行搜尋，例如直接搜尋“ERP 系統使用方式”、“IT 維修流程”、“2024 年經營情況分析”等關鍵詞，以實現檔案搜尋方式的便捷化，從而提升辦公效率。

    多媒體社交情境

    在多媒體社交情境中，您可以利用檢索能力，為您的使用者提供特定內容和多媒體資料檢索功能。例如，在某款社交應用程式中，使用者上傳了大量圖片資料。通過語義檢索，使用者可以直接根據內容進行圖片搜尋，比如直接搜尋內容為“郊外春遊”、“春節團聚”、“我見過的大海”等照片，從而為應用程式增加實用性和趣味性。

    網盤情境

    在網盤情境中，目前大多數提供基於標量檢索的檔案搜尋功能，例如按檔案名稱、建立時間或檔案尾碼進行搜尋。網盤通常應用於個人或企業情境，使用者可以利用向量檢索功能，對網盤中的特定內容進行搜尋，比如相關文檔或相簿中的相關圖片。

    視頻監控情境

    針對視頻監控儲存區的資料，企業可以利用向量檢索能力對監控資料中的部分檔案進行搜尋。比如輸入“雪天戶外監控”、“晴天中的果園”等關鍵詞，即可對相應檔案進行檢索。

    使用限制

    • 地區限制

      華北1（青島）、華北2（北京）、華北3（張家口）、華東1（杭州）、華東2（上海）、華南1（深圳）、華南3（廣州）、西南1（成都）、中國香港、新加坡、印尼（雅加達）、德國（法蘭克福）地區的Bucket支援使用向量檢索功能。

      說明

      中國香港、新加坡、印尼（雅加達）、德國（法蘭克福）地區暫不支援音頻檢索。

    • Bucket限制

      開通向量檢索的 Bucket，其包含的檔案數量最多為50億。Bucket內檔案數量超過50億時，可能出現檢索效能下降的情況。如需處理更大規模的資料，請聯絡支援人員進行評估。

    • 分區上傳

      對於通過分區上傳產生的Object，查詢結果中只顯示已通過CompleteMultipartUpload操作將片段（Part）合成的完整Object，不顯示已初始化但未完成（Complete）或者未中止（Abort）的片段。

    效能參考

    OSS 向量檢索模式的效能表現如下，供參考。

    • OSS提供的內網頻寬和QPS

      該內網頻寬和QPS（即每秒可處理1250個檔案請求）為 OSS 向量檢索模式額外提供，不佔用您 Bucket 的 QoS。

      地區

      內網頻寬

      預設QPS

      華北2（北京）、華東1（杭州）、華東2（上海）、華南1（深圳）

      10Gbps

      1250

      其他地區

      1Gbps

      1250

    • 存量檔案索引產生時間參考

      向量檢索模式的索引構建期間會產生 List/Head/Get 等 API 介面的請求次數費用。同時，視頻、音頻和文檔檔案的索引產生時間較圖片索引產生時間會更長，建議您在使用前合理評估檔案數量。

      • 若 Bucket 內檔案以結構化資料和圖片檔案為主。

        • 單 Buket 檔案數量 1000 萬：2～3 小時

        • 單 Buket 檔案數量 1 億：1 天

        • 單 Buket 檔案數量 10 億： 10 天左右

      • 若 Bucket 內檔案以視頻，文檔和音頻檔案為主。

        • 單 Buket 檔案數量 1000 萬：2～3 天左右

        • 單 Buket 檔案數量 1 億：7～9 天左右

    • 增量檔案索引更新時間參考

      當 Bucket 內新增、修改或刪除的QPS低於預設值1250時，檔案從上傳或修改到可被檢索的延遲通常在分鐘至小時級；若超過預設值1250QPS，您可以通過支援人員聯絡我們，我們將根據實際情況評估，並提供支援人員。

    • 檔案檢索響應效能

      檢索結果返回為秒級，預設逾時時間為 30 秒。

    開啟向量檢索

    使用OSS控制台

    1. 登入OSS管理主控台。

    2. 單擊Bucket 列表，然後單擊目標Bucket名稱。

    3. 在左側導覽列， 選擇檔案管理 > 資料索引。

    4. 在資料索引頁面，首次使用資料索引功能時，需要按指引完成對 AliyunMetaQueryDefaultRole 角色的授權，以便 OSS 服務能管理 Bucket 中的資料。授權後，單擊開通資料索引。

    5. 選擇向量檢索，單擊確認開啟。

      說明

      構建中繼資料索引需要等待一定的時間，具體等待時間長度取決於Bucket中Object的數量。若開啟時間過久可通過重新整理來查看開啟狀態。

    使用阿里雲SDK

    Java

    僅Java SDK 3.18.2及以上版本支援使用向量檢索功能，更多用法見向量檢索（Java SDK）。

    import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.MetaQueryMode;

public class OpenMetaQuery {
    public static void main(String[] args) throws com.aliyuncs.exceptions.ClientException {
        // 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 {
            // 開啟向量檢索功能。
            ossClient.openMetaQuery(bucketName, MetaQueryMode.SEMANTIC);
        } 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 {
            // 關閉OSSClient。
            if(ossClient != null){
                ossClient.shutdown();
            }
        }
    }
}

    Python

    更多用法見向量檢索。

    import argparse
import alibabacloud_oss_v2 as oss

# 建立命令列參數解析器，並添加描述資訊
parser = argparse.ArgumentParser(description="open meta query sample")
# 添加必需的命令列參數 --region，用於指定儲存空間所在的地區
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# 添加必需的命令列參數 --bucket，用於指定要操作的儲存空間名稱
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# 添加可選的命令列參數 --endpoint，用於指定訪問OSS時使用的網域名稱
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    # 解析命令列參數
    args = parser.parse_args()

    # 從環境變數中載入認證資訊
    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)

    # 構建一個OpenMetaQuery請求，，用於開啟儲存空間的向量檢索功能
    result = client.open_meta_query(oss.OpenMetaQueryRequest(
            bucket=args.bucket,
            mode='semantic',# 設定為"semantic"，表示選擇向量檢索
    ))

    # 列印請求的結果狀態代碼和請求ID
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          )

# 當作為主程式運行時調用main函數
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
)

// init函數在main函數之前執行，用來初始化程式
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用戶端執行個體

	// 構建一個OpenMetaQuery請求，用於開啟特定儲存空間的向量檢索功能
	request := &oss.OpenMetaQueryRequest{
		Bucket: oss.Ptr(bucketName),
		Mode:   oss.Ptr("semantic"), // 設定為"semantic"，表示開啟向量檢索功能
	}
	result, err := client.OpenMetaQuery(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to open meta query %v", err)
	}

	log.Printf("open 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\OpenMetaQueryRequest($bucket,'semantic');
$result = $client->openMetaQuery($request);

printf(
   'status code:' . $result->statusCode . PHP_EOL .
   'request id:' . $result->requestId
);

    使用ossutil

    以下樣本展示了如何開啟儲存空間examplebucket的向量檢索功能。命令樣本如下：

    ossutil api open-meta-query --bucket examplebucket --meta-query-mode semantic

    關於使用ossutil進行向量檢索的具體操作， 請參見open-meta-query。

    發起向量檢索

    使用OSS控制台

    以查詢內容為“發光的建築”、格式為JPG、圖片寬高在800*1200內的檔案為例進行示範，期望檢索結果為下圖“江邊的夜景.jpg”。

    江邊的夜景

    1. 登入OSS管理主控台。

    2. 單擊Bucket 列表，然後單擊目標Bucket名稱。

    3. 在左側導覽列， 選擇檔案管理 > 資料索引。

    4. 設定檢索條件，其他參數保留預設設定。

      • 在語義內容地區填寫對該圖片的描述，例如：發光的建築。image

      • 多媒體類型選擇圖片。

        • 圖片格式選擇 JPG/JPEG。

        • 圖片寬度設定小於800px。

        • 圖片高度設定小於1200px。

        image

    5. 單擊立即查詢。查詢結果符合預期，按照特徵描述成功查詢到該檔案。

      image

      如需瞭解完整的檢索條件和輸出設定，請參見檢索條件和輸出設定。

    使用阿里雲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\":\"image\"},\"SimpleQuery\":\"{\\\"Operation\\\":\\\"gt\\\", \\\"Field\\\": \\\"Size\\\", \\\"Value\\\": \\\"1\\\"}\"}" --meta-query-mode semantic

    關於該命令的更多資訊，請參見do-meta-query。

    關閉向量檢索

    • 關閉該功能不會影響您 OSS 中已儲存的資料。若後續重新開啟，系統將重新掃描存量檔案並構建索引，需要一定等待時間，具體時間取決於您的檔案數量。

    • 功能關閉後的下一小時會停止計費，但出賬會有一定延遲，請及時關注賬單金額。

    使用OSS控制台

    登入OSS控制台，在資料索引功能頁，單擊中繼資料管理右側關閉，按提示確認關閉即可。

    image

    使用阿里雲SDK

    Java

    僅Java SDK 3.18.2及以上版本支援使用向量檢索功能，更多用法見向量檢索（Java SDK）。

    import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;

public class CloseMetaQuery {
    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 {
            // 關閉儲存空間（Bucket）的向量檢索功能。
            ossClient.closeMetaQuery(bucketName);
        } 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 {
            // 關閉OSSClient。
            if(ossClient != null){
                ossClient.shutdown();
            }
        }
    }
}

    Python

    更多用法見向量檢索。

    import argparse
import alibabacloud_oss_v2 as oss

# 建立一個命令列參數解析器，用於處理命令列參數
parser = argparse.ArgumentParser(description="close meta query 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')

def main():
    # 解析命令列參數
    args = parser.parse_args()

    # 從環境變數中載入憑據資訊
    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)

    # 調用close_meta_query方法關閉儲存空間的檢索功能
    result = client.close_meta_query(oss.CloseMetaQueryRequest(
            bucket=args.bucket,
    ))

    # 列印響應的狀態代碼和請求ID
    print(f'status code: {result.status_code}, request id: {result.request_id}')

# 當此指令碼直接運行時執行main函數
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用戶端執行個體

	// 構建一個CloseMetaQuery請求，用於關閉特定儲存空間的中繼資料管理功能
	request := &oss.CloseMetaQueryRequest{
		Bucket: oss.Ptr(bucketName), // 指定要操作的儲存空間名稱
	}
	result, err := client.CloseMetaQuery(context.TODO(), request) // 執行請求以關閉儲存空間的中繼資料管理功能
	if err != nil {
		log.Fatalf("failed to close meta query %v", err)
	}

	log.Printf("close 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);

// 建立CloseMetaQueryRequest對象，用於關閉Bucket的檢索功能
$request = new \AlibabaCloud\Oss\V2\Models\CloseMetaQueryRequest(
    bucket: $bucket
);

// 執行關閉檢索功能的操作
$result = $client->closeMetaQuery($request);

// 列印關閉檢索功能的結果
printf(
    'status code:' . $result->statusCode . PHP_EOL . // HTTP狀態代碼，例如200表示成功
    'request id:' . $result->requestId . PHP_EOL     // 請求ID，用於調試或追蹤請求
);

    使用ossutil

    以下樣本展示了如何關閉儲存空間examplebucket的中繼資料管理功能。命令樣本如下：

    ossutil api close-meta-query --bucket examplebucket

    關於該命令的更多資訊，請參見close-meta-query。

    檢索條件和輸出設定

    檢索條件設定

    以下是完整的檢索條件，您可以根據需要設定單個或多個檢索條件。

    OSS中繼資料檢索條件

    檢索條件

    說明

    儲存類型

    您可以按需選擇希望在查詢結果中顯示的Object儲存類型。

    • 已選擇語義內容檢索條件：只支援檢索標準儲存、低頻儲存。

    • 未選擇語義內容檢索條件：預設支援檢索標準、低頻訪問、歸檔、冷歸檔和深度冷歸檔多種儲存類型。

    讀寫權限

    預設選中OSS支援的四種讀寫權限ACL，即繼承Bucket、私人、公用讀取以及公用讀寫。您可以按需選擇希望在查詢結果中顯示的Object讀寫權限。

    檔案名稱

    支援模糊比對和等於。如果您希望在查詢結果中顯示某個檔案名稱，例如exampleobject.txt。您可以通過以下兩種方式匹配目標檔案：

    • 選擇等於，然後輸入完整的檔案名稱exampleobject.txt。

    • 選擇模糊比對，然後輸入檔案首碼或者尾碼，例如example或者.txt。

      重要

      模糊比對可命中Object名稱的任一字元，例如輸入test，則查詢結果中將顯示localfolder/test/.example.jpg、localfolder/test.jpg等。

    上傳類型

    預設選中OSS支援的四種Object類型，您可以按需選擇希望在查詢結果中顯示的Object類型。Object類型說明如下：

    • Normal：通過簡單上傳方式產生的Object。

    • Multipart：通過分區上傳方式產生的Object。

    • Appendable：通過追加上傳方式產生的Object。

    • Symlink：為快速存取Object建立的軟連結。

    最後修改時間

    指定Object被最後修改的起始日期和結束日期，時間精確到秒。

    檔案大小

    支援等於、大於、大於等於、小於和小於等於五種篩選條件，檔案大小單位為KB。

    對象版本

    僅支援查詢目前的版本Object。

    對象Etag及標籤檢索條件

    如需根據對象Etag及標籤進行過濾尋找，可輸入您希望在查詢結果中顯示的Object對應的ETag或標籤資訊。

    • ETag僅支援精確匹配。ETag必須帶引號，樣本值為"5B3C1A2E0563E1B002CC607C6689"。可輸入多個ETag，每行一個。

    • 以索引值對（Key-Value）的形式指定對象標籤。對象標籤的Key和Value均區分大小寫。關於標籤規則的更多資訊，請參見對象標籤。

    多媒體中繼資料檢索條件

    您可以通過圖片、文檔、音頻、視頻的特定屬性來過濾得到您期望的結果。

    檢索條件

    說明

    圖片

    • 支援篩選多種圖片格式：JPG/JPEG、PNG、APNG、BMP、GIF、WEBP、TIFF、HEIC、HEIC-SEQUENCE、AVIF

    • 圖片寬高：允許設定寬高範圍，單位px。

    文檔

    • 支援篩選多種文檔格式：DOC、DOCX、PPTX、PPT、XLS、XLSX、PDF、RTF、TXT、LOG、XML、HTML

    視頻

    • 支援篩選多種視頻格式：AVI、 MPEG、 MPG、 RM、 MOV、WMV、 3GP、 MP4、 FLV、 MKV、 TS

    • 視頻解析度：允許設定視頻解析度範圍單位px。

    • 視頻時間長度：允許設定時間長度範圍，單位s。

    • 視頻碼率：允許設定碼率範圍，單位kbps。

    音頻

    • 支援篩選多種音頻格式：MP3、 WMA、 OGG、 RA、 MIDI、 AIF/AIFF、 M4A、MKA、 MP2

    • 音頻時間長度：允許設定時間長度範圍，單位s。

    語義內容檢索條件

    您可以通過輸入內容語義，快速檢索擷取其相關的圖片、文檔、視頻或音頻資源。

    • 自訂搜尋相關內容的檔案，長度限制：40字元。如搜尋“雪中故宮照片”、“無線印表機的使用方式”等。

    • 語義內容檢索使用限制。

      • 不支援設定對象排列和資料彙總輸出方式。

      • 必須勾選一組並且只能勾選一組多媒體中繼資料檢索條件。

      • 不支援尋找使用KMS內建密鑰BYOK加密的Object。

    自訂中繼資料檢索條件

    您可以通過輸入中繼資料的索引值對，利用自訂中繼資料精確檢索結果。

    • 以索引值對（Key-Value）的形式指定對象中繼資料。關於自訂中繼資料的更多資訊，請參見管理檔案中繼資料。

    • 支援添加多選（Key，Value 都必填），最多自訂20個。

    結果輸出設定

    設定“語義內容檢索條件”後，不支援指定排序方式以及資料彙總。

    您可對輸出結果進行排序和簡單統計。

    • 對象排序方式：支援根據最後修改時間、檔案名稱和檔案大小進行升序、降序及預設排序。您可以按需選擇並排序檢索結果，便於快速找到所需檔案。

    • 資料彙總：支援多種輸出類型，您可以對檢索結果進行去重統計、分組計數、最大值、最小值、平均值和求和等計算，便於高效分析和管理資料。

    相關API

    以上操作方式底層基於API實現，如果您的程式自訂要求較高，您可以直接發起REST API請求。直接發起REST API請求需要手動編寫代碼計算簽名。

    關於開啟中繼資料管理功能的更多資訊，請參見OpenMetaQuery。

    關於查詢滿足指定條件的檔案，請參見DoMetaQuery。

    關於關閉中繼資料管理功能的更多資訊，請參見CloseMetaQuery。

    計費說明

    • 向量檢索費用主要來自以下兩個方面：

      • 向量檢索功能計費項目（公測期間免費）

        包括Object的中繼資料管理費用。當前處於公測階段暫不計費，將於 2025 年 8 月 25 日公測結束後正式計費。公測結束後將按OSS資料索引定價標準計費，詳見資料索引費用。

      • API請求費用

        在存量檔案索引構建期間和增量檔案索引更新期間會產生API請求費用，按照API調用次數收費。涉及的API請求如下：

        行為

        API

        為Bucket中的檔案構建索引

        HeadObject和GetObject

        Bucket中檔案存在Tag

        GetObjectTag

        Bucket中檔案攜帶自訂Meta

        GetObjectMeta

        Bucket中存在軟連結檔案

        GetSymlink

        掃描Bucket中的檔案

        ListObjects

        關於OSS API的請求費用，請參見請求費用。

    • 如您希望停止相關計費，請及時關閉向量檢索。

    常見問題

    為什麼檔案上傳後，無法立即檢索到？

    檔案上傳後，對應檔案的索引產生需要一定時間，所以查詢結果會有一定程度的延遲，可能無法立即得到查詢結果，等待片刻後重試即可。