Validation Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/pipelineValidation.ts
• src/lib/oliveRecipeSchema.ts
• src/lib/recipePipeline.ts
• src/components/features/InBrowserValidation.tsx
• server.ts
• src/lib/aiWorkspaceContext.ts

The Validation Architecture in Olive Studio is a multi-layered system designed to ensure that Microsoft Olive optimization recipes are structurally sound, hardware-compatible, and logically consistent before execution. It spans from low-level TypeScript schema assertions to high-level AI-driven advisory reviews, providing a "fail-fast" mechanism that prevents suboptimal or impossible optimization runs.

The architecture ensures that user-defined pipelines—comprising model sources, hardware targets (Execution Providers), and optimization passes—adhere to the strict requirements of the Olive engine. By integrating validation into the UI, server preflight, and hardware probing phases, the system guides users toward valid configurations for specific hardware like NVIDIA GPUs, Intel OpenVINO, or Qualcomm QNN.

Multi-Layer Validation Strategy

The system employs five distinct layers of validation to catch errors at different stages of the recipe lifecycle.

Layer	Component	Responsibility
1. Pipeline Compatibility	pipelineValidation.ts	Enforces rules between optimization passes (e.g., AWQ requires GPU) and provides auto-sanitization.
2. Recipe Structure	oliveRecipeSchema.ts	Validates the final JSON object against the structural requirements of Olive (Input Models, Systems, Engines).
3. Unified Builder	recipePipeline.ts	Coordinates the transformation of UI state into a validated, runnable recipe artifact.
4. Server Preflight	server.ts	Performs a dry-run using the Olive CLI (--list_required_packages) to verify environment readiness.
5. AI Advisory	aiWorkspaceContext.ts	(Optional) Uses Large Language Models to provide high-level architectural feedback and "Review" notes.

Sources: README.md, src/lib/recipePipeline.ts:18-35

Structural Schema Validation

The structural layer ensures that the generated JSON contains all required top-level keys and that their values meet basic type requirements. This validation is shared across the UI, server, and CI scripts.

Validation Logic Flow

The validateOliveRecipeStructure function recursively checks the recipe for necessary components:

Key Structural Constraints

• input_model: Must contain a type and a config object.
• systems: Must define at least one system with a non-empty accelerators array.
• engine: Must define host and target keys that point to valid entries in the systems object.
• passes: Each pass must have a type recognized by the Olive pass catalog.

Sources: src/lib/oliveRecipeSchema.ts:37-77, src/lib/oliveRecipeSchema.ts:85-115

Pipeline Compatibility and Sanitization

The pipeline validation layer handles the complex inter-dependencies between optimization passes and hardware execution providers (IHV). It classifies issues into Critical (blocking) and Warning (advisory) severities.

Execution Provider (EP) Constraints

Certain optimization methods are restricted to specific hardware targets. The pipelineValidation.ts module defines these permissions:

• AWQ/GPTQ: Only allowed on GPU providers (CUDA, ROCM).
• QAT (Quantization Aware Training): Disallowed on QNN (Qualcomm).
• Structured Pruning: Only allowed on NVIDIA Tensor-Core providers (CUDA, TensorRT).
• OpenVINO Conversion: Only allowed on OpenVINOExecutionProvider.

Sources: src/lib/pipelineValidation.ts: (inferred from test implementation), src/lib/tests/pipelineValidation.test.ts:39-95

Auto-Sanitization

When a user switches hardware or selects conflicting passes, the sanitizePipelineState function automatically resolves critical issues to maintain a runnable state. For example, if a user selects AWQ but switches to a CPU target, the system will automatically coerce the method to standard PTQ.

Execution Readiness

The transition from a draft to an "Execute Live" state requires a final consistency check. The RecipePipelineResult interface encapsulates this final status.

Runnable Criteria

A recipe is deemed isRunnable only if:

1. validation.isBlocked is false (no critical IHV/Pass conflicts).
2. schema.valid is true (structural integrity is maintained).

Sources: src/lib/recipePipeline.ts:9-16, src/lib/recipePipeline.ts:33

Server-Side Preflight

Before spawning the actual optimization process, the server performs a preflight check using the Olive CLI. This verifies that the RunConfig can be parsed by the engine and that all required Python packages are installed in the virtual environment.

async function runOliveConfigPreflight(
  configPath: string,
  onLine: (line: string) => void,
  env: NodeJS.ProcessEnv = process.env,
  provider: IHVProvider = "CUDAExecutionProvider",
): Promise<{ ok: boolean; error?: string }> {
  const { executable, args } = resolveOliveCommand(provider, configPath, true);
  // ... spawns olive run --list_required_packages
}

Sources: server.ts:405-413

In-Browser Validation

For edge and web deployment targets, Olive Studio provides an InBrowserValidation module. This allows developers to test optimized .onnx or .ort files directly in the browser environment before finalized deployment.

Features

• Environment Probing: Checks for WebGPU and onnxruntime-web availability.
• Inference Metrics: Measures session initialization time and inference latency (ms).
• Tensor Validation: Verifies input/output names and shapes.

Sources: src/components/features/InBrowserValidation.tsx:43-75, src/components/features/InBrowserValidation.tsx:145-180

AI-Enhanced Advisory

The highest level of validation is the AI Review. This layer does not block execution but provides architectural insights by building an AiWorkspaceContext.

Workspace Context Data

The system aggregates the following data for AI analysis:

• Model Metadata: Source (HF/Local/Azure) and display name.
• Hardware context: Selected EP and CUDA version tags.
• Active Passes: A serialized list of enabled optimization techniques.
• Infrastructure: Cache directories and batch job status.

Sources: src/lib/aiWorkspaceContext.ts:4-31

AI Validation Endpoint

The /api/ai/validate endpoint uses this context to return a JSON object containing a summary of potential suboptimal settings and specific fix suggestions.

Sources: server.ts:895-920

Conclusion

The Validation Architecture provides a robust safeguard for model optimization workflows. By combining deterministic TypeScript schemas with hardware-aware compatibility rules and AI-driven insights, Olive Studio ensures that users can confidently build complex optimization pipelines that are guaranteed to be structurally valid and compatible with their target hardware. This layered approach significantly reduces the "long stderr traces" typically associated with manual Olive configuration.