Quick start for vector buckets

Step 1: Create a vector bucket

A vector bucket stores your vector data and indexes.

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

2. Configure the bucket:

   • Vector Bucket Name: A region-unique name, 3–32 characters long. Use only lowercase letters, digits, and hyphens (-). Cannot start or end with a hyphen.

   • Region: Select the region for your bucket, for example, China (Shenzhen).

3. Click OK.

Step 2: Create a vector index

A vector index defines the vector structure (dimension) and retrieval method (distance metric) for storing and querying vectors.

1. On the Vector Buckets page, click the name of your vector bucket.

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

3. Configure the index:

   • Index Table Name: A bucket-unique name, 1–63 characters. Use only letters and digits, starting with a letter.

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

   • Vector dimension: An integer from 1 to 4096, for example 128. All vectors uploaded to this index must share the same dimension.

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

     • Euclidean distance: Straight-line distance between two points. Best for measuring numerical differences.

     • Cosine distance: Measures directional difference between vectors. Best for semantic similarity in high-dimensional data (text, images).

4. Click OK.

Step 3: Upload vector data

Once the index is ready, upload your vector data to it.

1. In the index list, find the index you created 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 entries at once):

   • Primary key value: Set a unique identifier for the vector.

   • Vector data: A comma-separated array of numbers. The number of values must match the Vector dimension configured in Step 2.

   • Metadata: Optional key-value pairs (categories, titles, timestamps) used for filtering during retrieval.

4. Click OK.

Step 4: Perform vector retrieval

Use the OSS SDK to query your index and retrieve the most similar vectors.

The following example uses the Python SDK to retrieve the top 10 vectors most similar to a target vector, excluding entries where type is “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
    cfg.use_internal_endpoint = True  # To access the service over the public network, set this to False or remove this line.
    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()

Next steps

Manage vector buckets through the console, OSS SDK, ossutil, or API. For complete configurations and advanced usage:

• Vector Buckets

• Vector Indexes

• Vectors

• Access Control and Logs