# Models

Valohai Model Hub is a centralized registry for managing machine learning models throughout their lifecycle, from training to production deployment.

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-0502eee99c44f09919cc1c210f728ed04c8eb6c3%2Fimage.png?alt=media" alt=""><figcaption><p><strong>Centralized model documentation with version control.</strong> Customize fields and use markdown to document model details in the main view. The sidebar highlights the current approved version with download options and displays version history with approval status indicators (approved/pending/rejected).</p></figcaption></figure>

***

### Why Use Model Hub

#### The Problem: Scattered Model Artifacts

Without a model registry:

* Models saved as random files in cloud storage
* No clear "which model is in production?"
* Can't trace which data trained which model
* Manual approval processes via Slack/email
* No version comparison or rollback capability
* Team members can't find the right model

**Example chaos:**

```
s3://ml-bucket/project-a/
├── model_final.pkl
├── model_final_v2.pkl
├── model_actually_final.pkl
├── prod_model_jan.h5
└── best_model_DO_NOT_DELETE.pth
```

***

#### The Solution: Centralized Model Registry

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-458d4db0cd28bac57115ac8f9d7bbd8f2e8b1850%2Fimage.png?alt=media" alt=""><figcaption><p><strong>Centralized model inventory across all projects.</strong> Browse models with their latest version status (approved/pending), last modified date, associated projects, and ownership. Provides visibility into all models in the organization with filtering and search capabilities for easy discovery.</p></figcaption></figure>

Model Hub provides:

* **Single source of truth** for all models
* **Automatic versioning** from training pipelines
* **Built-in approval workflow** (pending → approved → rejected)
* **Complete lineage tracking** (data → code → model)
* **Version comparison** with metrics and artifacts
* **Access control** for governance
* **model:// URIs** for consistent references

**Example organization:**

```
model://customer-churn/v1 (approved, production)
model://customer-churn/v2 (pending review)
model://customer-churn/v3 (rejected, overfitting)
```

***

### Model Hub vs. Saving Model Files

#### When to Use Model Hub

| Scenario                            | Use Model Hub | Just Save Files |
| ----------------------------------- | ------------- | --------------- |
| **Production models**               | ✅ Yes         | ❌ No            |
| **Need approval workflow**          | ✅ Yes         | ❌ No            |
| **Multiple model versions**         | ✅ Yes         | ❌ No            |
| **Team collaboration**              | ✅ Yes         | ❌ No            |
| **Lineage tracking needed**         | ✅ Yes         | ✅ Yes           |
| **Quick experiment checkpoint**     | ⚠️ Optional   | ✅ Yes           |
| **Intermediate training artifacts** | ❌ No          | ✅ Yes           |

***

#### Workflow Comparison

**Without Model Hub:**

```python
# Training
model.save("/valohai/outputs/model.pkl")

# Later... where is the production model?
# Check Slack, find S3 path, download, hope it's the right one
```

**With Model Hub:**

```python
# Training: Create model version automatically
metadata = {
    "model.pkl": {
        "valohai.model-versions": ["model://customer-churn/"],
    },
}
```

```yaml
# Deployment: Reference current production model
inputs:
  - name: model
    default: model://customer-churn/v1  # Clear, versioned, approved
```

***

### Key Features

#### Automatic Lineage Tracking

Every model version automatically tracks:

* **Training data** — Which dataset versions were used
* **Code version** — Exact commit that trained the model
* **Hyperparameters** — All parameters from training
* **Environment** — Docker image, dependencies
* **Training metrics** — Loss, accuracy, custom metrics
* **Artifacts** — Model files, checkpoints, configs

**Benefit:** "Which data trained the production model?" → One click to see complete history.

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-de3a1a1081176f7b7f58b20279060938d366c11d%2Fimage.png?alt=media" alt=""><figcaption><p><strong>Model lineage view showing end-to-end traceability.</strong> The model (1) was created by execution #1805, which received preprocessed data from job #1799 that used training datasets and images.zip. Each execution is clickable to view full details. The right side shows downstream usage: this model has been consumed by 3 jobs, with one successfully generating predictions (3).</p></figcaption></figure>

***

#### Approval Workflow

Built-in state management for model lifecycle:

```
Training → model version created (Pending)
       ↓
    Review metrics and lineage
       ↓
    Approve → Production use
       OR
    Reject → Document why (overfitting, bias, etc.)
```

**States:**

* **Pending** — Newly created, awaiting review
* **Approved** — Validated for production use
* **Rejected** — Not suitable for production

**Benefit:** Clear approval trail for compliance and governance.

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-3572cd3154444255fc894bcb1804b25c51f50225%2Fimage.png?alt=media" alt=""><figcaption><p><strong>Complete audit trail of all model activities.</strong> Track when the model was used in executions (1), approved by team members like Sofia (2), and modified by users like Drazen (3). Every edit, usage, and approval of the model or its versions is automatically logged with timestamp, user, and location details.</p></figcaption></figure>

***

#### Version Comparison

Compare model versions side-by-side:

* Training metrics (accuracy, loss, F1)
* Hyperparameters
* Training data
* File sizes and artifacts
* Training duration

