Use

Esecuzione locale di Xinference

Cominciamo con un classico modello linguistico di grandi dimensioni qwen2.5-instruct per mostrare come eseguire un modello di grandi dimensioni localmente utilizzando Xinference.

Dopo questo avvio rapido, puoi proseguire imparando come distribuire Xinference in un ambiente cluster distribuito.

Avviare il servizio locale

Prima, assicurati di aver installato Xinference localmente seguendo la guida in questo documento. Avvia il servizio Xinference locale utilizzando il seguente comando:

shelloutput

xinference-local --host 0.0.0.0 --port 9997

Nota

Per impostazione predefinita, Xinference utilizza <HOME>/.xinference come directory principale per memorizzare alcune informazioni necessarie, come file di log e file di modelli, dove <HOME> è la directory home dell’utente corrente.

Puoi modificare la directory principale configurando la variabile d’ambiente XINFERENCE_HOME, ad esempio:

XINFERENCE_HOME=/tmp/xinference xinference-local --host 0.0.0.0 --port 9997

Congratulazioni! Hai avviato il servizio Xinference in locale. Una volta che il servizio Xinference è in esecuzione, puoi utilizzarlo in diversi modi, tra cui tramite interfaccia web, comandi cURL, riga di comando o l’SDK Python di Xinference.

È possibile utilizzare l’interfaccia utente accedendo a http://127.0.0.1:9997/ui e visualizzare la documentazione dell’API all’indirizzo http://127.0.0.1:9997/docs.

È possibile installarlo tramite il seguente comando e poi utilizzarlo con lo strumento a riga di comando Xinference o con codice Python:

pip install xinference

Lo strumento a riga di comando è xinference. È possibile visualizzare i comandi disponibili tramite il seguente comando:

shelloutput

xinference --help

Se è necessario installare solo l’SDK Python di Xinference, è possibile utilizzare il seguente comando per installare le dipendenze minime. È importante notare che la versione deve corrispondere a quella del servizio Xinference.

pip install xinference-client==${SERVER_VERSION}

motore di inferenza del modello

A partire dalla versione v0.11.0, prima di caricare un modello LLM, è necessario specificare il motore di inferenza specifico. Attualmente, Xinference supporta i seguenti motori di inferenza:

• vllm

• sglang

• llama.cpp

• transformers

• MLX

Per maggiori dettagli su questi motori di inferenza, consulta qui.

Attenzione, quando si carica il modello LLM, il motore che può essere eseguito è strettamente correlato ai parametri model_format e quantization.

Xinference fornisce il comando xinference engine per aiutarti a consultare le combinazioni di parametri correlate.

Ad esempio:

1. Desidero consultare le combinazioni di parametri relative al modello qwen-chat per determinare come possa funzionare su vari motori di inferenza.

xinference engine -e <xinference_endpoint> --model-name qwen-chat

1. Voglio eseguire qwen-chat sul motore di inferenza VLLM, ma non so quali altri parametri siano adatti a questo requisito.

xinference engine -e <xinference_endpoint> --model-name qwen-chat --model-engine vllm

1. Voglio caricare il modello qwen-chat in formato GGUF, ho bisogno di conoscere le altre combinazioni di parametri.

xinference engine -e <xinference_endpoint> --model-name qwen-chat -f ggufv2

In sintesi, rispetto alla versione precedente, quando si carica un modello LLM, è necessario passare il parametro aggiuntivo model_engine. Puoi utilizzare il comando xinference engine per verificare la relazione tra il motore di inferenza che desideri eseguire e altre combinazioni di parametri.

Nota

Riguardo a quando utilizzare quale motore, ecco alcuni suggerimenti:

• Linux

  • Quando possibile, dai la priorità all’uso di vLLM o SGLang, poiché offrono prestazioni migliori.

  • Se le risorse sono limitate, si può considerare l’uso di llama.cpp, poiché offre più opzioni di quantizzazione.

  • Altri considerano l’uso di Transformers, che supporta quasi tutti i modelli.

• Windows

  • Si consiglia di utilizzare WSL, in questo caso scegliere la stessa opzione di Linux.

  • Altre volte si consiglia di usare llama.cpp, per i modelli non supportati, si sceglie di usare Transformers.

• Mac

  • Quando supportato dal modello, si consiglia di utilizzare MLX Engine, che offre le migliori prestazioni.

  • Altre volte si consiglia di usare llama.cpp; per i modelli non supportati, optare per Transformers.

esegui qwen2.5-instruct

Eseguiamo un modello integrato qwen2.5-instruct. Quando devi eseguire un modello, il primo avvio richiede il download dei parametri del modello da HuggingFace, che generalmente richiede da 10 a 30 minuti a seconda delle dimensioni del modello. Una volta completato il download, Xinference lo memorizza nella cache locale, quindi non sarà necessario scaricarlo nuovamente per futuri esecuzioni dello stesso modello.

Nota

Xinference consente anche di scaricare modelli da altre piattaforme di hosting. È possibile specificare variabili d’ambiente quando si avvia Xinference. Ad esempio, se si desidera scaricare un modello da ModelScope, è possibile utilizzare il seguente comando:

XINFERENCE_MODEL_SRC=modelscope xinference-local --host 0.0.0.0 --port 9997

È possibile specificare l’UID del modello utilizzando il parametro --model-uid o -u. Se non specificato, Xinference genererà un ID casuale. L’ID predefinito corrisponde al nome del modello.

shellcURLPythonoutput

xinference launch --model-engine <inference_engine> -n qwen2.5-instruct -s 0_5 -f pytorch

Nota

