Docs

Torch Object Storage

Vector

QueryVectors（TOS Vectors Python SDK）

The query_vectors interface retrieves vectors. This article explains how to perform vector retrieval and return similar results using the query_vectors interface of the TOS Vectors Python SDK.

Notes

You need to fill in the region and access domain in the sample code according to your actual situation. For details, see Region and Access Domain (Endpoint).

To prevent key leakage, the sample code reads the Access Key ID and Secret Access Key from environment variables. Therefore, before using the SDK, you need to configure long-term access credentials. For details, see Configure Long-Term Access Credentials.

The TOS Vectors Python SDK supports using temporary access credentials. It also supports configuring timeout mechanisms, retry policies, and other settings. You can flexibly configure these based on business needs to enhance application security. For details, see Common Configuration Scenarios.

TOS Vectors supports float32 precision for vectors. Passing vectors with higher precision may result in precision loss.

Permissions required

The main account has all permissions by default, but IAM users have no permissions by default. If you need to use a sub-account to perform the query_vectors operation, the main account must grant the following permissions to the sub-account through IAM policy and bucket policy:

tosvectors:QueryVectors

Code example

Query the top K nearest vectors

# Query the nearest TopK vectors.​
import os​
import random​
import tos​
from tos.models2 import VectorData​
​
# Retrieve AK and SK information from environment variables.​
ak = os.getenv('TOS_ACCESS_KEY')​
sk = os.getenv('TOS_SECRET_KEY')​
# Fill in your endpoint and your region with the endpoint corresponding to the bucket's region. # For example, for China (Beijing), set your endpoint to https://tosvectors-cn-beijing.volces.com and your region to cn-beijing.​
endpoint = 'Provide your endpoint'​
region = 'Provide your region'​
account_id = os.getenv('TOS_ACCOUNT_ID')​
vector_bucket_name = 'Provide your bucket name'​
index_name = "testindex"​
​
try:​
    # Create a VectorClient object; all vector operations are handled through VectorClient.​
    client = tos.VectorClient(ak, sk, endpoint, region)​
    ​
    # Create query vector data, a floating-point vector with a dimension of 128.​
    query_vector = VectorData(float32=[float(random.random()) for _ in range(128)])​
    ​
    # Perform vector search and return the 5 most similar vectors.​
    result = client.query_vectors(​
        vector_bucket_name=vector_bucket_name,​
        account_id=account_id,​
        index_name=index_name,​
        query_vector=query_vector,​
        top_k=5,  # Return the 5 most similar vectors​
        return_distance=True,  # Return vector distance​
        return_metadata=True   # Return vector metadata​
    )​
    ​
    # Print request information.​
    print('Request ID: {}'.format(result.request_id))​
    print('Status Code: {}'.format(result.status_code))​
    print('Found {} similar vectors'.format(len(result.vectors)))​
    ​
    # Print search results.​
    for i, vector in enumerate(result.vectors):​
        print('\nTop {}:'.format(i + 1))​
        print('  Key: {}'.format(vector.key))​
        print('  Distance: {:.4f}'.format(vector.distance))​
        print('  Metadata: {}'.format(vector.metadata))​
        if vector.data and vector.data.float32:​
            print('  Vector dimension: {}'.format(len(vector.data.float32)))​
​
except tos.exceptions.TosClientError as e:​
    # The operation failed and a client exception was caught. This is usually due to invalid request parameters or a network exception.​
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))​
except tos.exceptions.TosServerError as e:​
    # The operation failed and a server exception occurred. See the response for the error details.​
    print('fail with server error, code: {}'.format(e.code))​
    # Use the request ID for troubleshooting purposes. We strongly recommend including the request ID in the logs.​
    print('error with request id: {}'.format(e.request_id))​
    print('error with message: {}'.format(e.message))​
    print('error with http code: {}'.format(e.status_code))​
    print('error with ec: {}'.format(e.ec))​
    print('error with request url: {}'.format(e.request_url))​
except Exception as e:​
    print('fail with unknown error: {}'.format(e))​