Esegui un endpoint LLM privato e OpenAI-compatibile sull'infrastruttura di Hugging Face con un solo comando - non è necessario provare server né configurare Kubernetes. Pagherai per ogni secondo che rimane attivo. Una volta avviato, potrai interrogarlo dal tuo laptop, da un notebook oppure da qualsiasi altra piattaforma.
Questo è il modo più veloce per avviare un modello per test, valutazioni o generazione in batch. Se invece cerchi un servizio controllato pronto per la produzione, allora i Inference Endpoints sono la scelta giusta. Ne parleremo nel dettaglio alla fine di questa guida.
hf jobs run è alla base della gestione del contenitore su HF Infrastructure. Utilizziamo l'immagine ufficiale vllm/vllm-openai, chiediamo un GPU con --flavor e apriamo la porta di vLLM con --expose:
--expose 8000 instrada la porta del contenitore attraverso il proxy pubblico per i jobs di Hugging Face. Per saperne di più sul funzionamento completo consulta la guida Serve Models. Il comando visualizza l'URL dove puoi raggiungere il server:
6a381ca1953ed90bfb947332 è l'ID del tuo job. Tieni traccia di esso, ne avremo bisogno per le successive azioni del post.
Dai qualche minuto alla tua esecuzione per scaricare i pesi e avviare il modello. Quando i log mostreranno "Application startup complete", il tuo server sarà online.
vLLM implementa l'API OpenAI, e ogni richiesta avrà bisogno del tuo token HF come token bearer. Il modo più diretto per testarlo è utilizzare curl:
La risposta sarà simile alla tipica risposta di OpenAI, mantenendo il contenuto del messaggio in choices[0].message.content, ad esempio "Hello! How can I assist you today? 😊".
Oppure, utilizza Python, puntando il client OpenAI verso l'URL esposto e passando il token come chiave API:
Prima di iniziare, fai una rapida verifica di salute inviando una richiesta a https://
Autenticazione e Sicurezza
🔐 L'endpoint è protetto, non pubblici. Ogni richiesta dovrà includere un token HF con accesso leggibile al job. Una semplice visita con il browser verrebbe rifiutata. In effetti, il proxy dei job è la tua passerella API: l'accesso è limitato a te e alla tua organizzazione. Funziona bene per utili privati, ma tratta l'URL con cura: non condividerlo pensando che sarà accessibile liberamente e non inserire il tuo token in luoghi non sicuri. Se necessiti di accesso più specifico o pubblico, aggiungi un gateway appropriato davanti.
Gestione e Costi
I jobs vengono fatturati per ogni secondo in esecuzione. Spegni il server quando hai finito:
--timeout è una misura di sicurezza (fermerà automaticamente) ma annullarlo esplicitamente è più economico. Un server con a10g-large costa $1.50/h. Per il prezzo completo consulta hf jobs hardware e seleziona la potenza di calcolo più bassa richiesta per il tuo modello.
Supporto a Modelli di Grandi Dimensioni
Lo stesso comando funziona per modelli molto grandi - prova un --flavor più potente e istruisci vLLM a condividere il modello tra più GPU usando --tensor-parallel-size. Per esempio, il modello Qwen3.5 da 122B su 2× H200:
--tensor-parallel-size dovrebbe rispecchiare il numero delle GPU nel flavor selezionato (h200x2 → 2, h200x8 → 8). Esegui hf jobs hardware per scoprire le opzioni disponibili. Modelli grandi come il Qwen3.5 da 122B richiedono spesso di assegnare più --timeout, in quanto richiedono tanto tempo per scaricare e caricare.
I flag --max-model-len 32768 --max-num-seqs 256 sono specifici per questo modello: Qwen3.5-122B utilizza un'architettura ibrida Mamba/attention con un contesto predefinito di 256K token. Ridurre il numero di token e di sequenze parallele è utile per gestire la memoria disponibile su GPU. Se ti trovi un errore memory o block cache durante l'avvio, prova a ridurre questi parametri. Il resto (l'URL esposta, il client OpenAI e l'autenticazione con il token) rimarrà identico.
Sviluppo e Debug
Preferisci una finestra di chat invece dell'utilizzo curl? Alcune righe di Gradio si collegano facilmente allo stesso endpoint. Con aggiunge --reasoning-parser deepseek_r1 al comando vllm serve per recuperare le informazioni riguardo il ragionamento come un campo separato (non obbligatorio ma comodo), e puoi eseguire il codice sul tuo computer (basta l'ID del job):
Apri il link http://127.0.0.1:7860, inizia a chattare e segui i ragionamenti in tempo reale, con il risultato sottostante.
Utilizzo SSH per il Monitoraggio
Hai bisogno di verificare un errore di avvio, monitorare la memoria GPU oppure seguire i log in tempo reale? Puoi accedere direttamente al contenitore in esecuzione lanciando il job con --ssh e assicurati che la tua chiave pubblica sia registrata in huggingface.co/settings/keys:
Sei ora dentro al contenitore, dove puoi eseguire nvidia-smi, controllare il processo o interagire direttamente con il modello - questo rende il debugging e il monitoraggio molto più semplice che non leggere solo i log esterni. Il supporto per SSH richiede huggingface_hub >= 1.20.0.
Agenti di Codifica Interattivo
Lo stesso endpoint può supportare un agente di codifica interattivo su terminale. Pi è un framework agnostico per agenti. Puntandolo al job otterrai un agente di lettura/scrittura/modifica/bash in esecuzione su un modello hostato da te.
Ti serve configurare qualcosa inizialmente: gli agenti richiamano modelli attraverso richiamate ad uno strumento, e vLLM accetta tale funzionalità solo se il server è avviato con enable-auto-tool-choice e un parser --tool-call-parser conforme alla famiglia del modello (ad esempio hermes per Qwen3). Gli agenti beneficiano anche di un modello più forte, quindi qui è un buon momento per portare in gioco il formato modello più potente:
Puoi configurare il job come fornitore personalizzato in ~/.pi/agent/models.json:
Ora il modello creato qualche istruzione fa, funge da agente interattivo in terminale.