Hub Python Library documentation

Points de terminaison d'inférence

Hub Python Library

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Points de terminaison d'inférence

Inference Endpoints offre une solution de production sécurisée pour déployer facilement des modèles sur une infrastructure dédiée et à mise à l’échelle automatique, gérée par Hugging Face. Un Inference Endpoint est construit à partir d’un modèle du Hub. Cette page est une référence pour l’intégration de huggingface_hub avec Inference Endpoints. Pour plus d’informations sur le produit Inference Endpoints, consultez sa documentation officielle.

Consultez le guide associé pour apprendre à utiliser huggingface_hub afin de gérer vos Inference Endpoints de manière programmatique.

Les Inference Endpoints peuvent être entièrement gérés via l'API. Les endpoints sont documentés avec Swagger. La classe InferenceEndpoint est un simple wrapper construit sur la base de cette API.

Méthodes

Un sous-ensemble des fonctionnalités de l’Inference Endpoint est implémenté dans HfApi :

get_inference_endpoint() et list_inference_endpoints() pour obtenir des informations sur vos Inference Endpoints
list_inference_endpoints_hardware() pour lister le matériel sur lequel vous pouvez déployer un Inference Endpoint
create_inference_endpoint(), update_inference_endpoint() et delete_inference_endpoint() pour déployer et gérer les Inference Endpoints
list_inference_catalog() et create_inference_endpoint_from_catalog() pour parcourir et déployer le Model Catalog curaté
pause_inference_endpoint() et resume_inference_endpoint() pour mettre en pause et reprendre un Inference Endpoint
scale_to_zero_inference_endpoint() pour mettre manuellement un Endpoint à 0 répliques

InferenceEndpoint

La principale dataclass est InferenceEndpoint. Elle contient des informations sur un InferenceEndpoint déployé, y compris sa configuration et son état actuel. Une fois déployé, vous pouvez exécuter de l'inférence sur l'Endpoint à l'aide des propriétés InferenceEndpoint.client et InferenceEndpoint.async_client, qui renvoient respectivement un objet InferenceClient et un objet AsyncInferenceClient.

classe huggingface_hub.InferenceEndpoint

( namespace: strraw: dict_token: str | bool | None_api: HfApi )

Paramètres

name (str) — Le nom unique du point de terminaison d’inférence.
namespace (str) — L'espace de noms où se trouve le point de terminaison d'inférence.
repository (str) — Le nom du dépôt de modèle déployé sur ce point de terminaison d’inférence.
status (InferenceEndpointStatus) — L’état actuel du point d’accès d’inférence.
url (str, facultatif) — L’URL de l’Inference Endpoint, si disponible. Seul un Inference Endpoint déployé possède une URL.
framework (str) — Le framework d’apprentissage automatique utilisé pour le modèle.
revision (str) — La révision spécifique du modèle déployée sur le point d'accès d'inférence.
task (str) — La tâche associée au modèle déployé.
created_at (datetime.datetime) — Horodatage de la création de l’Inference Endpoint.
updated_at (datetime.datetime) — Horodatage de la dernière mise à jour du point de terminaison d’inférence.
type (InferenceEndpointType) — Le type de l'Inference Endpoint (public, authentifié, privé).
raw (dict) — Les données brutes sous forme de dictionnaire renvoyées par l'API.
token (str ou bool, facultatif) — Jeton d’authentification pour l’Inference Endpoint, s’il est défini lors de la requête à l’API. Par défaut, le jeton enregistré localement est utilisé s’il n’est pas fourni. Passez token=False si vous ne souhaitez pas envoyer votre jeton au serveur.

Contient des informations sur un point de terminaison d’inférence déployé.

Exemple :

>>> from huggingface_hub import get_inference_endpoint
>>> endpoint = get_inference_endpoint("my-text-to-image")
>>> endpoint
InferenceEndpoint(name='my-text-to-image', ...)

# Get status
>>> endpoint.status
'running'
>>> endpoint.url
'https://68a0f3b5c6ee5c9dcc0e0a01.endpoints.huggingface.cloud'

# Run inference
>>> endpoint.client.text_to_image(...)

# Pause endpoint to save $$$
>>> endpoint.pause()

# ...
# Resume and wait for deployment
>>> endpoint.resume()
>>> endpoint.wait()
>>> endpoint.client.text_to_image(...)

from_raw

( raw: dictnamespace: strtoken: str | bool | None = Noneapi: typing.Optional[ForwardRef('HfApi')] = None )

Initialiser l'objet à partir d'un dictionnaire brut.

client

( ) → InferenceClient

Retourne

InferenceClient

un client d'inférence pointant vers le point de terminaison déployé.