**Benefit:** "Is v2 really better than v1?" → Compare metrics directly.

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-aee810a19ea743e157233c362e04d8712af8264a%2Fimage%20(5)%20(1).png?alt=media" alt=""><figcaption><p><strong>Compare model versions visually by plotting performance metrics.</strong> Select metrics for the horizontal axis (2) and vertical axis (3) to visualize tradeoffs across different model versions (1).</p></figcaption></figure>

***

#### Unified Access

All models in one place:

* Organization view → All models across projects
* Project view → Models relevant to this project
* Search and filter by tags, state, metrics
* Download artifacts or use in pipelines

**Benefit:** No hunting through S3 buckets or file shares.

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-15ade6bad0fd16b3bb5eb2de5513bd75c3374046%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

***

### Use Cases

#### Production Model Management

**Scenario:** Deploy and monitor production models with approval gates.

```
Train weekly → Create model version (Pending)
            ↓
         Review performance
            ↓
    Better than current? → Approve
            ↓
    Update deployment to model://churn-model/latest
```

**Benefit:** Controlled releases with audit trail.

***

#### A/B Testing

**Scenario:** Compare model variants in production.

```yaml
# Deploy two versions simultaneously
- deployment-a:
    model: model://recommendation-engine/v5
    traffic: 90%

- deployment-b:
    model: model://recommendation-engine/v6
    traffic: 10%
```

**Benefit:** Safe model rollout with easy rollback.

***

#### Model Lineage & Compliance

**Scenario:** Audit which data trained production models.

```
Regulator: "Which customer data trained your credit model?"
       ↓
Model Hub: model://credit-score/v3 (production)
       ↓
Lineage: Trained on dataset://credit-data/2024-q1
       ↓
Dataset: Contains data from Jan-Mar 2024
```

**Benefit:** Complete audit trail for compliance.

***

#### Team Collaboration

**Scenario:** Multiple data scientists training models, ML engineer deploying.

```
Data Scientist A: Creates model://fraud-detection/v10 (Pending)
                  "Improved recall by 5%"
       ↓
Data Scientist B: Reviews metrics, approves
       ↓
ML Engineer: Deploys model://fraud-detection/v10
             (Knows it's reviewed and approved)
```

**Benefit:** Clear handoff between roles.

***

#### Experiment Tracking

**Scenario:** Track dozens of training runs, pick best.

```
Training sweep: 50 model versions with different hyperparameters
       ↓
Model Hub: Compare metrics, filter by accuracy > 0.9
       ↓
Approve top 3 → Further testing
Reject others → Document findings
```

**Benefit:** Organized experimentation with clear winners.

***

### model:// URI Format

Models are referenced using `model://` URIs, similar to `datum://` and `dataset://` links.

#### Format

```
model://<model-name>/<version>
```

**Examples:**

```
model://customer-churn/v1        # Specific version
model://customer-churn/v2        # Another version
model://customer-churn/latest    # Latest approved version
```

#### Using model:// URIs

**In valohai.yaml:**

```yaml
- step:
    name: batch-inference
    image: python:3.9
    command: python predict.py
    inputs:
      - name: model
        default: model://customer-churn/v1
      - name: data
        default: dataset://inference-data/daily
```

**In code:**

```python
# Model downloaded to /valohai/inputs/model/
model_path = "/valohai/inputs/model/model.pkl"
model = load_model(model_path)
```

**Benefit:** Consistent, versioned references across all workflows.

***

### Model Hub vs. Other Registries

| Feature                  | Valohai Model Hub | MLflow             | W\&B               | SageMaker Model Registry |
| ------------------------ | ----------------- | ------------------ | ------------------ | ------------------------ |
| **Built-in lineage**     | ✅ Automatic       | ⚠️ Manual logging  | ⚠️ Manual logging  | ❌ Limited                |
| **Approval workflow**    | ✅ Built-in        | ❌ No               | ❌ No               | ✅ Manual                 |
| **Versioned inputs**     | ✅ `model://` URIs | ⚠️ Manual paths    | ⚠️ Manual paths    | ✅ ARNs                   |
| **Access control**       | ✅ Built-in        | ⚠️ Enterprise only | ✅ Yes              | ✅ Yes                    |
| **Training integration** | ✅ Automatic       | ⚠️ Manual tracking | ⚠️ Manual tracking | ⚠️ Manual                |
| **Reproducibility**      | ✅ Full pipeline   | ⚠️ Model only      | ⚠️ Model only      | ⚠️ Model only            |

**Valohai differentiator:** Automatic lineage from full pipeline execution, not just model files.

***

### Getting Started

Ready to use Model Hub? Follow these guides:

1. [**Create and Manage Models**](https://docs.valohai.com/models/manage-models) — Create models, versions, approval workflow
2. [**Model Artifacts & Versioning**](https://docs.valohai.com/models/artifacts-and-versioning) — Save models from training, use in deployment

***

### Related Pages

* [Load Files in Jobs](https://docs.valohai.com/data/data-versioning/load-files-in-jobs) — Use models as execution inputs

***

### Next Steps

* Create your first model in Model Hub
* Set up automatic model versioning from training
* Configure approval workflow for your team
* Deploy using versioned `model://` URIs