Environment Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Environment Configuration system in ONNX-Station provides a robust framework for defining, managing, and persisting the parameters required to orchestrate Hugging Face Optimum ONNX model exports and subsequent benchmarks. It acts as the central control plane, allowing users to switch between model source strategies, define task-specific modalities, and tune hardware-specific execution parameters.
At its core, the system utilizes a centralized React context to maintain the global ExportConfig state. This state synchronizes the user interface—including the command preview generator, the sidebar configuration panels, and the benchmarking engine—to ensure that all exported artifacts and performance metrics are consistent with the defined environment specifications.
Sources: src/WorkbenchContext.tsx, src/types.ts, metadata.json
Configuration State Architecture
The system architecture revolves around the WorkbenchProvider, which manages the ExportConfig object. This object contains all necessary flags for the optimum-cli tool and the local benchmarking runner.
Data Flow Diagram
The following diagram illustrates how configuration changes propagate through the system to generate CLI commands and drive the benchmarking engine.
The flow ensures that any change in the UI immediately updates the context, which in turn refreshes the generated command preview and prepares the benchmark parameters.
Sources: src/WorkbenchContext.tsx:112-140, src/components/CenterCanvas.tsx:49-65
Environment Parameters
The environment is defined by several categories of parameters that influence both the export process and the runtime performance.
Core Export Settings
These settings map directly to optimum-cli arguments used during the ONNX compilation phase.
| Parameter | Type | Description | CLI Flag |
|---|---|---|---|
modelPath | string | Repository ID or local directory path. | -m |
task | string | The specific ONNX task map (e.g., causal-lm). | --task |
opset | number | ONNX operator version (14, 15, or 17). | --opset |
device | string | Target hardware (cpu or cuda). | --device |
dtype | string | Precision override (fp32, fp16, bf16). | --dtype |
optimize | string | Graph optimization level (none, O1-O4). | --optimize |
Sources: src/types.ts:35-52, src/WorkbenchContext.tsx:142-168
Hardware and Execution Target
Configuration allows targeting specific execution providers. For instance, selecting cuda as the device maps to the webgpu provider in the browser-based benchmark runner, while cpu defaults to wasm.
Sources: src/lib/benchmark.ts:133-145
Structural and Validation Bounds
Users can configure structural directives that affect the final ONNX artifact's file structure and the precision validation against the original framework.
- Monolithic Weights: Forces the model into a single file, avoiding shards. Sources: src/components/CenterCanvas.tsx:147-158
- Force Split: Partitions components like encoder/decoder into separate files. Sources: src/components/CenterCanvas.tsx:162-171
- Tolerance (ATOL/RTOL): Sets the absolute and relative tolerance for comparing PyTorch and ONNX outputs. Sources: src/components/CenterCanvas.tsx:219-224
Profile and Preset Management
To streamline environment setup, the system supports "Optimization Profiles." These are stored in localStorage and can be switched dynamically.
System Presets
The project includes several predefined "System Benchmarks" for common targets:
- WebGPU fp16 Target: Optimized for modern GPU acceleration using O3 optimization and half-precision.
- CPU fp32 Portable: Focused on compatibility using O1 optimization and monolithic sharding.
- CUDA bf16 Heavy: Designed for high-end accelerators requiring component splitting (O4 optimization).
Sources: src/WorkbenchContext.tsx:6-37
Persistence Logic
User-defined presets are managed via the savePreset and loadPreset functions, which serialize the current ExportConfig to the onnx_workbench_presets key in browser storage.
Source Strategy Configuration
The environment supports two primary model ingestion pathways:
- Hugging Face Hub: Models are fetched dynamically via repository IDs (e.g.,
openai/whisper-base). - Local Path / Ingest: Users can drag-and-drop
.onnxfiles directly into the browser. The system creates a blob URL to use as themodelPathfor benchmarking.
Sources: src/components/Sidebar.tsx:109-178, src/WorkbenchContext.tsx:112-132
Conclusion
The Environment Configuration system ensures a seamless transition from parameter definition to model orchestration. By centralizing all export and benchmark variables into a single, observable state, ONNX-Station enables reproducible AI model deployment across diverse hardware targets.