Dépannage#

Aucune autorisation d’accès au dépôt Hugging Face.#

Lors de l’obtention du modèle, il peut parfois y avoir des problèmes de permissions. Par exemple, en récupérant le modèle llama2, vous pourriez rencontrer l’avis suivant :

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.

Ce problème est généralement dû à un manque d’autorisation sur le dépôt Hugging Face ou à l’absence de configuration du token Hugging Face. Vous pouvez résoudre ce problème en suivant les étapes ci-dessous.

Demander l’accès au dépôt Hugging Face#

Pour obtenir les droits d’accès, ouvrez le dépôt Hugging Face correspondant et acceptez ses conditions et ses remarques. Prenons llama2 comme exemple : vous pouvez ouvrir ce lien pour faire une demande : https://huggingface.co/meta-llama/Llama-2-7b-hf.

Définir les identifiants d’accès à Hugging Face#

Vous pouvez trouver les identifiants sur la page huggingface，https://huggingface.co/settings/tokens.

Vous pouvez définir les identifiants d’accès en configurant une variable d’environnement : export HUGGING_FACE_HUB_TOKEN=your_token_here.

Version du pilote NVIDIA incompatible avec la version de PyTorch#

Si vous utilisez une carte graphique NVIDIA, vous pourriez rencontrer l’erreur suivante :

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.)

Ce phénomène est généralement dû à une incompatibilité entre la version de CUDA et celle de PyTorch.

Vous pouvez installer la version précompilée de PyTorch correspondant à votre version de CUDA depuis le site officiel https://pytorch.org. En même temps, veuillez vérifier que la version installée de CUDA n’est pas inférieure à 11.8, et idéalement comprise entre 11.8 et 12.1.

Si votre version de CUDA est la 11.8, vous pouvez utiliser la commande suivante pour installer le PyTorch correspondant :

pip install torch==2.0.1+cu118

Les systèmes externes ne peuvent pas accéder au service Xinference via <IP>:9997.#

Au démarrage de Xinference, n’oubliez pas d’ajouter le paramètre -H 0.0.0.0 :

xinference-local -H 0.0.0.0

Ainsi, le service Xinference écoutera sur toutes les interfaces réseau (pas seulement sur 127.0.0.1 ou localhost).

Si vous utilisez Image Docker, ajoutez -p <PORT>:9997 à la commande d’exécution Docker, vous pourrez alors y accéder via <IP>:<PORT> sur votre machine locale.

Le démarrage du modèle intégré prend beaucoup de temps, et le téléchargement du modèle échoue parfois.#

Xinference utilise par défaut HuggingFace comme source de modèles. Si votre machine se trouve en Chine continentale, l’utilisation des modèles intégrés peut entraîner des problèmes d’accès.

Pour résoudre ce problème, vous pouvez ajouter la variable d’environnement XINFERENCE_MODEL_SRC=modelscope lors du démarrage de Xinference, ce qui changera la source du modèle vers ModelScope, où les téléchargements sont plus rapides en Chine continentale.

Si vous démarrez Xinference avec Docker, vous pouvez inclure l’option -e XINFERENCE_MODEL_SRC=modelscope dans la commande Docker.

Lors de l’utilisation de l’image Docker officielle, RayWorkerVllm meurt à cause d’une OOM, ce qui empêche le chargement du modèle.#

Le paramètre --shm-size de Docker peut être utilisé pour configurer la taille de la mémoire partagée. La taille par défaut de la mémoire partagée (/dev/shm) est de 64 Mo, ce qui peut être insuffisant pour le backend vLLM.

Vous pouvez augmenter sa taille en définissant le paramètre --shm-size :

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

Chargement du modèle LLM : paramètre model_engine manquant.#

À partir de la version v0.11.0, le chargement du modèle LLM nécessite de passer un paramètre supplémentaire model_engine. Pour plus d’informations, veuillez vous référer à la section ici.

Résolution du conflit de couche de threads MKL#

Au démarrage du serveur Xinference, si vous rencontrez l’erreur : ValueError: Model architectures ['Qwen2ForCausalLM'] failed to be inspected. . Please check the logs for more details.

La cause première affichée dans les journaux est :

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.

Cela est généralement dû au fait que votre NumPy a été installé via conda, et que la version de NumPy de conda est construite avec les optimisations Intel MKL, ce qui provoque un conflit avec la bibliothèque GNU OpenMP (libgomp) déjà chargée dans l’environnement.

Solution 1 : Réécrire la couche de threads#

Définir MKL_THREADING_LAYER=GNU peut forcer la bibliothèque de noyaux mathématiques Intel (MKL) à utiliser l’implémentation OpenMP de GNU :

MKL_THREADING_LAYER=GNU xinference-local

Solution 2 : Réinstaller NumPy avec pip#

Désinstallez numpy installé via conda, puis réinstallez-le avec pip.

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

Configurer le miroir PyPI pour accélérer l’installation des paquets#

Si vous êtes en Chine continentale, l’utilisation d’un miroir PyPI peut considérablement accélérer la vitesse d’installation des paquets logiciels. Voici quelques sources miroir couramment utilisées :

  • Miroir de l’Université Tsinghua : https://pypi.tuna.tsinghua.edu.cn/simple

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

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

