eyelevelai/groundx-on-prem

A Kubernetes deployable instance of GroundX for document parsing, storage, and search.

What is GroundX On‑Prem?

GroundX On‑Prem is an infrastructure‑as‑code package that lets you run EyeLevel AI’s RAG (retrieval‑augmented generation) pipeline inside your own Kubernetes cluster – even in air‑gapped, fully isolated environments. It bundles three pieces:

GroundX Ingest – a vision model (trained on >1 M enterprise pages) that parses complex documents, extracts text, layout, tables, etc., and creates semantic objects and vector embeddings ready for LLMs.
GroundX Store – encrypted storage for the raw files, the extracted objects and the vector embeddings.
GroundX Search – an OpenSearch‑based service that combines traditional text search with vector similarity and a fine‑tuned re‑ranker model to return highly relevant results.

The repo provides Helm charts, a values.yaml template, and optional Terraform scripts (AWS‑only) to provision the required Kubernetes resources (namespaces, PV classes, NVIDIA GPU operator, and supporting services such as Redis, MySQL, MinIO, OpenSearch, Kafka). It is marketed as a “no‑external‑dependency” deployment suitable for secure, on‑prem or private‑cloud use.

Key Components

Component	Role	Deployment notes
Ingest Service	Vision‑based document understanding (OCR, layout detection, table extraction)	Runs on GPU‑enabled nodes (`eyelevel‑gpu‑layout`). Requires NVIDIA GPU Operator, CUDA 12+.
Store	Secure object and vector storage	Uses MinIO (or external S3) for blobs and OpenSearch for vectors; both can be deployed or pointed at existing clusters.
Search Service	Text + vector retrieval with a re‑ranker	Deployed on OpenSearch‑backed nodes (`eyelevel‑gpu‑ranker`).
Redis	Caching and metrics	Optional – can use an existing Redis cluster or let Helm create one.
MySQL	Metadata persistence	Same optional pattern as Redis.
Kafka / SQS	Asynchronous job queue for ingestion pipelines	Optional; can be replaced with AWS SQS.
NVIDIA GPU Operator	Installs drivers, device plugin, and runtime on GPU nodes	Required for any GPU‑based pod.

Installation Overview

Prerequisites – bash, kubectl (or oc), and Helm v3.8+. A Kubernetes cluster with enough CPU, RAM, disk, and NVIDIA GPUs (CUDA 12+). |
Node‑group labeling – Pods are scheduled via nodeSelector/tolerations using the label eyelevel_node with values like eyelevel‑cpu‑only, eyelevel‑gpu‑layout, etc. The default values.yaml defines these labels; you must apply them to real nodes. |
Namespace & PV class – Create a namespace (default eyelevel) and a PersistentVolume class via the provided groundx-storageclass chart. |
GPU Operator – Install NVIDIA’s GPU Operator (Helm chart) – optional Azure‑specific values are provided. |
Supporting services – Deploy or point to existing Redis, MySQL, MinIO, OpenSearch, and Kafka clusters. |
Deploy GroundX – Run the GroundX Helm chart (helm install groundx groundx/groundx ...) with a customized values.yaml that reflects your node labels, resource limits, and any external service endpoints. |
(Optional) Autoscaling & Monitoring – Enable Horizontal Pod Autoscaler, custom metrics server, and Prometheus integration via the chart’s flags. |

How It Works

Ingestion pipeline: Documents are uploaded (via the SDK or API). The layout pod (GPU) runs OCR and layout detection, the pre‑process pod cleans the data, and the summary pod generates concise embeddings. Results are stored in MinIO and indexed in OpenSearch.
Search: A user sends a natural‑language query to the Search API. OpenSearch performs a hybrid text‑vector lookup, then the ranker model (GPU) re‑orders the hits for higher relevance.
Security: All data stays inside the cluster; storage is encrypted, and the deployment can run in air‑gapped networks.

SDKs & APIs

The README mentions ready‑made SDKs (language‑agnostic) and REST endpoints, but does not detail them. After deployment you can:

Retrieve the public API endpoint (kubectl get svc or via Helm output).
Use the provided client libraries (presumably in Python/JS) to call /ingest and /search endpoints.

Who Might Use This?

Enterprises that need confidential RAG on proprietary documents (legal, medical, finance) and cannot send data to a public cloud.
Organizations with existing Kubernetes/GPU infrastructure that want a turnkey RAG stack.
Teams that want to extend the pipeline (custom models, additional post‑processing) while keeping the core services managed via Helm.

What’s Not Included

The actual model binaries are not in the repo; they are pulled as container images during Helm install.
No hosted SaaS – the repo is the on‑prem version; a hosted version exists at eyelevel.ai.
The “Legacy Terraform Deployment” section only points to older scripts for AWS infra; the primary path is Helm on an existing cluster.

Bottom line: GroundX On‑Prem is a genuine, production‑grade open‑source project that provides the full stack (ingest, storage, search) for enterprise‑level Retrieval‑Augmented Generation, delivered as Kubernetes IaC with detailed resource‑planning guidance.