GroundX On-Prem Documentation

The Layout service is responsible for processing and analyzing document layouts, including OCR (Optical Character Recognition) capabilities. It is deployed via Terraform to Kubernetes or OpenShift environments and consists of four primary services:

• Layout API Service: Manages the API interface and cache dependencies.
• Layout Inference Service: Handles machine learning inference tasks and requires GPU resources.
• Layout OCR Service: Performs text recognition (note: this is not deployed if Google OCR is used).
• Layout Process Service: Manages document processing tasks and dynamic queue configuration.

GroundX On-Prem is a Kubernetes-based deployment for RAG (Retrieval-Augmented Generation) document ingestion and search capabilities. It is designed to run in isolated or air-gapped environments without external dependencies.

The system consists of three core components:

1. GroundX Ingest: A vision model optimized for document understanding that converts complex documents into queryable representations for LLMs.
2. GroundX Store: Secure, encrypted storage for source files, semantic objects, and vectors.
3. GroundX Search: A search service built on OpenSearch that combines text and vector search with a fine-tuned re-ranker model.

Deployment typically involves two steps:

1. (Optional) Infrastructure creation on AWS via Terraform.
2. Deployment of GroundX onto Kubernetes via Helm.

The services/ directory contains the Infrastructure-as-Code (IaC) configurations for deploying and managing the EyeLevel application ecosystem. Each subdirectory is managed via Terraform and Helm charts and represents a specific component.

Common files found in each service subdirectory include:

• variables.tf: Input variables for the service.
• main.tf (or service-specific files like redis.tf): Main Terraform resource definitions.
• outputs.tf: Terraform module outputs.

services/
├── cache/
├── db/
├── file/
├── search/
└── stream/

The initialization process follows a specific dependency chain:

1. Module Path Definition: The root locals.tf establishes the base module path.
2. Foundational Setup (add subdirectory): Sets up core Kubernetes resources such as the namespace, SSL certificates (Self-signed CA and Service certificates), and local storage classes.
3. Configuration Generation (config subdirectory): Generates service-specific configuration files (e.g., config.yaml, Layout, Ranker, and Summary service configs) and stores them in Kubernetes ConfigMaps.
4. Database Initialization: Creates a database initialization script (init-db.sql) and stores it in a Kubernetes ConfigMap for first-time database setup.

The Summary Client service is designed for cross-platform compatibility between standard Kubernetes and OpenShift.

Environment Handling

• OpenShift: Security contexts are automatically adjusted if an OpenShift environment is detected.
• User/Group IDs: The service runs with specific user and group IDs that are automatically set based on the cluster type.

Security Requirements

• Ensure appropriate RBAC (Role-Based Access Control) permissions are configured to allow the service to interact with other cluster components.

The Process service includes automated security handling:

• Security Contexts: The configuration automatically detects if it is running in an OpenShift or standard Kubernetes environment and adjusts security contexts accordingly.
• User/Group IDs: The service runs with specific user and group IDs determined by the cluster type.
• RBAC: You must ensure that the necessary Role-Based Access Control (RBAC) permissions are configured to allow the service to interact with other components in your cluster.

The Stream directory manages Apache Kafka configuration for the EyeLevel application using the Strimzi operator. The deployment workflow follows these steps:

1. Determine Kafka Deployment: The system checks if stream_existing is provided. If not, it prepares to create a new Kafka deployment.
2. Configure Kafka Settings: It combines settings from an existing Kafka instance (if provided) with internal defaults.
3. Deploy Strimzi Operator: If a new deployment is required, the Strimzi Operator is deployed via Helm.
4. Deploy Kafka Cluster: If a new deployment is required, the Kafka Cluster is deployed via Helm using the specified configurations.

GroundX operates via two primary data paths:

Ingestion Pipeline

Documents flow through a multi-stage pipeline that scales based on throughput:

1. Upload: API receives file $\rightarrow$ stored in MinIO/S3 $\rightarrow$ queued in Kafka/SQS.
2. Processing: Celery workers handle pre-processing and layout extraction (using Tesseract and GPU vision models).
3. Summarization: A summary client triggers the summary-api, which uses either an on-prem vLLM (GPU) or external providers like OpenAI/Azure.
4. Persistence: Final data is stored in OpenSearch (vectors/text), MySQL (metadata), and MinIO/S3 (objects).

Search Path

1. API/Load Balancer receives the query.
2. OpenSearch performs a hybrid query.
3. Ranker-api performs re-ranking using a GPU re-ranker model.
4. Results are returned to the user.

GroundX pods use node selector labels and tolerations to deploy to specific nodes. You must apply labels to your nodes using the key eyelevel_node with one of the following enumerated string values:

• eyelevel-cpu-only
• eyelevel-cpu-memory
• eyelevel-gpu-layout
• eyelevel-gpu-ranker
• eyelevel-gpu-summary

Note: All required node labels must exist on at least one node group within your cluster. If you use custom labels instead of the defaults, you must update all corresponding service node keys in values.yaml (e.g., layout.inference.node, ranker.inference.node, etc.).

nodeSelector:
  eyelevel_node: "eyelevel-cpu-only"
tolerations:
  - key: "eyelevel_node"
    value: "eyelevel-cpu-only"
    effect: "NoSchedule"