Finetuning Configuration

Finetuning allows you to adapt pre-trained models to specific tasks or domains with minimal computational overhead. The finetuning process leverages existing model knowledge while updating parameters to optimize for your specific use case.

FinetuningConfig

The main configuration class for finetuning experiments, building on the ExperimentConfig structure.

base_model_path

str

required

Path to the pre-trained model checkpoint or Hugging Face model identifier to finetune from

data_configs

DataConfig or List[DataConfig]

required

Data configuration(s) for finetuning tasks. Supports multi-task finetuning scenarios.

finetuning_config

FinetuningOptimizationConfig

required

Finetuning-specific optimization parameters with typically lower learning rates

model_config

ModelConfig

required

Model architecture configuration. Must match the base model architecture.

meta_config

MetaConfig

default:"Uses MetaConfig defaults"

Metadata and run-specific parameters for the finetuning experiment

MetaConfig

Configuration for experiment metadata and checkpointing behavior.

name

str

default:"trial-run"

Name identifier for this finetuning experimental run.

seed

int

default:"42"

Random seed for reproducible finetuning.

save_path

str

default:"current working directory / run_name"

Directory path for saving finetuned model checkpoints.

model_save_frequency

int

default:"-1"

Frequency (in steps) for saving model checkpoints. Set to -1 to save only at the end of finetuning.

max_checkpoints

int

default:"-1"

Maximum number of model checkpoints to retain. Set to -1 for no limit.

wandb_config

WandbConfig or None

default:"None"

Weights & Biases logging configuration for finetuning experiment tracking and visualization

WandbConfig

Configuration for Weights & Biases experiment tracking and logging during finetuning.

project

str

required

Weights & Biases project name for organizing finetuning experiments

entity

str or None

default:"None"

Weights & Biases team/organization name. If None, uses the default entity associated with your API key.

run_name

str or None

default:"None"

Custom run name for the finetuning experiment. If None, uses the MetaConfig name or auto-generates one.

FinetuningOptimizationConfig

Specialized optimization configuration for finetuning with recommended parameter ranges.

total_training_steps

int

required

Total number of finetuning steps. Typically much lower than full training (500-5000 steps).

max_learning_rate

float

required

Maximum learning rate for finetuning. Recommended range: 1e-5 to 5e-4 (lower than full training).

global_batch_size

int

required

Global batch size for finetuning. Can be smaller than full training due to fewer steps.

learning_rate_schedule

str or callable

default:"linear"

Learning rate scheduling strategy for finetuning:

"linear": Linear decay (recommended for finetuning)
"cosine": Cosine annealing
"constant": Constant learning rate
Custom function with signature: (learning_rate, current_step, total_steps) → decayed_rate

warmup_steps

int

default:"50"

Number of learning rate warmup steps. Typically 5-10% of total finetuning steps.

weight_decay

float

default:"0.01"

L2 regularization coefficient. Important for preventing overfitting in finetuning.

gradient_accumulation_steps

int

default:"1"

Number of steps to accumulate gradients before updating. Useful for effective larger batch sizes.

freeze_layers

List[str] or None

default:"None"

List of layer patterns to freeze during finetuning. Example: ["embeddings", "layer.0", "layer.1"]

lora_config

LoRAConfig or None

default:"None"

Low-Rank Adaptation configuration for parameter-efficient finetuning

optimizer_type

str

default:"AdamW"

Optimizer algorithm. Options: "AdamW", "Adam", "SGD"

clip_grad

float

default:"1.0"

Gradient clipping threshold. Important for stability in finetuning.

LoRAConfig

Configuration for Low-Rank Adaptation (LoRA) parameter-efficient finetuning.

rank

int

default:"16"

Rank of the adaptation matrices. Higher rank = more parameters but better expressiveness.

alpha

float

default:"32"

LoRA scaling parameter. Controls the magnitude of the adaptation.

dropout

float

default:"0.1"

Dropout probability for LoRA layers.

target_modules

List[str] or None

default:"Auto-detected"

List of module names to apply LoRA to. If None, automatically targets attention and MLP layers.

bias

str

default:"none"

Bias handling strategy:

"none": No bias adaptation
"all": Adapt all biases
"lora_only": Only adapt LoRA biases

FinetuningDataConfig

Extended data configuration with finetuning-specific options.

data_paths

str or List[str]

required

Path(s) to finetuning data files. Should be formatted according to your task type.

task_type

str

default:"text_generation"

Type of finetuning task:

"text_generation": Generative language modeling
"classification": Text classification
"instruction_following": Instruction-tuning
"code_generation": Code completion/generation
"time_series_forecasting": Time series tasks

max_sequence_length

int

default:"512"

Maximum sequence length for finetuning examples. Shorter than training can speed up finetuning.

validation_split

float

default:"0.1"

Portion of data reserved for validation during finetuning.

data_preprocessing

dict or None

default:"None"

Task-specific preprocessing options:

For instruction tuning: {"format": "alpaca", "prompt_template": "..."}
For classification: {"label_column": "label", "text_column": "text"}

Example Configurations

from pynolano import FinetuningConfig, FinetuningDataConfig, ModelConfig, FinetuningOptimizationConfig

def build() -> FinetuningConfig:
    return FinetuningConfig(
        base_model_path="Qwen/Qwen3-4B",
        data_configs=FinetuningDataConfig(
            data_paths="./finetuning_data",
            task_type="text_generation"
        ),
        model_config=ModelConfig(
            architecture="Qwen/Qwen3-4B",
            init_method="none"
        ),
        finetuning_config=FinetuningOptimizationConfig(
            total_training_steps=1000,
            max_learning_rate=5e-5,
            global_batch_size=16,
            learning_rate_schedule="linear",
            warmup_steps=100
        )
    )

Advanced Features

Multi-Task Finetuning

Finetune on multiple related tasks simultaneously for better generalization:

data_configs = [
    FinetuningDataConfig(data_paths="./task1_data", sampling_weight=0.4),
    FinetuningDataConfig(data_paths="./task2_data", sampling_weight=0.6)
]

Curriculum Learning

Gradually increase task complexity during finetuning:

Curriculum learning support is planned for future releases.

convert_finetuned_to_hf()

Convert finetuned models to Hugging Face format, preserving both base model and adaptations.

pynolano.convert_finetuned_to_hf(
    input_dir: str,
    config_file: str,
    output_dir: str,
    merge_lora: bool = False,
    upload: bool = False
)

input_dir

str

required

Path to the finetuned checkpoint directory

config_file

str

required

Path to the finetuning configuration YAML file

output_dir

str

required

Destination directory for the converted Hugging Face model

merge_lora

bool

default:"False"

Whether to merge LoRA weights into the base model. If False, saves LoRA adapters separately.

upload

bool

default:"False"

Whether to directly upload the converted model to Hugging Face Hub

Get Started

Core Concepts

Tutorials

Finetuning Configuration