ambiente virtuale del modello#

Added in version v1.5.0.

Background#

Alcuni modelli non vengono più mantenuti dopo il rilascio e le versioni delle librerie da cui dipendono rimangono obsolete. Ad esempio, il modello GOT-OCR2 dipende ancora da transformers 4.37.2. Se si aggiorna questa libreria a una versione più recente, il modello non funzionerà correttamente; mentre molti modelli nuovi richiedono la versione più recente di transformers. Questa differenza di versione può causare conflitti di dipendenza.

Soluzione#

Per risolvere questo problema, abbiamo introdotto la funzionalità ambiente virtuale del modello.

Eseguire il seguente comando per installare le dipendenze necessarie per questa funzionalità.

# all
pip install 'xinference[all]'
# or virtualenv
pip install 'xinference[virtualenv]'

Abilita questa funzionalità impostando la variabile d’ambiente XINFERENCE_ENABLE_VIRTUAL_ENV=1.

Esempi di utilizzo:

# For command line
XINFERENCE_ENABLE_VIRTUAL_ENV=1 xinference-local ...

# For Docker
docker run -e XINFERENCE_ENABLE_VIRTUAL_ENV=1 ...

Avvertimento

Questa funzionalità richiede una connessione di rete o l’utilizzo di un servizio mirror PyPI self-hosted.

Xinference erediterà per impostazione predefinita la configurazione corrente di pip.

Nota

Nota: quando si avvia il motore del modello vLLM/SgLang in un ambiente virtuale, se si incontra un errore cuDNN, è possibile impostare:

export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/cudnn/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/cusparselt/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/nccl/lib:$LD_LIBRARY_PATH

Cambiato nella versione v2.0.0: A partire da Xinference v2.0, la funzione ambiente virtuale del modello è abilitata per impostazione predefinita (cioè il valore predefinito di XINFERENCE_ENABLE_VIRTUAL_ENV è 1).

Per disabilitare globalmente questa funzionalità, imposta XINFERENCE_ENABLE_VIRTUAL_ENV=0 all’avvio di Xinference.

Quando questa funzione è attivata, Xinference crea automaticamente un ambiente virtuale dedicato per ogni modello durante il caricamento e vi installa le dipendenze corrispondenti. Ciò evita conflitti di dipendenze tra i modelli e garantisce che ciascun modello venga eseguito in modo indipendente in ambienti isolati.

Gestione ambienti virtuali (v2.0)#

Commutazione globale#

A partire dalla versione v2.0, l’ambiente virtuale è abilitato per impostazione predefinita. È comunque possibile sovrascrivere questa opzione tramite le impostazioni globali:

# Enable globally (default)
XINFERENCE_ENABLE_VIRTUAL_ENV=1 xinference-local -H 0.0.0.0 -p 9997

# Disable globally
XINFERENCE_ENABLE_VIRTUAL_ENV=0 xinference-local -H 0.0.0.0 -p 9997

Premere il modello all’avvio#

All’avvio del modello, è possibile sovrascrivere le impostazioni globali:

# Force enable for this model
xinference launch -n qwen2.5-instruct --model-engine transformers --enable-virtual-env

# Force disable for this model
xinference launch -n qwen2.5-instruct --model-engine transformers --disable-virtual-env

Aggiungere o sovrascrivere pacchetti all’avvio#

Nella riga di comando, usa --virtual-env-package o -vp per specificare una singola versione del pacchetto.

xinference launch -n qwen2.5-instruct --model-engine transformers \
  --virtual-env-package transformers==4.46.3 \
  --virtual-env-package accelerate==0.33.0

Se il pacchetto specificato è già presente nell’elenco dei pacchetti dell’ambiente virtuale predefinito del modello, la versione da voi specificata sovrascriverà quella predefinita, anziché essere aggiunta all’elenco.

Posizione di archiviazione#

Per impostazione predefinita, l’ambiente virtuale del modello viene memorizzato nel seguente percorso

  • Prima della v1.6.0: XINFERENCE_HOME / virtualenv / {model_name}

  • Da v1.6.0 a v1.13.0: XINFERENCE_HOME / virtualenv / v2 / {model_name}

  • A partire da v1.14.0: XINFERENCE_HOME / virtualenv / v3 / {model_name} / {python_version}

  • Dalla v2.0: XINFERENCE_HOME / virtualenv / v4 / {model_name} / {model_engine} / {python_version}

