Object Storage Service:Get started with vector buckets

Step 1: Create a vector bucket

Create a vector bucket. This bucket acts as a container for all your vector data and indexes.

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

2. Configure the bucket information:

   • Vector Bucket Name: Enter a globally unique name for the bucket within the same Alibaba Cloud account and region. The name must be 3 to 32 characters long, contain only lowercase letters, digits, and hyphens (-), and cannot start or end with a hyphen.

   • Region: Select the region where you want to create the bucket, such as China (Shenzhen).

3. Click OK.

Step 2: Create a vector index

After you create the bucket, create a vector index in it. The index defines the vector structure, such as dimensions, and the retrieval method, such as the distance measure. It is the foundation for storing and querying vector data.

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

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

3. Configure the index parameters:

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

   • Vector data type: The default is float32 (32-bit floating-point).

   • Vector Dimensions: Set the vector dimension. For example, 128. The value must be an integer from 1 to 4096. All vectors uploaded to this index must have this dimension.

   • Distance Measure Function: Select a distance calculation method based on your business scenario.

     • Euclidean Distance: The straight-line distance between two points in space. This is suitable for measuring numerical differences.

     • Cosine Distance: Measures the difference in direction between two vectors. This is suitable for calculating high-dimensional semantic similarity for text and images.

4. Click OK.

Step 3: Upload vector data

When the index is ready, upload your vector data to it. This makes the data available for searches.

1. In the index list, find the newly created index and click View Data on the right.

2. On the index page, click Insert Vector Data.

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

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

   • Vector Data: Enter an array of vector values as comma-separated numbers. The number of values must match the Vector Dimensions that you set in Step 2.

   • Metadata: You can add metadata, such as category, title, or timestamp. This data can be used as filter conditions in searches.

4. Click OK to insert the data.

Step 4: Perform a vector search

After you upload the data, you can perform a vector search. This is the core operation of the service. Typically, you use a software development kit (SDK) in your application to call the API. This lets you perform vector searches and quickly retrieve the data you need.

The following Python SDK example shows how to retrieve the top 10 data entries most similar to a target vector, 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 perform all Vector Bucket operations using the console, the OSS SDK, ossutil, or by making direct API calls. This quick start shows only 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