Lève

InferenceEndpointError

InferenceEndpointError — Si l’Inference Endpoint n’est pas encore déployé.

Retourne un client pour effectuer des prédictions sur ce point d'inférence.

async_client

( ) → AsyncInferenceClient

Retourne

AsyncInferenceClient

un client d'inférence compatible asyncio pointant vers le point de terminaison déployé.

Lève

InferenceEndpointError

InferenceEndpointError — Si l’Inference Endpoint n’est pas encore déployé.

Retourne un client pour effectuer des prédictions sur ce point d'inférence.

supprimer

( )

Supprimez le point de terminaison d'inférence.

Cette opération n’est pas réversible. Si vous ne souhaitez pas être facturé pour un Inference Endpoint, il est préférable de le mettre en pause avec InferenceEndpoint.pause() ou de le réduire à zéro avec InferenceEndpoint.scale_to_zero().

Ceci est un alias de HfApi.delete_inference_endpoint().

fetch

( ) → InferenceEndpoint

Retourne

InferenceEndpoint

le même Inference Endpoint, modifié sur place avec les données les plus récentes.

Récupérer les dernières informations sur le point d'accès d'inférence.

pause

( ) → InferenceEndpoint

Retourne

InferenceEndpoint

le même Inference Endpoint, modifié sur place avec les données les plus récentes.

Mettez l'Endpoint d'inférence en pause.

Un Inference Endpoint en pause n’est pas facturé. Il peut être repris à tout moment à l’aide de InferenceEndpoint.resume(). Ceci est différent du redimensionnement de l’Inference Endpoint à zéro avec InferenceEndpoint.scale_to_zero(), qui serait automatiquement redémarré lorsqu’une requête lui est adressée.

Ceci est un alias de HfApi.pause_inference_endpoint(). L'objet courant est modifié en place avec les données les plus récentes du serveur.

reprendre

( running_ok: bool = True ) → InferenceEndpoint

Paramètres

running_ok (bool, facultatif) — Si True, la méthode ne lèvera pas d’erreur si le Inference Endpoint est déjà en cours d’exécution. La valeur par défaut est True.

Retourne

InferenceEndpoint

le même Inference Endpoint, modifié sur place avec les données les plus récentes.

Reprendre le point de terminaison d’inférence.

Ceci est un alias de HfApi.resume_inference_endpoint(). L'objet actuel est modifié en place avec les données les plus récentes du serveur.

scale_to_zero

( ) → InferenceEndpoint

Retourne

InferenceEndpoint

le même Inference Endpoint, modifié sur place avec les données les plus récentes.

Mettre à l’échelle le point de terminaison d’inférence à zéro.

Un Inference Endpoint mis à l'échelle zéro ne sera pas facturé. Il sera repris à la prochaine requête qui lui est adressée, avec un délai de démarrage à froid. Cela diffère de la mise en pause de l'Inference Endpoint via InferenceEndpoint.pause(), qui nécessiterait une reprise manuelle via InferenceEndpoint.resume().

Ceci est un alias de HfApi.scale_to_zero_inference_endpoint(). L'objet actuel est modifié en place avec les données les plus récentes du serveur.

update

( accelerator: str | None = Noneinstance_size: str | None = Noneinstance_type: str | None = Nonemin_replica: int | None = Nonemax_replica: int | None = Nonescale_to_zero_timeout: int | None = Nonerepository: str | None = Noneframework: str | None = Nonerevision: str | None = Nonetask: str | None = Nonecustom_image: dict | None = Nonecontainer_command: list[str] | None = Nonecontainer_args: list[str] | None = Nonetensor_parallel_size: int | None = Nonedata_parallel_size: int | None = Nonesecrets: dict[str, str] | None = None ) → InferenceEndpoint

Paramètres

