Object Storage Service:Quick start for vector buckets

Step 1: Create a vector bucket

First, create a vector bucket. This bucket stores all your vector data and indexes.

1. On the Vector Buckets page, click Create a Vector Bucket.

2. Configure the bucket information:

   • Vector Bucket Name: Specify a globally unique name for the bucket. The name must be 3 to 32 characters long, contain only lowercase letters, numbers, and hyphens (-), and must not start or end with a hyphen.

   • Region: Select the region for the bucket, such as China (Shenzhen).

3. Click OK.

Step 2: Create a vector index

After you create the bucket, create a vector index within it. The index defines the vector structure, such as its dimensions, and the retrieval method, such as the distance measure. This index is used to store and query vector data.

1. On the Vector Buckets page, click the name of the vector bucket that you created.

2. On the Vector Indexes page, click Create Index Table.

3. Configure the index parameters:

   • Index Table Name: Specify a unique name for the index within the bucket. The name must be 1 to 63 characters long, consist of letters and numbers, and start with a letter.

   • Vector Data Type: The default is float32 (32-bit floating-point).

   • Vector dimension: Specify the number of vector dimensions, such as 128. The value must be an integer from 1 to 4096. All vectors uploaded to this index must have the same number of dimensions.

   • Distance metric function: Select a distance calculation method based on your requirements.

     • European distance: The straight-line distance between two points in 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, images, and more.

4. Click OK.

Step 3: Upload vector data

After the index is created, upload your vector data to make it available for retrieval.

1. In the index list, find the index that you just created and click View data on the right.

2. On the index page, click Vector datainsertion .

3. Configure the vector data. You can add multiple entries at once:

   • Primary Key Value: Set a unique identifier for the vector.

   • Vector data: Enter the vector data as a comma-separated array of numbers. The number of dimensions, which is the count of numbers in the array, must match the Vector Dimensions value that you set in Step 2.

   • Metadata: Add metadata, such as a category, title, or timestamp. You can use this information as a filter condition during retrieval.

4. Click Confirm to insert the data.

Step 4: Perform vector retrieval

After you upload the data, you can perform vector retrieval. Typically, you call the API from your application using an SDK to retrieve vectors and find your target data.

The following Python SDK example shows how to retrieve the top 10 data entries that are most similar to the target vector and where the type field is not "comedy" or "documentary".

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

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

    query_filter = {
        "$and": [{
            "type": {
                "$nin": ["comedy", "documentary"]
            }
        }]
    }

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

What to do next

You can manage Vector Buckets using the console, the OSS SDK, ossutil, or direct API calls. This Quick Start guide shows the fastest way to get started. For more information about complete configurations and advanced usage, see the following documents:

• Vector Buckets

• Vector Indexes

• Vectors

• Access control and logs