ベクターインデックス - Object Storage Service - Alibaba Cloud ドキュメントセンター

ベクターインデックスは、ベクターバケット内にベクトルデータを格納・管理します。各インデックスはベクトルのディメンション、距離メトリック、メタデータ構造を定義し、ベクトル取得の基盤を提供します。

ベクターインデックスの作成

PutVectorIndex API オペレーションのリクエストレートは、1 秒あたり 5 リクエストに制限されています。

コンソール

Vector Buckets ページで、対象のベクターバケットをクリックします。
Index List ページで、Create Index Table をクリックします。
インデックスパラメーターを構成します。
- Index Table Name：1～63 文字。バケット内で一意である必要があります。先頭は英字で、英数字のみを使用できます。
- Vector Data Type：デフォルトは float32（浮動小数点）です。
- Vector Dimension：1 から 4,096 の整数。このインデックスに追加されるすべてのベクトルは、このディメンションと一致している必要があります。
- Distance Metric：ユースケースに基づいて距離メトリックを選択します。
  - Euclidean Distance：空間内の 2 点間の直線距離。数値的な差異の測定に適しています。
  - Cosine Distance：2 つのベクトルの方向の違いを測定します。テキストや画像などの高次元におけるセマンティック類似度計算に適しています。
- Metadata Configuration：ベクトルに関連付ける記述情報を格納するためのフィルター不可なメタデータフィールドを構成します。これらのフィールドは検索フィルターには使用できません。以下の制限が適用されます。
  - メタデータフィールド数：1～10
  - 各メタデータキーの長さ：1～63 バイト
OK をクリックしてインデックスを作成します。

ossutil

SDK

Python

import argparse
import alibabacloud_oss_v2 as oss
import alibabacloud_oss_v2.vectors as oss_vectors

parser = argparse.ArgumentParser(description="vector put vector index 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')
parser.add_argument('--index_name', help='The name of the vector index.', required=True)
parser.add_argument('--account_id', help='The account id.', required=True)

def main():
    args = parser.parse_args()

    # Load credentials from environment variables
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the SDK's default configuration
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    cfg.account_id = args.account_id
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    vector_client = oss_vectors.Client(cfg)

    result = vector_client.put_vector_index(oss_vectors.models.PutVectorIndexRequest(
        bucket=args.bucket,
        index_name=args.index_name,
        dimension=512,          # Set to match your embedding model's output dimension
        data_type='float32',
        distance_metric='euclidean',
        metadata={"nonFilterableMetadataKeys": ["key1", "key2"]}
    ))

    print(f'status code: {result.status_code},'
          f' request ID: {result.request_id},'
    )

if __name__ == "__main__":
    main()

Go

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"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/vectors"
)

var (
	region     string
	bucketName string
	accountId  string
	indexName  string
)

func init() {
	flag.StringVar(&region, "region", "", "The region where the vector bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the vector bucket.")
	flag.StringVar(&accountId, "account-id", "", "The ID of the vector account.")
	flag.StringVar(&indexName, "index", "", "The name of the vector index.")
}

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")
	}

	if len(accountId) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, accountId required")
	}

	if len(indexName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, index required")
	}

	// Load credentials from environment variables and configure the client.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).WithAccountId(accountId)

	client := vectors.NewVectorsClient(cfg)

	request := &vectors.PutVectorIndexRequest{
		Bucket:         oss.Ptr(bucketName),
		DataType:       oss.Ptr("float32"),
		Dimension:      oss.Ptr(128),
		DistanceMetric: oss.Ptr("cosine"),
		IndexName:      oss.Ptr(indexName),
		Metadata: map[string]any{
			// nonFilterableMetadataKeys: metadata keys stored with the index but not used for filtering.
			"nonFilterableMetadataKeys": []string{"foo", "bar"},
		},
	}
	result, err := client.PutVectorIndex(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to put vector index %v", err)
	}
	log.Printf("put vector index result: %#v\n", result)
}

API

PutVectorIndex オペレーションを呼び出して、ベクターインデックスを作成します。

ベクターインデックスの取得

コンソール

Vector Buckets ページで、対象のベクターバケットをクリックします。Index List ページにベクターインデックス情報が表示されます。

ossutil

SDK

Python

import argparse
import alibabacloud_oss_v2 as oss
import alibabacloud_oss_v2.vectors as oss_vectors

parser = argparse.ArgumentParser(description="vector get vector index 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')
parser.add_argument('--index_name', help='The name of the vector index.', required=True)
parser.add_argument('--account_id', help='The account id.', required=True)

def main():
    args = parser.parse_args()

    # Load credentials from environment variables
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the SDK's default configuration
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    cfg.account_id = args.account_id
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    vector_client = oss_vectors.Client(cfg)

    result = vector_client.get_vector_index(oss_vectors.models.GetVectorIndexRequest(
        bucket=args.bucket,
        index_name=args.index_name,
    ))

    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          )

    if result.index:
        print(f'index name: {result.index}')

if __name__ == "__main__":
    main()

Go

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"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/vectors"
)

