Risoluzione problemi AI locale

Guida: Intelligenza Artificiale Locale › Troubleshooting

Se un modello locale è lento, dà errori di memoria o produce risposte poco affidabili, la diagnosi deve partire da log, memoria occupata e configurazione del runtime. Sono situazioni diverse: GPU non utilizzata, cache di contesto troppo grande, modello quantizzato male, retrieval impreciso o eccesso di richieste simultanee. Questa guida propone controlli progressivi prima di cambiare hardware o reinstallare tutto.

Risoluzione problemi

Registra modello e versione, quantizzazione, sistema operativo, driver, lunghezza di contesto e numero di utenti contemporanei. Poi riproduci il problema con una richiesta semplice e misura tempi e consumo di RAM/VRAM. In Ollama, ad esempio, il comando ollama ps aiuta a verificare dove è caricato il modello; la documentazione ufficiale chiarisce anche il consumo aggiuntivo di memoria per contesti lunghi. Per il dimensionamento confronta GPU e memoria.

“Il modello è lentissimo, una parola al secondo.” Quasi sempre il modello non entra in VRAM ed è traboccato nella RAM. Cause tipiche: modello troppo grande per la scheda, o la trappola del contesto (finestra di contesto enorme che gonfia la cache KV). Soluzioni: modello più piccolo o quantizzazione più aggressiva (Q4 invece di Q8), oppure riduci la finestra di contesto (num_ctx) a ciò che ti serve. Verifica con nvidia-smi quanta VRAM è occupata.

“Errore di memoria esaurita, il modello non si carica.” Non c’è abbastanza memoria per quel modello. Chiudi altre applicazioni che occupano VRAM, scegli una variante più piccola, o passa a una quantizzazione più leggera. Ricorda: in Q4, i gigabyte ≈ i miliardi di parametri, più lo spazio per la cache KV.

“La GPU non viene rilevata, gira tutto su CPU.” Problema di driver. Verifica che i driver e (per NVIDIA) il toolkit CUDA siano installati e che il sistema veda la scheda (nvidia-smi). Su Linux è il punto più delicato della configurazione: è qui che si spende il tempo iniziale. Sistemati i driver, Ollama usa la GPU automaticamente. Se usi Docker, assicurati che il container abbia accesso alla GPU (NVIDIA Container Toolkit).

“Le risposte sono scadenti sui miei dati.” Se sbaglia sui tuoi dati specifici, non è un problema del modello ma del fatto che non li conosce: ti serve il RAG (Parte V). Se le risposte generali sono deboli, prova un modello più capace, una quantizzazione meno aggressiva (Q8 invece di Q4 migliora la qualità a costo di memoria), o affina il prompt di sistema con istruzioni più precise.

“Produce un lungo testo di ragionamento prima della risposta.” Normale per i modelli reasoning (DeepSeek R1, Phi e simili): generano una catena di pensiero interna prima della risposta finale, racchiusa tra marcatori. Non è un errore. Se dà fastidio nell’uso quotidiano, usa un modello non-reasoning per la chiacchiera e tieni quelli di ragionamento per i problemi difficili. Via API, il blocco si filtra in post-elaborazione.

“Il RAG non trova le informazioni giuste.” Quasi sempre è questione di recupero, non di modello linguistico. Rivedi il chunking (pezzi della dimensione giusta, con sovrapposizione), prova un modello di embedding migliore (da nomic-embed-text a BGE-M3), aggiungi un reranker. Ricorda: nel RAG, la qualità del recupero conta più della taglia del modello.

“Sotto carico con più utenti rallenta.” Ollama gestisce il parallelismo ma ha limiti. Configura OLLAMA_NUM_PARALLEL e tieni il modello caricato (keep-alive), oppure, per molti utenti simultanei, passa a un motore da throughput come vLLM, o a hardware superiore.

Ottimizzazione generale. Tieni Ollama aggiornato. Dimensiona sempre il contesto al compito. Preferisci i MoE per la velocità. Tieni il modello caricato in memoria se l’assistente è sempre attivo. E misura: prova sul tuo carico reale prima di decidere che va bene, perché i benchmark raccontano solo una parte della storia.

Diagnosi rapida: sintomo, causa probabile, azione

Metodo di debug in cinque passaggi

Quando qualcosa non va, evita di cambiare dieci parametri insieme. Primo: verifica se il modello usa davvero la GPU. Secondo: misura quanta VRAM occupa appena caricato. Terzo: prova una domanda corta senza RAG, così separi il problema del modello dal problema dei documenti. Quarto: prova la stessa domanda con RAG e controlla quali chunk vengono recuperati. Quinto: cambia una sola variabile alla volta — modello, quantizzazione, contesto, embedding, prompt — e annota il risultato. Questo approccio sembra lento, ma evita ore perse a inseguire cause sbagliate.

Problemi tipici con Docker e Open WebUI

Se Open WebUI parte ma non vede Ollama, spesso è un problema di rete tra container o di endpoint configurato male. Se i dati spariscono dopo un riavvio, manca un volume persistente. Se l’interfaccia è raggiungibile solo dalla macchina locale, controlla bind, firewall e reverse proxy. In produzione evita porte esposte direttamente su internet: meglio un reverse proxy con HTTPS, autenticazione forte e regole firewall.

Quando cambiare hardware invece di ottimizzare

Non tutto si risolve con i parametri. Se il modello corretto per il tuo lavoro non entra in memoria, se devi servire più utenti contemporanei o se il tempo al primo token resta alto con contesti lunghi, probabilmente il limite è hardware. In quel caso la scelta non è “ottimizzare ancora”, ma dimensionare la macchina sul carico reale: modello target, numero utenti, lunghezza media del contesto, presenza di RAG e orari di picco.

Per gli impianti usati ogni giorno, crea anche una piccola scheda tecnica interna: modello installato, quantizzazione, contesto impostato, versione di Ollama, driver GPU, percorso dei volumi Docker, porta dell’interfaccia e data dell’ultimo test. Quando qualcosa si rompe dopo un aggiornamento, questa scheda permette di confrontare lo stato precedente con quello attuale e riduce drasticamente i tempi di diagnosi.

← Privacy e GDPRTorna alla guida →