Veuillez noter que certains paquets peuvent être absents de certaines sources miroirs. Par exemple, si vous utilisez uniquement le miroir Aliyun pour installer xinference[audio], l’installation pourrait échouer.

Cela est dû au fait que le paquet num2words dont dépend MeloTTS n’est pas disponible sur le miroir Alibaba Cloud. Par conséquent, lors de l’exécution de pip install xinference[audio], une version ancienne peut être installée par repli, comme xinference==1.2.0 et xoscar==0.8.0 (jusqu’au 27 octobre 2025).

Ces anciennes versions sont incompatibles et provoquent l’erreur suivante : 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

Pour éviter ce problème lors de l’installation du package audio xinference, il est recommandé d’utiliser plusieurs sources de miroir simultanément :

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

Échec de l’installation de Xinference 1.12.0 avec uv (jusqu’en novembre 2025).#

Remarque : Il s’agit d’un problème temporaire, dû à l’écosystème actuel des paquets et à la stratégie de résolution des dépendances d’uv, qui privilégie les versions élevées des dépendances directes au détriment des versions des dépendances indirectes.

Symptômes#

En novembre 2025, lors de l’installation de xinference 1.12.0 avec uv pip install xinference, vous pourriez rencontrer des problèmes d’installation de dépendances de versions très anciennes, notamment :

  • transformers==4.12.2 (provenant de la version 2021)

  • tokenizers==0.10.3 (version de 2021)

  • huggingface-hub==1.0.1

Ensuite, uv a signalé une erreur : « Échec de la construction de tokenizers==0.10.3 »

Cause première#

La raison de ce problème est que uv privilégie les versions élevées des dépendances directes tout en ignorant les contraintes de version dans les dépendances indirectes :

  1. xinference 1.12.0 spécifie huggingface-hub>=0.19.4 comme dépendance directe (sans contrainte de limite supérieure).

  2. Jusqu’au 6 novembre 2025, uv sélectionnera la version la plus récente : huggingface-hub==1.0.1

  3. Cependant, transformers<=4.57.3 (une dépendance indirecte introduite via peft) exige huggingface-hub<1.0.

  4. Pour résoudre le conflit de dépendances, uv a conservé la dépendance directe huggingface-hub==1.0.1 et a rétrogradé la dépendance indirecte transformers vers une version très ancienne, 4.12.2.

Cela fait partie des caractéristiques de conception de uv : il privilégie les dépendances que vous spécifiez explicitement (dépendances directes) plutôt que les dépendances transitives. Lien de référence : astral-sh/uv#16601

Mise à jour : Au 5 janvier 2026, la dernière version 4.57.3 de transformers dépend toujours de huggingface-hub<1.0.

Solution#

Solution 1 : Prélimiter la version de huggingface-hub (recommandé)

Explicitement, restreignez huggingface-hub à une plage de versions compatibles :

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

Cela force uv à sélectionner une version de huggingface-hub compatible avec la version moderne de transformers.

Solution 2 : Définir transformers comme dépendance directe

En spécifiant explicitement transformers, celui-ci deviendra une dépendance directe, et uv privilégiera les versions plus récentes :

uv pip install transformers xinference

Solution 3 : Utiliser pip

Ou utilisez directement pip install xinference, il résoudra automatiquement la combinaison de versions suivante :

  • transformers==4.57.1

  • huggingface-hub==0.36.0

  • tokenizers==0.22.1

Problème de compatibilité entre vLLM + Torch + Xinference (erreur de segmentation)#

Symptômes#

Si vous avez installé vLLM < 0.12.0 et mis à jour xinference (en particulier avec uv pip install -U xinference), xinference peut échouer au démarrage en raison d’une erreur de segmentation.

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)

Cause première#

Ce problème est causé par trois facteurs :

  1. Incompatibilité binaire : vLLM, dans les versions antérieures à 0.12.0, était compilé avec PyTorch 2.8.0, et ces versions ne sont pas compatibles avec PyTorch 2.9. Référence : Notes de version de vLLM v0.12.0

  2. Xinference n’impose pas de limite supérieure pour la dépendance Torch : Le fichier setup.cfg de Xinference ne spécifie pas de version maximale pour PyTorch.

    [options]
install_requires =
    torch                    # No version constraint!

    This allows package managers to upgrade PyTorch to incompatible versions.

  3. Différences de comportement des gestionnaires de paquets :

    • pip : plutôt conservateur — il ne met à niveau les dépendances associées que lorsqu’elles sont incompatibles, sinon il ne met à niveau que le paquet spécifié.

    • Utilisation de l’argument -U avec uv : la stratégie est plus agressive — elle réinterprète toutes les dépendances et sélectionne la version la plus récente.

Par conséquent, si vous n’êtes pas encore prêt à mettre à niveau l’ensemble de votre pile technique et souhaitez seulement mettre à niveau xinference, vous pouvez choisir d’utiliser :

  • pip install -U xinference

  • uv pip install "xinference==1.16.0" (sans utiliser le paramètre -U, cela mettra également à niveau uniquement xinference)