Risoluzione dei problemi#

Nessun permesso per il repository huggingface#

Quando si ottiene un modello, a volte si possono incontrare problemi di autorizzazione. Ad esempio, nel recuperare il modello llama2 potrebbe apparire il seguente messaggio:

Cannot access gated repo for url https://huggingface.co/api/models/meta-llama/Llama-2-7b-hf.
Repo model meta-llama/Llama-2-7b-hf is gated. You must be authenticated to access it.

Generalmente, questa situazione è dovuta alla mancanza dei permessi del repository Hugging Face o alla mancata configurazione del token Hugging Face. È possibile risolvere il problema nel modo seguente.

Richiedi i permessi per il repository di Hugging Face.#

Per ottenere l’accesso, aprire il repository huggingface corrispondente e accettare i suoi termini e condizioni. Prendendo llama2 come esempio, è possibile aprire questo link per fare richiesta: https://huggingface.co/meta-llama/Llama-2-7b-hf.

Imposta le credenziali di accesso a Hugging Face.#

Le credenziali sono disponibili nella pagina di Hugging Face, https://huggingface.co/settings/tokens.

È possibile impostare le credenziali di accesso attraverso le variabili d’ambiente, export HUGGING_FACE_HUB_TOKEN=your_token_here.

Driver NVIDIA e versione di PyTorch non corrispondono#

Se stai utilizzando una scheda grafica NVIDIA, potresti riscontrare il seguente errore:

UserWarning: CUDA initialization: The NVIDIA driver on your system is too old
(found version 10010). Please update your GPU driver by downloading and installi
ng a new version from the URL: http://www.nvidia.com/Download/index.aspx Alterna
tively, go to: https://pytorch.org to install a PyTorch version that has been co
mpiled with your version of the CUDA driver. (Triggered internally at  ..\c10\cu
da\CUDAFunctions.cpp:112.)

Generalmente, questa situazione è causata da una versione di CUDA incompatibile con la versione di PyTorch.

È possibile installare PyTorch dal sito ufficiale https://pytorch.org utilizzando la versione precompilata corrispondente a CUDA. Allo stesso tempo, assicurarsi che la versione di CUDA installata non sia inferiore a 11.8, preferibilmente compresa tra 11.8 e 12.1.

Ad esempio, se la tua versione di CUDA è 11.8, puoi installare la corrispondente PyTorch utilizzando il seguente comando:

pip install torch==2.0.1+cu118

I sistemi esterni non possono accedere al servizio Xinference tramite <IP>:9997.#

Quando si avvia Xinference, ricordarsi di aggiungere il parametro -H 0.0.0.0:

xinference-local -H 0.0.0.0

Quindi il servizio Xinforce ascolterà su tutte le interfacce di rete (non solo su 127.0.0.1 o localhost).

Se si utilizza Immagine Docker, aggiungere -p <PORT>:9997 al comando di esecuzione Docker, e sarà possibile accedere tramite <IP>:<PORT> della macchina locale.

L’avvio del modello integrato richiede molto tempo e talvolta il download del modello fallisce.#

Xinference utilizza HuggingFace come fonte predefinita per i modelli. Se la tua macchina si trova nella Cina continentale, potresti avere problemi di accesso utilizzando i modelli integrati.

Per risolvere questo problema, è possibile aggiungere la variabile d’ambiente XINFERENCE_MODEL_SRC=modelscope all’avvio di Xinference, modificando l’origine del modello in ModelScope per ottenere una velocità di download più elevata nella Cina continentale.

Se avvii Xinference con Docker, puoi includere l’opzione -e XINFERENCE_MODEL_SRC=modelscope nel comando Docker.

Quando si utilizza l’immagine Docker ufficiale, RayWorkerVllm muore a causa di OOM, impedendo il caricamento del modello.#

Il parametro --shm-size di Docker può essere utilizzato per impostare la dimensione della memoria condivisa. La dimensione predefinita della memoria condivisa (/dev/shm) è di 64MB, che potrebbe non essere sufficiente per il backend vLLM.

Puoi aumentarne la dimensione impostando il parametro --shm-size.

docker run --shm-size=128g ...

Caricamento del modello LLM: manca il parametro model_engine#

