Utilisation

Exécution locale de Xinference

Prenons un modèle de langage classique, qwen2.5-instruct, pour montrer comment exécuter un modèle localement avec Xinference.

Après ce démarrage rapide, vous pouvez continuer à apprendre comment déployer Xinference dans un environnement de cluster distribué.

Démarrer le service local

Tout d’abord, veuillez vous assurer que Xinference est installé localement en suivant les instructions de ce document. Démarrez le service Xinference local en utilisant la commande suivante :

shelloutput

xinference-local --host 0.0.0.0 --port 9997

Note

Par défaut, Xinference utilise <HOME>/.xinference comme répertoire principal pour stocker certaines informations nécessaires, telles que les fichiers journaux et les fichiers de modèles, où <HOME> correspond au répertoire personnel de l’utilisateur actuel.

Vous pouvez modifier le répertoire principal en configurant la variable d’environnement XINFERENCE_HOME, par exemple :

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

Félicitations ! Vous avez lancé le service Xinference localement. Une fois le service Xinference opérationnel, plusieurs façons de l’utiliser s’offrent à vous, notamment via une page Web, la commande cURL, la ligne de commande ou le SDK Python de Xinference.

L’interface utilisateur est accessible via http://127.0.0.1:9997/ui, et la documentation de l’API via http://127.0.0.1:9997/docs.

Vous pouvez l’installer via la commande suivante, puis l’utiliser avec l’outil en ligne de commande Xinference ou du code Python :

pip install xinference

L’outil en ligne de commande est xinference. Vous pouvez consulter les commandes disponibles avec la commande suivante :

shelloutput

xinference --help

Si vous avez uniquement besoin d’installer le SDK Python de Xinference, vous pouvez utiliser la commande suivante pour installer les dépendances minimales. Notez que la version doit correspondre à celle du service Xinference.

pip install xinference-client==${SERVER_VERSION}

Moteur d’inférence du modèle

À partir de la version v0.11.0, vous devez spécifier le moteur d’inférence concret avant de charger le modèle LLM. Actuellement, Xinference prend en charge les moteurs d’inférence suivants :

• vllm

• sglang

• llama.cpp

• transformers

• MLX

Pour plus de détails sur ces moteurs d’inférence, veuillez vous référer à ici.

Attention, lors du chargement d’un modèle LLM, les moteurs exécutables sont étroitement liés aux paramètres model_format et quantization.

Xinference fournit la commande xinference engine pour vous aider à interroger les combinaisons de paramètres pertinentes.

Par exemple :

1. Je souhaite consulter les combinaisons de paramètres liées au modèle qwen-chat, afin de déterminer comment il peut fonctionner sur différents moteurs d’inférence.

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

1. Je veux exécuter qwen-chat sur le moteur d’inférence VLLM, mais je ne sais pas quels autres paramètres répondent à cette exigence.

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

1. Je souhaite charger le modèle qwen-chat au format GGUF, j’ai besoin de connaître la combinaison de ses autres paramètres.

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

En résumé, par rapport à la version précédente, lors du chargement du modèle LLM, il est nécessaire de transmettre en supplément le paramètre model_engine. Vous pouvez utiliser la commande xinference engine pour interroger les relations entre le moteur d’inférence que vous souhaitez exécuter et d’autres combinaisons de paramètres.

Note

Voici quelques suggestions concernant le choix du moteur à utiliser :

• Linux

  • Lorsque cela est possible, privilégiez vLLM ou SGLang, car ils offrent de meilleures performances.

  • Si les ressources sont limitées, vous pouvez envisager d’utiliser llama.cpp, car il offre davantage d’options de quantification.

  • Autres considérations d’utilisation Utilisez Transformers, qui prend en charge presque tous les modèles.

• Windows

  • Il est recommandé d’utiliser WSL, et dans ce cas, choisissez la même option que pour Linux.

  • Dans les autres cas, il est recommandé d’utiliser llama.cpp ; pour les modèles non pris en charge, choisissez Transformers.

• Mac

  • Lorsque le modèle le prend en charge, il est recommandé d’utiliser le moteur MLX, qui offre les meilleures performances.

  • D’autres fois, il est recommandé d’utiliser llama.cpp ; pour les modèles non supportés, choisissez d’utiliser Transformers.

Exécutez qwen2.5-instruct

Lançons un modèle intégré qwen2.5-instruct. Lorsque vous devez exécuter un modèle, la première exécution télécharge les paramètres du modèle depuis HuggingFace, ce qui prend généralement entre 10 et 30 minutes selon la taille du modèle. Une fois le téléchargement terminé, Xinference conserve un cache local, de sorte que les exécutions ultérieures du même modèle ne nécessitent pas de re-téléchargement.

Note