Salta le librerie già installate#

Added in version v1.8.1: Questa funzionalità richiede xoscar >= 0.7.12, che è la versione minima di Xoscar richiesta da Xinference v1.8.1.

xinference utilizza lo strumento uv per creare un ambiente virtuale e imposta i system site-packages di Python corrente come ambiente di base. Per impostazione predefinita, uv non verifica se i pacchetti sono già presenti nell’ambiente di sistema, ma reinstalla tutte le dipendenze nell’ambiente virtuale. Questo approccio garantisce un migliore isolamento dai pacchetti di sistema, ma può comportare installazioni duplicate, tempi di inizializzazione più lunghi e un maggiore utilizzo del disco.

A partire dalla versione v1.8.1, viene fornita una funzionalità sperimentale: impostando la variabile d’ambiente XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1, uv salterà i pacchetti già esistenti nei site-packages di sistema.

Cambiato nella versione v2.0: Questa funzionalità è abilitata per impostazione predefinita nella versione v2.0. Per disabilitarla, impostare XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=0.

Vantaggi#

  • Evitare di installare ripetutamente dipendenze di grandi dimensioni (ad esempio torch + CUDA).

  • Accelerare la velocità di creazione dell’ambiente virtuale.

  • Ridurre l’occupazione dello spazio su disco.

Usare#

# Enable experimental feature

# For command line
XINFERENCE_ENABLE_VIRTUAL_ENV=1 XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1 xinference-local ...
# For docker
docker run -e XINFERENCE_ENABLE_VIRTUAL_ENV=1 -e XINFERENCE_VIRTUAL_ENV_SKIP_INSTALLED=1 ...

Confronto delle prestazioni#

Con il modello CosyVoice 0.5B come esempio:

Quando la funzione non è abilitata:

Installed 98 packages in 187ms
 + aiohappyeyeballs==2.6.1
 + aiohttp==3.12.13
 ...
 + torch==2.7.1
 ...
 + yarl==1.20.1
 + zipp==3.23.0

Dopo aver attivato questa funzione:

Installed 7 packages in 12ms
 + diffusers==0.29.0
 + hf-xet==1.1.5
 + huggingface-hub==0.33.2
 + importlib-metadata==8.7.0
 + pillow==11.3.0
 + typing-extensions==4.14.0
 + urllib3==2.5.0

Caricamento del modello: attivazione dell’ambiente virtuale e personalizzazione delle dipendenze#

Added in version v1.8.1.

A partire da v1.8.1, supportiamo l’attivazione di ambienti virtuali per il caricamento di singoli modelli, sovrascrivendo le impostazioni predefinite del modello con dipendenze di pacchetti personalizzate.

Spazio virtuale del modello di commutazione#

Durante il caricamento del modello, è possibile specificare se abilitare l’ambiente virtuale del modello. Se non specificato, per impostazione predefinita si segue la configurazione della variabile d’ambiente.

Nell’interfaccia Web, è possibile attivare o disattivare questa funzione tramite un interruttore di impostazione opzionale.

actor

Al caricamento da riga di comando, utilizza l’opzione --enable-virtual-env per abilitare l’ambiente virtuale e l’opzione --disable-virtual-env per disabilitarlo.

Esempi di utilizzo:

xinference launch xxx --enable-virtual-env

Imposta le dipendenze dei pacchetti dell’ambiente virtuale.#

Per i modelli supportati, Xinference ha già definito le dipendenze dei pacchetti e i requisiti di versione nell’ambiente virtuale. Tuttavia, se è necessario specificare una versione particolare o installare dipendenze aggiuntive, è possibile fornirle manualmente durante il caricamento del modello.

Nell’interfaccia web, è possibile aggiungere dipendenze personalizzate facendo clic sull’icona del segno più nella stessa posizione dell’interruttore dell’ambiente virtuale.

Nella riga di comando, usa --virtual-env-package o -vp per specificare una singola versione del pacchetto.

