ベクトルデータでのデータ管理操作の実行 - OSS

ベクターはベクターバケットにおけるコアリソースであり、以下の 3 つの部分で構成されます。

キー：ベクターの一意の識別子です。
データ：高次元の数値配列です。
メタデータ：カテゴリ、ソース、タイムスタンプなど、ベクターの追加属性を格納するキーと値の構造です。クエリのポストフィルタリングにメタデータを使用できます。

各ベクターは特定のベクターインデックスに格納され、そのインデックスに設定されたディメンション、データ型、距離メジャーを継承します。

ベクターデータの書き込み

指定されたベクターインデックスにベクターデータを書き込みます。

PutVectors API は、バッチあたり最大 500 ベクターをサポートし、最大 QPS (リクエスト/秒) は 5 です。

コンソール

ベクターバケットページで、対象のベクターバケットをクリックします。
インデックスの行で [データを表示] をクリックし、次に [ベクターデータの挿入] をクリックします。
ベクターデータを設定します。一度に複数のベクターを追加できます：
- キー：ベクターの一意の識別子を設定します。
- ベクターデータ：ベクターの数値配列を、0.1, 0.2, 0.3, 0.4, 0.5 のようにコンマ区切りの数値リストとして入力します。ベクターのディメンションは、インデックスに設定されたディメンションと一致する必要があります。
- メタデータ：カテゴリ、タイトル、タイムスタンプなど、ベクターのメタデータを追加します。合計サイズは 40 KB を超えることはできません。
  - メタデータでサポートされているデータ型は文字列のみです。
  - 1 つのベクターで、フィルタリング可能なメタデータフィールドとフィルタリング不可のメタデータフィールドを合わせて最大 10 個までサポートされます。
  - フィルタリング不可のメタデータのキーの長さは 1～63 文字です。
  - フィルタリング可能なメタデータフィールド 1 つのサイズは最大 2 KB です。
  - フィルタリング可能なメタデータに対する各ポストフィルタリング命令は、最大 64 KB のフィルタリング可能なメタデータ、最大 1,024 個のフィルタリング可能なメタデータフィールド、および最大 8 階層のネストをサポートします。フィルターコンテンツが空でもかまいません。
[OK] をクリックしてデータを追加します。

SDK

Python

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

parser = argparse.ArgumentParser(description="vector put vectors 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()

    # 環境変数から認証情報をロードします
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # クライアント設定をビルドします
    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)

    # アップロードするベクターレコードを定義します。
    # 各レコードには、一意のキー、float32 のベクターデータ、およびオプションのメタデータが必要です。
    vectors = [
        {
            "key": "key1",                                                          # 一意のレコード識別子
            "data": {"float32": [0.1] * 128},                                       # 128 次元の float32 ベクター
            "metadata": {"metadata1": "value1", "metadata2": "value2"}             # オプションのキーと値のメタデータ
        },
        {
            "key": "key2",
            "data": {"float32": [0.2] * 128},
            "metadata": {"metadata3": "value3", "metadata4": "value4"}
        }
    ]

    # 1 回の呼び出しですべてのレコードをアップロードします
    result = vector_client.put_vectors(oss_vectors.models.PutVectorsRequest(
        bucket=args.bucket,
        index_name=args.index_name,
        vectors=vectors,
    ))

    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
)

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 Alibaba Cloud account.")
}

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

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

	client := vectors.NewVectorsClient(cfg)

	request := &vectors.PutVectorsRequest{
		Bucket:    oss.Ptr(bucketName),
		IndexName: oss.Ptr("exampleIndex"),

		Vectors: []map[string]any{
			{
				"key": "vector1",
				"data": map[string]any{
					"float32": []float32{1.2, 2.5, 3},
				},
				"metadata": map[string]any{
					"Key1": "value2",
					"Key2": []string{"1", "2", "3"},
				},
			},
		},
	}

	result, err := client.PutVectors(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to put vectors %v", err)
	}
	log.Printf("put vectors result:%#v\n", result)
}

ossutil

API

PutVectors 操作を呼び出してベクターデータを書き込みます。

ベクター検索

セマンティックコンテンツとメタデータでベクターインデックスを検索し、一致するベクターを迅速に見つけます。このサービスは、約 90% の取得率で、サブ秒レベルの検索パフォーマンスを提供します。

コンソール

