Start Training

You have joined a use case and accepted the terms. Training a model is easy: you run a Jupyter notebook locally to connect and submit models to the platform. For a smooth first run, let’s follow the step by step notebook in the public GitHub repository along with the documentation below. Alternatively, run the same notebook in Google Colab, with nothing to install locally. Click Start training on the use case page: it opens the notebook in Google Colab in a new tab. Choose File > Save a copy in Drive to run and edit your own copy, then jump directly to Step 1.

Pull Training Notebook and Model Repositories

On your machine, pull the Quickstart GitHub repository and, inside it, the Model Zoo GitHub repository. The notebook contains all commands to connect and start training, the model zoo contains starter templates that you adapt to the use case’s parameters. The easiest way to customize models is by starting from the model zoo. Open a terminal and run the following commands:

git clone https://github.com/tracebloc/quickstart.git
cd quickstart
git clone https://github.com/tracebloc/model-zoo.git

This puts the model zoo at quickstart/model-zoo, where the notebook looks for it: the notebook’s clone cell skips the clone when the folder exists. The notebook runs from quickstart/notebooks, so model paths in the notebook start with ../model-zoo/model_zoo/.

Create a Virtual Environment

The SDK requires Python 3.11 or later (>=3.11,<3.15); Python 3.11 or 3.12 is recommended. On an older Python, no release satisfies the >=1.2.42 requirement below, so pip stops with a No matching distribution found error instead of installing anything. Create an environment named, for example, “tracebloc”. Python’s built-in venv is the lightest option; use Anaconda if you already work with conda:

venv
conda

python3.12 -m venv .venv    # or python3.11
source .venv/bin/activate   # Windows: .venv\Scripts\activate

conda create -n tracebloc python=3.12
conda activate tracebloc

Then, install requirements:

python -m pip install --upgrade pip

# Install with the extra that matches your framework:
pip install "tracebloc[pytorch]>=1.2.42"
# pip install "tracebloc[sklearn]>=1.2.42"
# pip install "tracebloc[all]>=1.2.42"  # pytorch + sklearn + lifelines + scikit-survival

Install and Launch Jupyter Notebook

Install Jupyter into your environment:

python -m pip install notebook

Launch the notebook:

jupyter notebook notebooks/traceblocTrainingGuide.ipynb

1. Connect to the tracebloc platform

Follow the instructions in the notebook to authenticate. Have your tracebloc user credentials ready:

Getting Help

For more info about available functions and methods, call the help function:

user.help()

2. Upload Model & Customize

Choose a model from the tracebloc model zoo, it is the easiest way to get started. The model zoo provides starter templates you can modify freely. Make sure the mandatory variables in your model file match the use case parameters. You can find all the necessary info from the use case description and exploratory data analysis (EDA). Alternatively, you can define your own architecture from scratch.

Model Parameters by Task

Every model file declares framework, main_class (or main_method for a function-based model), batch_size and category. Add the task-specific variables below:

Data Type	Task	Model Parameters
Image	Classification	`image_size` has to match image x/y-dimensions `output_classes` has to match # of image classes
Image	Object Detection	`image_size` = input edge the model is built for; images are resized to it `output_classes` has to match # of object types `model_type` = `torchvision_detection` for torchvision-style detectors, or `yolo` for the grid models in the zoo’s `yolo_v*` folders, which ship a `loss.py`
Image	Semantic Segmentation	`image_size` has to match image x/y-dimensions `output_classes` has to match # of object classes
Image	Keypoint Detection	`image_size` has to match image x/y-dimensions `output_classes` has to match # of object classes `num_feature_points` has to match # of keypoints
Tabular	Tabular Classification	`output_classes` has to match # of classes `num_feature_points` has to match # of features
Tabular	Tabular Regression	`num_feature_points` has to match # of features
Tabular	Time-to-Event Prediction	`num_feature_points` has to match # of features
Time series	Time Series Classification	`output_classes` has to match # of classes `num_feature_points` has to match # of feature columns `sequence_length` = time steps per window
Time series	Time Series Forecasting	`num_feature_points` has to match # of feature columns `sequence_length` = time steps per input window `forecast_horizon` = # of future steps to predict
Text	Text Classification	`sequence_length` = tokens per sample (max. 512) `output_classes` has to match # of classes
Text	Sentence Pair Classification	`sequence_length` = tokens per sample (max. 512) `output_classes` has to match # of classes
Text	Token Classification	`sequence_length` = tokens per sample (max. 512) `output_classes` has to match # of distinct tags (for example BIO tags)
Text	Masked Language Modeling	`sequence_length` = tokens per sample (max. 512) `vocab_size` has to match the tokenizer and the model’s token-embedding size
Text	Causal Language Modeling	`sequence_length` = tokens per sample (max. 512) `vocab_size` has to match the tokenizer and the model’s token-embedding size
Text	Seq2Seq	`sequence_length` = tokens per sample (max. 512) `vocab_size` has to match the tokenizer and the model’s token-embedding size
Text	Embeddings	`sequence_length` = tokens per sample (max. 512) `vocab_size` has to match the tokenizer and the model’s token-embedding size

