Docs /Templates/ sinapsis-unsloth

UnslothConversationTrainer

sinapsis-unslothUnsloth

Python template · sinapsis_unsloth.templates.training.unsloth_conversation_trainer

Overview

Template for conversation-based-fine-tuning on language models using Unsloth framework.

Handles the complete training pipeline including dataset preparation, template application, and model training with SFTTrainer.

Capabilities

Capabilities: not set

Installation

Install the published package using pip or uv.

Terminalbash
pip install sinapsis-unsloth==1.0.0
uv pip install sinapsis-unsloth==1.0.0
uv add sinapsis-unsloth==1.0.0

Configuration

Effective fields from the inspector schema, including nested Pydantic model fields.

metadata
sinapsis_core.template_base.base_models.TemplateMetadata | None
Optional
Default: null
lora_args
UnslothLoraArgs
Optional
Default: null
r

The rank of the LoRA matrices. Higher rank allows for more expressivity but increases trainable parameters and memory usage. Defaults to 16.

int
Optional
Default: 16
bias

Specifies how biases are handled. Options are "none", "all", or "lora_only". Unsloth optimizes for "none". Defaults to "none".

str
Optional
Default: "none"
lora_alpha

The scaling factor for LoRA. A higher alpha places more emphasis on the adapter weights. Defaults to 16.

int
Optional
Default: 16
use_rslora

If True, uses Rank-Stabilized LoRA (scaling = alpha / sqrt(r)) instead of standard LoRA (scaling = alpha / r). Defaults to False.

bool
Optional
Default: false
loftq_config

Configuration for LoftQ initialization. Used only if LoftQ is required. Defaults to an empty dict.

dict
Optional
Default: null
lora_dropout

The dropout probability for LoRA layers. Unsloth recommends 0.0 for optimized performance. Defaults to 0.0.

float
Optional
Default: 0
random_state

Random seed for initialization reproducibility. Defaults to 3407.

int
Optional
Default: 3407
target_modules

List of module names to apply LoRA adapters to. Defaults to all linear layers ["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"].

list[str]
Optional
Default: ["q_proj","k_proj","v_proj","o_proj","gate_proj","up_proj","down_proj"]
modules_to_save

List of additional modules (like "embed_tokens" or "lm_head") to be set as trainable and saved. Defaults to None.

list[str] | None
Optional
Default: null
use_gradient_checkpointing

Enables gradient checkpointing to save VRAM. "unsloth" uses optimized kernels, True uses standard PyTorch checkpointing. Defaults to "unsloth".

str | bool
Optional
Default: "unsloth"
save_pathRequired
str
Required
Default: null
model_argsRequired
UnslothModelArgs
Required
Default: null
dtype

Data type for model weights. Defaults to "auto".

typing.Literal['auto', 'bfloat16', 'float16']
Optional
Default: "auto"
cache_dir

Directory where models are cached. Defaults to SINAPSIS_CACHE_DIR.

str
Optional
Default: "/home/ariel/.cache/sinapsis"
device_map

Device mapping strategy for model parallelism. Defaults to "sequential".

str
Optional
Default: "sequential"
model_nameRequired

The name of the model to be used.

str
Required
Default: null
load_in_4bit

Whether to use 4-bit quantization. Defaults to True.

bool
Optional
Default: true
load_in_8bit

Whether to use 8-bit quantization. Defaults to False.

bool
Optional
Default: false
random_state

Random state for reproducibility. Defaults to 3407.

int
Optional
Default: 3407
load_in_16bit

Whether to use 16-bit quantization. Defaults to False.

bool
Optional
Default: false
max_lora_rank

Maximum rank for LoRA layers. Defaults to 64.

int
Optional
Default: 64
fast_inference

Whether to enable fast inference mode. Defaults to False.

bool
Optional
Default: false
max_seq_length

Maximum sequence length for input data. Defaults to 2048.

int
Optional
Default: 2048
full_finetuning

Whether to perform full fine-tuning. Defaults to False.

bool
Optional
Default: false
gpu_memory_utilization

Maximum GPU memory utilization as a fraction of total available memory. Defaults to 0.5.

float
Optional
Default: 0.5
use_gradient_checkpointing

