Query vectors for similarity search with OSS SDK for Python 2.0 - Object Storage Service

Call query_vectors() to run a similarity search against a vector index in an OSS bucket. The method accepts a query vector and an optional metadata filter, and returns the top-K nearest neighbors ranked by distance.

Prerequisites

Before you begin, ensure that you have:

An OSS bucket with a vector index already created
The oss:QueryVectors permission granted to your Alibaba Cloud account, RAM user, or RAM role via a RAM policy or a bucket policy
OSS SDK for Python 2.0 installed
Access credentials available as environment variables

Permissions

By default, an Alibaba Cloud account has all permissions. Resource Access Management (RAM) users and RAM roles have no permissions by default and must be granted access explicitly.

API	Action	Description
QueryVectors	`oss:QueryVectors`	Queries vector data.

Method signature

query_vectors(request: QueryVectorsRequest, **kwargs) → QueryVectorsResult

Parameter	Type	Description
`request`	`QueryVectorsRequest`	Sets the query vector, filter condition, and the number of results to return. See QueryVectorsRequest.

Returns a QueryVectorsResult containing the matched vectors. See QueryVectorsResult.

For the full method definition, see query_vectors.

Query vectors

Minimal example

The following example shows the core call: pass a query vector and retrieve the top-K nearest neighbors.

import alibabacloud_oss_v2 as oss
import alibabacloud_oss_v2.vectors as oss_vectors

# Initialize the client
cfg = oss.config.load_default()
cfg.credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
cfg.region = "<region-id>"
cfg.account_id = "<account-id>"
vector_client = oss_vectors.Client(cfg)

# Run a similarity search
result = vector_client.query_vectors(oss_vectors.models.QueryVectorsRequest(
    bucket="<bucket-name>",
    index_name="<index-name>",
    query_vector={"float32": [0.1] * 128},
    top_k=10,
))

for vector in result.vectors:
    print(vector)

Replace the following placeholders:

Placeholder	Description
`<region-id>`	The region where the bucket is located, e.g., `cn-hangzhou`
`<account-id>`	Your Alibaba Cloud account ID
`<bucket-name>`	The name of your OSS bucket
`<index-name>`	The name of the vector index to search

Query with a metadata filter

Add a filter to narrow results to vectors whose metadata matches the condition. The following example excludes vectors tagged as comedy or documentary, and returns each match with its distance score and metadata:

query_filter = {
    "$and": [{
        "type": {
            "$nin": ["comedy", "documentary"]
        }
    }]
}

result = vector_client.query_vectors(oss_vectors.models.QueryVectorsRequest(
    bucket="<bucket-name>",
    index_name="<index-name>",
    filter=query_filter,
    query_vector={"float32": [0.1] * 128},
    return_distance=True,    # include similarity distance in each result
    return_metadata=True,    # include vector metadata in each result
    top_k=10,
))

Full runnable example

The following script accepts command-line arguments and is ready to run locally:

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

Run the script with:

python query_vectors.py \
  --region cn-hangzhou \
  --bucket <bucket-name> \
  --index_name <index-name> \
  --account_id <account-id>

For the complete sample code, see query_vectors.py.