Introduction

Modern AI applications struggle to maintain low-latency search across billions of high-dimensional vectors as they scale. Vald is a cloud-native, distributed approximate nearest neighbor (ANN) dense vector search engine designed to solve this exact bottleneck, boasting over 1,600 GitHub stars. By leveraging a microservices architecture on Kubernetes, Vald enables horizontal scaling of both memory and CPU to handle massive datasets that would crash a single-node database. It replaces the need for complex, manual sharding of vector indexes by providing an automated, distributed search platform.

What Is Vald?

Vald is a distributed fast approximate nearest neighbor (ANN) dense vector search engine that provides high-performance similarity search for target users building large-scale AI retrieval systems. Developed and maintained by the vdaas team, it is licensed under the Apache License 2.0 and primarily written in Go, with C++ integrations for the NGT (Neighborhood Graph Tearing) algorithm.

The project is designed as a cloud-native system, meaning every component is containerized and managed via Kubernetes. This allows Vald to distribute vector indexes across multiple agents, ensuring that no single node becomes a bottleneck for search or indexing operations.

Why Vald Matters

Traditional vector databases often struggle with the “stop-the-world” problem during index updates, where the entire system locks to incorporate new data. Vald solves this by using a distributed index graph, allowing the system to continue processing search queries while indexing occurs in the background.

As the industry shifts toward Retrieval Augmented Generation (RAG) and Large Language Models (LLMs), the demand for vector stores that can scale to billions of entries without sacrificing millisecond latency is critical. Vald provides the infrastructure to support these workloads, offering automated index backup and replication to ensure high availability in production environments.

With adoption in production services at Yahoo Japan for similar image search and content recommendation, Vald has proven its ability to handle enterprise-grade workloads that require extreme scalability and reliability.

Key Features

• Asynchronous Auto Indexing: Vald uses distributed index graphs to prevent system locks during indexing, ensuring that search operations remain active and responsive even as new data is added.
• Cloud-Native Architecture: Built specifically for Kubernetes, Vald supports horizontal scaling of CPU and memory, allowing users to add nodes to the cluster to handle increasing data volumes.
• Automated Index Backup: The system supports automatic backups to Object Storage or Persistent Volumes, enabling rapid disaster recovery and preventing data loss during pod failures.
• Distributed Indexing and Replication: Vector indexes are distributed across multiple agents, and each index is replicated across several agents to ensure high availability and automatic rebalancing when a node goes down.
• Customizable Ingress/Egress Filtering: Vald provides highly customizable filters that can be configured via gRPC to manipulate incoming data (e.g., vectorization) or rerank search results before they are returned to the user.
• Multi-Language SDK Support: Official client libraries are available for Go, Java, Node.js, and Python, making it easy to integrate Vald into existing application stacks.
• Pluggable ANN Algorithms: While it primarily uses the fast NGT algorithm, Vald is designed to support multiple ANN algorithms, including Faiss, to optimize search performance based on the dataset.
• gRPC and REST API: The system provides a high-performance gRPC interface for low-latency communication and an optional REST API for broader compatibility.

How Vald Compares

Vald’s primary differentiator is its extreme focus on Kubernetes-native distribution. While Pinecone offers a seamless SaaS experience, Vald is built for organizations that require full control over their infrastructure and data residency, providing a distributed architecture that can scale to billions of vectors without the lock-in of a managed service.

Compared to Milvus, Vald emphasizes a highly decoupled microservices approach where the Gateway, Discoverer, and Agents are independent pods. This allows for more granular scaling of specific components based on the bottleneck—for example, increasing the number of LB Gateways if the API request traffic is high, but keeping the number of Agents constant if the data volume is stable.

Getting Started: Installation

Vald requires a Kubernetes cluster (v1.19+) and AVX2 instructions on the underlying hardware (required by the NGT agent).

Using Helm

The fastest way to deploy Vald is via the official Helm charts. Run the following commands to add the repository and install the cluster:

helm repo add vald https://vald.vdaas.org/charts
helm install vald-cluster vald/vald

Using Helm-operator

For more advanced management, Vald provides a Helm-operator that automates the lifecycle of the cluster. This is recommended for production environments where automated updates and scaling are required.

After installation, you can verify the deployment by checking the pods in your namespace:

kubectl get pods -n vald

How to Use Vald

Vald operates as a distributed system where the client interacts primarily with the LB Gateway. The basic workflow involves creating an index, inserting vectors, and then performing a similarity search.

First, the user defines the vector dimension and distance type (e.g., L2 or Cosine) through the Index Manager. Once the index is initialized, vectors are inserted via the gRPC API. The LB Gateway fans out the search request to all Vald Agents, each of which searches its local shard of the index. The Gateway then merges the results and returns the top-k nearest neighbors to the client.