var (
	region     string
	bucketName string
	indexName  string
	accountId  string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the vector bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the vector bucket.")
	flag.StringVar(&indexName, "index", "", "The name of the vector index.")
	flag.StringVar(&accountId, "account-id", "", "The ID of the vector account.")
}

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")
	}

	if len(indexName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, index required")
	}

	if len(accountId) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, accountId required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).WithAccountId(accountId)

	client := vectors.NewVectorsClient(cfg)

	request := &vectors.GetVectorIndexRequest{
		Bucket:    oss.Ptr(bucketName),
		IndexName: oss.Ptr(indexName),
	}
	result, err := client.GetVectorIndex(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to get vector index %v", err)
	}
	log.Printf("get vector index result:%#v\n", result)
}

API

GetVectorIndex オペレーションを呼び出して、ベクターインデックスの情報を取得します。

ベクターインデックスの一覧表示

ListVectorIndexes API オペレーションは、1 回の呼び出しにつき最大 500 個のインデックスを返します。後続ページを取得するには、ページネーションを使用してください。このオペレーションの同時実行数は 16 に制限されています。

コンソール

Vector Buckets ページでベクターバケットをクリックすると、そのバケット内のすべてのインデックスが表示される Index List ページが開きます。

ossutil

SDK

Python

import argparse
import alibabacloud_oss_v2 as oss
import alibabacloud_oss_v2.vectors as oss_vectors

parser = argparse.ArgumentParser(description="list vector indexes sample")

parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--account_id', help='The account id.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)

def main():

    args = parser.parse_args()

    # Loading credentials values from the environment variables
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Using the SDK's default configuration
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    cfg.account_id = args.account_id
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss_vectors.Client(cfg)

    # Create the Paginator for the ListVectorIndex operation
    paginator = client.list_vector_indexes_paginator()

    # Iterate through the vector index pages
    for page in paginator.iter_page(oss_vectors.models.ListVectorIndexesRequest(
        bucket=args.bucket
        )
    ):
        for o in page.indexes:
            print(f'Index: {o.get("indexName")}, {o.get("dataType")}, {o.get("dimension")}, {o.get("status")}')

if __name__ == "__main__":
    main()

Go

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"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/vectors"
)

var (
	region     string
	bucketName string
	accountId  string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the vector bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the vector bucket.")
	flag.StringVar(&accountId, "account-id", "", "The ID of the vector account.")
}

func main() {
	flag.Parse()
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket required")
	}

	if len(accountId) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, accountId required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).WithAccountId(accountId)

	client := vectors.NewVectorsClient(cfg)

	request := &vectors.ListVectorIndexesRequest{
		Bucket: oss.Ptr(bucketName),
	}
	p := client.NewListVectorIndexesPaginator(request)

	var i int
	log.Println("Vector Indexes:")
	for p.HasNext() {
		i++

		page, err := p.NextPage(context.TODO())
		if err != nil {
			log.Fatalf("failed to get page %v, %v", i, err)
		}

		for _, index := range page.Indexes {
			log.Printf("index:%v, %v, %v, %v\n", oss.ToString(index.IndexName), oss.ToTime(index.CreateTime), oss.ToString(index.DataType), oss.ToString(index.Status))
		}
	}
}

API

ListVectorIndexes オペレーションを呼び出して、ベクターバケット内のすべてのベクターインデックスを一覧表示します。

ベクターインデックスの削除

インデックスを削除すると、その中に含まれるすべてのベクトルデータも削除されます。この操作は取り消せません。慎重に実行し、重要なデータは事前にバックアップしてください。

コンソール

Vector Buckets ページでベクターバケットをクリックすると、Index List ページが開きます。削除するインデックスを選択し、削除を確定します。

ossutil

SDK

Python

import argparse
import alibabacloud_oss_v2 as oss
import alibabacloud_oss_v2.vectors as oss_vectors

parser = argparse.ArgumentParser(description="vector delete vector index 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')
parser.add_argument('--index_name', help='The name of the vector index.', required=True)
parser.add_argument('--account_id', help='The account id.', required=True)

def main():
    args = parser.parse_args()

    # Loading credentials values from the environment variables
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Using the SDK's default configuration
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    cfg.account_id = args.account_id
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    vector_client = oss_vectors.Client(cfg)

    result = vector_client.delete_vector_index(oss_vectors.models.DeleteVectorIndexRequest(
        bucket=args.bucket,
        index_name=args.index_name,
    ))

    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
    )

if __name__ == "__main__":
    main()

Go

package main

import (
	"context"
	"log"

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

func main() {
	// Load credentials from environment variables:
	// OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("<region>").
		WithAccountId("<account-id>")

	client := vectors.NewVectorsClient(cfg)

	request := &vectors.DeleteVectorIndexRequest{
		Bucket:    oss.Ptr("<bucket-name>"),
		IndexName: oss.Ptr("<index-name>"),
	}

	result, err := client.DeleteVectorIndex(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to delete vector index: %v", err)
	}

	log.Printf("delete vector index result: %#v\n", result)
}

API

DeleteVectorIndex オペレーションを呼び出して、ベクターインデックスを削除します。