Hub Python Library documentation
Exécuter l'inférence sur des serveurs
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 :
- Fournisseurs d’inférence : 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 pour obtenir la liste des fournisseurs pris en charge.
- Inference Endpoints : 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.
- Points de terminaison locaux : vous pouvez également exécuter l’inférence avec des serveurs d’inférence locaux tels que llama.cpp, Ollama, vLLM, LiteLLM ou Text Generation Inference (TGI) en connectant le client à ces points de terminaison locaux.
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 ou les pages de documentation Inference Endpoints.
Pour le développement web, un client JS a été publié. Si vous êtes intéressé par le développement de jeux, vous pouvez jeter un œil à notre projet C#.
Premiers pas
Commençons par une tâche de génération d’images à partir de texte :
>>> 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 avec un fournisseur tiers, Replicate. 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().
Passons maintenant à un exemple utilisant l'API chat_completion(). Cette tâche utilise un LLM pour générer une réponse à partir d'une liste de messages :
>>> 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) 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().
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 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 pour obtenir la liste des fournisseurs pris en charge.
>>> 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 :
>>> 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")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. Cependant, cette recommandation peut évoluer dans le temps, il est donc préférable de définir explicitement un modèle une fois que vous avez décidé lequel utiliser. Pour les fournisseurs tiers, vous devez toujours spécifier un modèle compatible avec ce fournisseur.
Consultez la page Models 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. 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 :
>>> 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 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.
>>> 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)De la même manière que le client Python d'OpenAI, 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. Vous pouvez fournir votre jeton Hugging Face directement en utilisant le paramètre api_key :
>>> client = InferenceClient(
provider="replicate",
api_key="hf_****" # Your HF token
)Si vous ne passez 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 déjà connecté. Consultez le Guide d’authentification pour plus de détails sur la connexion.
>>> 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 :
>>> 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.
Fournisseurs et tâches pris en charge
L’objectif de 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() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| audio_to_audio() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| automatic_speech_recognition() | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| chat_completion() | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ |
| document_question_answering() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| feature_extraction() | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ |
| fill_mask() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| image_classification() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| image_segmentation() | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| image_to_image() | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| image_to_video() | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
| image_to_text() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| object_detection() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| question_answering() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| sentence_similarity() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| summarization() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| table_question_answering() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| text_classification() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| text_generation() | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| text_to_image() | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ |
| text_to_speech() | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ |
| text_to_video() | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| tabular_classification() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| tabular_regression() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| token_classification() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| translation() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| visual_question_answering() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| zero_shot_image_classification() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| zero_shot_classification() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
Consultez la page Tasks pour en savoir plus sur chaque tâche.
Compatibilité OpenAI
La tâche chat_completion suit la syntaxe du client Python d’OpenAI. 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 !
- 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 des modèles pris en charge. Pour l’authentification, vous devez passer un User Access Token valide en tant que api_key ou vous authentifier à l’aide de huggingface_hub (voir le guide d’authentification).
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 pour exécuter l’inférence à l’aide de asyncio :
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 plutôt que le client d’OpenAI ? Il y a plusieurs raisons à cela :
- InferenceClient est configuré pour les services Hugging Face. Vous n’avez pas besoin de fournir un
base_urlpour exécuter des modèles avec les Inference Providers. Vous n’avez pas non plus besoin de fournir untokenou uneapi_keysi votre machine est déjà correctement connectée. - 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. - 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 pour plus de détails.
InferenceClient.chat.completions.createest simplement un alias deInferenceClient.chat_completion. Consultez la référence du package de chat_completion() pour plus de détails. Les paramètresbase_urletapi_keylors de l’instanciation du client sont également des alias demodelettoken. Ces alias ont été définis pour réduire la friction lors du passage deOpenAIà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 comme fournisseur d’inférence :
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)
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 comme fournisseur d’inférence :
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)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. Son initialisation et ses API sont strictement identiques à celles de la version synchrone.
# 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.
Client MCP
La bibliothèque huggingface_hub intègre désormais un 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 (MCP). Ce client étend un AsyncInferenceClient afin d’intégrer l’utilisation d’outils de manière transparente.
Le 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). Si le LLM décide d'utiliser un outil, 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 via le fournisseur d'inférence Novita. 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.
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 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. Il est conçu comme une simple boucle while construite directement sur un MCPClient. Vous pouvez exécuter ces Agents directement depuis la ligne de commande :
# 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. Passons maintenant à 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="<your_org_name>" à InferenceClient. Pour que cela fonctionne, votre organisation doit être abonnée à Enterprise Hub. Pour plus de détails sur la facturation, consultez ce guide.
>>> 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 attend « indéfiniment » jusqu’à la fin de l’inférence. Si vous souhaitez un contrôle plus fin 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 est levée, que vous pouvez capturer dans votre code :
>>> 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 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 (
strouPath) pointant vers un fichier local - une URL (
str) pointant vers un fichier distant (par exemplehttps://...). Dans ce cas, le fichier est téléchargé localement avant d’être envoyé à l’API.
>>> 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'}, ...]