Gradient checkpointing strategy. Defaults to "unsloth".

str
Optional
Default: "unsloth"
trainer_args
UnslothTrainerArgs
Optional
Default: null
packing

Whether to group multiple sequences into fixed-length blocks to improve computational efficiency. Defaults to False.

bool
Optional
Default: false
loss_type

Type of loss to use. "nll" (Negative Log-Likelihood) or "dft" (Dynamic Fine-Tuning). Defaults to "nll".

typing.Literal['nll', 'dft']
Optional
Default: "nll"
max_length

Maximum length of the tokenized sequence. Sequences longer than this are truncated. Defaults to 1024.

int
Optional
Default: 1024
eval_packing

Whether to pack the eval dataset. Defaults to False.

bool
Optional
Default: false
dataset_num_proc

Number of processes to use for processing the dataset. Defaults to None.

int | None
Optional
Default: null
packing_strategy

Strategy for packing sequences. "bfd" (Best-Fit Decreasing) or "wrapped". Defaults to "bfd".

typing.Literal['bfd', 'wrapped']
Optional
Default: "bfd"
dataset_text_field

Name of the column containing the text data. Defaults to "text".

str
Optional
Default: "text"
assistant_only_loss

Whether to compute loss only on the assistant part of the sequence. Supported for conversational datasets. Defaults to False.

bool
Optional
Default: false
completion_only_loss

Whether to compute loss only on the completion part of the sequence. Supported for prompt-completion datasets. Defaults to None.

bool | None
Optional
Default: null
activation_offloading

Whether to offload activations to the CPU to save VRAM. Defaults to False.

bool
Optional
Default: false
chat_templateRequired
TrainingChatTemplateConfig
Required
Default: null
mapping

Role mapping configuration.

ChatMapping
Optional
Default: null
role

Key name for the role field.

str
Optional
Default: "role"
user

Value identifying the user role.

str
Optional
Default: "user"
content

Key name for the content field.

str
Optional
Default: "content"
assistant

Value identifying the assistant role.

str
Optional
Default: "assistant"
map_eos_token

Whether to map the EOS token.

bool
Optional
Default: true
target_formatRequired

The name of the target chat template (e.g., 'deepseek-r1').

str
Required
Default: null
system_message

System message to prepend to conversations.

str | None
Optional
Default: null
train_datasetRequired
ConversationalDatasetConfig
Required
Default: null
shuffle
ShuffleConfig
Optional
Default: null
args
ShuffleArgs
Optional
Default: null
seed

Random seed for shuffling.

int | None
Optional
Default: null
keep_in_memory

Whether to keep the shuffled dataset in memory.

bool
Optional
Default: false
load_from_cache_file
bool
Optional
Default: true
enabled

Whether to shuffle the dataset. Defaults to False. shuffle_args (ShuffleArgs): Arguments passed to the shuffle method.

bool
Optional
Default: false
map_args
MapArgs
Optional
Default: null
desc

Meaningful description for the progress bar. remove_columns (str | list[str] | None): Columns to remove after mapping.

str | None
Optional
Default: null
batched

Whether to provide a batch of examples to the function.

bool
Optional
Default: false
num_proc

Number of processes for multiprocessing.

int
Optional
Default: 0
batch_size

Number of examples per batch. Defaults to 1000.

int
Optional
Default: 1000
keep_in_memory
bool
Optional
Default: false
load_from_cache_file
bool
Optional
Default: true
loader_argsRequired
DataLoaderArgs
Required
Default: null
name

The configuration name of the dataset.

str | None
Optional
Default: null
pathRequired

The path or identifier of the dataset (e.g., 'imdb', 'json').

str
Required
Default: null
split

Which split of the data to load (e.g., 'train').

str | None
Optional
Default: null
data_dir

Path to the directory containing the data files.

str | None
Optional
Default: null
features
datasets.features.features.Features | None
Optional
Default: null
num_proc

Number of processes for loading.

int | None
Optional
Default: null
cache_dir

Directory to read/write data. Defaults to SINAPSIS_CACHE_DIR.

str
Optional
Default: "/home/ariel/.cache/sinapsis"
data_files

Path(s) to source data files.

str | None
Optional
Default: null
input_formatRequired

Input dataset format.