Xinference permet également de télécharger des modèles depuis d’autres plateformes d’hébergement de modèles. Vous pouvez spécifier des variables d’environnement lors du lancement de Xinference. Par exemple, si vous souhaitez télécharger un modèle depuis ModelScope, utilisez la commande suivante :

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

Vous pouvez utiliser le paramètre --model-uid ou -u pour spécifier l’UID du modèle. Si aucun n’est spécifié, Xinference générera un ID aléatoire. Par défaut, l’ID est identique au nom du modèle.

shellcURLPythonoutput

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

Note

Pour certains moteurs d’inférence, comme vLLM, l’utilisateur doit spécifier des paramètres liés au moteur lors de l’exécution du modèle. Dans ce cas, il suffit de préciser directement le nom et la valeur du paramètre correspondant en ligne de commande, par exemple :

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

En exécutant le modèle, gpu_memory_utilization=0.9 est transmis au backend vllm.

Note

Pour plus d’astuces sur le chargement de modèles, consultez Guide de chargement des modèles.

À ce stade, félicitations, vous avez réussi à exécuter qwen2.5-instruct via Xinference. Une fois ce modèle en cours d’exécution, nous pouvons interagir avec lui via la ligne de commande, cURL ou le code 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 fournit une API compatible avec OpenAI, ce qui permet d’utiliser les modèles exécutés par Xinference comme une alternative locale à OpenAI. Par exemple :

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)

Voici les API OpenAI prises en charge :

• Génération de dialogues : https://platform.openai.com/docs/api-reference/chat

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

• Génération de vecteurs : https://platform.openai.com/docs/api-reference/embeddings

Xinference prend également en charge l’appel à l’API Anthropic via l’URL de base http://127.0.0.1:9997/anthropic, vous pouvez utiliser Xinference dans des environnements comme Claude Code. Pour plus de détails, veuillez consulter anthropic client.

Gestion des modèles

En plus de démarrer un modèle, Xinference offre la capacité de gérer l’ensemble du cycle de vie du modèle. De même, vous pouvez utiliser la ligne de commande, cURL et le code Python pour la gestion.

Listez tous les modèles de type spécifié pris en charge par Xinference.

shellcURLPython

xinference registrations -t LLM

La commande suivante permet de lister tous les modèles en cours d’exécution :

shellcURLPython

xinference list

Lorsque vous n’avez plus besoin d’un modèle en cours d’exécution, vous pouvez l’arrêter et libérer les ressources de la manière suivante :

shellcURLPython

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

Déploiement de Xinference dans un cluster

Pour déployer Xinference dans un environnement cluster, il est nécessaire de démarrer un nœud superviseur sur une machine, puis de lancer des nœuds workers sur la même machine ou sur d’autres machines.

Tout d’abord, conformément à la documentation, assurez-vous que Xinference est installé sur tous les serveurs. Ensuite, suivez les étapes :

Démarrer Supervisor

Exécutez la commande suivante sur le serveur pour démarrer le nœud Supervisor :

xinference-supervisor -H "${supervisor_host}"

Remplacez ${supervisor_host} par l’adresse IP du nœud actuel.

L’interface web est accessible à l’adresse http://${supervisor_host}:9997/ui, et la documentation de l’API à l’adresse http://${supervisor_host}:9997/docs.

Démarrer le Worker

Exécutez la commande suivante sur la machine où vous devez démarrer le worker Xinference :

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

Note

Il est important de noter que l’adresse IP du nœud Worker actuel doit être utilisée pour remplacer ${worker_host}.

Note

Notez que si vous devez interagir avec le cluster via la ligne de commande, vous devez spécifier l’adresse du superviseur en utilisant le paramètre -e ou --endpoint, par exemple :

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

Utilisation de Docker pour déployer Xinference

Utilisez la commande suivante pour exécuter Xinference dans un conteneur :

Exécuter sur une machine équipée d’une carte graphique NVIDIA.

Pour 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

Pour cuda 12.8 :

Ajouté dans la version v1.8.1: La version 12.8 de CUDA est expérimentale, n’hésitez pas à nous faire part de vos retours pour l’améliorer.

Modifié dans la version v1.16.0: La version CUDA 12.8 a été supprimée dans 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

Pour CUDA 12.9 :

Ajouté dans la version v1.16.0: Après la sortie de Xinference v2.0.0, CUDA 12.9 deviendra la version par défaut.

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

Exécuter sur une machine avec uniquement un 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

Remplacez <your_version> par la version de Xinference, par exemple v0.10.3, et utilisez latest pour la version la plus récente.

Pour plus d’utilisation de Docker, veuillez vous référer à Utilisation de l’image Docker.

Plus

Félicitations, vous avez déjà maîtrisé les bases de l’utilisation de Xinference ! Pour vous aider à mieux utiliser l’outil, voici d’autres documents et ressources de guidage :

• Comment créer différents types de modèles avec Python

• Choisir le bon moteur d’inférence