If you are using the Python SDK, the process is simplified into a few method calls to the Vald client, which handles the gRPC communication and index management.

Code Examples

The following examples demonstrate how to interact with Vald using the Python SDK. These examples are based on the project’s official client libraries.

Basic Vector Insertion

This snippet shows how to connect to the Vald cluster and insert a single vector into a specific index.

from vald.client import ValdClient

client = ValdClient(host="vald-gateway.vald.svc.cluster.local", port=8081)
client.insert(index_name="my_index", vector=[0.1, 0.2, 0.3, ...], id="vector_1")

Performing a Similarity Search

This example shows how to retrieve the top 10 nearest neighbors for a given query vector.

from vald.client import ValdClient

client = ValdClient(host="vald-gateway.vald.svc.cluster.local", port=8081)
results = client.search(index_name="my_index", vector=[0.1, 0.2, 0.3, ...], k=10)

for result in results:
    print(f"ID: {result.id}, Distance: {result.distance}")

Integration with LangChain

Vald can be used as a VectorStore for LangChain to power RAG applications. This requires configuring the Vald agent dimension to match the embedding model (e.g., 768 for BERT).

from langchain.vectorstores import Vald

# Initialize Vald vector store
vector_store = Vald( 
    vald_host="vald-gateway.vald.svc.cluster.local", 
    vald_port=8081, 
    embedding_function=my_embedding_model
)

# Add documents to the store
vector_store.add_texts(["This is a document about AI", "This is a document about vectors"])

Advanced Configuration

Vald provides extensive configuration options via the values.yaml file in the Helm chart. Key environment variables and settings allow for fine-tuning the search performance and resource allocation.

Search Parameter Tuning

To optimize the balance between search speed and accuracy (recall), you can adjust the following parameters in the Vald Agent (NGT) settings:

• epsilon: Controls the search range. A higher value typically increases recall but increases search time.
• search_edge_size: Defines the number of edges to explore during the search. Increasing this value improves precision but adds latency.
• create_edge_size: Sets the number of edges created during index construction.

Resource Allocation

The server_config section allows you to enable/disable the REST server and configure gRPC ports. You can also define the number of replicas for the Index Manager and Discoverer to ensure high availability of the control plane.

Real-World Use Cases

Vald is best suited for scenarios where the dataset is too large for a single machine and requires distributed search across a Kubernetes cluster.

• Similar Image Search: A product recommendation engine that finds visually similar images across a corpus of billions of product photos. The advantage of Vald is consultants’ ability to handle the massive scale of the image embeddings without slowing down.
• Face Recognition: A security system that compares a captured face embedding against a database of millions of registered users in real-time. Vald’s low-latency gRPC API ensures the match is found in milliseconds.
• RAG for Enterprise Knowledge Bases: An internal AI assistant that retrieves relevant documents from a massive corporate archive using BERT embeddings. Vald acts as the high-performance retrieval layer that feeds the LLM.
• AI Malware Detection: A security tool that vectorizes binary files and uses Vald to find similar known malware samples to identify new variants of a threat.

Contributing to Vald

The vdaas team welcomes contributions from the community. Developers can contribute by submitting Pull Requests for new features, bug fixes, or improving the documentation. The project provides a CONTRIBUTING.md guide and a specific coding style for Go and C++.

To get started with development, it is recommended to use the provided devcontainer.json for VS Code, which sets up the local environment automatically. You can run unit tests using make test and E2E tests by deploying a local k3d cluster using make k3d/start.

Community and Support

Vald is maintained by the vdaas team and has a strong presence on GitHub. Official support channels include:

• GitHub Discussions: The primary place for reporting bugs and requesting features.
• Slack: The official community Slack channel for real-time discussions and support.
• Official Documentation: A comprehensive guide available at vald.vdaas.org/docs.
• X (Twitter): Follow @vdaas_vald for project updates.

Conclusion

Vald is the right choice for teams building AI applications that have outgrown single-node vector databases. When your data volume reaches billions of vectors and you require a Kubernetes-native, distributed architecture to ensure high availability and automated scaling, Vald provides the necessary infrastructure.

While it requires a Kubernetes cluster to run, the trade-off is an enterprise-grade distributed system that prevents the “stop-the-world” indexing problem and ensures millisecond latency at scale. For those who need a fully managed SaaS experience, a tool like Pinecone may be more appropriate, but for those who prioritize data control and open-source flexibility, Vald is a powerful alternative.

Star the repo, try the quickstart, and join the community to start building scalable similarity search.

Resources

• Vald GitHub Repository
• Official Vald Documentation
• Vald Helm Charts