typing.Literal['alpaca', 'sharegpt']
Required
Default: null
pre_tokenize
PreTokenizeConfig
Optional
Default: null
args
TokenizerArgs
Optional
Default: null
stride

Window overlap for overflowing tokens. return_tensors (str | None): If set, will return tensors instead of lists ('pt', 'tf', 'np').

int
Optional
Default: 0
padding

Padding strategy ("longest", "max_length", etc.).

typing.Literal['longest', 'max_length', 'do_not_pad']
Optional
Default: "do_not_pad"
verbose
bool
Optional
Default: true
max_length

Maximum length of the returned list and/or tensor.

int | None
Optional
Default: null
truncation

Truncation strategy.

typing.Literal['longest_first', 'only_first', 'only_second', 'do_not_truncate']
Optional
Default: "do_not_truncate"
padding_side
str | None
Optional
Default: null
add_special_tokens

Whether to encode the sequences with special tokens.

bool
Optional
Default: true
is_split_into_words
bool
Optional
Default: false
enabled

Whether to pre-tokenize the dataset before training. tokenization_args (TokenizerArgs): Arguments passed to the tokenizer.

bool
Optional
Default: false
map_args

Arguments passed to the map function during tokenization.

MapArgs
Optional
Default: null
desc

Meaningful description for the progress bar. remove_columns (str | list[str] | None): Columns to remove after mapping.

str | None
Optional
Default: null
batched

Whether to provide a batch of examples to the function.

bool
Optional
Default: false
num_proc

Number of processes for multiprocessing.

int
Optional
Default: 0
batch_size

Number of examples per batch. Defaults to 1000.

int
Optional
Default: 1000
keep_in_memory
bool
Optional
Default: false
load_from_cache_file
bool
Optional
Default: true
to_sharegpt_args

Arguments for converting Alpaca to ShareGPT.

ToShareGPTArgs
Optional
Default: null
random_state

Random seed for reproducibility.

int
Optional
Default: 3407
merged_prompt

Prompt string for merging instruction and input.

str
Optional
Default: ""
merged_column_name

Column name for the merged instruction.

str
Optional
Default: "instruction"
output_column_name

Column name for the response output.

str
Optional
Default: "output"
remove_unused_columns

Whether to remove columns not used in conversion.

bool
Optional
Default: true
conversation_extension

Number of additional messages for multi-turn simulation.

int
Optional
Default: 1
training_args
UnslothTrainingArgs
Optional
Default: null
bf16

Whether to use BF16 16-bit precision (requires Ampere+ GPU).

bool
Optional
Default: false
fp16

Whether to use FP16 16-bit precision.

bool
Optional
Default: false
seed
int
Optional
Default: 3407
optim

Optimizer name (e.g., "adamw_torch", "adamw_8bit").

str
Optional
Default: "adamw_torch"
use_cpu
bool
Optional
Default: false
data_seed
int | None
Optional
Default: null
max_steps

Total number of training steps. Overrides epochs.

int | None
Optional
Default: null
report_to

List of integrations to report to (e.g., "wandb").

str | list[str]
Optional
Default: "none"
eval_steps

Number of steps between evaluations.

int | float | None
Optional
Default: null
output_dir

Directory where checkpoints and model outputs will be saved.

str
Optional
Default: "trainer_output"
save_steps

Number of steps between saves.

int | float
Optional
Default: 500
push_to_hub

Whether to push the model to the Hub after training.

bool
Optional
Default: false
hub_model_id
str | None
Optional
Default: null
warmup_ratio

Ratio of total steps used for linear warmup.

float
Optional
Default: 0
warmup_steps
int | None
Optional
Default: null
weight_decay

Weight decay to apply to all layers except bias/LayerNorm.

float
Optional
Default: 0
eval_strategy

Strategy for evaluation.

typing.Literal['no', 'steps', 'epoch']
Optional
Default: "no"
learning_rate

Initial learning rate for AdamW.

float
Optional
Default: 0.00005
logging_steps

Number of steps between logging events.

int | float
Optional
Default: 500
max_grad_norm
float
Optional
Default: 1
save_strategy

Strategy for saving checkpoints.

