How vdaas/vald works
Main Architectural Layers
• Frontend / Client Devices: These represent the applications or clients that send search/insertion requests (for example, via SDKs or REST/gRPC calls).
• API Gateways: Vald has gateways (both load-balancer and filter gateways) that front external requests. They provide routing, load balancing, and potentially authentication.
• Core Search Components:
– Vald Agent(s): The heart of the system where the ANN search happens using engines like NGT (and optionally Faiss). There are two variants: the standard “Agent” and the “Agent Sidecar” which operate in tandem.
– Discoverer: A separate component that monitors cluster state and health for dynamic clustering.
– Index Manager: Responsible for tasks like index correction (saving, deleting, rotating) that help in maintaining the vector index over time.
• Orchestration and Management:
– Helm Operator and related charts: These are used for deploying, managing, and scaling the system on Kubernetes.
• Supporting Services: This includes data compression, backup mechanisms, observability/metrics (gRPC, Prometheus, Jaeger, etc.), and configuration management.
File Structure and README Insights
• The “cmd” and “pkg” directories show multiple services (agent, index, discoverer, gateway, manager, tools) while “apis”, “internal”, and “docker” indicate a well-modularized microservice architecture.
• The README and assets provide visual overviews and detailed descriptions of how these components interoperate (e.g., the “Vald Architecture Overview” image).
Relationships and Data Flow
• The Agent internally uses specialized ANN algorithms (NGT, Faiss, possibly integrated via packages such as “pkg/agent/core/ngt” or “pkg/agent/core/faiss”) to perform vector searches.
• Parallel to the Agent, the Discoverer service monitors the health and registration state of agents.
• The Index Manager interacts with Agents to perform correction, backup, and maintenance tasks on the indices.
• An orchestration layer (Helm Operator) and Kubernetes-related configurations show how these components are deployed, scaled, and managed.
Architectural Patterns & Design Principles
• Microservices: Each core function (agent, index correction, discoverer, gateway, manager) is implemented as a separate service, which can be scaled horizontally.
• Cloud-Native / Kubernetes: Emphasize that the services are designed for dynamic orchestration, auto-scaling, and resilience with health checks managed by Kubernetes.
• Modular design: Clear separation between network communication layers (gRPC APIs), core algorithms (NGT, Faiss usecases), and orchestration code.
• Clear labels for each component:
• “Client / SDK”
• “Gateway (LB & Filter)”
• “Vald Agent (NGT)” and optionally “Agent Sidecar”
• “Discoverer”
• “Index Manager”
• “Helm Operator / Deployment Manager”
• The flow of a search query from the Client to the Gateway to the Agent.
• Management or control flows from the Index Manager to the agents.
• Health and status reporting flows from the Agent to the Discoverer.
• Deployment control signals from the Helm Operator to the Kubernetes cluster.
• Microservices could be shown as rounded rectangles.
• Kubernetes-related elements can be enclosed in a “cluster” boundary.