Text Generation WebUI (Oobabooga): Guida all'installazione, ai loader e all'uso

text-generation-webui è un'interfaccia web open source e auto-hosted per l'esecuzione locale di modelli linguistici di grandi dimensioni. È mantenuta su GitHub come oobabooga/text-generation-webui, si avvia nel browser all'indirizzo http://localhost:7860, supporta un'ampia gamma di formati di modello grazie a backend di inferenza intercambiabili ed espone un'API REST compatibile con OpenAI. È il frontend più completo disponibile, a fronte di una curva di installazione più ripida rispetto ad applicazioni desktop come LLM locale LM Studio o Jan LM Studio.

Cos’è text-generation-webui (e perché viene chiamata Oobabooga)

Il nome utente GitHub del progetto è oobabooga, che è diventato il termine colloquiale usato dalla comunità per indicare lo strumento stesso. Entrambi i nomi fanno riferimento allo stesso progetto disponibile all’indirizzo github.com/oobabooga/text-generation-webui.

L’interfaccia è costruita su Gradio e funziona interamente sulla tua macchina locale — nessun dato lascia il tuo sistema. Oltre alla chat di base, supporta:

• Tre modalità di input: Chat (instruct), Chat (roleplay con schede personaggio) e Notebook (completamento raw)
• Caricamento di LoRA per pesi adattatori finetunati sopra un modello base
• Un sistema di estensioni con plugin della community per riassunti, sintesi vocale, generazione di didascalie per immagini e molto altro
• Un endpoint API compatibile con OpenAI per connettere client di terze parti e script di automazione

Prima di scegliere un modello, utilizza il Calcolatore VRAM calcolatore di memoria VRAM

Installazione di text-generation-webui

Il metodo consigliato su ogni piattaforma è l’installer a un clic. Crea automaticamente un ambiente Conda isolato e installa tutte le dipendenze Python. Non installare nell’ambiente Python di sistema, a meno che tu non abbia una ragione specifica per farlo.

Windows

1. Clona il repository o scarica l’archivio zip della release dalla pagina GitHub:
   git clone https://github.com/oobabooga/text-generation-webui
2. Fai doppio clic su start_windows.bat nella cartella clonata.
3. Lo script rileva il tipo di GPU (NVIDIA, AMD o solo CPU) e installa le dipendenze corrispondenti — seleziona l’opzione appropriata quando richiesto.
4. Al termine della configurazione, il server viene avviato automaticamente. Apri http://localhost:7860 nel tuo browser.

Nei successivi avvii, fai doppio clic nuovamente su start_windows.bat . L’ambiente Conda è già stato creato; l’avvio richiede solo pochi secondi.

Linux

1. Clona il repository ed entra nella directory:

   git clone https://github.com/oobabooga/text-generation-webui
   cd text-generation-webui

2. Rendi lo script eseguibile ed eseguilo:

   chmod +x start_linux.sh
   ./start_linux.sh

3. Quando richiesto, seleziona il tipo di GPU: NVIDIA, AMD, solo CPU o Apple Silicon (non applicabile su Linux, ma la richiesta compare comunque).
4. Accedi all’interfaccia all’indirizzo http://localhost:7860 non appena il server è in esecuzione.

macOS

1. Clona il repository ed esegui lo script di avvio:

   git clone https://github.com/oobabooga/text-generation-webui
   cd text-generation-webui
   ./start_macos.sh

2. Quando richiesto, seleziona l’opzione D (Apple Silicon / Metal) o C (solo CPU).
3. Il backend llama.cpp utilizza Metal per l’accelerazione GPU sui chip M-series — non è richiesto CUDA.

Gli utenti macOS possono utilizzare esclusivamente i loader llama.cpp e Transformers. ExLlamaV2 richiede CUDA e non è compatibile con Apple Silicon.

Loader dei modelli: quale scegliere

text-generation-webui separa logicamente il motore di inferenza dall’interfaccia utente. Puoi selezionare un loader specifico per ciascun modello dalla scheda Modello Loader

Predefinito pratico: Se hai scaricato un .gguf file (il formato più comune sulle pagine dei modelli di HuggingFace), utilizza llama.cpp. Se disponi di una GPU NVIDIA e desideri la massima velocità di generazione, cerca una variante EXL2 dello stesso modello e utilizza ExLlamaV2.

Per una panoramica dei modelli che effettivamente si adattano a ciascuna GPU, consulta Requisiti di VRAM per i principali LLM.

Caricamento passo passo di un modello GGUF

