Guida implementazione vLLM

Guida implementazione vLLM

Indice dei contenuti Guida implementazione vLLM

1. Cos’è vLLM
2. A cosa serve: casi d’uso tipici
3. Requisiti hardware e software
4. Installazione passo dopo passo
5. Come avviare il server e fare le prime richieste
6. Caso d’uso pratico: chatbot interno aziendale
7. Conclusioni e formazione professionale

1. Cos’è vLLM

vLLM è una libreria open source veloce e semplice da usare per l’inferenza e il serving di Large Language Model (LLM). Originariamente sviluppata nello Sky Computing Lab dell’Università di Berkeley, è oggi uno dei progetti AI open source più attivi al mondo, mantenuto da una comunità di oltre 2.000 contributori provenienti da decine di istituzioni accademiche e aziende.

Il nome vLLM sta per “Virtual LLM” e il suo elemento tecnico distintivo è PagedAttention, un meccanismo di gestione della memoria ispirato al paging dei sistemi operativi. L’idea centrale di PagedAttention è partizionare la KV cache di ogni richiesta in blocchi (KV Blocks), ciascuno contenente chiavi e valori di attenzione per un numero fisso di token. L’algoritmo consente a questi blocchi di essere memorizzati in posizioni fisiche non contigue della memoria GPU, eliminando così sprechi e frammentazione.

vLLM supporta tecniche di quantizzazione come GPTQ, AWQ, INT4, INT8 e FP8, l’esecuzione rapida dei modelli tramite CUDA/HIP graph, il continuous batching delle richieste in ingresso e kernel CUDA ottimizzati con integrazione FlashAttention e FlashInfer.

2. A cosa serve: casi d’uso tipici – Guida implementazione vLLM

vLLM è progettato per chi vuole eseguire modelli linguistici di grandi dimensioni in produzione con alte prestazioni e costi contenuti. I principali scenari di utilizzo includono:

Servizi di inferenza ad alto traffico, dove è necessario gestire decine o centinaia di richieste simultanee senza degradazione delle prestazioni. Ambienti di sviluppo e test di applicazioni AI basate su modelli open source come Llama, Qwen, Mistral o Gemma. Pipeline di elaborazione batch di testi su larga scala, come classificazione, riassunti automatici o generazione di contenuti. Deployment aziendale privato di LLM, per mantenere i dati all’interno dell’infrastruttura interna senza dipendere da API cloud esterne.

vLLM supporta oltre 200 architetture di modelli su HuggingFace, tra cui modelli decoder-only come Llama e Qwen, modelli Mixture-of-Experts come Mixtral e DeepSeek-V3, modelli multimodali come LLaVA e Qwen-VL, e modelli di embedding e retrieval come E5-Mistral e ColBERT.

Un elemento di grande praticità per gli sviluppatori è che vLLM espone un server compatibile con le API OpenAI, con supporto aggiuntivo per le API Anthropic Messages e gRPC, rendendo possibile sostituire una chiamata a GPT-4 con un modello locale senza modificare una sola riga del codice applicativo.

3. Requisiti hardware e software

Prima di procedere all’installazione, è fondamentale verificare la compatibilità del proprio ambiente.

Hardware supportato: vLLM supporta GPU NVIDIA, GPU AMD e CPU x86/ARM/PowerPC. Sono disponibili inoltre plugin hardware per Google TPU, Intel Gaudi, IBM Spyre, Huawei Ascend, Apple Silicon e altro ancora. Per un deployment efficiente in produzione, si raccomanda almeno una GPU NVIDIA con 24 GB di VRAM (ad esempio A10G, RTX 3090/4090, A100, H100) per modelli da 7-13 miliardi di parametri. Per modelli più grandi, è necessario il multi-GPU con tensor parallelism.

Requisiti software: si raccomanda Python 3.12 come ambiente di esecuzione. Per GPU NVIDIA è richiesta la CUDA Toolkit (la versione raccomandata è CUDA 12.6 o superiore). Se si riscontrano difficoltà nel build, si consiglia di utilizzare l’immagine Docker ufficiale NVIDIA PyTorch. Il sistema operativo raccomandato è Linux (Ubuntu 22.04 o superiore). Non è supportato nativamente Windows senza WSL2

4. Installazione passo dopo passo

Il metodo più rapido utilizza uv, il moderno gestore di ambienti Python. Ecco la sequenza completa:

# Passo 1: Installare uv (se non già presente)
pip install uv

# Passo 2: Creare un ambiente virtuale con Python 3.12
uv venv vllm-env --python 3.12 --seed
source vllm-env/bin/activate

# Passo 3: Installare vLLM con rilevamento automatico del backend CUDA
uv pip install vllm --torch-backend=auto

# Verifica dell'installazione
python -c "import vllm; print(vllm.__version__)"

L’opzione --torch-backend=auto consente a uv di selezionare automaticamente il corretto indice PyTorch a runtime, ispezionando la versione del driver CUDA installato.

In alternativa, per chi preferisce Docker, vLLM offre immagini Docker ufficiali disponibili su Docker Hub come vllm/vllm-openai, che possono essere usate direttamente per avviare un server compatibile con le API OpenAI.

# Avvio tramite Docker (richiede nvidia-container-toolkit)
docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai \
  --model meta-llama/Llama-3.1-8B-Instruct

5. Come avviare il server e fare le prime richieste