Text models also ship their tokenizer: put a <model>_tokenizer.json (or tokenizer.json) next to the model file, where the SDK picks it up automatically, or pass its path with user.upload_model(..., tokenizer="path/to/tokenizer.json"). The text models in the model zoo come with their tokenizer file. The SDK matches <model>_tokenizer.json by the model file’s name, so when you copy or rename a model-zoo file (for example to try another batch_size), copy and rename its tokenizer too: distilgpt2.py and distilgpt2_tokenizer.json become distilgpt2_bs4.py and distilgpt2_bs4_tokenizer.json. A text model uploaded without a tokenizer fails validation.

Example

A 3-way classification task on 224x224 images with LeNet would need the following lenet.py configuration:

import torch
import torch.nn as nn

# Mandatory variables, adapt as necessary.
framework = "pytorch"
main_class = "MyModel"
image_size = 224
batch_size = 16
output_classes = 3
category = "image_classification"


class MyModel(nn.Module):
    def __init__(self):
        super(MyModel, self).__init__()
        self.layer1 = nn.Sequential(
            nn.Conv2d(3, 6, kernel_size=5, stride=1, padding=0),
            nn.BatchNorm2d(6),
            nn.ReLU(),
            nn.MaxPool2d(kernel_size=2, stride=2),
        )
        self.layer2 = nn.Sequential(
            nn.Conv2d(6, 16, kernel_size=5, stride=1, padding=0),
            nn.BatchNorm2d(16),
            nn.ReLU(),
            nn.MaxPool2d(kernel_size=2, stride=2),
        )
        self.fc = nn.Linear(16 * 53 * 53, 120)
        self.relu = nn.ReLU()
        self.fc1 = nn.Linear(120, 84)
        self.relu1 = nn.ReLU()
        self.fc2 = nn.Linear(84, output_classes)

    def forward(self, x):
        out = self.layer1(x)
        out = self.layer2(out)
        out = out.reshape(out.size(0), -1)
        out = self.fc(out)
        out = self.relu(out)
        out = self.fc1(out)
        out = self.relu1(out)
        out = self.fc2(out)
        return out

The variables at the top are mandatory for the use case but the model definition is fully flexible. Open the model file from the model zoo in your editor, e.g.:

model-zoo/model_zoo/image_classification/pytorch/lenet.py

Modify the architecture however you like: add layers, change activations, swap to a different backbone entirely. The only requirement is that the mandatory variables (framework, main_class, image_size, batch_size, output_classes, category) stay consistent with the use case parameters. In case of multiple uploads, only the most recently uploaded model will be linked to the dataset.

Upload

Upload the model to the use case from your notebook:

user.upload_model(model_name="../model-zoo/model_zoo/<task>/<framework>/model.py")

The model zoo’s YOLO templates (yolo_v1/, yolo_v5/, yolo_v8/) are folders holding model.py and the loss.py the model trains with. Upload the .zip that sits next to each folder, not the folder’s model.py:

user.upload_model(model_name="../model-zoo/model_zoo/object_detection/pytorch/yolo_v8.zip")

Many model zoo templates are pretrained models, for example distilgpt2, t5_small and vit_google. They build their architecture without the pretrained weights. The weights come in a separate <template>_weights.pkl file, which is not in the model zoo repository. Without it, the model trains from random weights. Fetch the file into the model file’s directory with user.fetch_seed_weights(), then upload with weights=True:

model_dir = "../model-zoo/model_zoo/causal_language_modeling/pytorch"

# Writes distilgpt2_weights.pkl next to distilgpt2.py
user.fetch_seed_weights("distilgpt2", directory=model_dir)
user.upload_model(model_name=f"{model_dir}/distilgpt2.py", weights=True)

