Repository files navigation

A Python vector database you just need - no more, no less.

vectordb is a Pythonic vector database offers a comprehensive suite ofCRUD (Create, Read, Update, Delete) operations and robustscalability options, including sharding and replication. It's readily deployable in a variety of environments, fromlocal toon-premise andcloud.vectordb delivers exactly what you need - no more, no less. It's a testament to effective Pythonic design without over-engineering, making it a lean yet powerful solution for all your needs.

vectordb capitalizes on the powerful retrieval prowess ofDocArray and the scalability, reliability, and serving capabilities ofJina. Here's the magic: DocArray serves as the engine driving vector search logic, while Jina guarantees efficient and scalable index serving. This synergy culminates in a robust, yet user-friendly vector database experience - that'svectordb for you.

pip install vectordb

1. Kick things off by defining a Document schema with theDocArray dataclass syntax:

fromdocarrayimportBaseDocfromdocarray.typingimportNdArrayclassToyDoc(BaseDoc):text:str=''embedding:NdArray[128]

2. Opt for a pre-built database (likeInMemoryExactNNVectorDB orHNSWVectorDB), and apply the schema:

fromdocarrayimportDocListimportnumpyasnpfromvectordbimportInMemoryExactNNVectorDB,HNSWVectorDB# Specify your workspace pathdb=InMemoryExactNNVectorDB[ToyDoc](workspace='./workspace_path')# Index a list of documents with random embeddingsdoc_list= [ToyDoc(text=f'toy doc{i}',embedding=np.random.rand(128))foriinrange(1000)]db.index(inputs=DocList[ToyDoc](doc_list))# Perform a search queryquery=ToyDoc(text='query',embedding=np.random.rand(128))results=db.search(inputs=DocList[ToyDoc]([query]),limit=10)# Print out the matchesforminresults[0].matches:print(m)

Since we issued a single query,results contains only one element. The nearest neighbour search results are conveniently stored in the.matches attribute.

vectordb is designed to be easily served as a service, supportinggRPC,HTTP, andWebsocket communication protocols.

On the server side, you would start the service as follows:

withdb.serve(protocol='grpc',port=12345,replicas=1,shards=1)asservice:service.block()

This command startsvectordb as a service on port12345, using thegRPC protocol with1 replica and1 shard.

On the client side, you can access the service with the following commands:

fromvectordbimportClient# Instantiate a client connected to the server. In practice, replace 0.0.0.0 to the server IP address.client=Client[ToyDoc](address='grpc://0.0.0.0:12345')# Perform a search queryresults=client.search(inputs=DocList[ToyDoc]([query]),limit=10)

This allows you to perform a search query, receiving the results directly from the remotevectordb service.

You can seamlessly deploy yourvectordb instance to Jina AI Cloud, which ensures access to your database from any location.

Start by embedding your database instance or class into a Python file:

# example.pyfromdocarrayimportBaseDocfromvectordbimportInMemoryExactNNVectorDBdb=InMemoryExactNNVectorDB[ToyDoc](workspace='./vectordb')# notice how `db` is the instance that we want to serveif__name__=='__main__':# IMPORTANT: make sure to protect this part of the code using __main__ guardwithdb.serve()asservice:service.block()

Next, follow these steps to deploy your instance:

1. If you haven't already, sign up for aJina AI Cloud account.

2. Use thejc command line to login to your Jina AI Cloud account:

jc login

3. Deploy your instance:

vectordb deploy --db example:db

After deployment, use thevectordb Client to access the assigned endpoint:

fromvectordbimportClient# replace the ID with the ID of your deployed DB as shown in the screenshot abovec=Client(address='grpcs://ID.wolf.jina.ai')

You can then list, pause, resume or delete your deployed DBs withjc command:

jcloud list ID

jcloud pause ID orjcloud resume ID

jcloud remove ID

Vector databases serve as sophisticated repositories for embeddings, capturing the essence of semantic similarity among disparate objects. These databases facilitate similarity searches across a myriad of multimodal data types, paving the way for a new era of information retrieval. By providing contextual understanding and enriching generation results, vector databases greatly enhance the performance and utility of Language Learning Models (LLM). This underscores their pivotal role in the evolution of data science and machine learning applications.

Both the local library usage and the client-server interactions invectordb share the same API. This providesindex,search,update, anddelete functionalities:

• index: Accepts aDocList to index.
• search: Takes aDocList of batched queries or a singleBaseDoc as a single query. It returns either single or multiple results, each withmatches andscores attributes sorted byrelevance.
• delete: Accepts aDocList of documents to remove from the index. Only theid attribute is necessary, so make sure to track theindexedIDs if you need to delete documents.
• update: Accepts aDocList of documents to update in the index. Theupdate operation will replace theindexed document with the same index with the attributes and payload from the input documents.

