È possibile avviare un endpoint LLM privato e compatibile con OpenAI sull'infrastruttura Hugging Face grazie a un singolo comando: non è necessario disporre di server o di Kubernetes, si applica il pagamento al secondo. Dopo l'avvio, lo si può accedere dal proprio computer, da un notebook o da qualsiasi altra posizione.

Si tratta del metodo più rapido per eseguire un modello con test, valutazioni o generazione su larga scala. Se si è alla ricerca, invece, di un servizio gestito e pronto per la produzione, si utilizzano invece gli Inference Endpoints (per maggiori informazioni su quando utilizzarli e su quando scegliere gli altri, si continui a leggere alla fine del paragrafo).

hf jobs run rappresenta sostanzialmente docker run per l'infrastruttura Hugging Face. Si utilizzano le immagini ufficiali vllm/vllm-openai, si chiede una GPU con --flavor, e si espone la porta di vLLM con --expose:

--expose 8000 instrada la porta del container attraverso il proxy dei lavori pubblici HF (per informazioni dettagliate si consulti il Manuale di servizio dei modelli).

Il comando stampa l'URL al quale è raggiungibile il server:

6a381ca1953ed90bfb947332 è il job ID. Si tenga conto di esso, perché ne avremo bisogno. Si utilizzerà <job_id> come segnaposto per il resto dell'articolo.

Si attendano un paio di minuti per scaricare i pesi e per l'attivazione completa del modello. Quando i log mostrano "Application startup complete", il server è attivo.

vLLM si basa sull'API OpenAI, e ogni richiesta richiede il token di accesso a HF come token bearer. Il modo più rapido per effettuare una query è utilizzare curl:

Ritorna il formato JSON come OpenAI, con choices[0].message.content che mostra "Hello! How can I assist you today? 😊".

O alternativamente si utilizza Python per puntare il client OpenAI all'URL esposto e fornire il token come chiave API:

Controllo di salute rapido

Prima di iniziare, curl https://<job_id>--8000.hf.jobs/v1/models -H "Authorization: Bearer $(hf auth token)" dovrà elencare il modello.

Il punto di accesso non è pubblico, è protetto da un token HF con autorizzazioni di lettura.

L'interfaccia del proxy dei lavori funge da gate di API, l'accesso è limitato all'utente e al proprio organismo.

Non condividere l'URL, né tantomeno il token, in luoghi poco sicuri. Se si richiede accesso pubblico, si debba considerare un gateway diverso. Per informazioni su HF Jobs ed Endpoints di inferenza: proseguire alla fine.

I jobs vengono fatturati al secondo, quindi quando non in uso è consigliabile arrestarlo:

--timeout si utilizza come protezione automatica (il job si arresta), ma un arresto esplicito risulta più economico.

Ad esempio, 10g-larg costa 1,50 dollari/ora. Si consulta hf jobs hardware per un piano completo e selezionare il flavor più piccolo che si adatta al modello.

Modelli su larga scala

Lo stesso comando funziona per modelli molto grandi: si sceglie un --flavor più robusto e si indica a vLLM di suddividere il modello tra diverse GPU utilizzando --tensor-parallel-size. Ad esempio, per un modello Qwen3.5 122B su 2× H200:

--tensor-parallel-size dovrà corrispondere al numero di GPU nel flavor (h200x2→ 2, h200x8→ 8).

Digitare hf jobs hardware per verificare le opzioni e dare ai modelli grandi un --timeout più lungo, poiché richiedono più tempo per essere scaricati e caricati.

Per modelli grandi i flavor H200 sono solitamente il rapporto qualità-prezzo migliore.

--max-model-len 32768 --max-num-seqs 256 sono specifici per Qwen3.5-122B, un modello ibrido Mamba/attention con 256K-token di default. Per mantenere i limiti della memoria GPU, è consigliabile regolare la lunghezza dei token e il conteggio delle sequenze parallele. Se il modello si arresta a causa di errori di memoria o cache, regolare questi due parametri può risultare determinante. Tutto il resto (l'URL esposto, il client OpenAI e l'autenticazione del token) rimarrà invariato.

Opzioni alternative

Più semplice utilizzare un'interfaccia di chat rispetto a curl? Un paio di righe in Gradio si collegano al punto accesso. Aggiungere --reasoning-parser deepseek_r1 al comando vllm serve in modo che il ragionamento di Qwen3 sia restituito in un campo separato (facoltativo, ma molto utile). Digitando queste righe si esegue localmente il codice (servirà solo il job ID):

Eseguire il codice, aprire http://127.0.0.1:7860 e iniziare a chiacchierare: il ragionamento scorre nel pannello espandibile, l'output si visualizza in basso.

Bisogno di Debug

Iscriversi all'interno del lavoro in esecuzione per controllare eventuali problemi iniziali, monitorare la memoria GPU o seguire i log in tempo reale? Si può accedere direttamente al container in esecuzione aprendo una shell. Avviare con --ssh e assicurarsi che la chiave pubblica sia registrata in huggingface.co/settings/keys:

Ora si è dentro al container, dove si può eseguire nvidia-smi, controllare il processo o manipolare il modello direttamente — facilita notevolmente il debug e il monitoraggio rispetto a leggere i log esterni. Il supporto SSH richiede la versione 1.20.0 o superiore di huggingface_hub.

Agenti per Codifica Terminale

Lo stesso endpoint può supportare un agente di codifica interattiva. L'agente Pi è progettato in modo indipendente dal fornitore. Si punti su questo job e si ottiene un agente Read/Write/Edit/Bash in esecuzione su un modello personalizzato sull'utente.

Una configurazione preliminare è richiesta: gli agenti agiscono sui modelli tramite richieste, e v