Hub Python Library documentation
Points de terminaison d'inférence
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_hubafin 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
< source >( 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 (
stroubool, 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. Passeztoken=Falsesi 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
< source >( raw: dictnamespace: strtoken: str | bool | None = Noneapi: typing.Optional[ForwardRef('HfApi')] = None )
Initialiser l'objet à partir d'un dictionnaire brut.
client
< source >( ) → InferenceClient
Retourne
un client d'inférence pointant vers le point de terminaison déployé.
- 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
< source >( ) → AsyncInferenceClient
Retourne
un client d'inférence compatible asyncio pointant vers le point de terminaison déployé.
- 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.
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
< source >( ) → InferenceEndpoint
Retourne
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
< source >( ) → InferenceEndpoint
Retourne
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
< source >( running_ok: bool = True ) → InferenceEndpoint
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
< source >( ) → InferenceEndpoint
Retourne
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
< source >( 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}}, égalementsGLang,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.commanddans 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.argsdans 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). Lorsquecustom_imagen'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 exigemodel.imagedans 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
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
< source >( 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. SiNone, 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
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èstimeoutsecondes.
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
< source >( 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 surnum_accelerators).Nonepour 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', ...)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
< source >( 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 derepo_idsitué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', ...)Initialiser un objet à partir d'un dictionnaire d'élément de catalogue brut.
InferenceCatalogRecipe
classe huggingface_hub.InferenceCatalogRecipe
< source >( 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 querecipe_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).
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
< source >( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )
Une énumération.
InferenceEndpointType
classe huggingface_hub.InferenceEndpointType
< source >( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )
Une énumération.
InferenceEndpointError
Exception générique lors de la gestion des Inference Endpoints.