Object Storage Service:Vector bucket quick start

Step 1: Create a vector bucket

Create a vector bucket to serve as a container for all your vector data and indexes.

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

2. Configure the bucket information:

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

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

3. Click OK.

Step 2: Create a vector index

After creating the bucket, create a vector index within it. An index defines the structure of your vectors, such as their dimension and the retrieval method, and provides 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: 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: Set the number of dimensions for your 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 metric based on your use case.

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

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

4. Click OK.

Step 3: Upload vector data

Once the index is ready, upload your vector data to the specified vector index 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 Insert Vector Data.

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

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

   • Vector Data: Enter the vector as an array of comma-separated numbers. The vector's dimension (the number of values) must match the Vector Dimension you set in Step 2.

   • Metadata: You can add metadata, such as a category, title, or timestamp. This information can be used to filter queries.

4. Click OK.

Step 4: Perform vector retrieval

After preparing the data, you can perform vector retrieval, the core step of the process. Typically, you use an SDK in your application to perform vector retrieval and quickly locate your target data.

The following Python SDK example shows how to retrieve the top 10 data entries that are most similar to a query 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()

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

    # Filter: exclude comedy and documentary vectors
    query_filter = {
        "$and": [{
            "type": {
                "$nin": ["comedy", "documentary"]
            }
        }]
    }

    # Query vector: 128-dimensional float32 vector
    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 manage the entire vector bucket workflow using the console, an OSS SDK, ossutil, or direct API calls. This guide demonstrates a basic workflow. For complete configurations and advanced usage, see the following topics:

• Vector Buckets

• Vector Indexes

• Vectors

• Access Control and Logs