Object detection works the same way. These object detection templates have a seed: faster_rcnn_convnext_small, faster_rcnn_resnet_v2, faster_rcnn_swin_t, fcos_convnext_small, fcos_swin_t, retinanet_v2, ssd_vgg16 and ssdlite_mobilenet. Their seed carries the backbone only: the class head starts fresh, sized by output_classes.

model_dir = "../model-zoo/model_zoo/object_detection/pytorch"

user.fetch_seed_weights("ssdlite_mobilenet", directory=model_dir)
user.upload_model(model_name=f"{model_dir}/ssdlite_mobilenet.py", weights=True)

For a template without pretrained weights, fetch_seed_weights raises an error saying so. The SDK matches the weights file by the model file’s name, as it does the tokenizer, so if you rename the model file, rename the weights file too: distilgpt2_bs4.py needs distilgpt2_bs4_weights.pkl. For details on model code formats, mandatory variables per framework, and pre-trained weights, see Customize Models.

3. Link Model with Dataset

Navigate to the use case and copy the “Training Dataset ID” at the center of the use case pane and enter it to establish the link

training_plan = user.link_model_dataset(dataset_id='Dataset ID')

You should get “Assignment successful!” and the dataset parameters.

4. Configure the experiment

Set the experiment name and configure hyperparameters.

# Set experiment name
training_plan.experiment_name("My Experiment")

# Set training parameters
training_plan.epochs(10)
...

# Check the experiment's settings
training_plan.get_training_plan()

Call get_training_plan() to check the settings before you start the training. For a detailed list of all hyperparameter options, see Hyperparameters. For classical, non federated and non gradient descent-based machine learning algorithms like random forests, XGBoost, SVMs, logistic regression, use simplified settings:

# Set training parameters
training_plan.epochs(1)

# Set federated learning cycles = 1
training_plan.cycles(1)

5. Start Training

To send the model to the data owner’s secure environment and start training on the training data, run:

training_plan.start()

Go to the tracebloc website and your use case, then navigate to the “Training/Finetuning” tab you will see your experiment. Monitor the training process hover over the learning curves to check the performance at specific epochs and cycles.

If you want to run a second experiment, overwrite parameters and re-start training with training_plan.start().

Pause, Re-Start and Stop:

To pause, stop, or resume running experiments, click here:

Resuming restarts the interrupted cycle from its start, so the epochs that cycle already ran are repeated. Once stopped, an experiment cannot be rerun. Note: The compute budget is set by the use case owner. Your team shares one compute budget with no per-person limit.

Submit an Experiment to the Leaderboard

Once training is complete, submit your best model to the leaderboard for evaluation on the test dataset. For the full submission flow and leaderboard details, see the Evaluate Model guide.

Inviting Others to Your Team

See the Join guide for instructions.

Next Steps

customize models: Follow model optimisation.

Need Help?

For more info about available functions and methods, call the help function in your notebook:

user.help()

Email us at [email protected]

Overview

Create a Use Case

Join a Use Case

Environment Setup

Tools & Help

Releases

Pull Training Notebook and Model Repositories

Create a Virtual Environment

Install and Launch Jupyter Notebook

1. Connect to the tracebloc platform

Getting Help

2. Upload Model & Customize

Model Parameters by Task

Example

Upload

3. Link Model with Dataset

4. Configure the experiment

5. Start Training

Pause, Re-Start and Stop:

Submit an Experiment to the Leaderboard

Inviting Others to Your Team

Next Steps

Need Help?

​Pull Training Notebook and Model Repositories

​Create a Virtual Environment

​Install and Launch Jupyter Notebook

​1. Connect to the tracebloc platform

​Getting Help

​2. Upload Model & Customize

​Model Parameters by Task

​Example

​Upload

​3. Link Model with Dataset

​4. Configure the experiment

​5. Start Training

​Pause, Re-Start and Stop:

​Submit an Experiment to the Leaderboard

​Inviting Others to Your Team

​Next Steps

​Need Help?

Pull Training Notebook and Model Repositories

Create a Virtual Environment

Install and Launch Jupyter Notebook

1. Connect to the tracebloc platform

Getting Help

2. Upload Model & Customize

Model Parameters by Task

Example

Upload

3. Link Model with Dataset

4. Configure the experiment

5. Start Training

Pause, Re-Start and Stop:

Submit an Experiment to the Leaderboard

Inviting Others to Your Team

Next Steps

Need Help?