Per alcuni motori di inferenza, come vllm, l’utente deve specificare i parametri relativi al motore durante l’esecuzione del modello. In questo caso, è sufficiente specificare direttamente il nome del parametro e il valore corrispondente nella riga di comando, ad esempio:

xinference launch --model-engine vllm -n qwen2.5-instruct -s 0_5 -f pytorch --gpu_memory_utilization 0.9

Durante l’esecuzione del modello, gpu_memory_utilization=0.9 viene passato al backend vllm.

Nota

Per ulteriori suggerimenti sul caricamento dei modelli, consulta Guida al caricamento dei modelli.

A questo punto, congratulazioni, hai avviato con successo qwen2.5-instruct tramite Xinference. Una volta che il modello è in esecuzione, puoi interagire con esso tramite riga di comando, cURL o codice Python:

cURLPythonoutput

curl -X 'POST' \
  'http://127.0.0.1:9997/v1/chat/completions' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen2.5-instruct",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "What is the largest animal?"
        }
    ]
  }'

Xinference fornisce API compatibili con OpenAI, quindi è possibile utilizzare i modelli eseguiti da Xinference come sostituti locali di OpenAI. Ad esempio:

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:9997/v1", api_key="not used actually")

response = client.chat.completions.create(
    model="qwen2.5-instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the largest animal?"}
    ]
)
print(response)

Ecco le API OpenAI supportate:

• Generazione di dialoghi: https://platform.openai.com/docs/api-reference/chat

• https://platform.openai.com/docs/api-reference/completions

• Generazione di vettori: https://platform.openai.com/docs/api-reference/embeddings

Xinference supporta anche la chiamata all’API Anthropic tramite l’URL di base http://127.0.0.1:9997/anthropic, consentendoti di utilizzare Xinference in ambienti come Claude Code. Per maggiori dettagli, consulta anthropic client.

Gestione dei modelli

Oltre ad avviare il modello, Xinference offre la possibilità di gestire l’intero ciclo di vita del modello. Allo stesso modo, puoi utilizzare la riga di comando, cURL e il codice Python per la gestione.

Modelli supportati da Xinference per tipo specificato:

shellcURLPython

xinference registrations -t LLM

Il seguente comando elenca tutti i modelli in esecuzione:

shellcURLPython

xinference list

Quando non hai più bisogno di un modello in esecuzione, puoi fermarlo e liberare le risorse nel modo seguente:

shellcURLPython

xinference terminate --model-uid "qwen2.5-instruct"

Distribuzione di Xinference in un cluster

Per distribuire Xinference in un ambiente cluster, è necessario avviare un nodo supervisor su una macchina e avviare i nodi worker sulla stessa macchina o su altre macchine.

Innanzitutto, secondo la documentazione, assicurati che Xinference sia installato su tutti i server. Successivamente, segui i passaggi:

Avviare Supervisor

Esegui il seguente comando sul server per avviare il nodo Supervisor:

xinference-supervisor -H "${supervisor_host}"

Sostituisci ${supervisor_host} con l’IP del nodo corrente.

È possibile accedere all’interfaccia web all’indirizzo http://${supervisor_host}:9997/ui e alla documentazione API all’indirizzo http://${supervisor_host}:9997/docs.

Avviare il Worker

Esegui il seguente comando sulla macchina in cui deve essere avviato il worker di Xinference:

xinference-worker -e "http://${supervisor_host}:9997" -H "${worker_host}"

Nota

È importante notare che è necessario utilizzare l’IP del nodo Worker corrente per sostituire ${worker_host}.

Nota

È importante notare che, se hai bisogno di interagire con il cluster tramite la riga di comando, dovresti specificare l’indirizzo del supervisor utilizzando il parametro -e o --endpoint, ad esempio:

xinference launch -n qwen2.5-instruct -s 0_5 -f pytorch -e "http://${supervisor_host}:9997"

Distribuisci Xinference con Docker

Esegui Xinference in un contenitore con il seguente comando:

Esegui su una macchina con scheda grafica NVIDIA.

Per CUDA 12.4:

docker run -e XINFERENCE_MODEL_SRC=modelscope -p 9998:9997 --gpus all xprobe/xinference:<your_version> xinference-local -H 0.0.0.0 --log-level debug

Per CUDA 12.8:

Added in version v1.8.1: La versione CUDA 12.8 è sperimentale, i vostri feedback per miglioramenti sono benvenuti.

Cambiato nella versione v1.16.0: CUDA 12.8 è stato rimosso nella versione v1.16.0.

docker run -e XINFERENCE_MODEL_SRC=modelscope -p 9998:9997 --gpus all xprobe/xinference:<your_version>-cu128 xinference-local -H 0.0.0.0 --log-level debug

Per CUDA 12.9:

Added in version v1.16.0: Dopo il rilascio di Xinference v2.0.0, CUDA 12.9 diventerà la versione predefinita.

docker run -e XINFERENCE_MODEL_SRC=modelscope -p 9998:9997 --gpus all xprobe/xinference:<your_version>-cu129 xinference-local -H 0.0.0.0 --log-level debug

Esecuzione su una macchina con solo CPU

docker run -e XINFERENCE_MODEL_SRC=modelscope -p 9998:9997 xprobe/xinference:<your_version>-cpu xinference-local -H 0.0.0.0 --log-level debug

Sostituisci <your_version> con la versione di Xinference, ad esempio v0.10.3, e puoi usare latest per la versione più recente.

Per maggiori dettagli sull’uso di Docker, consultare uso dell’immagine Docker.

Altro

Congratulazioni! Hai già acquisito le basi dell’uso di Xinference! Per aiutarti a utilizzare meglio lo strumento, ecco altri documenti e risorse di guida:

• Come creare diversi tipi di modelli con Python

• Scegliere il motore di inferenza corretto