Una volta installato, avviare il server di inferenza è immediato. Il comando seguente scarica automaticamente il modello da HuggingFace (la prima volta richiede tempo per il download):

# Avvio del server OpenAI-compatible su porta 8000
vllm serve meta-llama/Llama-3.2-3B-Instruct --port 8000

A server avviato, è possibile interagire con esso tramite qualsiasi client HTTP. Con Python e la libreria openai:

from openai import OpenAI

# Puntare il client verso il server vLLM locale
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="token-non-necessario"  # vLLM non richiede autenticazione di default
)

risposta = client.chat.completions.create(
    model="meta-llama/Llama-3.2-3B-Instruct",
    messages=[
        {"role": "system", "content": "Sei un assistente tecnico esperto."},
        {"role": "user", "content": "Spiega cos'è il tensor parallelism in due frasi."}
    ],
    temperature=0.7,
    max_tokens=256
)

print(risposta.choices[0].message.content)

Per l’inferenza offline in batch (senza server HTTP), vLLM offre anche un’API Python diretta:

from vllm import LLM, SamplingParams

llm = LLM(model="meta-llama/Llama-3.2-3B-Instruct")

prompts = [
    "Scrivi una breve descrizione di Python:",
    "Quali sono i vantaggi di Kubernetes?",
    "Cos'è una REST API?"
]

params = SamplingParams(temperature=0.8, top_p=0.95, max_tokens=150)
outputs = llm.generate(prompts, params)

for output in outputs:
    print(f"Prompt: {output.prompt}")
    print(f"Risposta: {output.outputs[0].text}\n")

6. Caso d’uso pratico: chatbot interno aziendale

Supponiamo di dover implementare un assistente interno per un’azienda software, in grado di rispondere a domande sulla documentazione tecnica aziendale senza inviare dati sensibili a servizi cloud esterni.

L’architettura è semplice: un modello Llama-3.1-8B-Instruct in esecuzione su un server con GPU A10G (24 GB VRAM), esposto internamente tramite vLLM. Il frontend (ad esempio un’interfaccia Slack o web) invia le richieste all’API OpenAI-compatible di vLLM.

import os
from openai import OpenAI

CONTEXT_AZIENDALE = """
Sei l'assistente tecnico interno di Acme Srl. 
Rispondi solo in italiano. 
Fai riferimento alle best practice di sviluppo software aziendale.
Non condividere informazioni riservate.
"""

def chiedi_assistente(domanda: str, storico: list) -> str:
    client = OpenAI(
        base_url=os.getenv("VLLM_ENDPOINT", "http://gpu-server:8000/v1"),
        api_key="interno"
    )

    messaggi = [{"role": "system", "content": CONTEXT_AZIENDALE}]
    messaggi.extend(storico)
    messaggi.append({"role": "user", "content": domanda})

    risposta = client.chat.completions.create(
        model="meta-llama/Llama-3.1-8B-Instruct",
        messages=messaggi,
        temperature=0.5,
        max_tokens=512
    )
    return risposta.choices[0].message.content

# Esempio di conversazione
storico = []
risposta = chiedi_assistente("Come gestiamo il versionamento dei microservizi?", storico)
print(risposta)

Questo pattern è immediatamente scalabile: vLLM supporta il multi-LoRA per servire contemporaneamente richieste per più adapter LoRA in modo efficiente, il che permette di personalizzare il comportamento del modello per diversi team o reparti aziendali senza moltiplicare le istanze del server.

7. Conclusioni e formazione professionale

vLLM rappresenta oggi uno degli strumenti più maturi e performanti per portare modelli linguistici di grandi dimensioni in ambienti di produzione, combinando semplicità di utilizzo, flessibilità hardware e prestazioni di livello enterprise.

Quello che emerge con chiarezza, tuttavia, va oltre il singolo strumento: l’intelligenza artificiale ha ormai permeato ogni aspetto del lavoro degli sviluppatori software, dall’automazione del testing alla generazione di codice, dal deployment intelligente all’analisi dei log. Non è più possibile distinguere nettamente il ruolo dello sviluppatore da quello del professionista AI. Chi lavora nell’IT si trova quotidianamente a dover scegliere, configurare, integrare e ottimizzare strumenti basati su modelli linguistici, e farlo in modo consapevole richiede una formazione tecnica solida e aggiornata.

Solo un percorso formativo strutturato consente ai team IT di adottare questi strumenti in modo efficace, evitando errori costosi, scelte architetturali sbagliate e rischi di sicurezza. La differenza tra un team che “usa l’AI” e un team che “sa usare l’AI” si misura in mesi di vantaggio competitivo.

Per questo motivo, se sei un’azienda che vuole accelerare l’adozione consapevole degli strumenti di AI Generativa nel proprio reparto tecnico, ti consigliamo i Corsi AI Generativa di Innovaformazione, pensati appositamente per aziende e team IT.

I corsi sono erogati in modalità online classe virtuale, con calendario concordabile direttamente con la tua organizzazione e un preventivo dedicato in base alle esigenze specifiche del team. È inoltre possibile accedere a finanziamenti tramite Fondimpresa o altri fondi interprofessionali, con supporto nella predisposizione del piano formativo finanziato.

Per richiedere informazioni, un preventivo o iniziare a pianificare il percorso formativo per il tuo team:

• 📧 info@innovaformazione.net
• 📞 347 101 2275 — Dario Carrassi

(fonte) (fonte) (fonte)

Per altri articoli di settore consigliamo di navigare sul nostro blog QUI.