# Training

## Overview

Start your model training with LuxonisTrain using the CLI or Python API. Below are examples of how to call the training process
and what the configuration looks like.

### CLI

To train your model, use the following command:

```bash
luxonis_train train --config configs/detection_light_model.yaml
```

You can also customize configuration parameters directly from the command line if needed:

```bash
luxonis_train train \
  --config configs/detection_light_model.yaml \
  loader.params.dataset_dir "roboflow://team-roboflow/coco-128/2/coco"
```

This command overrides the loader.params.dataset_dir parameter in the configuration file.

train, test, and tune can also be run with the --debug flag when you want to exercise the model setup without a fully functional
dataset.

### Python API

Alternatively, you can use the Python API for more programmatic control:

```python
from luxonis_train import LuxonisModel

model = LuxonisModel(
  "configs/detection_light_model.yaml",
  {"loader.params.dataset_dir": "roboflow://team-roboflow/coco-128/2/coco"}
)
model.train()
```

### Configuration File Example

Below is a sample configuration file, detection_light_model.yaml, used for training. For more information about the model, please
see the [Detection Model
details](https://github.com/luxonis/luxonis-train/blob/main/luxonis_train/config/predefined_models/README.md#detectionmodel).

The trainer section is very important and influences the training process. To learn more about the trainer hyperparameters, refer
to the [Luxonis Train Trainer section](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#trainer).

In this example, the dataset will be parsed to create the LuxonisDataset dataset. However, if you are using a custom dataset,
ensure your dataset is structured according to the LuxonisDataset format. For detailed guidance on preparing your data, refer to
the [LuxonisML](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml.md) docs.

```yaml
model:
  name: model_name

  predefined_model:
    name: DetectionModel
    params:
      variant: light
      loss_params:
        iou_type: "siou"
        n_warmup_epochs: 0

loader:
  params:
    dataset_name: "coco_test"
    dataset_dir: "roboflow://team-roboflow/coco-128/2/coco"

trainer:
  batch_size: 8
  epochs: 200
  n_workers: 8
  validation_interval: 10

  preprocessing:
    train_image_size: [384, 384]
    normalize:
      active: true
    augmentations:
      - name: Defocus
      - name: Sharpen
      - name: Flip

  callbacks:
    - name: ConvertOnTrainEnd
    - name: TestOnTrainEnd

  optimizer:
    name: SGD
    params:
      lr: 0.02

  scheduler:
    name: ConstantLR
```

Important aspects of training include hyperparameter tuning and tracking your training process.

## Hyperparameter Tuning

If not using one of the predefined models and the hyperparameters provided with them from
[here](https://github.com/luxonis/luxonis-train/tree/main/configs), it is advisable to perform hyperparameter tuning before
tackling the training on a larger dataset.

Hyperparameter tuning is essential for achieving optimal model performance. LuxonisTrain leverages Optuna to help you experiment
with different hyperparameter settings, improving model accuracy and efficiency.

For more information, see the [LuxonisTrain tuner configuration
reference](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#tuner).

### Configuration Example

Include a tuner section in your configuration file:

```yaml
tuner:
  study_name: det_study
  n_trials: 10
  storage:
    backend: sqlite
  params:
    trainer.optimizer.name_categorical: ["Adam", "SGD"]
    trainer.optimizer.params.lr_float: [0.0001, 0.001]
    trainer.batch_size_int: [4, 16, 4]
```

### CLI

To start the hyperparameter tuning process, use the following command:

```bash
luxonis_train tune --config configs/example_tuning.yaml
```

### Python API

You can also use the Python API to start the tuning process:

```python
from luxonis_train import LuxonisModel

model = LuxonisModel("configs/example_tuning.yaml")
model.tune()
```

## Tracking

Tracking the training process is crucial for monitoring model performance, diagnosing issues, and making informed improvements.
LuxonisTrain supports popular tracking tools and remote database storage to facilitate effective logging and tracking throughout
your training workflow.

For more information, see the [Tracker Luxonis-train
section](https://github.com/luxonis/luxonis-train/blob/main/configs/README.md#tracker).

### Supported Tracking Tools

 * MLFlow: To use MLFlow for tracking, the following environment variables are required:
   
   * MLFLOW_S3_BUCKET
   * MLFLOW_S3_ENDPOINT_URL
   * MLFLOW_TRACKING_URI

 * WandB (Weights & Biases): To use WandB, you will need:
   
   * WANDB_API_KEY

 * TensorBoard: Luxonis Train also supports TensorBoard for visualizing your training process.

### Remote Database Storage

For remote database storage, we support:

 * POSTGRES_PASSWORD
 * POSTGRES_HOST
 * POSTGRES_PORT
 * POSTGRES_DB

### Configuration Example

Here's an example of how to configure tracking in your detection_light_model.yaml file:

```yaml
tracker:
  project_name: coco_test
  save_directory: output
  is_tensorboard: true
  is_wandb: false
  is_mlflow: false
```

> Make sure to set the necessary environment variables based on the tracking tool you choose to use.