Object Storage Service:Vector index

Console

1. On the Vector Buckets page, click the target vector bucket.

2. On the Index List page, click Create Index Table.

3. Configure the index parameters:

   • Index Table Name: 1–63 characters. The name must be unique within the vector bucket, start with a letter, and contain only letters and digits.

   • Vector Data Type: Defaults to float32 (floating-point).

   • Vector Dimension: An integer from 1 to 4,096. All vectors added to this index must have this exact number of values.

   • Distance Metric: Select a distance metric based on your use case.

     • Euclidean Distance: The straight-line distance between two points in a space. Suitable for measuring numerical differences.

     • Cosine Distance: Measures the difference in direction between two vectors. Suitable for high-dimensional semantic similarity calculations for text and images.

   • Metadata Configuration: Configure non-filterable metadata fields to store descriptive information for vectors. You cannot use these fields in search filters. The following limits apply:

     • Number of metadata fields: 1 to 10

     • Length of each metadata key: 1 to 63 bytes

4. Click OK to create the index.

ossutil

ossutil vectors-api put-vector-index --bucket examplebucket --index-name index --data-type float32 --dimension 512 --distance-metric euclidean

SDK

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

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

Call the PutVectorIndex operation to create a vector index.

Console

On the Vector Buckets page, click the target vector bucket. The Index List page displays the vector index information.

ossutil

ossutil vectors-api get-vector-index --bucket examplebucket --index-name index

SDK

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

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 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, accounId 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

Call the GetVectorIndex operation to retrieve information about a vector index.

Console

On the Vector Buckets page, click a vector bucket to open the Index List page, which lists all indexes in the bucket.

ossutil

ossutil vectors-api list-vector-indexes --bucket examplebucket

SDK

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

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

Call the ListVectorIndexes operation to list all vector indexes in a vector bucket.

Console

On the Vector Buckets page, click a vector bucket to open the Index List page. Select the index to delete and confirm the deletion.

ossutil

ossutil vectors-api delete-vector-index --bucket examplebucket --index-name index

SDK

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

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

Call the DeleteVectorIndex operation to delete a vector index.