Hello World

Start building reproducible ML experiments in minutes. This guide walks you through creating and running your first Valohai execution with the help of the valohai-utils library.

Prerequisites

• Python 3.8 or later

• A Valohai account (create one free)

Install the CLI

Get the Valohai CLI and utilities for experiment tracking:

pip install valohai-cli

Tip: Use pipx install valohai-cli to avoid dependency conflicts.

Login

vh login

Using SSO or self-hosted Valohai?

SSO Users (Azure, Google, SAML)

Generate a personal access token:

1. Go to Hi, [username] → My Profile → Authentication

2. Click Manage Tokens → Create a new personal token

3. Save the token securely (shown only once)

vh login --token <your-token>

Self-Hosted Installations

vh login --host https://your-company.valohai.io

💡 Combine options: vh login --host https://your-company.valohai.io --token <token>

Create Your First Project

Set up a project directory and connect it to Valohai:

mkdir my-ml-project
cd my-ml-project
vh project create --name my-ml-project

This links your local directory to Valohai for experiment tracking.

Already have a project? Link to it with vh project link and select from the list.

Write Your Training Script

Save this as train.py:

import valohai
import json

# Define hyperparameters with automatic tracking
params = {
    "learning_rate": valohai.parameters("learning_rate").value,
    "epochs": valohai.parameters("epochs").value,
}

print(f"Training with lr={params['learning_rate']} for {params['epochs']} epochs")

# Simulate training (replace with your model code)
for epoch in range(params["epochs"]):
    accuracy = 0.85 + (epoch * 0.02)  # Mock improving accuracy
    valohai.log_metric("accuracy", accuracy, step=epoch)
    print(f"Epoch {epoch}: accuracy={accuracy:.3f}")

# Save model or results
output_path = valohai.outputs().path("model_results.json")
with open(output_path, "w") as f:
    json.dump(
        {
            "final_accuracy": accuracy,
            "parameters": params,
            "model_version": "1.0",
        },
        f,
    )

print(f"Results saved to {output_path}")
print("Training complete!")

Configure Your Execution Environment

Create valohai.yaml to define how your code runs:

- step:
    name: train
    image: python:3.9
    command:
    - pip install valohai-utils
    - python train.py
    parameters:
      - name: learning_rate
        type: float
        default: 0.001
      - name: epochs
        type: integer
        default: 10

About Docker Images

The image field specifies your execution environment. Think of it as a clean environment with only the software you specify. For example:

• Python: python:3.9, python:3.11

• TensorFlow: tensorflow/tensorflow:2.13.0

• PyTorch: pytorch/pytorch:2.0.0-cuda11.7-cudnn8-runtime

• R: r-base:4.3.0

• Custom: Your own Docker images with specific dependencies

Note: The Docker image can different from your local Python version. Valohai runs your code in this isolated environment for reproducibility.

Run Your First Execution

Submit the job and watch logs in real-time:

vh execution run train --adhoc --watch

What happens:

• --adhoc uploads your current code without pushing to Git (great for testing)

• --watch streams logs to your terminal

• Valohai tracks all inputs, outputs, and parameters automatically

View Results in the UI

Open your execution in the browser:

vh execution open

The UI shows:

• Real-time logs and metrics charts

• Parameter values and configuration

• Output files (downloadable)

• Full reproducibility information

What's Next?

You've successfully run your first Valohai execution! Here's where to go next:

🎓 Valohai Academy Free courses on MLOps best practices and advanced Valohai features

Working with Data Upload datasets and connect them to executions

Building Pipelines Chain multiple steps for end-to-end ML workflows

Using Git Integration Connect repositories for production-ready experiments

---

Troubleshooting

Command 'vh' not found

The CLI isn't in your system PATH. Fix it:

macOS/Linux:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows: Add the Python Scripts folder to your PATH environment variable.

Alternative: Run with python -m valohai_cli instead of vh.

Project not linked

Run vh project link to connect your directory to an existing Valohai project.

Import error for valohai module

Install the Valohai utilities as a part of your step in valohai.yaml:

pip install valohai-utils