vLLM e Langfuse: server LLM in 12 passi in 90 minuti (2026)

Perché osservare un LLM self‑hosted

L’architettura che proponiamo si basa su tre componenti fondamentali: il server vLLM, l’applicazione FastAPI e la piattaforma di tracing Langfuse. Il server vLLM carica il modello in GPU e espone le API compatibili con OpenAI su una porta locale. L’applicazione, scritta in Python, chiama quel server usando il client ufficiale openai, avvolto dalla versione di Langfuse. Langfuse, in cloud o self‑hosted, riceve le tracce e le trasforma in tabelle, grafici e allarmi.

Guardare solo i log di vLLM non è sufficiente perché i log descrivono il motore, non il prodotto. Essi indicano che una richiesta è durata un certo numero di secondi, ma non mostrano chi l’ha fatta, quale prompt di sistema era attivo, se la risposta era in italiano o se la stessa domanda, ripetuta dieci volte, ha prodotto dieci risposte diverse. Una piattaforma di osservabilità lega tutto a una singola traccia, consentendo di ricostruire il contesto completo.

Motivazioni legali ed economiche

Servire il modello in casa mantiene i prompt all’interno del proprio perimetro, una necessità particolarmente importante in Europa. La regione UE di Langfuse Cloud (cloud.langfuse.com) o un’installazione self‑hosted tengono le tracce vicino al luogo di elaborazione, riducendo i rischi di trasferimento di dati personali. Le banche europee, ad esempio, valutano i modelli open‑weight perché offrono controllo sui dati, costi prevedibili e nessuna dipendenza da un unico fornitore di API.

Le tracce, però, contengono testo degli utenti e devono essere trattate come dati personali, rispettando le cautele descritte nella sezione sui consigli avanzati.

Cosa otterrai al termine del percorso

Al termine dei 12 passi avrai a disposizione:

• Un pannello con richieste per minuto, latenza per modello, token in ingresso e in uscita.
• Un costo stimato per utente.
• Due punteggi automatici sulla qualità delle risposte.
• Una procedura di 10 minuti per scoprire perché un utente ha ricevuto una risposta sbagliata.

In pratica, avrai un osservatorio completo sul comportamento del tuo LLM, pronto a supportare team di sviluppo e operation.

Prerequisiti e versioni da installare

Il percorso più semplice usa Docker per vLLM e un ambiente virtuale Python per l’applicazione. La documentazione di vLLM indica l’immagine vllm/vllm-openai come strada principale per il deploy; il quick‑start tradizionale sta passando in secondo piano, perciò si parte dal container.

Tabella dei componenti richiesti

• vLLM: v0.33.0 (immagine vllm/vllm-openai), tag fissato, niente latest in produzione.
• Python: 3.12 consigliato (minimo 3.10 per vLLM). Un solo interprete per ambiente virtuale e container applicativo.
• CUDA: 13.x (13.0 e 13.1). Le immagini CUDA 12.9 non vengono più pubblicate.
• Driver NVIDIA: abbastanza recente per CUDA 13. Il minimo è indicato nella pagina Docker di vLLM e nella tabella di compatibilità NVIDIA.
• Docker: motore recente con NVIDIA Container Toolkit. Serve il runtime nvidia per il flag --gpus all.
• Langfuse: Cloud (regione UE) o self‑hosted v4. Progetto creato su v4, chiavi pubblica e segreta.
• SDK Langfuse: ultima major per Python, installata con pip install langfuse.
• Client OpenAI: pacchetto openai 1.x o successivo, compatibile con l’integrazione di Langfuse.

Se la tua GPU è consumer e utilizza un driver datato, aggiornalo prima di avviare Docker: le immagini CUDA 13 richiedono un driver recente, mentre la modalità di compatibilità accetta driver più vecchi solo su alcune GPU professionali e datacenter.

Modello di esempio

Il modello suggerito nel quickstart di vLLM è Qwen/Qwen2.5-1.5B-Instruct. Non è il più recente della famiglia, ma è leggero, gira su GPU consumer con pochi gigabyte liberi, risponde in italiano in modo accettabile per una prova e permette di concentrarsi sulla pipeline. Il nome del modello è definito in una variabile d’ambiente, quindi cambiarlo con un modello più grande richiede una sola riga di configurazione.

Per completare il setup ti serviranno:

• Un account Hugging Face con token di lettura (per i modelli che richiedono accettare una licenza).
• Un account Langfuse con un progetto vuoto.
• Una porta 8000 libera sulla macchina.

Tutto il resto verrà creato passo passo.

Novità di novembre 2026: vLLM 0.33.0 e Langfuse v4

Molti tutorial ancora in circolazione descrivono versioni di un anno fa, con comandi che oggi falliscono. Prima di scrivere codice è fondamentale fissare lo stato delle cose al 8 novembre 2026.

Tabella di riepilogo

• vLLM: v0.33.0 disponibile (novembre 2026). PyTorch 2.14, CUDA 12.9 abbandonato, default su CUDA 13. Requisiti: Python 3.10+, consigliato 3.12+, compatibile con tutte le CUDA 13.x.
• Langfuse v4: disponibile su Cloud e generale per self‑hosted (17 agosto 2026). Modello dati centrato sulle observation, tabelle e dashboard più veloci.
• Langfuse Cloud: solo v4 (16 novembre 2026). Endpoint e funzioni v3 rimossi, è necessario completare le azioni di migrazione.
• Langfuse self‑hosted v3: solo patch di sicurezza fino a gennaio 2027. Nessun cutover forzato, puoi aggiornare con calma.
• Langfuse AI Gateway: public beta (4 novembre 2026). Le app possono puntare a Langfuse invece che al provider, con tracing automatico.
• Tokenizzazione automatica Langfuse: in ritiro (dal 6 novembre 2026). L’uso dei token deve arrivare dal server, altrimenti risulta mancante.