コンソールは、単一ベクターの類似性検索のみをサポートします。バッチ検索または反復検索を実行するには、API または SDK を使用してください。

ベクターバケットページで、対象のベクターバケットをクリックします。
インデックスの行で [データを表示] をクリックし、次に [ベクターデータクエリ] をクリックします。
検索パラメーターを設定します：
- ベクターデータ：挿入時と同じコンマ区切りのフォーマットでクエリベクターデータを入力します。例：0.15, 0.25, 0.35, 0.45, 0.55
- フィルタリング可能なメタデータ：カテゴリや時間範囲などのメタデータに基づいて結果をフィルターします。
- top-k (結果数)：返す最も類似した結果の数を設定します。値の範囲は 1～100 です。
- 類似性距離を返す：類似性距離を返すかどうかを選択します。
- メタデータを返す：ベクターのメタデータを返すかどうかを選択します。
[OK] をクリックしてクエリを実行します。

応答は、類似度順にソートされたベクターのリストです。

SDK

Python

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

parser = argparse.ArgumentParser(description="vector query vectors 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()

    # 環境変数から認証情報をロードします
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト設定を使用します
    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)

    # フィルター：コメディとドキュメンタリーのベクターを除外します
    query_filter = {
        "$and": [{
            "type": {
                "$nin": ["comedy", "documentary"]
            }
        }]
    }

    # クエリベクター：128 次元の float32 ベクター
    query_vector = {"float32": [0.1] * 128}

    result = vector_client.query_vectors(oss_vectors.models.QueryVectorsRequest(
        bucket=args.bucket,
        index_name=args.index_name,
        filter=query_filter,
        query_vector=query_vector,
        return_distance=True,
        return_metadata=True,
        top_k=10,
    ))

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

    if result.vectors:
        for vector in result.vectors:
            print(f'vector: {vector}')


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

	// 環境変数から認証情報をロードします
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).WithAccountId(accountId)

	client := vectors.NewVectorsClient(cfg)

	request := &vectors.QueryVectorsRequest{
		Bucket:    oss.Ptr(bucketName),
		IndexName: oss.Ptr(indexName),
		// $and + $in を使用したフィルター：「type」が「comedy」または「documentary」であるベクターに一致させます
		Filter: map[string]any{
			"$and": []map[string]any{
				{
					"type": map[string]any{
						"$in": []string{"comedy", "documentary"},
					},
				},
			},
		},
		QueryVector: map[string]any{
			"float32": []float32{float32(32)},
		},
		ReturnMetadata: oss.Ptr(true),
		ReturnDistance: oss.Ptr(true),
		TopK:           oss.Ptr(10),
	}

	result, err := client.QueryVectors(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to query vectors %v", err)
	}
	log.Printf("query vectors result:%#v\n", result)
}

ossutil

この例では、クエリベクターに最も類似する上位 10 個のベクターを検索します。検索は、「examplebucket」ベクターバケット内の「index」ベクターインデックスを対象とし、「comedy」および「documentary」タイプのベクターをフィルターします。

ossutil vectors-api query-vectors --bucket examplebucket --index-name index --filter "{\"$and\":[{\"type\":{\"$in\":[\"comedy\",\"documentary\"]}}]}" --query-vector "{\"float32\":[32]}" --top-k 10

API

QueryVectors 操作を呼び出して、ベクター類似性検索を実行します。

ベクターデータの取得

コンソール

ベクターバケットページで、対象のベクターバケットをクリックして [インデックスリスト] ページを開きます。インデックス名をクリックしてベクターデータページに移動し、ベクター情報を表示します。

SDK

Python

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

parser = argparse.ArgumentParser(description="vector get vectors 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()

    # 環境変数から認証情報をロードします
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト設定を使用します
    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)

    keys = ['key1', 'key2']

    result = vector_client.get_vectors(oss_vectors.models.GetVectorsRequest(
        bucket=args.bucket,
        index_name=args.index_name,
        keys=keys,
        return_data=True,
        return_metadata=True
    ))

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

    if result.vectors:
        for vector in result.vectors:
            print(f'vector id: {vector}')


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

	// 環境変数から認証情報をロードします
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).WithAccountId(accountId)

	client := vectors.NewVectorsClient(cfg)

	request := &vectors.GetVectorsRequest{
		Bucket:         oss.Ptr(bucketName),
		IndexName:      oss.Ptr("index"),
		Keys:           []string{"key1", "key2", "key3"},
		ReturnData:     oss.Ptr(true),    // false に設定すると、ベクター値をスキップして応答サイズを削減します
		ReturnMetadata: oss.Ptr(false),   // true に設定すると、応答にメタデータが含まれます
	}
	result, err := client.GetVectors(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to get vectors %v", err)
	}
	log.Printf("get vectors result:%#v\n", result)
}

