can-i-finetune-this — Guida pratica

Cosa fa

Questo strumento risponde alla domanda: “Posso fare fine‑tuning di questo LLM sulla mia GPU consumer?” — prima di scaricare i pesi o perdere tempo con un errore OOM. Fornisce:

• Stima della memoria – modella il consumo di VRAM per un dato modello, metodo (LoRA/QLoRA), lunghezza della sequenza, dimensione del batch e rango LoRA, includendo pesi, gradienti, stati dell'ottimizzatore, attivazioni e un margine di sicurezza per la frammentazione.
• Verifica di fattibilità – indica se una configurazione è adatta alla tua GPU, con un livello di confidenza.
• Raccomandazione – cerca una configurazione fattibile (ad esempio, raccomanda un rango inferiore o una lunghezza di sequenza più corta).
• Benchmarking – esegue un mini‑step di addestramento reale su un modello minuscolo (sshleifer/tiny-gpt2, ~5 MB) per misurare il picco effettivo di VRAM sulla tua macchina.
• Calibrazione – utilizza i risultati del benchmark per correggere le stime statiche, rendendole più accurate per il tuo specifico stack GPU/driver/software.
• Generazione di ricette – produce uno script di addestramento Hugging Face + PEFT + TRL pronto all'uso, personalizzato per la configurazione scelta.
• Report e confronto – genera report in Markdown dei risultati del benchmark e confronta più esecuzioni.

L'intuizione principale è che le semplici stime statiche (come accelerate estimate-memory) coprono solo il caricamento del modello, non l'overhead dell'addestramento. Questo strumento aggiunge un modello di memoria dettagliato e un ciclo di feedback con misurazioni reali.

Come iniziare

Installazione

canifinetune ha due livelli di installazione:

Importante: PyTorch dovrebbe generalmente essere installato con la wheel CUDA corrispondente al tuo driver. Ad esempio, con uv:

uv pip install torch --index-url https://download.pytorch.org/pypi/cu121

Se stai usando uv per tutto l'ambiente:

uv venv
uv pip install -e ".[dev,report]"
# Add training deps when you want to run benchmarks:
uv pip install -e ".[dev,train,report]"

Fare riferimento a docs/troubleshooting.md per i dettagli su Windows, WSL e bitsandbytes.

Configurazione minima

1. Installa il pacchetto core (o core + training se intendi eseguire i benchmark).
2. (Opzionale ma consigliato) Esegui canifinetune doctor per verificare il tuo ambiente e la visibilità della GPU.
3. Ora puoi utilizzare qualsiasi comando della CLI.

Utilizzo pratico

Tutti i comandi vengono invocati tramite la CLI canifinetune. Il README mostra i seguenti flussi di lavoro:

1. Controlla la tua macchina

canifinetune doctor

Stampa le informazioni hardware (GPU, driver, versione CUDA) e verifica che le dipendenze necessarie siano disponibili.

2. Stima della VRAM per una configurazione specifica

canifinetune estimate \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --method qlora \
  --gpu-vram-gb 16 \
  --seq-len 2048 \
  --micro-batch-size 1 \
  --lora-rank 16

L'output è una tabella con un verdetto di fattibilità (SÌ/NO) e una suddivisione della memoria per componente (modello statico, overhead di quantizzazione, parametri addestrabili, gradienti, stati dell'ottimizzatore, attivazioni, frammentazione CUDA, margine di sicurezza, totale).

3. Lascia che lo strumento consigli una configurazione fattibile

canifinetune recommend --model Qwen/Qwen2.5-1.5B-Instruct --gpu-vram-gb 16

Cerca una configurazione (rank, lunghezza della sequenza, metodo) che si adatti alla tua GPU.

4. Esegui un benchmark reale (richiede gli extra [train])

canifinetune bench --model sshleifer/tiny-gpt2 --method lora --steps 3

Scarica un modello piccolo ed esegue alcuni passaggi di addestramento, misurando il picco effettivo di VRAM. I risultati vengono salvati localmente per essere utilizzati successivamente per la calibrazione.

5. Genera una ricetta di addestramento pronta per l'esecuzione

canifinetune recipe \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --method qlora \
  --seq-len 2048 \
  --output recipes/qwen2.5-1.5b-qlora-4080

Produce una cartella contenente uno script di addestramento (run_qlora.py o simile) e un file di configurazione, pronti per essere eseguiti con modifiche minime.

6. Calibra le stime utilizzando i risultati dei benchmark

canifinetune calibrate --benchmarks benchmarks/results

Legge i file JSON del benchmark e aggiorna i parametri interni dello stimatore statico per adattarsi meglio al tuo hardware.