typing.Literal['no', 'steps', 'epoch', 'best']
Optional
Default: "steps"
save_only_model
bool
Optional
Default: false
logging_strategy
typing.Literal['no', 'steps', 'epoch']
Optional
Default: "steps"
num_train_epochs

Total number of training epochs.

float
Optional
Default: 3
lr_scheduler_type

Scheduler type (e.g., "linear", "cosine").

str
Optional
Default: "linear"
logging_first_step
bool
Optional
Default: false
dataloader_drop_last
bool
Optional
Default: false
overwrite_output_dir

If True, overwrite the content of the output directory.

bool
Optional
Default: false
metric_for_best_model
str
Optional
Default: "loss"
remove_unused_columns
bool
Optional
Default: true
dataloader_num_workers
int
Optional
Default: 0
load_best_model_at_end
bool
Optional
Default: false
eval_accumulation_steps

Number of steps to accumulate evaluation predictions.

int | None
Optional
Default: null
torch_empty_cache_steps
int | None
Optional
Default: null
per_device_eval_batch_size

Batch size per GPU for evaluation.

int
Optional
Default: 8
gradient_accumulation_steps

Number of update steps to accumulate gradients for.

int
Optional
Default: 1
per_device_train_batch_size

Batch size per GPU for training.

int
Optional
Default: 8
data_collator_args
DataCollatorArgs
Optional
Default: null
padding

Padding strategy.

typing.Literal['longest', 'max_length', 'do_not_pad']
Optional
Default: "do_not_pad"
max_length

Max sequence length for padding.

int | None
Optional
Default: null
label_pad_token_id

Token ID used for padding labels. Defaults to -100.

int
Optional
Default: -100
train_responses_only

Whether to only compute loss on assistant responses data_collator_kwargs (dict[str, Any]): Custom arguments for conversation data collation

bool
Optional
Default: true
resume_from_checkpoint
bool
Optional
Default: false

Configuration example

Example from the Python docstring:

yaml
agent:
  name: my_test_agent
templates:
- template_name: InputTemplate
  class_name: InputTemplate
  attributes: {}
- template_name: UnslothConversationTrainer
  class_name: UnslothConversationTrainer
  template_input: InputTemplate
  attributes:
    model_args:
      model_name: 'unsloth/DeepSeek-R1-Distill-Qwen-7B'
      max_seq_length: 2048
      dtype: auto
      load_in_4bit: true
      use_gradient_checkpointing: unsloth
      gpu_memory_utilization: 0.5
      random_state: 3407
      max_lora_rank: 64
    lora_args:
      r: 16
      target_modules:
      - q_proj
      - k_proj
      - v_proj
      - o_proj
      - gate_proj
      - up_proj
      - down_proj
      lora_alpha: 16
      lora_dropout: 0.0
      bias: none
      use_gradient_checkpointing: unsloth
      random_state: 3407
      use_rslora: false
      modules_to_save: null
    trainer_args:
      dataset_text_field: text
      dataset_num_proc: null
      max_length: 1024
      packing: false
    training_args:
      per_device_train_batch_size: 4
      gradient_accumulation_steps: 8
      warmup_ratio: 0.1
      num_train_epochs: 2
      learning_rate: 0.00005
      embedding_learning_rate: 0.00001
      fp16: false
      bf16: true
      logging_steps: 1
      optim: adamw_8bit
      weight_decay: 0.01
      lr_scheduler_type: linear
      seed: 3407
      output_dir: outputs
      save_strategy: "epoch"
      report_to: none
    train_dataset:
      loader_args:
        path: 'json'
        data_files: 'path/to/dataset.jsonl'
        split: train
      map_args:
        batched: false
        batch_size: 1000
        num_proc: 0
        keep_in_memory: false
        load_from_cache_file: true
      shuffle:
        enabled: true
        args:
          seed: 3407
      pre_tokenize:
        enabled: false
      input_format: 'alpaca'
      to_sharegpt_args:
        merged_prompt: '{instruction}[[{input}]]'
        merged_column_name: instruction
        output_column_name: output
        remove_unused_columns: true
        conversation_extension: 1
        random_state: 3407
    resume_from_checkpoint: false
    save_path: 'path/to/fine-tuned-lora/'
    chat_template:
      mapping:
        role: role
        content: content
        user: user
        assistant: assistant
      map_eos_token: true
      system_message: "You're a useful assistant"
      target_format: 'deepseek-r1'
    train_responses_only: true
