Python client

AVS provides a gRPC API and a Python client that developers can use to create AI applications leveraging the search capability.

Prerequisites

• Python 3.9 or higher
• pip 9.0.1 or higher

Importing Python clients

Install the AVS package from PyPI:

pip install aerospike-vector-search

The client package provides two separate clients:

• avs_client performs database operations with vector data. The client supports Hierarchical Navigable Small World (HNSW) vector searches, allowing users to find vectors similar to a given query vector within an index.

• avs_admin_client conducts AVS administrative operations, such as creating indexes, querying index information, and dropping indexes.

The client package also provides a types module that contains classes necessary for interacting with the various client APIs.

from aerospike_vector_search import Client
from aerospike_vector_search import AdminClient
from aerospike_vector_search import types

Creating a Vector admin client

Initialize a new client by providing one or more seed hosts to which the client can connect.

from aerospike_vector_search import AdminClient, types

seeds = types.HostPort(
    host=Config.AVS_HOST,
    port=Config.AVS_PORT,
    is_tls=Config.AVS_VERIFY_TLS,
)

avs_admin_client = AdminClient(
    seeds=seeds,
    listener_name=Config.AVS_ADVERTISED_LISTENER,
    is_loadbalancer=Config.AVS_IS_LOADBALANCER,
)

Once initialized, admin_client is ready for use.

Creating an index using the admin client

To search across a set of vectors, you need to create an index associated with those vectors. AVS uses an index to traverse the HNSW neighborhoods to perform queries.

tip

See Manage AVS indexes for details about creating an index.

Example:

avs_admin_client.index_create(
    namespace=Config.AVS_NAMESPACE,
    name="search-space",
    vector_field="image_embedding",
    dimensions=512,
    vector_distance_metric=types.VectorDistanceMetric.COSINE,
    sets="index-set",
    index_params=types.HnswParams(
        m=32,
        ef_construction=200,
        ef=400,
    ),
    index_meta_data={"model-used": "CLIP"},
)

Creating a Vector client

Initialize a new client by providing one or more seed hosts to which the client can connect.

from aerospike_vector_search import Client, types

seeds = types.HostPort(
    host=Config.AVS_HOST,
    port=Config.AVS_PORT,
    is_tls=Config.AVS_VERIFY_TLS,
)

avs_client = Client(
    seeds=seeds,
    listener_name=Config.AVS_ADVERTISED_LISTENER,
    is_loadbalancer=Config.AVS_IS_LOADBALANCER,
)

Once initialized, client is ready for use.

Adding vector entries

Vectors must exist in AVS before searches can be performed.

To insert records, use the upsert method and specify the following values when writing a record:

• namespace - Namespace in which the index exists.
• key - Primary identifier for your record.
• record data - Map of any data you want to associate with your vector.
• setName (optional) - Set in which to place the record.

The following call creates an index:

avs_client.upsert(
    namespace=Config.AVS_NAMESPACE,
    key="string_key",
    record_data={
        "url": f"http://host.com/data{i}",
        "vector": [0.1, 0.2, 0.3],
        "map": {"a": "A", "inlist": [1, 2, 3]},
        "list": ["a", 1, "c", {"a": "A"}]
    },
    set_name=Config.AVS_SET
)

Waiting for index construction

After inserting vectors into AVS, it will take some time to build the index. If the index is not complete, vector search results may be inaccurate. If you are running a batch job and want confirmation that index construction is complete, you can do the following:

print("waiting for indexing to complete")
avs_client.wait_for_index_completion(namespace='test', name='search-space')

Waiting for the index to complete may provide more accurate search results.

Checking if a vector is indexed​

Alternatively, you can check individual records to see if they have completed indexing.

status = avs_client.is_indexed(
    namespace=Config.AVS_NAMESPACE,
    key="string_key",
    set_name=Config.AVS_SET,
    index_name="search-space",
)

Searching

After vectors have been indexed, you can begin searching them by providing a vector for search. This generally entails running your machine learning model on user input, and then performing a search using the generated embedding.

results = avs_client.result = client.vector_search(
    namespace=Config.AVS_NAMESPACE,
    index_name="search-space",
    query=vector_embedding,
    limit=100,
    bin_names=["image_embedding"],
)

Results are a list of nearest neighbors. You can loop through the results from your entries to extract the relevant properties to use in your application:

for result in results:
    print(str(result.key) + " -> " + str(result.bins))

Get vector data

You can read a record from AVS using the following:

 record = avs_client.get(
    namespace=Config.AVS_NAMESPACE,
    key="string_key",
    field_names=["image_embedding"],
    set_name=Config.AVS_SET,
)

AVS Python Client using Asyncio

The aerospike-vector-search module provides an aio module with asynchronous clients that replace any client methods with coroutine methods. The asynchronous client are initialized in the same way as the synchronous clients. Simply add await in front of synchronous code to convert code examples:

from aerospike_vector_search.aio import Client
from aerospike_vector_search import types

seeds = types.HostPort(
    host=Config.AVS_HOST,
    port=Config.AVS_PORT,
    is_tls=Config.AVS_VERIFY_TLS,
)

avs_client = Client(
    seeds=seeds,
    listener_name=Config.AVS_ADVERTISED_LISTENER,
    is_loadbalancer=Config.AVS_IS_LOADBALANCER,
)

# Use await on client methods to await completion of the coroutine

await avs_client.wait_for_index_completion(namespace='test', name='search-space')
result = await avs_client.vector_search(
    namespace=Config.AVS_NAMESPACE,
    index_name="search-space",
    query=vector_embedding,
    limit=100,
    bin_names=["image_embedding"],
)

Read the Docs

For details about using the Python client, visit our Read the Docs page.