accelerator (str, facultatif) — L'accélérateur matériel à utiliser pour l'inférence (par ex. "cpu").
instance_size (str, facultatif) — La taille ou le type d’instance à utiliser pour l’hébergement du modèle (par ex. "x4").
instance_type (str, facultatif) — Le type d’instance cloud sur lequel l’Inference Endpoint sera déployé (par ex. "intel-icl").
min_replica (int, facultatif) — Le nombre minimal de répliques (instances) à maintenir en cours d’exécution pour l’Inference Endpoint.
max_replica (int, facultatif) — Le nombre maximal de répliques (instances) vers lequel mettre à l’échelle l’Inference Endpoint.
scale_to_zero_timeout (int, facultatif) — Durée, en minutes, avant qu'un point de terminaison inactif ne soit mis à l'échelle zéro.
repository (str, facultatif) — Le nom du dépôt de modèle associé à l'Inference Endpoint (par exemple "gpt2").
framework (str, facultatif) — Le framework d’apprentissage automatique utilisé pour le modèle (par exemple "custom").
revision (str, facultatif) — La révision spécifique du modèle à déployer sur l’Inference Endpoint (par exemple "6c0e6080953db56375760c0471a8c5f2929baf11").
task (str, facultatif) — La tâche sur laquelle déployer le modèle (par ex. "text-classification").
custom_image (dict, facultatif) — L’image conteneur à exécuter. Soit un dictionnaire indexé par variante d’image (par ex. {"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}‌}, également sGLang, tgi, tei, llamacpp, hfServe, …), qui est transmis tel quel, soit un dictionnaire plat décrivant un conteneur personnalisé (par ex. {"url": ..., "port": ...}), qui est envoyé sous la forme {"custom": ...}.
container_command (list[str], facultatif) — Remplace la commande d’entrée du conteneur (correspond à model.command dans la charge utile de l’API). Fonctionne avec les images d’ingénierie gérées (par exemple vLLM, SGLang) et les images personnalisées.
container_args (list[str], facultatif) — Arguments ajoutés à l’entrypoint du conteneur (correspond à model.args dans la charge utile de l’API). Fonctionne avec les images d’engine gérées (par exemple vLLM, SGLang) et les images personnalisées.
tensor_parallel_size (int, facultatif) — Nombre d'accélérateurs sur lesquels répartir une copie unique du modèle (images vLLM et SGLang). Lorsque custom_image n'est pas fourni, l'image actuellement configurée sur le point de terminaison est récupérée et mise à jour en place, car l'API exige model.image dans son ensemble.
data_parallel_size (int, facultatif) — Nombre de copies du modèle à exécuter, une par accélérateur (images vLLM).
secrets (dict[str, str], facultatif) — Valeurs secrètes à injecter dans l'environnement du conteneur.

Retourne

InferenceEndpoint

le même Inference Endpoint, modifié sur place avec les données les plus récentes.

Mettre à jour le point de terminaison d’inférence.

Cette méthode permet de mettre à jour la configuration de calcul, le modèle déployé, ou les deux. Tous les arguments sont facultatifs, mais au moins un doit être fourni.

Ceci est un alias de HfApi.update_inference_endpoint(). L'objet actuel est modifié en place avec les données les plus récentes du serveur.

wait

( timeout: int | None = Nonerefresh_every: int = 5 ) → InferenceEndpoint

Paramètres

timeout (int, facultatif) — Durée maximale d’attente du déploiement de l’Inference Endpoint, en secondes. Si None, l’attente est indéfinie.
refresh_every (int, facultatif) — Temps d’attente entre chaque récupération de l’état du point de terminaison d’inférence, en secondes. Valeur par défaut : 5 s.

Retourne

InferenceEndpoint

le même Inference Endpoint, modifié sur place avec les données les plus récentes.

Lève

InferenceEndpointError ou InferenceEndpointTimeoutError

InferenceEndpointError — Si l’Inference Endpoint est passé dans un état d’échec.
InferenceEndpointTimeoutError — Si l’Inference Endpoint n’est pas déployé après timeout secondes.

Attendez que le point de terminaison d'inférence soit déployé.

Les informations du serveur seront récupérées toutes les 1 s. Si le point de terminaison d'inférence n'est pas déployé après timeout secondes, une InferenceEndpointTimeoutError sera levée. Le InferenceEndpoint sera modifié sur place avec les données les plus récentes.

InferenceEndpointHardware

classe huggingface_hub.InferenceEndpointHardware

( id: strvendor: strregion: straccelerator: strinstance_type: strinstance_size: strarchitecture: strnum_accelerators: intnum_cpus: int | Nonememory_gb: floatgpu_memory_gb: int | Noneprice_per_hour: floatstatus: strmax_accelerators: intused_accelerators: int )

Paramètres

id (str) — Identifiant matériel unique, par exemple "aws-us-east-1-nvidia-l4-x1".
vendor (str) — Le fournisseur cloud qui héberge le matériel, par exemple "aws".
region (str) — La région cloud dans laquelle le matériel est disponible, par exemple "us-east-1".
accelerator (str) — Le type d'accélérateur matériel, par exemple "cpu", "gpu" ou "neuron".
instance_type (str) — Le type d’instance cloud, par exemple "nvidia-l4".
instance_size (str) — Le multiplicateur de taille de l'instance, par exemple "x1".
architecture (str) — Description matérielle lisible par l'humain, par exemple "Nvidia L4".
num_accelerators (int) — Nombre d'unités d'accélération par réplique.
num_cpus (int, facultatif) — Nombre de vCPUs par réplique.
memory_gb (float) — RAM par réplique, en Go.
gpu_memory_gb (int, facultatif) — Mémoire GPU totale par réplique, en Go (c’est-à-dire la somme sur num_accelerators). None pour le matériel non-GPU.
price_per_hour (float) — Coût par réplique et par heure, en USD.
status (str) — Disponibilité du matériel : "available", "low_availability", "not_available", "reserved" ou "deprecated".
max_accelerators (int) — Nombre maximal d'accélérateurs de ce type que l'espace de noms est autorisé à exécuter.
used_accelerators (int) — Nombre d'accélérateurs de ce type actuellement utilisés par l'espace de noms.

Contient des informations sur une configuration matérielle disponible pour les Inference Endpoints.

Les champs vendor, region, accelerator, instance_type et instance_size correspondent exactement aux valeurs à passer à create_inference_endpoint() (ou hf endpoints deploy) pour déployer sur ce matériel.

Exemple :

>>> from huggingface_hub import list_inference_endpoints_hardware
>>> hardware = list_inference_endpoints_hardware()
>>> hardware[0]
InferenceEndpointHardware(id='aws-us-east-1-nvidia-l4-x1', vendor='aws', region='us-east-1', ...)

from_raw

( raw: dictvendor: strregion: str )

Initialise l'objet à partir d'un dictionnaire de calcul brut, imbriqué sous un fournisseur et une région dans la réponse de l'API.

InferenceCatalogModel

classe huggingface_hub.InferenceCatalogModel

( repo_id: strname: strauthor: strlicense: strtask: strcreated_at: datetimerecipes: list )

Paramètres

repo_id (str) — L’identifiant du dépôt de modèle sur le Hub, par exemple "meta-llama/Llama-3.1-8B-Instruct".
name (str) — Le nom du modèle, c'est-à-dire la partie de repo_id située après l'auteur, par exemple "Llama-3.1-8B-Instruct".
author (str) — L'auteur du dépôt de modèle, par exemple "meta-llama".
license (str) — La licence du modèle, par exemple "Apache 2.0".
task (str) — La tâche sur laquelle le modèle est déployé, par exemple "text-generation".
created_at (datetime) — La date à laquelle le modèle a été ajouté au catalogue.
recipes (list[InferenceCatalogRecipe]) — Les méthodes testées pour déployer ce modèle.

Contient des informations sur un modèle disponible dans le catalogue d’inférence.

Exemple :

>>> from huggingface_hub import list_inference_catalog
>>> catalog = list_inference_catalog(engine="vllm")
>>> catalog[0]
InferenceCatalogModel(repo_id='Qwen/Qwen2.5-Coder-7B-Instruct', name='Qwen2.5-Coder-7B-Instruct', ...)

from_raw

( raw: dict )

Initialiser un objet à partir d'un dictionnaire d'élément de catalogue brut.

InferenceCatalogRecipe

classe huggingface_hub.InferenceCatalogRecipe

( id: straccelerator: strengine: strgguf_file: str | Nonerevision: str | None )

Paramètres

id (str) — L’identifiant public de la recette, à passer à create_inference_endpoint_from_catalog() en tant que recipe_id.
accelerator (str) — Le type d'accélérateur matériel sur lequel la recette s'exécute, par exemple "cpu", "gpu" ou "neuron".
engine (str) — Le moteur d’inférence utilisé par la recette, par exemple "vllm", "llamacpp", "tei" ou "sglang".
gguf_file (str, facultatif) — Le fichier GGUF déployé par la recette. Défini uniquement pour les recettes "llamacpp".
revision (str, facultatif) — La révision du modèle à laquelle la recette est liée, le cas échéant.

Contient des informations sur une méthode de déploiement d'un modèle du catalogue d'inférence, testée à l'avance.

Une recette est une combinaison de matériel et de moteur que l'équipe Inference Endpoints a testée pour un modèle donné. Un modèle possède généralement une seule recette, mais il peut en avoir plusieurs (par exemple, une pour GPU et une pour Neuron, ou une par quantification GGUF).

from_raw

( raw: dict )

Initialiser un objet à partir d'un dictionnaire de recette brut, imbriqué sous un modèle dans la réponse de l'API.

InferenceEndpointStatus

classe huggingface_hub.InferenceEndpointStatus

( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )

Une énumération.

InferenceEndpointType

classe huggingface_hub.InferenceEndpointType

( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )

Une énumération.

InferenceEndpointError

classe huggingface_hub.InferenceEndpointError

( )

Exception générique lors de la gestion des Inference Endpoints.

Update on GitHub

←Client d'inférence Client MCP→