Installation

Install the Python SDK with pip install actian-vectorai-client.

The Python SDK provides synchronous and asynchronous clients for VectorAI DB over gRPC, plus optional REST-based auth/admin helpers.

Prerequisites

To use the Python SDK, make sure you have:

• Python 3.10 or later
• numpy 1.26 or later
• grpcio 1.80 or later
• pydantic 2.10 or later

Follow these steps to install and begin using the SDK:

Install the SDK

Install the core SDK from PyPI.

pip install actian-vectorai-client

Optional extras

Install extras when your application needs the related integration.

Extra	Command	Use case
OpenAI embeddings	pip install "actian-vectorai-client[openai]"	Use OpenAIEmbedder helpers.
Fast serialization	pip install "actian-vectorai-client[fast]"	Add optional high-performance JSON dependencies.
Telemetry	pip install "actian-vectorai-client[telemetry]"	Enable OpenTelemetry support.
Everything	pip install "actian-vectorai-client[all]"	Install all optional runtime extras.

Configure the client

The SDK reads ACTIAN_VECTORAI_* environment variables and .env files automatically. Constructor arguments take precedence over environment values.

Variable	Default	Description
ACTIAN_VECTORAI_URL	localhost:6574	gRPC server address.
ACTIAN_VECTORAI_REST_URL	http://localhost:6573	REST API base URL for auth/admin operations.
ACTIAN_VECTORAI_ACCESS_TOKEN	unset	Bearer token for authenticated gRPC and REST requests.
ACTIAN_VECTORAI_TLS	false	Enable TLS.
ACTIAN_VECTORAI_TIMEOUT	30.0	Default per-call timeout in seconds.
ACTIAN_VECTORAI_MAX_RETRIES	3	Retry attempts for transient failures.
ACTIAN_VECTORAI_POOL_SIZE	1	gRPC connection pool size.
ACTIAN_VECTORAI_LOG_LEVEL	WARNING	SDK log level.

Verify installation

VectorAI DB required: To verify your installation, run VectorAI DB locally first. Follow the local installation guide if you need a server.

Run a health check against the default gRPC endpoint.

from actian_vectorai import VectorAIClient

with VectorAIClient("localhost:6574") as client:
    info = client.health_check()
    print(f"Server: {info['title']} v{info['version']}")

Virtual environments

Install the SDK inside a virtual environment to avoid dependency conflicts.

venv

python -m venv .venv
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows
pip install actian-vectorai-client

conda

conda create -n vectorai python=3.10
conda activate vectorai
pip install actian-vectorai-client

Troubleshooting

Issue	Solution
ModuleNotFoundError	Verify the SDK is installed in the active Python environment.
gRPC connection errors	Confirm VectorAI DB is reachable at localhost:6574 or set ACTIAN_VECTORAI_URL.
Python version mismatch	Run python --version; the SDK requires Python 3.10 or later.
Permission errors during install	Install in a virtual environment or use pip install --user actian-vectorai-client.

Next steps

Quickstart

Create a collection, insert vectors, and run a search.

Python reference

Review namespaces, configuration, filters, batching, and errors.