1. Copia il file nella cartella text-generation-webui/models/. I file GGUF monofile (ad esempio, mistral-7b-instruct.Q4_K_M.gguf) vanno inseriti direttamente in tale cartella. I file suddivisi in più parti devono essere collocati in una sottocartella denominata.
2. Apri la scheda Modello l’indirizzo http://localhost:7860.
3. Seleziona il tuo file dal menu a discesa dei modelli (fai clic sull'icona di aggiornamento se non compare).
4. Impostare Loader a llama.cpp.
5. Impostare n-gpu-layers per controllare lo scarico sulla GPU. Inserisci un numero elevato (ad esempio, 999) per spostare il maggior numero possibile di livelli nella VRAM; inserisci 0 per l'inferenza esclusivamente su CPU.
6. Clicca Carica. Un messaggio di conferma appare nella casella di stato non appena il modello è pronto.

Passa alla scheda Chat per avviare una conversazione oppure alla scheda Predefinito per il completamento diretto del prompt. Il template instruct viene impostato automaticamente per le famiglie di modelli note; per modelli sconosciuti, selezionalo manualmente dal menu a discesa Template istruzioni nella scheda Parametri.

L’estensione API compatibile con OpenAI

L'estensione integrata openai espone endpoint REST che replicano il formato delle API OpenAI Chat Completions e Completions. Qualsiasi client che accetti un URL base personalizzato — LangChain, Open WebUI, Continue.dev o uno script curl — può connettersi al tuo modello locale senza modifiche al codice.

Abilitala passando una flag all'avvio:

# Linux / macOS
./start_linux.sh --extensions openai

# oppure avvia direttamente server.py all'interno dell'ambiente Conda
python server.py --extensions openai

In alternativa, abilitala dalla scheda Sessione nell'interfaccia utente, quindi fai clic su Applica flag / Riavvia.

Per impostazione predefinita, l'API ascolta sulla porta 5000, distinta dall'interfaccia Gradio sulla porta 7860. Configura il tuo client con:

base_url = "http://localhost:5000/v1"
api_key  = "qualsiasi_valore"  # richiesto dalla maggior parte dei client, ma non convalidato localmente

Gli endpoint supportati includono /v1/chat/completions, /v1/completions, e /v1/models. La porta è configurabile tramite la flag di avvio --api-port .

text-generation-webui vs LM Studio vs Jan

Tutti e tre gli strumenti eseguono i modelli localmente, senza dipendenze dal cloud. Sono rivolti a utenti e casi d'uso diversi.

Scegli text-generation-webui quando hai bisogno di più backend di caricamento, delle prestazioni di EXL2 su NVIDIA, del caricamento di LoRA o dell’ecosistema di estensioni, oppure di accesso API tramite script per l’automazione e i flussi di sviluppo.

Scegli LM Studio o Jan quando desideri un installer ben rifinito, una ricerca integrata di modelli con download in un solo clic e una configurazione minima. Consulta la Guida completa a LM Studio per una guida dettagliata su questa opzione.

Se stai valutando se l’inferenza locale valga effettivamente il costo hardware, il Calcolatore del punto di pareggio tra auto-hosting e utilizzo di API può quantificare il compromesso rispetto al pagamento per l’accesso all’API in base al tuo volume di utilizzo.

Domande frequenti

Perché l’installer con un solo clic richiede così tanto tempo alla prima esecuzione?

Scarica Miniconda e crea un ambiente Python isolato con PyTorch e tutte le librerie per il caricamento dei modelli da zero. Su una connessione veloce ciò richiede tipicamente 5–15 minuti. Avvii successivi saltano questo passaggio e partono in pochi secondi.

Posso eseguire text-generation-webui senza GPU?

Sì. Seleziona l’opzione CPU-only durante l’installazione, quindi imposta n-gpu-layers a 0 al momento del caricamento di un modello GGUF. Un modello da 7B può generare 2–5 token al secondo su una CPU desktop moderna — sufficiente per test ma lento per conversazioni. Quantizzazioni più leggere (Q4 e inferiori) migliorano il throughput. Controlla le migliori GPU per LLM locali se stai considerando un aggiornamento hardware.

Come aggiorno text-generation-webui?

Esegui git pull nella directory del repository per recuperare l’ultimo codice, quindi riesegui lo script di avvio. Lo script rileva le modifiche all’ambiente e aggiorna automaticamente le dipendenze. Puoi anche eseguire manualmente pip install -r requirements.txt nell’ambiente Conda attivo, se preferisci un aggiornamento mirato.

Qual è la differenza tra GGUF ed EXL2?

Entrambi sono formati quantizzati che riducono le dimensioni del file del modello e i requisiti di VRAM. GGUF (tramite llama.cpp) funziona su NVIDIA, AMD e Apple Silicon — è la scelta più portabile e dispone della maggiore disponibilità di modelli. EXL2 (tramite ExLlamaV2) è supportato esclusivamente su NVIDIA, ma genera generalmente token più velocemente a parità di qualità. Se possiedi una GPU NVIDIA e la velocità è la priorità, vale la pena procurarsi modelli in formato EXL2.

Dove vengono salvati i log delle conversazioni?

I log vengono memorizzati nella cartella text-generation-webui/logs/. Ogni conversazione viene salvata come file JSON. Puoi inoltre esportarla direttamente dall’interfaccia della scheda Chat utilizzando il pulsante di download sotto la finestra della conversazione.

Più utenti possono connettersi a un’unica istanza?

Il --listen Il flag di avvio rende il server accessibile sulla tua rete locale anziché solo su localhost. Tuttavia, text-generation-webui non è progettato per distribuzioni produttive multi-utente: non include autenticazione integrata e l’interfaccia Gradio supporta una sola sessione alla volta. L’estensione OpenAI API gestisce meglio le richieste API concorrenti rispetto all’interfaccia web nei casi con più client, ma, se si espone il servizio oltre localhost, è necessario aggiungere un reverse proxy con autenticazione.