--- title: "Managing Model Files" description: "Upload and manage ONNX and TFLite model files" source_url: https://ai-ops.com/docs/models/model-files --- # Managing Model Files Model files contain the pre-trained neural network weights and structure that Koios uses for inference. Models must be [trained externally](https://ai-ops.com/docs/models/training-a-model.md) and exported as ONNX or TFLite before uploading. Each model can have multiple file versions, but only one is **active** at a time. ## Supported Formats | Format | Extension | Notes | |--------|-----------|-------| | **ONNX** | `.onnx` | Must not use external data files. Batch dimension can be dynamic; time/depth dimension must be static. IR version must be 13 or lower. | | **TFLite** | `.tflite` | Must have at least 2 dimensions (batch and depth). | Both formats must use **float32** data type. --- ## Uploading a File Open the model's **Files** tab and click **Upload New File**. | Field | Required | Description | |-------|----------|-------------| | **File** | Yes | Drag and drop or click to select an `.onnx` or `.tflite` file | | **Version** | No | A label like `1.0.0` or `v2-beta`. Auto-generated if left blank (e.g. `warm-fox-12`). Must be unique per model. | | **Notes** | No | Optional notes about this version | ### What Happens During Upload Koios validates the file and extracts: | Property | Description | |----------|-------------| | **num_inputs** | Number of input features (creates one input binding per feature) | | **num_outputs** | Number of output features (creates one output binding per feature) | | **input_depth** | Number of historical time steps the model expects | | **output_depth** | Number of future time steps the model predicts (1 for single-step models) | If this is the model's **first file**, it is automatically activated and bindings are created. For subsequent uploads, you choose when to activate. --- ## Activating a File When you upload a second or later file, Koios shows a post-upload step before activation: ### Activation Preview Before activating, Koios shows what will change: - **Binding changes** — if the new file has a different number of inputs or outputs, bindings will be added or removed. Existing bindings (and their tag assignments) are preserved where the binding order matches. - **Action map diff** (discrete models only) — if the new file's action map differs from the current one, you can choose to keep the current map or use the new file's map. - **Metadata preview** — if the file contains embedded metadata, a summary shows what will be applied (see [Embedded Metadata](#embedded-metadata) below). You can toggle this on or off. Click **Set as Active** to activate, or **Close** to keep the current file active and activate later. ### Activating Later From the file version history on the Files tab, click the **Set Active** button on any inactive file. You'll see the same activation preview before confirming. ### Binding Review After activation, a review step lets you verify and edit binding names and descriptions. Named bindings enable fuzzy tag matching recommendations, so it's worth filling these in. --- ## File Version History The Files tab shows all uploaded versions in a timeline, newest first. The active file is marked with a checkmark and an **Active** badge. Each version shows: - Version label and filename - Input/output counts and input depth - Creation timestamp - Action count (for discrete models) ### Actions per File | Action | Description | |--------|-------------| | **Set Active** | Activate this file (not shown on the currently active file) | | **View** | Open the file's detail page with structure visualization and metadata | | **Download** | Download the original file | | **Edit** | Change the version label or notes | | **Delete** | Remove this version (disabled for the active file) | --- ## Embedded Metadata ONNX files can include Koios-specific metadata that is automatically applied to the model's configuration and bindings. This reduces manual setup — especially useful when deploying models from a training pipeline. > [!NOTE] Evolving feature > Embedded metadata support is functional but still being expanded. The properties described below are supported today. Additional metadata fields and tooling for embedding them during training are planned. ### How It Works Metadata is stored as custom properties in the ONNX file's `metadata_props`, using keys prefixed with `koios.`. When a file with metadata is uploaded: - **First file:** metadata is applied automatically - **Subsequent files:** you can toggle "Apply metadata from this file" during activation ### Training Metadata (`koios.training`) Applied to the model's configuration: | Key | Applied To | |-----|-----------| | `sample_rate` | Model's sample rate and scan rate | | `model_type` | Output application (Absolute / Relative) | | `output_mode` | Output mode (Continuous / Discrete) | | `action_map` | Action map on the model file (discrete models) | ### Binding Metadata (`koios.bindings`) Applied to each binding by binding order: | Key | Applied To | |-----|-----------| | `name`, `description` | Binding name and description | | `normalization_type` | Normalization type (None / Min-Max / Symmetric / Z-Score) | | `normalization_source` | Normalization source (Tag Range / Custom) | | `custom_minimum`, `custom_maximum` | Custom normalization bounds | | `custom_mean`, `custom_std` | Custom Z-Score parameters | | `range_min`, `range_max` | Failure range bounds | ### Reset from Metadata If a model has an active file with embedded metadata, you can re-apply it at any time using the **Reset from Metadata** action on the model's overview page. This updates configuration and binding settings from the metadata without affecting tag assignments. ### Viewing Metadata Open the file's detail page (click **View** on any file version) and go to the **Metadata** tab to see the raw training and binding metadata extracted from the file. --- ## File Detail Page Each file version has its own detail page with: | Tab | Content | |-----|---------| | **Overview** | Input depth, output depth, creation date. For discrete models, the action map editor. | | **Visualize** | Interactive network graph of the model structure (rendered via Netron) | | **Metadata** | Training info and binding metadata extracted from the file (ONNX only) | --- ## What's Next - [Assigning Bindings](https://ai-ops.com/docs/models/assigning-bindings.md) — connect model inputs and outputs to tags - [Model Inference Requirements](https://ai-ops.com/docs/models/inference-requirements.md) — tensor shape requirements and data preparation