Training

Fine-tune a local model from the Desktop app — one run at a time, with live loss and reconnect-safe progress

The Train tab turns a praisonai-train fine-tune into a form, a live loss chart, and a run history — all against your local engine.

from praisonaiagents import Agent

# After a Train-tab run finishes, point an Agent at the saved model
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    llm="ollama/yourname/my-finetune",
)
agent.start("Test my fine-tuned model")

The Train tab is a desktop wrapper around the praisonai-train llm CLI. The engine writes a config.yaml, spawns python -m praisonai_train llm --config <run_dir>/config.yaml as its own process group, and reports on it live.

Quick Start

1. Open the Train tab

   Click Train in the sidebar. The app remembers your last-picked view, so it reopens where you left off. The one exception is a launch where the engine still needs setup or has failed — the app forces Chat while the wizard/banner is on screen, and returns to your saved view the moment the engine is healthy, in the same session (PraisonAI #4471, #4623).

2. Pick a model and dataset

   Defaults are unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit on yahma/alpaca-cleaned. Leave them as-is for your first run.

3. Click Start training

   The button becomes Training…. A live card shows the loss chart, step / total, current loss, and elapsed time; the log auto-follows.

4. Close the lid — come back

   Reopen the app; the Train tab reattaches to the running job and repopulates step, loss, elapsed, and log from history.

How It Works

The engine runs one job at a time and keeps its progress in a replayable ring buffer, so closing the window never loses a run.

The engine parses two line shapes from the trainer’s output: a step / total tqdm bar and the {'loss': ..., 'learning_rate': ..., 'epoch': ...} dict trl prints each logging step. Everything else is shown verbatim in the log pane.

Reconnect & resync

Opening the tab after a gap replays from your cursor; a long run that overflowed the ring buffer tells you so rather than silently skipping output.

sequenceDiagram
    participant App as 🌐 Train Tab
    participant Engine as ⚙️ Engine

    App->>Engine: GET /train/progress?run=<id>&cursor=N
    alt N still in ring buffer
        Engine-->>App: replay events from N, then follow
    else N evicted
        Engine-->>App: event: resync
        App->>App: "… earlier output dropped; full log in run dir"
        Engine-->>App: deliver oldest held events, cursor reset
    end

Adopting a run after restart

On restart the engine reads each runs/<id>/run.json and only adopts a run it can prove is still its own — a live pid is not enough because pids are recycled.

The fingerprint is recorded at spawn while the child is certainly still ours; reading it at adoption time would fingerprint whoever holds the pid then, which is the case being guarded against.

Choosing a method

method picks the trainer. sft works with the default dataset; the rest need differently-shaped data, named in the per-method hint under the dropdown.

Configuration

The form posts a config object to /train/start. Basic fields are always visible; LoRA and quantization live in the Advanced panel.

train: true
ollama_save: false
huggingface_save: false

Environment variables

Common Patterns

export PRAISONAI_TRAIN_CMD="/opt/cuda-venv/bin/python -m praisonai_train llm"

Reference

Every route lives on the local engine (127.0.0.1, no auth — the app’s existing design for every route).

SSE event kinds: start, state, log, progress, metric, end, plus resync when history was evicted past your cursor.

Run summary shape: {id, state, step, total, started, ended, error, elapsed, last_loss}.

state is one of:

Best Practices

Related