A partire dalla versione v0.11.0, è necessario passare il parametro aggiuntivo model_engine durante il caricamento del modello LLM. Per maggiori dettagli, consulta qui.

Risoluzione del conflitto nel livello di threading MKL#

Durante l’avvio del server Xinference, se si incontra l’errore: ValueError: Model architectures ['Qwen2ForCausalLM'] failed to be inspected. . Please check the logs for more details.

La causa principale mostrata nei log è:

Error: mkl-service + Intel(R) MKL: MKL_THREADING_LAYER=INTEL is incompatible with libgomp-a34b3233.so.1 library.
Try to import numpy first or set the threading layer accordingly. Set MKL_SERVICE_FORCE_INTEL to force it.

Ciò è solitamente dovuto al fatto che NumPy è stato installato tramite conda, e la versione di NumPy di conda è costruita con l’ottimizzazione Intel MKL, causando un conflitto con la libreria GNU OpenMP (libgomp) già caricata nell’ambiente.

Soluzione 1: Riscrittura del livello thread#

Impostando MKL_THREADING_LAYER=GNU si forza la Intel Math Kernel Library (MKL) a utilizzare l’implementazione GNU di OpenMP:

MKL_THREADING_LAYER=GNU xinference-local

Soluzione 2: reinstallare NumPy con pip#

Disinstalla numpy installato con conda, poi reinstallalo usando pip.

pip uninstall -y numpy && pip install numpy
#Or just --force-reinstall
pip install --force-reinstall numpy

Configurare un mirror PyPI per accelerare l’installazione dei pacchetti.#

Se ti trovi nella Cina continentale, l’uso di un mirror PyPI può accelerare notevolmente la velocità di installazione dei pacchetti software. Di seguito sono riportate alcune fonti mirror comunemente utilizzate:

  • Mirror di Tsinghua: https://pypi.tuna.tsinghua.edu.cn/simple

  • Mirror di Alibaba Cloud: https://mirrors.aliyun.com/pypi/simple/

  • Mirror Tencent Cloud: https://mirrors.cloud.tencent.com/pypi/simple

Tuttavia, tieni presente che su alcuni mirror potrebbero mancare alcuni pacchetti. Ad esempio, se utilizzi solo il mirror di Alibaba Cloud per installare xinference[audio], l’installazione potrebbe fallire.

Ciò è dovuto al fatto che il pacchetto num2words, da cui dipende MeloTTS, non è disponibile nel mirror di Alibaba Cloud. Pertanto, durante l’esecuzione di pip install xinference[audio], potrebbe verificarsi un rollback all’installazione di versioni precedenti, come xinference==1.2.0 e xoscar==0.8.0 (aggiornato al 27 ottobre 2025).

Queste vecchie versioni non sono compatibili e causano il seguente errore: MainActorPool.append_sub_pool() got an unexpected keyword argument 'start_method'

curl -s https://mirrors.aliyun.com/pypi/simple/num2words/ | grep -i "num2words"
# Returns NOTHING! But it works on Tsinghua or Tencent mirrors.
# uv pip install "xinference[audio]" will then install the following packages (as of Oct 27, 2025):
+ x-transformers==2.10.2
+ xinference==1.2.0
+ xoscar==0.8.0

Per evitare questo problema durante l’installazione del pacchetto audio di xinference, si consiglia di utilizzare più sorgenti mirror contemporaneamente.

uv pip install xinference[audio] --index-url https://mirrors.aliyun.com/pypi/simple --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple

# Optional: Set this globally in your uv config
mkdir -p ~/.config/uv
cat >> ~/.config/uv/uv.toml << EOF
index-url = "https://mirrors.aliyun.com/pypi/simple"
extra-index-url = ["https://pypi.tuna.tsinghua.edu.cn/simple"]
EOF

Installazione di Xinference 1.12.0 con uv fallita (a novembre 2025)#

Nota: Si tratta di un problema temporaneo, dovuto all’attuale ecosistema dei pacchetti software e alla strategia di risoluzione delle dipendenze di uv, che dà priorità alle versioni più recenti delle dipendenze dirette anziché alle versioni delle dipendenze indirette.

Sintomo#