You can servevectordb and access it from a client with the following parameters:

• protocol: The serving protocol. It can begRPC,HTTP,websocket or a combination of them, provided as a list. Default isgRPC.
• port: The service access port. Can be a list of ports for each provided protocol. Default is 8081.
• workspace: The path where the VectorDB persists required data. Default is '.' (current directory).

You can set two scaling parameters when serving or deploying your Vector Databases withvectordb:

• Shards: The number of data shards. This improves latency, asvectordb ensures Documents are indexed in only one of the shards. Search requests are sent to all shards and results are merged.
• Replicas: The number of DB replicas.vectordb uses theRAFT algorithm to sync the index between replicas of each shard. This increases service availability and search throughput, as multiple replicas can respond in parallel to more search requests while allowing CRUD operations. Note: In JCloud deployments, the number of replicas is set to 1. We're working on enabling replication in the cloud.

Here are the parameters for eachVectorDB type:

This database performs exhaustive search on embeddings and has limited configuration settings:

• workspace: The folder where required data is persisted.

InMemoryExactNNVectorDB[MyDoc](workspace='./vectordb')InMemoryExactNNVectorDB[MyDoc].serve(workspace='./vectordb')

This database employs the HNSW (Hierarchical Navigable Small World) algorithm fromHNSWLib for Approximate Nearest Neighbor search. It provides several configuration options:

• workspace: Specifies the directory where required data is stored and persisted.

Additionally, HNSWVectorDB offers a set of configurations that allow tuning the performance and accuracy of the Nearest Neighbor search algorithm. Detailed descriptions of these configurations can be found in theHNSWLib README:

• space: Specifies the similarity metric used for the space (options are "l2", "ip", or "cosine"). The default is "l2".
• max_elements: Sets the initial capacity of the index, which can be increased dynamically. The default is 1024.
• ef_construction: This parameter controls the speed/accuracy trade-off during index construction. The default is 200.
• ef: This parameter controls the query time/accuracy trade-off. The default is 10.
• M: This parameter defines the maximum number of outgoing connections in the graph. The default is 16.
• allow_replace_deleted: If set toTrue, this allows replacement of deleted elements with newly added ones. The default isFalse.
• num_threads: This sets the default number of threads to be used duringindex andsearch operations. The default is 1.

vectordb includes a simple CLI for serving and deploying your database:

• User-friendly Interface: Withvectordb, simplicity is key. Its intuitive interface is designed to accommodate users across varying levels of expertise.

• Minimalistic Design:vectordb packs all the essentials, with no unnecessary complexity. It ensures a seamless transition from local to server and cloud deployment.

• Full CRUD Support: From indexing and searching to updating and deleting,vectordb covers the entire spectrum of CRUD operations.

• DB as a Service: Harness the power of gRPC, HTTP, and Websocket protocols withvectordb. It enables you to serve your databases and conduct insertion or searching operations efficiently.

• Scalability: Experience the raw power ofvectordb's deployment capabilities, including robust scalability features like sharding and replication. Improve your service latency with sharding, while replication enhances availability and throughput.

• Cloud Deployment: Deploying your service in the cloud is a breeze withJina AI Cloud. More deployment options are coming soon!

• Serverless Capability:vectordb can be deployed in a serverless mode in the cloud, ensuring optimal resource utilization and data availability as per your needs.

• Multiple ANN Algorithms:vectordb offers diverse implementations of Approximate Nearest Neighbors (ANN) algorithms. Here are the current offerings, with more integrations on the horizon:

  • InMemoryExactNNVectorDB (Exact NN Search): Implements Simple Nearest Neighbor Algorithm.
  • HNSWVectorDB (based on HNSW): UtilizesHNSWLib

The future of Vector Database looks bright, and we have ambitious plans! Here's a sneak peek into the features we're currently developing:

• More ANN Search Algorithms: Our goal is to support an even wider range of ANN search algorithms.
• Enhanced Filtering Capabilities: We're working on enhancing our ANN Search solutions to support advanced filtering.
• Customizability: We aim to makevectordb highly customizable, allowing Python developers to tailor its behavior to their specific needs with ease.
• Expanding Serverless Capacity: We're striving to enhance the serverless capacity ofvectordb in the cloud. While we currently support scaling between 0 and 1 replica, our goal is to extend this to 0 to N replicas.
• Expanded Deployment Options: We're actively working on facilitating the deployment ofvectordb across various cloud platforms, with a broad range of options.

Need help withvectordb? Interested in using it but require certain features to meet your unique needs? Don't hesitate to reach out to us. Join ourDiscord community to chat with us and other community members.

The VectorDB project is backed byJina AI and licensed under Apache-2.0. Contributions from the community are greatly appreciated! If you have an idea for a new feature or an improvement, we would love to hear from you. We're always looking for ways to makevectordb more user-friendly and effective.