Show schema-based configuration skeleton
yaml
templates:
  - template_name: "UnslothConversationTrainer"
    class_name: "UnslothConversationTrainer"
    attributes:
      lora_args:
        r: 16
        bias: "none"
        lora_alpha: 16
        use_rslora: false
        loftq_config: {}
        lora_dropout: 0
        random_state: 3407
        target_modules: ["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]
        modules_to_save: null
        use_gradient_checkpointing: "unsloth"
      save_path: "<required>"
      model_args:
        dtype: "auto"
        cache_dir: "/home/ariel/.cache/sinapsis"
        device_map: "sequential"
        model_name: "<required>"
        load_in_4bit: true
        load_in_8bit: false
        random_state: 3407
        load_in_16bit: false
        max_lora_rank: 64
        fast_inference: false
        max_seq_length: 2048
        full_finetuning: false
        gpu_memory_utilization: 0.5
        use_gradient_checkpointing: "unsloth"
      trainer_args:
        packing: false
        loss_type: "nll"
        max_length: 1024
        eval_packing: false
        dataset_num_proc: null
        packing_strategy: "bfd"
        dataset_text_field: "text"
        assistant_only_loss: false
        completion_only_loss: null
        activation_offloading: false
      chat_template:
        mapping:
          role: "role"
          user: "user"
          content: "content"
          assistant: "assistant"
        map_eos_token: true
        target_format: "<required>"
        system_message: null
      train_dataset:
        shuffle:
          args:
            seed: null
            keep_in_memory: false
            load_from_cache_file: true
          enabled: false
        map_args:
          desc: null
          batched: false
          num_proc: 0
          batch_size: 1000
          keep_in_memory: false
          load_from_cache_file: true
        loader_args:
          name: null
          path: "<required>"
          split: null
          data_dir: null
          features: null
          num_proc: null
          cache_dir: "/home/ariel/.cache/sinapsis"
          data_files: null
        input_format: "<required>"
        pre_tokenize:
          args:
            stride: 0
            padding: "do_not_pad"
            verbose: true
            max_length: null
            truncation: "do_not_truncate"
            padding_side: null
            add_special_tokens: true
            is_split_into_words: false
          enabled: false
          map_args:
            desc: null
            batched: false
            num_proc: 0
            batch_size: 1000
            keep_in_memory: false
            load_from_cache_file: true
        to_sharegpt_args:
          random_state: 3407
          merged_prompt: ""
          merged_column_name: "instruction"
          output_column_name: "output"
          remove_unused_columns: true
          conversation_extension: 1
      training_args:
        bf16: false
        fp16: false
        seed: 3407
        optim: "adamw_torch"
        use_cpu: false
        data_seed: null
        max_steps: null
        report_to: "none"
        eval_steps: null
        output_dir: "trainer_output"
        save_steps: 500
        push_to_hub: false
        hub_model_id: null
        warmup_ratio: 0
        warmup_steps: null
        weight_decay: 0
        eval_strategy: "no"
        learning_rate: 0.00005
        logging_steps: 500
        max_grad_norm: 1
        save_strategy: "steps"
        save_only_model: false
        logging_strategy: "steps"
        num_train_epochs: 3
        lr_scheduler_type: "linear"
        logging_first_step: false
        dataloader_drop_last: false
        overwrite_output_dir: false
        metric_for_best_model: "loss"
        remove_unused_columns: true
        dataloader_num_workers: 0
        load_best_model_at_end: false
        eval_accumulation_steps: null
        torch_empty_cache_steps: null
        per_device_eval_batch_size: 8
        gradient_accumulation_steps: 1
        per_device_train_batch_size: 8
      data_collator_args:
        padding: "do_not_pad"
        max_length: null
        label_pad_token_id: -100
      train_responses_only: true
      resume_from_checkpoint: false

Inheritance

Immediate parent: sinapsis_unsloth.templates.training.unsloth_fine_tuning_base.UnslothFineTuningBase

Environment variables

Environment definitions belong to their canonical Python modules.

No directly related environment variables listed.