Object Storage Service:OSS Vectors quick start

Step 1: Create a vector bucket

Create a vector bucket to contain 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: Enter a name for the bucket that is unique to your Alibaba Cloud account within a region. The name must be 3 to 32 characters in length and can contain only lowercase letters, digits, and hyphens (-). It cannot start or end with a hyphen.

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

3. Click OK to create the bucket.

Step 2: Create a vector index

After creating the bucket, create a vector index within it. The index defines the structure of your vectors, such as their dimension, and the retrieval method, such as the distance metric. It is the foundation for storing and querying 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: Enter a name for the index that is unique within the bucket. The name must be 1 to 63 characters in length, consist of letters and digits, and start with a letter.

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

   • Vector Dimension: Set the dimension of the vectors, for example, 128. The value must be an integer from 1 to 4,096. All vectors that you upload to this index must have the same dimension.

   • Distance Metric Function: Select a distance calculation method based on your use case.

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

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

4. Click OK to create the index.

Step 3: Upload vector data

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

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 Data Insertion.

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

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

   • Vector Data: Enter the vector values as a comma-separated list of numbers. The dimension of the vector (the number of values) must exactly match the Vector Dimension set in Step 2.

   • Metadata: You can add optional metadata, such as categories, titles, or timestamps. Metadata enables precise filtering during retrieval.

4. Click OK to insert the data.

Step 4: Perform vector retrieval

After you prepare the data, you can perform vector retrieval, which is the core part of the workflow. Typically, you call the API from your application by using an SDK to perform vector retrieval and quickly locate the target data.

The following Python SDK example shows how to retrieve the top 10 data entries that are most similar to a target vector and whose 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
    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

You can perform all operations on vector buckets by using the console, the OSS SDK, ossutil, or direct API calls. This quick start shows the fastest way to get started. For details on advanced configurations and usage, see the following topics:

• Vector buckets

• Vector indexes

• Vectors

• Access control and log monitoring