7. Genera un report Markdown dei benchmark

canifinetune report --benchmarks benchmarks/results --out report.md
canifinetune compare --benchmarks benchmarks/results --out compare.md

Configurazione e opzioni

Tutti i parametri principali vengono passati come flag CLI. Non esiste un file di configurazione separato (sebbene il comando recipe generi script che contengono la configurazione). I parametri principali sono:

La stima statica utilizza anche assunzioni interne su target_modules (standard per l'architettura del modello), gradient checkpointing (disattivato per impostazione predefinita) e ottimizzatore (AdamW). Queste sono elencate nel blocco assumptions dell'output.

Vincoli e limitazioni noti

Il README elenca esplicitamente l'ambito attuale e le lacune note:

• Solo GPU consumer singola – nessun supporto multi‑GPU, DeepSpeed o FSDP (anche se la roadmap futura potrebbe aggiungerlo).
• Nodo singolo – nessun addestramento distribuito.
• Solo LoRA / QLoRA – il fine‑tuning completo non è considerato.
• Solo LM causale – le architetture di classificazione o encoder‑decoder non sono modellate (la roadmap potrebbe estendersi).
• Stack Hugging Face – sono supportati solo modelli/dataset/trainer dell'ecosistema HF.
• Le stime statiche hanno accuratezza limitata – la memoria di attivazione è particolarmente difficile da prevedere. Ogni stima è etichettata con un livello di confidenza e un blocco assumptions. Lo strumento incoraggia a eseguire bench e calibrate per ancorare i numeri.
• Il comando bench attualmente usa un modello minuscolo (sshleifer/tiny-gpt2) come proxy – potrebbe non scalare perfettamente a modelli grandi, ma cattura gli overhead del tuo ambiente (decompressione bitsandbytes, frammentazione, ecc.).

La roadmap del progetto aggiunge ulteriori contesti: la modellazione del throughput (token/sec), l'auto‑tuning dei passi di accumulo del gradiente e un'interfaccia web non sono ancora implementati.

Buone pratiche

Sebbene il README non abbia una sezione dedicata alle 'Buone pratiche', si possono ricavare i seguenti consigli:

• Esegui sempre prima canifinetune doctor per confermare che la tua GPU e le librerie richieste siano visibili.
• Usa canifinetune recommend come punto di partenza – troverà una configurazione fattibile senza tentativi ed errori manuali.
• Esegui canifinetune bench sulla tua macchina reale, poi canifinetune calibrate per migliorare l'accuratezza delle stime future. La differenza tra VRAM statica e misurata può essere significativa (il README mostra 3.16 GB statici contro 7.10 GB reali per un Qwen 1.5B QLoRA con seq_len=2048 su una RTX 4080).
• Installa PyTorch separatamente con la corretta wheel CUDA – non affidarti alla dipendenza [train] per scegliere la versione giusta; usa l'URL dell'indice mostrato nella sezione di installazione.
• Quando usi uv, installa torch dopo aver creato il venv, prima di aggiungere le dipendenze extra per l'addestramento, per evitare conflitti di versione.
• Consulta docs/troubleshooting.md se incontri problemi su Windows o WSL, specialmente con bitsandbytes.

Procedure notevoli

Installare PyTorch con il backend CUDA corretto

Il README fornisce questo schema esplicito (usando uv come esempio):

uv pip install torch --index-url https://download.pytorch.org/whl/cu121

Questo deve essere fatto prima (o al posto) della risoluzione automatica delle dipendenze da [train]. Lo stesso principio vale per pip.

Aggiornamento da una versione precedente

Non sono documentati passaggi di migrazione specifici. I comandi principali sono retrocompatibili, a patto che tu reinstalli canifinetube da PyPI. Se hai risultati di benchmark salvati localmente, rimangono in benchmarks/results/ e possono essere riutilizzati.

Utilizzo dell'output della ricetta

Il comando canifinetune recipe genera una cartella contenente uno script di training e un file di configurazione. Questo script è pensato per essere eseguito così com'è (con il tuo dataset e tokenizer), ma potrebbe richiedere piccole modifiche per puntare ai tuoi dati. Il README non descrive i dettagli interni dello script, ma si basa sul trainer TRL di Hugging Face.

Raccolta di baseline per una nuova GPU

La directory scripts/ del repository contiene script di supporto per eseguire benchmark in batch su molte configurazioni. Le baseline per RTX 4080 in docs/rtx4080_baselines.md sono state prodotte con questi script. Puoi adattarli per generare la tua tabella di riferimento.