Le due righe più critiche sono la rimozione della tokenizzazione automatica e la scadenza del 16 novembre per gli endpoint v3. Se il tuo server non restituisce l’uso dei token, la traccia mostrerà un valore mancante al posto di una stima fuorviante. Con vLLM il problema si evita, ma con lo streaming serve un’opzione esplicita che vedremo al passo 8.

Se usi Langfuse Cloud con progetti creati prima della v4, la pagina di migrazione mostra le azioni da completare e Langfuse invia agli amministratori dei progetti un riepilogo. Per un progetto nuovo non devi fare nulla, ma le chiavi e l’SDK devono parlare con gli endpoint v4.

Passo‑passo: 12 step per il server LLM

Passo 1 – Preparare l’ambiente Docker: installa Docker Engine e NVIDIA Container Toolkit. Verifica il driver con nvidia-smi e assicurati che la GPU supporti CUDA 13.

Passo 2 – Pull dell’immagine vLLM: docker pull vllm/vllm-openai:0.33.0. L’immagine contiene PyTorch 2.14 e le librerie CUDA 13 pre‑installate.

Passo 3 – Configurare le variabili d’ambiente: definisci MODELID=Qwen/Qwen2.5-1.5B-Instruct, HFTOKEN=yourhftoken, CUDAVISIBLEDEVICES=0. Puoi cambiare MODELID in futuro con una sola riga.

Passo 4 – Avviare il container vLLM: docker run --gpus all -p 8000:8000 -e MODELID -e HFTOKEN vllm/vllm-openai:0.33.0 --port 8000. Il server espone le API OpenAI su http://localhost:8000/v1.

Passo 5 – Creare l’ambiente Python per l’applicazione: python -m venv .venv && source .venv/bin/activate. Installa le dipendenze: pip install fastapi uvicorn openai langfuse.

Passo 6 – Configurare Langfuse: crea un progetto su Langfuse Cloud (regione UE) o installa la versione self‑hosted v4. Ottieni le chiavi LANGFUSEPUBLICKEY e LANGFUSESECRETKEY e impostale come variabili d’ambiente.

Passo 7 – Scrivere l’app FastAPI: crea app.py con un endpoint /chat che riceve prompt, chiama il client OpenAI puntando a http://localhost:8000/v1, e avvolge la chiamata con il wrapper Langfuse @langfuse.trace. Salva prompt, risposta, token, latenza, utente e sessione.

Passo 8 – Gestire lo streaming e i token: attiva lo streaming con stream=True e aggiungi l’opzione logprobs=True per ottenere il conteggio dei token dal server. Senza questi parametri Langfuse non potrà registrare il numero di token usati.

Passo 9 – Avviare l’applicazione: uvicorn app:app --host 0.0.0.0 --port 8080. Ora l’app è raggiungibile su http://localhost:8080 e invia tracce a Langfuse.

Passo 10 – Verificare le tracce in Langfuse: accedi al dashboard, controlla le osservazioni, i grafici di latenza e i punteggi di qualità. Configura allarmi per soglie di latenza o errori di risposta.

Passo 11 – Analisi dei costi per utente: Langfuse calcola il costo stimato in base al numero di token in ingresso e in uscita. Usa il filtro “utente” per ottenere il consumo individuale.

Passo 12 – Migrazione e manutenzione: se utilizzi Langfuse Cloud, segui la checklist di migrazione v3→v4. Aggiorna periodicamente il driver NVIDIA e le versioni Docker per mantenere la compatibilità con CUDA 13.

Consigli avanzati e best practice

Gestione della privacy: le tracce contengono testo degli utenti; assicurati di anonimizzare o cancellare dati sensibili secondo il GDPR. Langfuse offre API per la rimozione programmata delle osservazioni.

Scalabilità: per servire più richieste contemporanee, replica il container vLLM su più GPU e usa un bilanciatore di carico (es. Nginx) davanti all’app FastAPI.

Monitoraggio della GPU: integra nvidia-smi con Prometheus per raccogliere metriche di utilizzo memoria e temperatura, così da correlare picchi di latenza a saturazione della GPU.

Versioning dei modelli: mantieni un file models.yml con nome, versione, hash SHA256 e data di deploy. Aggiorna la variabile MODELID solo dopo aver testato il nuovo modello in un ambiente di staging.

Debugging rapido: Langfuse permette di filtrare le tracce per session_id. Se un utente segnala una risposta sbagliata, basta cercare la sua sessione per vedere prompt, top‑p, temperature e eventuali errori di streaming.

Conclusioni

Combinare vLLM 0.33.0 e Langfuse v4 fornisce una soluzione completa per servire modelli open‑weight in modo rapido, sicuro e osservabile. In circa 90 minuti, con una GPU NVIDIA compatibile e Docker, è possibile passare dal download del modello su Hugging Face al deployment di un assistente interno che registra ogni dettaglio della conversazione. Le novità di novembre 2026 – soprattutto la rimozione della tokenizzazione automatica e la migrazione obbligatoria a v4 – richiedono attenzione, ma garantiscono un ecosistema più robusto e pronto per le esigenze di compliance europee. Seguendo i 12 step descritti, avrai un’infrastruttura pronta a scalare, a monitorare costi e performance e a fornire feedback di qualità in tempo reale.