Esempi di utilizzo:

xinference launch xxx --virtual-env-package transformers==4.54.0

Oltre alla modalità standard di specifica delle dipendenze dei pacchetti (come transformers==xxx), Xinference supporta anche alcune sintassi estese.

  • #system_xxx#: utilizzare la stessa versione dei pacchetti di sistema site-packages, ad esempio #system_numpy#, per garantire che la versione del pacchetto installato corrisponda a quella di numpy presente nei site-packages di sistema, evitando conflitti di dipendenze.

Gestione dell’ambiente virtuale#

Added in version v1.14.0.

Xinference fornisce funzionalità complete di gestione dell’ambiente virtuale, consentendo di creare ambienti Python indipendenti per ogni modello, soddisfacendo specifiche esigenze di dipendenza dei pacchetti.

actoractor

Funzionalità principali#

Supporto per più versioni di Python: Ogni modello può disporre di ambienti virtuali con diverse versioni di Python (ad esempio Python 3.10.18, 3.11.5), garantendo compatibilità con i vari requisiti del modello.

Isolamento delle dipendenze: ogni ambiente virtuale contiene un insieme indipendente di pacchetti, prevenendo conflitti di dipendenza tra diversi modelli.

Operazioni di gestione#

Elencare gli ambienti virtuali: Visualizza tutti gli ambienti virtuali nel cluster, supporta il filtraggio per nome del modello o indirizzo IP del nodo di lavoro.

Creazione dell’ambiente : Creata automaticamente quando si avvia il modello con enable_virtual_env=true. Il sistema rileva la versione corrente di Python e crea un ambiente indipendente contenente i pacchetti necessari.

Eliminazione dell’ambiente : è possibile eliminare un ambiente virtuale specifico in base al nome del modello e alla versione opzionale di Python, oppure eliminare tutti gli ambienti di un modello.

ModelHub JSON formato (adatto per modelli Xinference)#

Se prevedi di aggiungere il modello all’Model Hub di Xinference, definisci un blocco virtualenv nel JSON del modello. Dalla versione v2.0 (flusso v4), si consiglia di utilizzare marcatori sensibili al motore in modo che un singolo file JSON possa coprire più motori.

Regola importante: se il nuovo modello supporta un motore specifico, è obbligatorio includere almeno una voce di pacchetto per tale motore in virtualenv.packages, con un tag aggiuntivo (ad esempio #engine# == "vllm"). Quando l’ambiente virtuale è attivo, la verifica della disponibilità del motore si basa su questi tag per la convalida.

{
  "virtualenv": {
    "packages": [
      "#transformers_dependencies# ; #engine# == \"transformers\"",
      "#vllm_dependencies# ; #engine# == \"vllm\"",
      "#sglang_dependencies# ; #engine# == \"sglang\"",
      "#llama_cpp_dependencies# ; #engine# == \"llama.cpp\"",
      "#mlx_dependencies# ; #engine# == \"mlx\"",
      "#system_numpy# ; #engine# == \"vllm\""
    ]
  }
}

  • packages (obbligatorio): elenco di stringhe o marcatori di requisiti pip.

  • inherit_pip_config (valore predefinito: true): se esiste un file di configurazione pip di sistema, ne eredita le impostazioni.

  • index_url / extra_index_url / find_links / trusted_host : controllo dell’indice pip e dei mirror.

  • index_strategy：passato all’installatore dell’ambiente virtuale (usato da alcuni motori).

  • no_build_isolation : interruttore di isolamento della build pip per la gestione di build complesse.

Utilizzo dei segnaposto per iniettare i valori predefiniti del motore:

  • #vllm_dependencies#

  • #sglang_dependencies#

  • #mlx_dependencies#

  • #transformers_dependencies#

  • #llama_cpp_dependencies#

  • #diffusers_dependencies#

  • #sentence_transformers_dependencies#

Usa #engine# o #model_engine# per il confronto (distingue tra maiuscole e minuscole). I valori del motore vengono passati internamente in minuscolo, quindi si consiglia di utilizzare valori minuscoli, ad esempio #engine# == "vllm" o #engine# == "transformers".