ossutil

API

GetVectors 操作を呼び出して、指定されたベクターデータを取得します。

ベクターデータのリスト表示

コンソール

ベクターバケットページで、対象のベクターバケットをクリックして [インデックスリスト] ページを開きます。インデックス名をクリックして、そのベクターを表示します。

SDK

Python

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

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

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
    cfg.account_id = args.account_id
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss_vectors.Client(cfg)

    # ページネーターを作成します — SDK は継続トークンを自動的に処理します
    paginator = client.list_vectors_paginator()

    request = oss_vectors.models.ListVectorsRequest(
        bucket=args.bucket,
        index_name=args.index_name
    )

    # すべてのページを反復処理します。ベクターがなくなるとループは終了します
    for page in paginator.iter_page(request):
        for vector in page.vectors:
            print(f'Vector: {vector}')

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 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 vector account.")
	flag.StringVar(&indexName, "index", "", "The name of vector index.")
}

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

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

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

	// 環境変数から認証情報をロードします。
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).WithAccountId(accountId)

	client := vectors.NewVectorsClient(cfg)

	// ReturnMetadata: true — 各ページにベクターメタデータを含めます。
	// ReturnData: false — 生のベクターデータを省略して応答サイズを削減します。
	request := &vectors.ListVectorsRequest{
		Bucket:         oss.Ptr(bucketName),
		IndexName:      oss.Ptr(indexName),
		ReturnMetadata: oss.Ptr(true),
		ReturnData:     oss.Ptr(false),
	}

	// ページネーターを作成します。NextPage() を呼び出すたびに、1 ページ分の結果がフェッチされます。
	p := client.NewListVectorsPaginator(request)

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

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

		// page.Vectors には、このページで返されたベクターが含まれます。
		for _, v := range page.Vectors {
			log.Printf("vector:%v\n", v)
		}
	}
}

ossutil

API

ListVectors 操作を呼び出して、ベクターインデックス内のすべてのベクターデータをリスト表示します。

ベクターデータの削除

ベクターデータをバッチで削除できます。この操作は元に戻せません。続行する前に、すべての重要なデータをバックアップしてください。

コンソール

ベクターバケットページで、対象のベクターバケットをクリックして [インデックスリスト] ページを開きます。インデックス名をクリックしてベクターデータページに移動し、削除したいベクターを選択して削除します。

SDK

Python

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

parser = argparse.ArgumentParser(description="vector delete vectors 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()

    # 環境変数から認証情報をロードします
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト設定を使用します
    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)

    keys = ['key1', 'key2', 'key3']

    result = vector_client.delete_vectors(oss_vectors.models.DeleteVectorsRequest(
        bucket=args.bucket,
        index_name=args.index_name,
        keys=keys,
    ))

    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
)

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 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(accountId) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, accountId required")
	}

	// 設定を作成し、認証情報プロバイダー、リージョン、アカウント ID を設定します。
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).
		WithAccountId(accountId)

	// ベクターストアクライアントを作成します。
	client := vectors.NewVectorsClient(cfg)

	// ベクターデータを削除するリクエストを構築します。
	request := &vectors.DeleteVectorsRequest{
		Bucket:    oss.Ptr(bucketName),
		IndexName: oss.Ptr("index"),
		Keys: []string{
			"key1", "key2", // 削除するベクターキーのリスト。
		},
	}

	// ベクターデータを削除する操作を実行します。
	result, err := client.DeleteVectors(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to delete vectors %v", err)
	}

	// 操作結果を出力します。
	log.Printf("delete vectors result:%#v\n", result)
}

ossutil

「examplebucket」という名前のベクターバケット内の「index」という名前のインデックスから、プライマリキーが `key` と `key1` のベクターを削除します。

ossutil vectors-api delete-vectors --bucket examplebucket --index-name index --keys key,key1

API

DeleteVectors 操作を呼び出してベクターデータを削除します。