# Exécuter l'inférence sur des serveurs L'inférence est le processus consistant à utiliser un modèle entraîné pour effectuer des prédictions sur de nouvelles données. Étant donné que ce processus peut être intensif en calcul, l'exécution sur un service dédié ou externe peut être une option intéressante. La bibliothèque `huggingface_hub` fournit une interface unifiée pour exécuter l'inférence sur plusieurs services pour les modèles hébergés sur le Hugging Face Hub : 1. [Fournisseurs d’inférence](https://huggingface.co/docs/inference-providers/index) : un accès unifié et simplifié à des centaines de modèles de machine learning, propulsé par nos partenaires d’inférence serverless. Cette nouvelle approche s’appuie sur notre précédente API d’inférence serverless, offrant davantage de modèles, des performances améliorées et une fiabilité accrue grâce à des fournisseurs de premier plan. Consultez la [documentation](https://huggingface.co/docs/inference-providers/index#partners) pour obtenir la liste des fournisseurs pris en charge. 2. [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index) : un produit permettant de déployer facilement des modèles en production. L'inférence est exécutée par Hugging Face sur une infrastructure dédiée et entièrement gérée, chez le fournisseur cloud de votre choix. 3. Points de terminaison locaux : vous pouvez également exécuter l’inférence avec des serveurs d’inférence locaux tels que [llama.cpp](https://github.com/ggerganov/llama.cpp), [Ollama](https://ollama.com/), [vLLM](https://github.com/vllm-project/vllm), [LiteLLM](https://docs.litellm.ai/docs/simple_proxy) ou [Text Generation Inference (TGI)](https://github.com/huggingface/text-generation-inference) en connectant le client à ces points de terminaison locaux. > [!TIP] > [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient) est un client Python qui effectue des appels HTTP vers nos API. Si vous souhaitez effectuer les appels HTTP directement à l’aide de votre outil préféré (curl, postman, ...), veuillez consulter la documentation [Inference Providers](https://huggingface.co/docs/inference-providers/index) ou les pages de documentation [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index). > > Pour le développement web, un [client JS](https://huggingface.co/docs/huggingface.js/inference/README) a été publié. Si vous êtes intéressé par le développement de jeux, vous pouvez jeter un œil à notre [projet C#](https://github.com/huggingface/unity-api). ## Premiers pas Commençons par une tâche de génération d'images à partir de texte : ```python >>> from huggingface_hub import InferenceClient # Example with an external provider (e.g. replicate) >>> replicate_client = InferenceClient( provider="replicate", api_key="my_replicate_api_key", ) >>> replicate_image = replicate_client.text_to_image( "A flying car crossing a futuristic cityscape.", model="black-forest-labs/FLUX.1-schnell", ) >>> replicate_image.save("flying_car.png") ``` Dans l'exemple ci-dessus, nous avons initialisé un [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient) avec un fournisseur tiers, [Replicate](https://replicate.com/). Lors de l'utilisation d'un fournisseur, vous devez spécifier le modèle que vous souhaitez utiliser. L'identifiant du modèle doit être l'identifiant du modèle sur le Hugging Face Hub, et non l'identifiant du modèle provenant du fournisseur tiers. Dans notre exemple, nous avons généré une image à partir d'un prompt texte. La valeur retournée est un objet `PIL.Image` qui peut être enregistré dans un fichier. Pour plus de détails, consultez la documentation de [text_to_image()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_image). Passons maintenant à un exemple utilisant l'API [chat_completion()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion). Cette tâche utilise un LLM pour générer une réponse à partir d'une liste de messages : ```python >>> from huggingface_hub import InferenceClient >>> messages = [ { "role": "user", "content": "What is the capital of France?", } ] >>> client = InferenceClient( provider="together", model="meta-llama/Meta-Llama-3-8B-Instruct", api_key="my_together_api_key", ) >>> client.chat_completion(messages, max_tokens=100) ChatCompletionOutput( choices=[ ChatCompletionOutputComplete( finish_reason="eos_token", index=0, message=ChatCompletionOutputMessage( role="assistant", content="The capital of France is Paris.", name=None, tool_calls=None ), logprobs=None, ) ], created=1719907176, id="", model="meta-llama/Meta-Llama-3-8B-Instruct", object="text_completion", system_fingerprint="2.0.4-sha-f426a33", usage=ChatCompletionOutputUsage(completion_tokens=8, prompt_tokens=17, total_tokens=25), ) ``` Dans l’exemple ci-dessus, nous avons utilisé un fournisseur tiers ([Together AI](https://www.together.ai/)) et indiqué le modèle à utiliser (`"meta-llama/Meta-Llama-3-8B-Instruct"`). Nous avons ensuite fourni une liste de messages à compléter (ici, une seule question) et transmis un paramètre supplémentaire à l’API (`max_token=100`). La sortie est un objet `ChatCompletionOutput` qui suit la spécification OpenAI. Le contenu généré est accessible via `output.choices[0].message.content`. Pour plus de détails, consultez la documentation de [chat_completion()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion). > [!WARNING] > L’API est conçue pour être simple. Tous les paramètres et options ne sont pas disponibles ou décrits pour l’utilisateur final. Consultez [cette page](https://huggingface.co/docs/api-inference/detailed_parameters) si vous souhaitez en savoir plus sur tous les paramètres disponibles pour chaque tâche. ### Utiliser un fournisseur spécifique Si vous souhaitez utiliser un fournisseur spécifique, vous pouvez le spécifier lors de l'initialisation du client. La valeur par défaut est "auto", qui sélectionne le premier des fournisseurs disponibles pour le modèle, triés selon l'ordre défini par l'utilisateur dans https://hf.co/settings/inference-providers. Reportez-vous à la section [Fournisseurs et tâches pris en charge](#supported-providers-and-tasks) pour obtenir la liste des fournisseurs pris en charge. ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(provider="replicate", api_key="my_replicate_api_key") ``` ### Utiliser un modèle spécifique Que se passe-t-il si vous souhaitez utiliser un modèle spécifique ? Vous pouvez le spécifier soit en tant que paramètre, soit directement au niveau d'une instance : ```python >>> from huggingface_hub import InferenceClient # Initialize client for a specific model >>> client = InferenceClient(provider="together", model="meta-llama/Llama-3.1-8B-Instruct") >>> client.text_to_image(...) # Or use a generic client but pass your model as an argument >>> client = InferenceClient(provider="together") >>> client.text_to_image(..., model="meta-llama/Llama-3.1-8B-Instruct") ``` > [!TIP] > Lors de l’utilisation du fournisseur « hf-inference », chaque tâche est associée à un modèle recommandé parmi les plus d’un million de modèles disponibles sur le Hub. Toutefois, cette recommandation peut évoluer au fil du temps, il est donc préférable de définir explicitement un modèle une fois que vous avez choisi celui à utiliser. Pour les fournisseurs tiers, vous devez toujours spécifier un modèle compatible avec ce fournisseur. > > Consultez la page [Models](https://huggingface.co/models?inference=warm) sur le Hub pour explorer les modèles disponibles via les Inference Providers. ### Utilisation des points de terminaison d'inférence Les exemples que nous avons vus ci-dessus utilisent des fournisseurs d’inférence. Bien que ceux-ci s’avèrent très utiles pour le prototypage et les tests rapides, une fois que vous êtes prêt à déployer votre modèle en production, vous devrez utiliser une infrastructure dédiée. C’est là qu’interviennent les [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index). Ils vous permettent de déployer n’importe quel modèle et de l’exposer sous forme d’API privée. Une fois le déploiement effectué, vous obtenez une URL à laquelle vous pouvez vous connecter en utilisant exactement le même code qu’auparavant, en ne modifiant que le paramètre `model` : ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") # or >>> client = InferenceClient() >>> client.text_to_image(..., model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") ``` Notez que vous ne pouvez pas spécifier à la fois une URL et un fournisseur - ils sont mutuellement exclusifs. Les URL sont utilisées pour se connecter directement aux points de terminaison déployés. ### Utilisation de points de terminaison locaux Vous pouvez utiliser [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient) pour exécuter des complétions de chat avec des serveurs d’inférence locaux (llama.cpp, vllm, litellm server, TGI, mlx, etc.) fonctionnant sur votre propre machine. L’API doit être compatible avec l’API OpenAI. ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(model="http://localhost:8080") >>> response = client.chat.completions.create( ... messages=[ ... {"role": "user", "content": "What is the capital of France?"} ... ], ... max_tokens=100 ... ) >>> print(response.choices[0].message.content) ``` > [!TIP] > De la même manière que le client Python d'OpenAI, [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient) peut être utilisé pour exécuter une inférence de Chat Completion avec n'importe quel point de terminaison compatible avec l'API REST d'OpenAI. ### Authentification L'authentification peut être effectuée de deux manières : **Passage par Hugging Face** : utilisez Hugging Face comme proxy pour accéder à des fournisseurs tiers. Les appels sont routés via l’infrastructure de Hugging Face en utilisant nos clés de fournisseur, et l’utilisation est facturée directement à votre compte Hugging Face. Vous pouvez vous authentifier à l'aide d'un [User Access Token](https://huggingface.co/docs/hub/security-tokens). Vous pouvez fournir votre jeton Hugging Face directement en utilisant le paramètre `api_key` : ```python >>> client = InferenceClient( provider="replicate", api_key="hf_****" # Your HF token ) ``` Si vous ne *transmettez pas* de `api_key`, le client tentera de trouver et d'utiliser un jeton stocké localement sur votre machine. Cela se produit généralement si vous vous êtes connecté précédemment. Consultez le [Guide d'authentification](https://huggingface.co/docs/huggingface_hub/quick-start#authentication) pour plus de détails sur la connexion. ```python >>> client = InferenceClient( provider="replicate", token="hf_****" # Your HF token ) ``` **Accès direct au fournisseur** : utilisez votre propre clé API pour interagir directement avec le service du fournisseur : ```python >>> client = InferenceClient( provider="replicate", api_key="r8_****" # Your Replicate API key ) ``` Pour plus de détails, consultez la [documentation sur la tarification des fournisseurs d'inférence](https://huggingface.co/docs/inference-providers/pricing#routed-requests-vs-direct-calls). ## Fournisseurs et tâches pris en charge L’objectif de [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient) est de fournir l’interface la plus simple pour exécuter de l’inférence sur les modèles Hugging Face, sur n’importe quel fournisseur. Il dispose d’une API simple qui prend en charge les tâches les plus courantes. Voici un tableau indiquant les tâches prises en charge par chaque fournisseur : | Tâche | Baseten | Cerebras | Cohere | DeepInfra | fal-ai | Featherless AI | Fireworks AI | Groq | HF Inference | Novita AI | Nscale | OVHcloud AI Endpoints | IA publique | Répliquer | Scaleway | Ensemble | Wavespeed | Zai | | --------------------------------------------------- | ------- | -------- | ------ | --------- | ------ | -------------- | ------------ | ---- | ------------ | --------- | ------ | --------------------- | --------- | --------- | -------- | -------- | --------- | --- | | [audio_classification()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.audio_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [audio_to_audio()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.audio_to_audio) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [automatic_speech_recognition()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.automatic_speech_recognition) | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | | [chat_completion()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion) | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ | | [document_question_answering()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.document_question_answering) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [feature_extraction()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.feature_extraction) | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | | [fill_mask()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.fill_mask) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [image_classification()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.image_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [image_segmentation()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.image_segmentation) | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [image_to_image()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.image_to_image) | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | | [image_to_video()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.image_to_video) | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | | [image_to_text()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.image_to_text) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [object_detection()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.object_detection) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [question_answering()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.question_answering) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [sentence_similarity()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.sentence_similarity) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [summarization()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.summarization) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [table_question_answering()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.table_question_answering) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [text_classification()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.text_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [text_generation()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.text_generation) | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | | [text_to_image()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_image) | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | | [text_to_speech()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_speech) | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | | [text_to_video()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_video) | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | | [tabular_classification()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.tabular_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [tabular_regression()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.tabular_regression) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [token_classification()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.token_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [translation()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.translation) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [visual_question_answering()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.visual_question_answering) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [zero_shot_image_classification()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.zero_shot_image_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [zero_shot_classification()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.zero_shot_classification) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | > [!TIP] > Consultez la page [Tasks](https://huggingface.co/tasks) pour en savoir plus sur chaque tâche. ## Compatibilité OpenAI La tâche `chat_completion` suit la syntaxe du [client Python d'OpenAI](https://github.com/openai/openai-python). Que signifie cela pour vous ? Cela signifie que si vous êtes habitué à manipuler les API d'`OpenAI`, vous pourrez passer à `huggingface_hub.InferenceClient` pour travailler avec des modèles open source en ne modifiant que 2 lignes de code ! ```diff - from openai import OpenAI + from huggingface_hub import InferenceClient - client = OpenAI( + client = InferenceClient( base_url=..., api_key=..., ) output = client.chat.completions.create( model="meta-llama/Meta-Llama-3-8B-Instruct", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Count to 10"}, ], stream=True, max_tokens=1024, ) for chunk in output: print(chunk.choices[0].delta.content) ``` Et c'est tout ! Les seules modifications requises consistent à remplacer `from openai import OpenAI` par `from huggingface_hub import InferenceClient` et `client = OpenAI(...)` par `client = InferenceClient(...)`. Vous pouvez choisir n'importe quel modèle LLM du Hugging Face Hub en passant son identifiant de modèle en tant que paramètre `model`. [Voici la liste](https://huggingface.co/models?pipeline_tag=text-generation&other=conversational,text-generation-inference&sort=trending) des modèles pris en charge. Pour l'authentification, vous devez passer un [User Access Token](https://huggingface.co/settings/tokens) valide en tant que `api_key` ou vous authentifier à l'aide de `huggingface_hub` (voir le [guide d'authentification](https://huggingface.co/docs/huggingface_hub/quick-start#authentication)). Tous les paramètres d’entrée et le format de sortie sont strictement identiques. En particulier, vous pouvez passer `stream=True` pour recevoir les jetons au fur et à mesure de leur génération. Vous pouvez également utiliser le [AsyncInferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.AsyncInferenceClient) pour exécuter l’inférence à l’aide de `asyncio` : ```diff import asyncio - from openai import AsyncOpenAI + from huggingface_hub import AsyncInferenceClient - client = AsyncOpenAI() + client = AsyncInferenceClient() async def main(): stream = await client.chat.completions.create( model="meta-llama/Meta-Llama-3-8B-Instruct", messages=[{"role": "user", "content": "Say this is a test"}], stream=True, ) async for chunk in stream: print(chunk.choices[0].delta.content or "", end="") asyncio.run(main()) ``` Vous vous demandez peut-être pourquoi utiliser [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient) plutôt que le client d'OpenAI ? Il y a plusieurs raisons à cela : 1. [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient) est configuré pour les services Hugging Face. Vous n'avez pas besoin de fournir un `base_url` pour exécuter des modèles avec les Inference Providers. Vous n'avez pas non plus besoin de fournir un `token` ou une `api_key` si votre machine est déjà correctement connectée. 2. [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient) est conçu pour les frameworks Text-Generation-Inference (TGI) et `transformers`, ce qui garantit qu’il restera toujours à jour avec les dernières mises à jour. 3. [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient) est intégré à notre service Inference Endpoints, ce qui facilite le lancement d’un Inference Endpoint, la vérification de son statut et l’exécution d’inférence dessus. Consultez le guide [Inference Endpoints](./inference_endpoints) pour plus de détails. > [!TIP] > `InferenceClient.chat.completions.create` est simplement un alias de `InferenceClient.chat_completion`. Consultez la référence du package de [chat_completion()](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion) pour plus de détails. Les paramètres `base_url` et `api_key` lors de l’instanciation du client sont également des alias de `model` et `token`. Ces alias ont été définis pour réduire la friction lors du passage de `OpenAI` à `InferenceClient`. ## Appel de fonction Le « function calling » permet aux LLM d’interagir avec des outils externes, tels que des fonctions définies ou des API. Cela permet aux utilisateurs de créer facilement des applications adaptées à des cas d’usage spécifiques et à des tâches réelles. `InferenceClient` implémente la même interface de « tool calling » que l’API OpenAI Chat Completions. Voici un exemple simple de « tool calling » utilisant [Novita](https://novita.ai/) comme fournisseur d’inférence : ```python from huggingface_hub import InferenceClient tools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get current temperature for a given location.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "City and country e.g. Paris, France" } }, "required": ["location"], }, } } ] client = InferenceClient(provider="novita") response = client.chat.completions.create( model="Qwen/Qwen2.5-72B-Instruct", messages=[ { "role": "user", "content": "What's the weather like the next 3 days in London, UK?" } ], tools=tools, tool_choice="auto", ) print(response.choices[0].message.tool_calls[0].function.arguments) ``` > [!TIP] > Veuillez consulter la documentation des fournisseurs pour vérifier quels modèles sont pris en charge par eux pour l'appel de fonctions/outils (Function/Tool Calling). ## Sorties structurées & mode JSON InferenceClient prend en charge le mode JSON pour des réponses JSON syntaxiquement valides et les sorties structurées pour des réponses conformes à un schéma. Le mode JSON fournit des données lisibles par machine sans structure stricte, tandis que les sorties structurées garantissent à la fois un JSON valide et le respect d'un schéma prédéfini pour un traitement en aval fiable. Nous suivons les spécifications de l’API OpenAI pour le mode JSON et les Structured Outputs. Vous pouvez les activer via l’argument `response_format`. Voici un exemple de Structured Outputs utilisant [Cerebras](https://www.cerebras.ai/) comme fournisseur d’inférence : ```python from huggingface_hub import InferenceClient json_schema = { "name": "book", "schema": { "properties": { "name": { "title": "Name", "type": "string", }, "authors": { "items": {"type": "string"}, "title": "Authors", "type": "array", }, }, "required": ["name", "authors"], "title": "Book", "type": "object", }, "strict": True, } client = InferenceClient(provider="cerebras") completion = client.chat.completions.create( model="Qwen/Qwen3-32B", messages=[ {"role": "system", "content": "Extract the books information."}, {"role": "user", "content": "I recently read 'The Great Gatsby' by F. Scott Fitzgerald."}, ], response_format={ "type": "json_schema", "json_schema": json_schema, }, ) print(completion.choices[0].message) ``` > [!TIP] > Veuillez consulter la documentation des fournisseurs pour vérifier quels modèles sont pris en charge par eux pour les Structured Outputs et le JSON Mode. ## Client asynchrone Une version asynchrone du client est également fournie, basée sur `asyncio` et `httpx2`. Tous les points de terminaison d’API asynchrones sont disponibles via [AsyncInferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.AsyncInferenceClient). Son initialisation et ses API sont strictement identiques à celles de la version synchrone. ```py # Code must be run in an asyncio concurrent context. # $ python -m asyncio >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> image = await client.text_to_image("An astronaut riding a horse on the moon.") >>> image.save("astronaut.png") >>> async for token in await client.text_generation("The Huggingface Hub is", stream=True): ... print(token, end="") a platform for sharing and discussing ML-related content. ``` Pour plus d'informations sur le module `asyncio`, veuillez consulter la [documentation officielle](https://docs.python.org/3/library/asyncio.html). ## Client MCP La bibliothèque `huggingface_hub` intègre désormais un [MCPClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/mcp#huggingface_hub.MCPClient) expérimental, conçu pour doter les grands modèles de langage (LLM) de la capacité d’interagir avec des outils externes via le [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Ce client étend un [AsyncInferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.AsyncInferenceClient) afin d’intégrer l’utilisation d’outils de manière transparente. Le [MCPClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/mcp#huggingface_hub.MCPClient) se connecte aux serveurs MCP (scripts locaux `stdio` ou services distants `http`/`sse`) qui exposent des outils. Il transmet ces outils à un LLM (via [AsyncInferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.AsyncInferenceClient)). Si le LLM décide d'utiliser un outil, [MCPClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/mcp#huggingface_hub.MCPClient) gère la requête d'exécution auprès du serveur MCP et renvoie la sortie de l'outil au LLM, en diffusant souvent les résultats en temps réel. Dans l'exemple suivant, nous utilisons le modèle [Qwen/Qwen2.5-72B-Instruct](https://huggingface.co/Qwen/Qwen2.5-72B-Instruct) via le fournisseur d'inférence [Novita](https://novita.ai/). Nous ajoutons ensuite un serveur MCP distant, en l'occurrence un serveur SSE qui mettait à disposition du LLM l'outil de génération d'images Flux. ```python import os from huggingface_hub import ChatCompletionInputMessage, ChatCompletionStreamOutput, MCPClient async def main(): async with MCPClient( provider="novita", model="Qwen/Qwen2.5-72B-Instruct", api_key=os.environ["HF_TOKEN"], ) as client: await client.add_mcp_server(type="sse", url="https://evalstate-flux1-schnell.hf.space/gradio_api/mcp/sse") messages = [ { "role": "user", "content": "Generate a picture of a cat on the moon", } ] async for chunk in client.process_single_turn_with_tools(messages): # Log messages if isinstance(chunk, ChatCompletionStreamOutput): delta = chunk.choices[0].delta if delta.content: print(delta.content, end="") # Or tool calls elif isinstance(chunk, ChatCompletionInputMessage): print( f"\nCalled tool '{chunk.name}'. Result: '{chunk.content if len(chunk.content) < 1000 else chunk.content[:1000] + '...'}'" ) if __name__ == "__main__": import asyncio asyncio.run(main()) ``` Pour un développement encore plus simple, nous proposons une classe [Agent](/docs/huggingface_hub/v2.4.0/fr/package_reference/mcp#huggingface_hub.Agent) de plus haut niveau. Cet « Agent Tiny » simplifie la création d’Agents conversationnels en gérant la boucle de discussion et l’état, agissant essentiellement comme un wrapper autour de [MCPClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/mcp#huggingface_hub.MCPClient). Il est conçu comme une simple boucle while construite directement sur un [MCPClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/mcp#huggingface_hub.MCPClient). Vous pouvez exécuter ces Agents directement depuis la ligne de commande : ```bash # install latest version of huggingface_hub with the mcp extra pip install -U huggingface_hub[mcp] # Run an agent that uses the Flux image generation tool tiny-agents run julien-c/flux-schnell-generator ``` Lors de son lancement, l'Agent charge et liste les Tools qu'il a découverts sur ses serveurs MCP connectés, puis il est prêt à recevoir vos prompts ! ## Conseils avancés Dans la section ci-dessus, nous avons vu les principaux aspects de [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient). Passons à quelques conseils plus avancés. ### Facturation En tant qu’utilisateur de HF, vous disposez de crédits mensuels pour exécuter de l’inférence via divers fournisseurs sur le Hub. Le montant des crédits que vous recevez dépend de votre type de compte (Free ou PRO ou Enterprise Hub). Vous êtes facturé pour chaque requête d’inférence, selon le barème tarifaire du fournisseur. Par défaut, les requêtes sont facturées à votre compte personnel. Toutefois, il est possible de configurer la facturation afin que les requêtes soient imputées à une organisation dont vous êtes membre, en transmettant simplement `bill_to=""` à `InferenceClient`. Pour que cela fonctionne, votre organisation doit être abonnée à Enterprise Hub. Pour plus de détails sur la facturation, consultez [ce guide](https://huggingface.co/docs/api-inference/pricing#features-using-inference-providers). ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(provider="fal-ai", bill_to="openai") >>> image = client.text_to_image( ... "A majestic lion in a fantasy forest", ... model="black-forest-labs/FLUX.1-schnell", ... ) >>> image.save("lion.png") ``` Notez qu'il n'est PAS possible de facturer un autre utilisateur ou une organisation dont vous n'êtes pas membre. Si vous souhaitez accorder des crédits à quelqu'un d'autre, vous devez créer une organisation commune avec cette personne. ### Délai d'attente Les appels d'inférence peuvent prendre un temps considérable. Par défaut, [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient) attend « indéfiniment » jusqu'à la fin de l'inférence. Si vous souhaitez un meilleur contrôle dans votre flux de travail, vous pouvez définir le paramètre `timeout` sur une valeur spécifique en secondes. Si le délai d'attente expire, une [InferenceTimeoutError](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceTimeoutError) est levée, que vous pouvez capturer dans votre code : ```python >>> from huggingface_hub import InferenceClient, InferenceTimeoutError >>> client = InferenceClient(timeout=30) >>> try: ... client.text_to_image(...) ... except InferenceTimeoutError: ... print("Inference timed out after 30s.") ``` ### Entrées binaires Certaines tâches nécessitent des entrées binaires, par exemple lors du traitement d’images ou de fichiers audio. Dans ce cas, [InferenceClient](/docs/huggingface_hub/v2.4.0/fr/package_reference/inference_client#huggingface_hub.InferenceClient) tente d’être aussi permissif que possible et accepte différents types : - brut `bytes` - un objet de type fichier, ouvert en binaire (`with open("audio.flac", "rb") as f: ...`) - un chemin (`str` ou `Path`) pointant vers un fichier local - une URL (`str`) pointant vers un fichier distant (par exemple `https://...`). Dans ce cas, le fichier sera téléchargé localement avant envoyés à l'API. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg") [{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...] ```