Se installi xinference 1.12.0 con uv pip install xinference a novembre 2025, potresti riscontrare problemi di installazione con versioni molto vecchie dei pacchetti dipendenti, in particolare:

  • transformers==4.12.2 (della versione del 2021)

  • tokenizers==0.10.3 (della versione del 2021)

  • huggingface-hub==1.0.1

Successivamente, uv segnala un errore: «Failed to build tokenizers==0.10.3» (costruzione di tokenizers==0.10.3 fallita).

Causa principale#

Il motivo del problema è che uv seleziona prioritariamente le versioni più recenti delle dipendenze dirette, ignorando i requisiti di versione specificati nelle dipendenze indirette:

  1. xinference 1.12.0 specifica huggingface-hub>=0.19.4 come dipendenza diretta (senza vincoli di limite superiore).

  2. A partire dal 6 novembre 2025, uv selezionerà la versione più recente: huggingface-hub==1.0.1

  3. Tuttavia, transformers<=4.57.3 (una dipendenza indiretta introdotta tramite peft) richiede huggingface-hub<1.0.

  4. Per risolvere i conflitti di dipendenza, uv ha mantenuto la dipendenza diretta huggingface-hub==1.0.1 e ha downgradato la dipendenza indiretta transformers alla versione molto vecchia 4.12.2.

Questa è una caratteristica di progettazione di uv: dà priorità alle dipendenze specificate esplicitamente (dipendenze dirette) rispetto a quelle transitive. Link di riferimento: astral-sh/uv#16601

Aggiornamento: Al 05/01/2026, l’ultima versione di transformers, 4.57.3, dipende ancora da huggingface-hub<1.0.

Soluzione#

Soluzione 1: Specificare in anticipo la versione di huggingface-hub (consigliata)

Limita esplicitamente huggingface-hub a un intervallo di versioni compatibili:

uv pip install "huggingface-hub>=0.34.0,<1.0" xinference

Questo obbliga uv a selezionare una versione di huggingface-hub compatibile con la versione moderna di transformers.

Soluzione 2: Impostare transformers come dipendenza diretta

Specificando esplicitamente transformers, questo diventerà una dipendenza diretta e uv sceglierà preferibilmente una versione più recente:

uv pip install transformers xinference

Soluzione 3: Utilizzare pip

Oppure usa direttamente pip install xinference, che analizzerà automaticamente la combinazione di versioni seguente:

  • transformers==4.57.1

  • huggingface-hub==0.36.0

  • tokenizers==0.22.1

vLLM + Torch + Xinference problemi di compatibilità (errore di segmentazione)#

Sintomo#

Se hai installato vLLM < 0.12.0 e hai aggiornato xinference (specialmente usando uv pip install -U xinference), xinference potrebbe fallire all’avvio a causa di un errore di segmentazione:

root@server:/home# xinference-local --host 0.0.0.0 --port 9997
INFO 12-30 17:35:37 [__init__.py:216] Automatically detected platform cuda.
Aborted (core dumped)

Causa principale#

Questo problema è causato dalla combinazione di tre fattori:

  1. Incompatibilità binaria: vLLM, nelle versioni precedenti alla 0.12.0, è stato compilato basandosi su PyTorch 2.8.0. Queste versioni non sono compatibili con PyTorch 2.9. Riferimento: Note di rilascio di vLLM v0.12.0

  2. Dipendenze di Torch senza limite superiore in Xinference: Il file setup.cfg di Xinference non specifica un limite superiore di versione per PyTorch:

    [options]
install_requires =
    torch                    # No version constraint!

    This allows package managers to upgrade PyTorch to incompatible versions.

  3. Differenze di comportamento tra i vari gestori di pacchetti:

    • pip: più conservativo — aggiorna le dipendenze solo in caso di incompatibilità, altrimenti aggiorna solo il pacchetto specificato.

    • Usare il parametro -U con uv: la strategia è più aggressiva — rielabora tutte le dipendenze e seleziona la versione più recente.

Pertanto, quando non sei ancora pronto per aggiornare l’intero stack tecnologico, ma desideri solo aggiornare xinference, puoi scegliere di utilizzare:

  • pip install -U xinference （mantieni invariata la versione di PyTorch, aggiorna solo xinference）

  • uv pip install "xinference==1.16.0" (without -U flag, only upgrades xinference too)