Fine-tuning with a Specific Loss Function

This tutorial shows how to fine-tune a model using a specific loss function. You will learn which loss functions are supported, how to configure your Nixtla client, and how to evaluate different approaches for best results.

When you fine-tune, the model trains on your dataset to tailor predictions to your specific scenario. You can specify the loss function to be used during fine-tuning. Below are the available loss functions:

Default

A proprietary function robust to outliers.

MAE

Mean Absolute Error

MSE

Mean Squared Error

RMSE

Root Mean Squared Error

MAPE

Mean Absolute Percentage Error

sMAPE

Symmetric Mean Absolute Percentage Error

1. Import Packages

Make sure you have the necessary dependencies installed (such as pandas and nixtla).

Imports for Fine-Tuning
import pandas as pd
from nixtla import NixtlaClient
from utilsforecast.losses import mae, mse, rmse, mape, smape

Initialize the NixtlaClient object
Replace api_key='my_api_key_provided_by_nixtla' with the API key from your Nixtla account.

Nixtla Client Initialization
nixtla_client = NixtlaClient(
    # defaults to os.environ.get("NIXTLA_API_KEY")
    api_key='my_api_key_provided_by_nixtla'
)

Using an Azure AI endpoint
Pass the base_url argument explicitly:

Azure AI Client Example
nixtla_client = NixtlaClient(
    base_url="your azure ai endpoint",
    api_key="your api_key"
)

2. Load Data

Load your data and prepare it for fine-tuning. Here, we will demonstrate using an example dataset of air passenger counts.

Load Air Passengers Data
df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv')
df.insert(loc=0, column='unique_id', value=1)

df.head()

	unique_id	timestamp	value
0	1	1949-01-01	112
1	1	1949-02-01	118
2	1	1949-03-01	132
3	1	1949-04-01	129
4	1	1949-05-01	121

3. Fine-Tune the Model

Fine-tuning with MAE

To fine-tune using Mean Absolute Error (MAE), specify finetune_loss='mae' in the forecast method:

Fine-Tuning with MAE Loss
timegpt_fcst_finetune_mae_df = nixtla_client.forecast(
    df=df,
    h=12,
    finetune_steps=10,
    finetune_loss='mae',   # Select desired loss function
    time_col='timestamp',
    target_col='value',
)

Azure AI Model
If you are using Azure AI, set model="azureai" in your forecast call:

Azure AI Model Forecast Call
nixtla_client.forecast(..., model="azureai")

For the public API, timegpt-1 and timegpt-1-long-horizon are supported. By default, timegpt-1 is used. See the Long Horizon Forecasting Tutorial for more details.

Fine-tuning Log Output

Log Output
INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: MS
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...

After training completes, you can visualize the forecast:

Plot Forecast Results
nixtla_client.plot(
    df, 
    timegpt_fcst_finetune_mae_df, 
    time_col='timestamp', 
    target_col='value',
)

Fine tuning with MAE

For other fine-tuning configurations, simply change finetune_loss to your preferred loss function (mse, rmse, mape, or smape).

Details of Each Loss Function

Selecting the appropriate loss function during fine-tuning ensures the model is optimized around what matters most for your use case.

Perform a quick evaluation to compare metrics across different loss functions. Fine-tuning with a specific loss can yield better accuracy for your goals.

	mae	mse	rmse	mape	smape
Metric improvement (%)	8.54	0.31	0.64	31.02	7.36

By aligning the model’s training objective with your key evaluation metric, you achieve more targeted performance improvements for your forecasting tasks.

QUICK START

GETTING STARTED

CAPABILITIES

DEPLOYMENT

TUTORIALS

USE CASES

REFERENCE

About

Default

MAE

MSE

RMSE

MAPE

sMAPE