Hub Python Library documentation
Inférence
Inférence
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.
Ces services peuvent être appelés à l'aide de l'objet InferenceClient. Veuillez consulter ce guide pour plus d'informations sur son utilisation.
Client d'inférence
classe huggingface_hub.InferenceClient
< source >( model: str | None = Noneprovider: typing.Union[typing.Literal['baseten', 'cerebras', 'cohere', 'deepinfra', 'fal-ai', 'featherless-ai', 'fireworks-ai', 'groq', 'hf-inference', 'novita', 'nscale', 'openai', 'ovhcloud', 'publicai', 'replicate', 'scaleway', 'together', 'wavespeed', 'zai-org'], typing.Literal['auto'], NoneType] = Nonetoken: str | None = Nonetimeout: float | None = Noneheaders: dict[str, str] | None = Nonecookies: dict[str, str] | None = Nonebill_to: str | None = Nonebase_url: str | None = Noneapi_key: str | None = None )
Paramètres
- model (
str,optional) — The model to run inference with. Can be a model id hosted on the Hugging Face Hub, e.g.meta-llama/Meta-Llama-3-8B-Instructor a URL to a deployed Inference Endpoint. Defaults to None, in which case a recommended model is automatically selected for the task. Note: for better compatibility with OpenAI’s client,modelhas been aliased asbase_url. Those 2 arguments are mutually exclusive. If a URL is passed asmodelorbase_urlfor chat completion, the(/v1)/chat/completionssuffix path will be appended to the URL. - provider (
str, facultatif) — Nom du fournisseur à utiliser pour l’inférence. Peut être"baseten","cerebras","cohere","deepinfra","fal-ai","featherless-ai","fireworks-ai","groq","hf-inference","novita","nscale","openai","ovhcloud","publicai","replicate","scaleway","together","wavespeed"ou"zai-org". Valeur par défaut : « auto » : routage automatique, qui privilégie par défaut le fournisseur « fastest » ; vous pouvez passer à l’ordre « cheapest » ou « preferred » sur https://hf.co/settings/inference-providers. Si model est une URL ou sibase_urlest transmis, alorsprovidern’est pas utilisé. - token (
str, facultatif) — Jeton Hugging Face. Par défaut, le jeton enregistré localement est utilisé s’aucun n’est fourni. Remarque : pour une meilleure compatibilité avec le client OpenAI,tokena été aliasé enapi_key. Ces deux arguments sont mutuellement exclusifs et ont exactement le même comportement. - timeout (
float,optional) — The maximum number of seconds to wait for a response from the server. Defaults to None, meaning it will loop until the server is available. - headers (
dict[str, str],optional) — En-têtes supplémentaires à envoyer au serveur. Par défaut, seuls les en-têtes d'autorisation et user-agent sont envoyés. Les valeurs de ce dictionnaire remplacent les valeurs par défaut. - bill_to (
str,optional) — Le compte de facturation à utiliser pour les requêtes. Par défaut, les requêtes sont facturées sur le compte de l’utilisateur. Les requêtes ne peuvent être facturées qu’à une organisation dont l’utilisateur est membre et qui a souscrit à Enterprise Hub. - cookies (
dict[str, str],optional) — Cookies supplémentaires à envoyer au serveur. - base_url (
str,optional) — URL de base pour exécuter l'inférence. Cet argument est dupliqué depuismodelafin que InferenceClient suive le même schéma que le clientopenai.OpenAI. Ne peut pas être utilisé simodelest défini. Valeur par défaut : None. - api_key (
str,optional) — Jeton à utiliser pour l’authentification. Cet argument est dupliqué depuistokenafin que InferenceClient suive le même schéma que le clientopenai.OpenAI. Ne peut pas être utilisé sitokenest défini. Valeur par défaut : None.
Initialiser un nouveau client d'inférence.
InferenceClient vise à offrir une expérience unifiée pour effectuer de l’inférence. Le client peut être utilisé de manière transparente avec l’API d’inférence (gratuite), les Inference Endpoints auto-hébergés ou des Inference Providers tiers.
audio_classification
< source >( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonetop_k: int | None = Nonefunction_to_apply: typing.Optional[ForwardRef('AudioClassificationOutputTransform')] = None ) → list[AudioClassificationOutputElement]
Paramètres
- audio (Union[str, Path, bytes, BinaryIO]) — Le contenu audio à classifier. Il peut s’agir de données audio brutes, d’un fichier audio local ou d’une URL pointant vers un fichier audio.
- model (
str, facultatif) — Le modèle à utiliser pour la classification audio. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour la classification audio sera utilisé. - top_k (
int, facultatif) — Lorsqu’il est spécifié, limite la sortie aux K classes les plus probables. - function_to_apply (
"AudioClassificationOutputTransform", facultatif) — La fonction à appliquer aux sorties du modèle afin de récupérer les scores.
Retourne
list[AudioClassificationOutputElement]
Liste d'éléments AudioClassificationOutputElement contenant les étiquettes prédites et leur confiance.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuez la classification audio sur le contenu audio fourni.
audio_to_audio
< source >( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = None ) → list[AudioToAudioOutputElement]
Paramètres
- audio (Union[str, Path, bytes, BinaryIO]) — Le contenu audio pour le modèle. Il peut s’agir d’octets audio bruts, d’un fichier audio local ou d’une URL pointant vers un fichier audio.
- model (
str, facultatif) — Le modèle peut être n’importe quel modèle qui prend un fichier audio en entrée et renvoie un autre fichier audio. Il peut s’agir d’un identifiant de modèle hébergé sur le Hugging Face Hub ou d’une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour audio_to_audio sera utilisé.
Retourne
list[AudioToAudioOutputElement]
Une liste d'éléments AudioToAudioOutputElement contenant l'étiquette audio, le type de contenu et le contenu audio au format blob.
Lève
InferenceTimeoutError ou HfHubHTTPError
InferenceTimeoutError— Si le modèle est indisponible ou si la demande expirHfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectue plusieurs tâches liées à l'audio-vers-audio en fonction du modèle (par exemple : amélioration de la parole, séparation des sources).
automatic_speech_recognition
< source >( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Noneextra_body: dict | None = None ) → AutomaticSpeechRecognitionOutput
Paramètres
- audio (Union[str, Path, bytes, BinaryIO]) — Le contenu à transcrire. Il peut s'agir d'octets audio bruts, d'un fichier audio local ou d'une URL vers un fichier audio.
- model (
str, facultatif) — Le modèle à utiliser pour l’ASR. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour l’ASR sera utilisé. - extra_body (
dict, facultatif) — Paramètres supplémentaires spécifiques au fournisseur à transmettre au modèle. Consultez la documentation du fournisseur pour les paramètres pris en charge.
Retourne
Un élément contenant le texte transcrit et, le cas échéant, les segments horodatés.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuer la reconnaissance automatique de la parole (ASR ou audio-vers-texte) sur le contenu audio fourni.
chat_completion
< source >( messages: listmodel: str | None = Nonestream: bool = Falsefrequency_penalty: float | None = Nonelogit_bias: list[float] | None = Nonelogprobs: bool | None = Nonemax_tokens: int | None = Nonen: int | None = Nonepresence_penalty: float | None = Noneresponse_format: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatText, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONSchema, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONObject, NoneType] = Noneseed: int | None = Nonestop: list[str] | None = Nonestream_options: huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputStreamOptions | None = Nonetemperature: float | None = Nonetool_choice: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputToolChoiceClass, ForwardRef('ChatCompletionInputToolChoiceEnum'), NoneType] = Nonetool_prompt: str | None = Nonetools: list[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputTool] | None = Nonetop_logprobs: int | None = Nonetop_p: float | None = Noneextra_body: dict | None = None ) → ChatCompletionOutput or Iterable of ChatCompletionStreamOutput
Paramètres
- messages (Liste de ChatCompletionInputMessage) — Historique de la conversation composé de paires de rôles et de contenu.
- model (
str, facultatif) — Le modèle à utiliser pour la complétion de chat. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle recommandé par défaut pour la génération de texte basée sur le chat sera utilisé. Voir https://huggingface.co/tasks/text-generation pour plus de détails. Simodelest un identifiant de modèle, il est transmis au serveur en tant que paramètremodel. Si vous souhaitez définir une URL personnalisée tout en définissantmodeldans la charge utile de la requête, vous devez définirbase_urllors de l'initialisation de InferenceClient. - frequency_penalty (
float, facultatif) — Pénalise les nouveaux jetons en fonction de leur fréquence existante dans le texte jusqu'à présent. Plage : [-2,0, 2,0]. Valeur par défaut : 0,0. - logit_bias (
list[float], facultatif) — Ajuste la probabilité d’apparition de jetons spécifiques dans la sortie générée. - logprobs (
bool, facultatif) — Indique s'il faut retourner les logarithmes des probabilités des jetons de sortie ou non. Si la valeur est true, les logarithmes des probabilités de chaque jeton de sortie sont retournés dans le contenu du message. - max_tokens (
int, facultatif) — Nombre maximal de jetons autorisés dans la réponse. Valeur par défaut : 100. - n (
int, facultatif) — Le nombre de complétions à générer pour chaque invite. - presence_penalty (
float, facultatif) — Nombre compris entre -2,0 et 2,0. Les valeurs positives pénalisent les nouveaux jetons en fonction de leur apparition dans le texte jusqu’à présent, augmentant ainsi la probabilité que le modèle aborde de nouveaux sujets. - response_format (
ChatCompletionInputGrammarType(), facultatif) — Contraintes de grammaire. Peut être un JSONSchema ou une expression régulière. - seed (Optionnel
int, optionnel) — Graine pour un flux de contrôle reproductible. Valeur par défaut : None. - stop (
list[str], facultatif) — Jusqu’à quatre chaînes de caractères qui déclenchent la fin de la réponse. Valeur par défaut : None. - stream (
bool, facultatif) — Active le streaming en temps réel des réponses. Valeur par défaut : False. - stream_options (ChatCompletionInputStreamOptions, facultatif) — Options pour les complétions en streaming.
- temperature (
float, facultatif) — Contrôle l’aléatoire des générations. Des valeurs plus faibles garantissent des complétions moins aléatoires. Intervalle : [0, 2]. Valeur par défaut : 1.0. - top_logprobs (
int, facultatif) — Un entier compris entre 0 et 5 qui spécifie le nombre de jetons les plus probables à retourner à chaque position de jeton, chacun avec une probabilité logarithmique associée. logprobs doit être défini sur true si ce paramètre est utilisé. - top_p (
float, facultatif) — Fraction des mots suivants les plus probables à échantillonner. Doit être comprise entre 0 et 1. Valeur par défaut : 1.0. - tool_choice (ChatCompletionInputToolChoiceClass ou
ChatCompletionInputToolChoiceEnum(), facultatif) — L’outil à utiliser pour la complétion. La valeur par défaut est « auto ». - tool_prompt (
str, facultatif) — Un prompt à ajouter avant les outils. - tools (Liste de ChatCompletionInputTool, facultatif) — Une liste d'outils que le modèle peut appeler. Actuellement, seules les fonctions sont prises en charge en tant qu'outil. Utilisez ce paramètre pour fournir une liste de fonctions pour lesquelles le modèle peut générer des entrées JSON.
- extra_body (
dict, facultatif) — Paramètres supplémentaires spécifiques au fournisseur à transmettre au modèle. Consultez la documentation du fournisseur pour les paramètres pris en charge.
Retourne
ChatCompletionOutput ou itérable de ChatCompletionStreamOutput
Texte généré renvoyé par le serveur :
- si
stream=False, le texte généré est renvoyé sous forme de ChatCompletionOutput (par défaut). - si
stream=True, le texte généré est renvoyé jeton par jeton sous forme d'une séquence de ChatCompletionStreamOutput.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Une méthode pour compléter des conversations à l'aide d'un modèle de langage spécifié.
La méthode
client.chat_completionest aliasée enclient.chat.completions.createpour assurer la compatibilité avec le client d’OpenAI. Les entrées et les sorties sont strictement identiques et l’utilisation de l’une ou l’autre syntaxe donnera les mêmes résultats. Consultez le guide d’inférence pour plus de détails sur la compatibilité avec OpenAI.
Vous pouvez passer des paramètres spécifiques au fournisseur au modèle en utilisant l'argument
extra_body.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> messages = [{"role": "user", "content": "What is the capital of France?"}]
>>> client = InferenceClient("meta-llama/Meta-Llama-3-8B-Instruct")
>>> 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
)
)Exemple utilisant le streaming :
>>> from huggingface_hub import InferenceClient
>>> messages = [{"role": "user", "content": "What is the capital of France?"}]
>>> client = InferenceClient("meta-llama/Meta-Llama-3-8B-Instruct")
>>> for token in client.chat_completion(messages, max_tokens=10, stream=True):
... print(token)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content='The', role='assistant'), index=0, finish_reason=None)], created=1710498504)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' capital', role='assistant'), index=0, finish_reason=None)], created=1710498504)
(...)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' may', role='assistant'), index=0, finish_reason=None)], created=1710498504)Exemple utilisant la syntaxe d’OpenAI :
# instead of `from openai import OpenAI`
from huggingface_hub import InferenceClient
# instead of `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)Exemple d’utilisation d’un fournisseur tiers directement avec des paramètres supplémentaires (spécifiques au fournisseur). L’utilisation sera facturée sur votre compte Together AI.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="together", # Use Together AI provider
... api_key="<together_api_key>", # Pass your Together API key directly
... )
>>> client.chat_completion(
... model="meta-llama/Meta-Llama-3-8B-Instruct",
... messages=[{"role": "user", "content": "What is the capital of France?"}],
... extra_body={"safety_model": "Meta-Llama/Llama-Guard-7b"},
... )Exemple d'utilisation d'un fournisseur tiers via Hugging Face Routing. L'utilisation sera facturée sur votre compte Hugging Face.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="novita", # Use Novita provider
... api_key="hf_...", # Pass your HF token
... )
>>> client.chat_completion(
... model="meta-llama/Meta-Llama-3-8B-Instruct",
... messages=[{"role": "user", "content": "What is the capital of France?"}],
... )Exemple utilisant Image + Texte en entrée :
>>> from huggingface_hub import InferenceClient
# provide a remote URL
>>> image_url ="https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
# or a base64-encoded image
>>> image_path = "/path/to/image.jpeg"
>>> with open(image_path, "rb") as f:
... base64_image = base64.b64encode(f.read()).decode("utf-8")
>>> image_url = f"data:image/jpeg;base64,{base64_image}"
>>> client = InferenceClient("meta-llama/Llama-3.2-11B-Vision-Instruct")
>>> output = client.chat.completions.create(
... messages=[
... {
... "role": "user",
... "content": [
... {
... "type": "image_url",
... "image_url": {"url": image_url},
... },
... {
... "type": "text",
... "text": "Describe this image in one sentence.",
... },
... ],
... },
... ],
... )
>>> output
The image depicts the iconic Statue of Liberty situated in New York Harbor, New York, on a clear day.Exemple utilisant des outils :
>>> client = InferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> messages = [
... {
... "role": "system",
... "content": "Don't make assumptions about what values to plug into functions. Ask for clarification if a user request is ambiguous.",
... },
... {
... "role": "user",
... "content": "What's the weather like the next 3 days in San Francisco, CA?",
... },
... ]
>>> tools = [
... {
... "type": "function",
... "function": {
... "name": "get_current_weather",
... "description": "Get the current weather",
... "parameters": {
... "type": "object",
... "properties": {
... "location": {
... "type": "string",
... "description": "The city and state, e.g. San Francisco, CA",
... },
... "format": {
... "type": "string",
... "enum": ["celsius", "fahrenheit"],
... "description": "The temperature unit to use. Infer this from the users location.",
... },
... },
... "required": ["location", "format"],
... },
... },
... },
... {
... "type": "function",
... "function": {
... "name": "get_n_day_weather_forecast",
... "description": "Get an N-day weather forecast",
... "parameters": {
... "type": "object",
... "properties": {
... "location": {
... "type": "string",
... "description": "The city and state, e.g. San Francisco, CA",
... },
... "format": {
... "type": "string",
... "enum": ["celsius", "fahrenheit"],
... "description": "The temperature unit to use. Infer this from the users location.",
... },
... "num_days": {
... "type": "integer",
... "description": "The number of days to forecast",
... },
... },
... "required": ["location", "format", "num_days"],
... },
... },
... },
... ]
>>> response = client.chat_completion(
... model="meta-llama/Meta-Llama-3-70B-Instruct",
... messages=messages,
... tools=tools,
... tool_choice="auto",
... max_tokens=500,
... )
>>> response.choices[0].message.tool_calls[0].function
ChatCompletionOutputFunctionDefinition(
arguments={
'location': 'San Francisco, CA',
'format': 'fahrenheit',
'num_days': 3
},
name='get_n_day_weather_forecast',
description=None
)Exemple d'utilisation de response_format :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> messages = [
... {
... "role": "user",
... "content": "I saw a puppy a cat and a raccoon during my bike ride in the park. What did I see and when?",
... },
... ]
>>> response_format = {
... "type": "json",
... "value": {
... "properties": {
... "location": {"type": "string"},
... "activity": {"type": "string"},
... "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5},
... "animals": {"type": "array", "items": {"type": "string"}},
... },
... "required": ["location", "activity", "animals_seen", "animals"],
... },
... }
>>> response = client.chat_completion(
... messages=messages,
... response_format=response_format,
... max_tokens=500,
... )
>>> response.choices[0].message.content
'{
y": "bike ride",
": ["puppy", "cat", "raccoon"],
_seen": 3,
n": "park"}'document_question_answering
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]question: strmodel: str | None = Nonedoc_stride: int | None = Nonehandle_impossible_answer: bool | None = Nonelang: str | None = Nonemax_answer_len: int | None = Nonemax_question_len: int | None = Nonemax_seq_len: int | None = Nonetop_k: int | None = Noneword_boxes: list[list[float] | str] | None = None ) → list[DocumentQuestionAnsweringOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO]) — L’image d’entrée pour le contexte. Elle peut être des octets bruts, un fichier image ou une URL vers une image en ligne. - question (
str) — Question à laquelle il faut répondre. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de question-réponse sur document. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de question-réponse sur document recommandé par défaut sera utilisé. Valeur par défaut : None. - doc_stride (
int, facultatif) — Si les mots du document sont trop longs pour s’insérer avec la question pour le modèle, il sera découpé en plusieurs fragments avec un certain chevauchement. Cet argument contrôle la taille de ce chevauchement. - handle_impossible_answer (
bool, facultatif) — Indique s'il faut accepter « impossible » comme réponse - lang (
str, facultatif) — Langue à utiliser lors de l'exécution de l'OCR. La valeur par défaut est english. - max_answer_len (
int, facultatif) — La longueur maximale des réponses prédites (par exemple, seules les réponses d’une longueur inférieure sont prises en compte). - max_question_len (
int, facultatif) — La longueur maximale de la question après tokenisation. Elle sera tronquée si nécessaire. - max_seq_len (
int, facultatif) — La longueur maximale de la phrase totale (contexte + question) en jetons de chaque fragment transmis au modèle. Le contexte sera divisé en plusieurs fragments (en utilisant doc_stride comme chevauchement) si nécessaire. - top_k (
int, facultatif) — Le nombre de réponses à retourner (sélectionnées par ordre de probabilité). Peut retourner moins de top_k réponses s'il n'y a pas suffisamment d'options disponibles dans le contexte. - word_boxes (
list[Union[list[float], str, facultatif) — Une liste de mots et de boîtes englobantes (normalisées 0->1000). Si fournie, l’inférence ignorera l’étape OCR et utilisera les boîtes englobantes fournies à la place.
Retourne
list[DocumentQuestionAnsweringOutputElement]
une liste d'éléments DocumentQuestionAnsweringOutputElement contenant l'étiquette prédite, la probabilité associée, les identifiants des mots et le numéro de page.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Répondre à des questions sur des images de documents.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.document_question_answering(image="https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png", question="What is the invoice number?")
[DocumentQuestionAnsweringOutputElement(answer='us-001', end=16, score=0.9999666213989258, start=16)]feature_extraction
< source >( text: str | list[str]normalize: bool | None = Noneprompt_name: str | None = Nonetruncate: bool | None = Nonetruncation_direction: typing.Optional[typing.Literal['left', 'right']] = Nonedimensions: int | None = Noneencoding_format: typing.Optional[typing.Literal['float', 'base64']] = Nonemodel: str | None = None ) → np.ndarray
Paramètres
- text (str ou list[str]) — Le texte ou la liste de textes à encoder.
- model (str, facultatif) — Le modèle à utiliser pour la tâche d'extraction de caractéristiques. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle d'extraction de caractéristiques recommandé par défaut sera utilisé. Valeur par défaut : None.
- normalize (bool, facultatif) — Indique s'il faut normaliser les embeddings ou non. Uniquement disponible sur les serveurs alimentés par Text-Embedding-Inference.
- prompt_name (str, facultatif) —
Le nom du prompt qui doit être utilisé pour l’encodage. S’il n’est pas défini, aucun prompt ne sera appliqué.
Doit être une clé du dictionnaire prompts de la configuration Sentence Transformers.
Par exemple, si
prompt_nameest « query » et quepromptsest {“query”: “query: ”,…}, la phrase « What is the capital of France? » sera encodée comme « query: What is the capital of France? » car le texte du prompt sera préfixé avant tout texte à encoder. - truncate (bool, facultatif) — Indique s'il faut tronquer les embeddings ou non. Uniquement disponible sur les serveurs alimentés par Text-Embedding-Inference.
- truncation_direction (Literal[“left”, “right”], facultatif) — Côté de l'entrée à tronquer lorsque truncate=True est passé.
- dimensions (int, facultatif) — Le nombre de dimensions que les embeddings de sortie résultants doivent avoir. Uniquement disponible sur les points de terminaison d'embedding compatibles OpenAI.
- encoding_format (Literal[“float”, “base64”], facultatif) — Le format des embeddings de sortie. Soit “float”, soit “base64”. Uniquement disponible sur les points de terminaison d’embedding compatibles OpenAI.
Retourne
np.ndarray
L'embedding représentant le ou les textes d'entrée sous forme de tableau numpy float32.
Lève
[InferenceTimeoutError] ou [HfHubHTTPError]
- [InferenceTimeoutError] — Si le modèle est indisponible ou si la demande expirée.
- [HfHubHTTPError] — Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Générer des embeddings pour un texte donné ou un lot de textes.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.feature_extraction("Hi, who are you?")
array([[ 2.424802 , 2.93384 , 1.1750331 , ..., 1.240499, -0.13776633, -0.7889173 ],
[-0.42943227, -0.6364878 , -1.693462 , ..., 0.41978157, -2.4336355 , 0.6162071 ],
...,
[ 0.28552425, -0.928395 , -1.2077185 , ..., 0.76810825, -2.1069427 , 0.6236161 ]], dtype=float32)fill_mask
< source >( text: strmodel: str | None = Nonetargets: list[str] | None = Nonetop_k: int | None = None ) → list[FillMaskOutputElement]
Paramètres
- text (
str) — une chaîne de caractères à compléter, doit contenir le jeton [MASK] (consultez la fiche du modèle pour le nom exact du masque). - model (
str, facultatif) — Le modèle à utiliser pour la tâche de fill mask. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de fill mask recommandé par défaut sera utilisé. - targets (
list[str, facultatif) — Lorsqu’il est fourni, le modèle limite les scores aux cibles transmises au lieu de parcourir tout le vocabulaire. Si les cibles fournies ne figurent pas dans le vocabulaire du modèle, elles sont tokenisées et le premier jeton résultant est utilisé (avec un avertissement, et cela peut être plus lent). - top_k (
int, facultatif) — Lorsqu’il est fourni, il remplace le nombre de prédictions à retourner.
Retourne
list[FillMaskOutputElement]
une liste d'éléments FillMaskOutputElement contenant l'étiquette prédite, la probabilité associée, la référence du jeton et le texte complété.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Compléter un trou avec un mot manquant (un jeton, pour être précis).
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.fill_mask("The goal of life is <mask>.")
[
FillMaskOutputElement(score=0.06897063553333282, token=11098, token_str=' happiness', sequence='The goal of life is happiness.'),
FillMaskOutputElement(score=0.06554922461509705, token=45075, token_str=' immortality', sequence='The goal of life is immortality.')
]get_endpoint_info
< source >( model: str | None = None ) → dict[str, Any]
Paramètres
- model (
str, facultatif) — Le modèle à utiliser pour l'inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l'instance. Valeur par défaut : None.
Retourne
dict[str, Any]
Informations sur le point de terminaison.
Obtenir des informations sur le point de terminaison déployé.
Cet endpoint n’est disponible que sur les endpoints alimentés par Text-Generation-Inference (TGI) ou Text-Embedding-Inference (TEI).
Les endpoints alimentés par transformers renvoient une charge utile vide.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> client.get_endpoint_info()
{
'model_id': 'meta-llama/Meta-Llama-3-70B-Instruct',
'model_sha': None,
'model_dtype': 'torch.float16',
'model_device_type': 'cuda',
'model_pipeline_tag': None,
'max_concurrent_requests': 128,
'max_best_of': 2,
'max_stop_sequences': 4,
'max_input_length': 8191,
'max_total_tokens': 8192,
'waiting_served_ratio': 0.3,
'max_batch_total_tokens': 1259392,
'max_waiting_tokens': 20,
'max_batch_size': None,
'validation_workers': 32,
'max_client_batch_size': 4,
'version': '2.0.2',
'sha': 'dccab72549635c7eb5ddb17f43f0b7cdff07c214',
'docker_label': 'sha-dccab72'
}health_check
< source >( model: str | None = None ) → bool
Vérifiez l'état de santé du point de terminaison déployé.
Le contrôle d’intégrité n’est disponible qu’avec les Inference Endpoints propulsés par Text-Generation-Inference (TGI) ou Text-Embedding-Inference (TEI).
image_classification
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonefunction_to_apply: typing.Optional[ForwardRef('ImageClassificationOutputTransform')] = Nonetop_k: int | None = None ) → list[ImageClassificationOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The image to classify. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - model (
str, facultatif) — Le modèle à utiliser pour la classification d’images. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour la classification d’images sera utilisé. - function_to_apply (
"ImageClassificationOutputTransform", facultatif) — La fonction à appliquer aux sorties du modèle afin de récupérer les scores. - top_k (
int, facultatif) — Lorsqu’il est spécifié, limite la sortie aux K classes les plus probables.
Retourne
list[ImageClassificationOutputElement]
une liste d'éléments ImageClassificationOutputElement contenant l'étiquette prédite et la probabilité associée.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuez la classification d'image sur l'image donnée à l'aide du modèle spécifié.
Exemple :
>>> 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")
[ImageClassificationOutputElement(label='Blenheim spaniel', score=0.9779096841812134), ...]image_segmentation
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonemask_threshold: float | None = Noneoverlap_mask_area_threshold: float | None = Nonesubtask: typing.Optional[ForwardRef('ImageSegmentationSubtask')] = Nonethreshold: float | None = None ) → list[ImageSegmentationOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The image to segment. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - model (
str, facultatif) — Le modèle à utiliser pour la segmentation d’images. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour la segmentation d’images sera utilisé. - mask_threshold (
float, facultatif) — Seuil à utiliser pour convertir les masques prédits en valeurs binaires. - overlap_mask_area_threshold (
float, facultatif) — Seuil de chevauchement des masques pour éliminer les petits segments non connectés. - subtask (
"ImageSegmentationSubtask", facultatif) — Tâche de segmentation à effectuer, en fonction des capacités du modèle. - threshold (
float, facultatif) — Seuil de probabilité pour filtrer les masques prédits.
Retourne
list[ImageSegmentationOutputElement]
Une liste d'éléments ImageSegmentationOutputElement contenant les masques segmentés et les attributs associés.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuez la segmentation d'image sur l'image donnée à l'aide du modèle spécifié.
Vous devez avoir
PILinstallé si vous souhaitez travailler avec des images (pip install Pillow).
image_to_image
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]prompt: str | None = Nonenegative_prompt: str | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Nonemodel: str | None = Nonetarget_size: huggingface_hub.inference._generated.types.image_to_image.ImageToImageTargetSize | None = None**kwargs ) → Image
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The input image for translation. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - prompt (
str, facultatif) — Le texte de l'invite pour guider la génération de l'image. - negative_prompt (
str, facultatif) — Un prompt pour guider ce qui ne doit PAS être inclus dans la génération d’image. - num_inference_steps (
int, facultatif) — Pour les modèles de diffusion. Le nombre d’étapes de débruitage. Un plus grand nombre d’étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d’une inférence plus lente. - guidance_scale (
float, facultatif) — Pour les modèles de diffusion. Une valeur de guidance scale plus élevée encourage le modèle à générer des images étroitement liées au prompt texte, au détriment de la qualité de l'image. - model (
str, facultatif) — Le modèle à utiliser pour l'inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l'instance. Valeur par défaut : None. - target_size (
ImageToImageTargetSize, facultatif) — La taille en pixels de l'image de sortie. Ce paramètre n'est pris en charge que par certains fournisseurs et pour des modèles spécifiques. Il sera ignoré s'il n'est pas pris en charge.
Retourne
Image
L'image traduite.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuer une traduction d'image en image à l'aide d'un modèle spécifié.
Vous devez avoir
PILinstallé si vous souhaitez travailler avec des images (pip install Pillow).
image_to_text
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = None ) → ImageToTextOutput
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The input image to caption. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - model (
str, facultatif) — Le modèle à utiliser pour l'inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l'instance. Valeur par défaut : None.
Retourne
Le texte généré.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Prend une image en entrée et renvoie du texte.
Les modèles peuvent produire des sorties très différentes selon votre cas d’usage (légende d’images, reconnaissance optique de caractères (OCR), Pix2Struct, etc.). Consultez la fiche du modèle pour en savoir plus sur les spécificités d’un modèle.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.image_to_text("cat.jpg")
'a cat standing in a grassy field '
>>> client.image_to_text("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
'a dog laying on the grass next to a flower pot 'image_to_video
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Noneprompt: str | None = Nonenegative_prompt: str | None = Nonenum_frames: float | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Noneseed: int | None = Nonetarget_size: huggingface_hub.inference._generated.types.image_to_video.ImageToVideoTargetSize | None = None**kwargs ) → bytes
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The input image to generate a video from. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - model (
str, facultatif) — Le modèle à utiliser pour l'inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l'instance. Valeur par défaut : None. - prompt (
str, facultatif) — Le texte de l'invite pour guider la génération de la vidéo. - negative_prompt (
str, facultatif) — Un prompt pour guider ce qui ne doit PAS être inclus dans la génération de la vidéo. - num_frames (
float, facultatif) — Le paramètre num_frames détermine le nombre de frames vidéo générées. - num_inference_steps (
int, facultatif) — Pour les modèles de diffusion. Le nombre d’étapes de débruitage. Un plus grand nombre d’étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d’une inférence plus lente. - guidance_scale (
float, facultatif) — Pour les modèles de diffusion. Une valeur de guidance scale plus élevée encourage le modèle à générer des vidéos étroitement liées au prompt texte, au détriment de la qualité de l'image. - seed (
int, facultatif) — La graine à utiliser pour la génération de la vidéo. - target_size (
ImageToVideoTargetSize, facultatif) — La taille en pixels des images de la vidéo de sortie. - num_inference_steps (
int, facultatif) — Le nombre d’étapes de débruitage. Un plus grand nombre d’étapes de débruitage conduit généralement à une vidéo de meilleure qualité, au prix d’une inférence plus lente. - seed (
int, facultatif) — Graine pour le générateur de nombres aléatoires.
Retourne
bytes
La vidéo générée.
Générer une vidéo à partir d'une image d'entrée.
détection d'objets
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonethreshold: float | None = None ) → list[ObjectDetectionOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The image to detect objects on. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - model (
str, facultatif) — Le modèle à utiliser pour la détection d’objets. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour la détection d’objets (DETR) sera utilisé. - threshold (
float, facultatif) — La probabilité nécessaire pour effectuer une prédiction.
Retourne
list[ObjectDetectionOutputElement]
Une liste d'éléments ObjectDetectionOutputElement contenant les boîtes englobantes et les attributs associés.
Lève
InferenceTimeoutError ou HfHubHTTPError ou ValueError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.ValueError— Si la sortie de la requête n'est pas une List.
Effectuez la détection d'objets sur l'image donnée à l'aide du modèle spécifié.
Vous devez avoir
PILinstallé si vous souhaitez travailler avec des images (pip install Pillow).
question_answering
< source >( question: strcontext: strmodel: str | None = Nonealign_to_words: bool | None = Nonedoc_stride: int | None = Nonehandle_impossible_answer: bool | None = Nonemax_answer_len: int | None = Nonemax_question_len: int | None = Nonemax_seq_len: int | None = Nonetop_k: int | None = None ) → Union[QuestionAnsweringOutputElement, listQuestionAnsweringOutputElement]
Paramètres
- question (
str) — Question à laquelle il faut répondre. - context (
str) — Le contexte de la question. - model (
str) — Le modèle à utiliser pour la tâche de question-réponse. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. - align_to_words (
bool, facultatif) — Tente d’aligner la réponse sur des mots réels. Améliore la qualité pour les langues séparées par des espaces. Peut nuire aux langues non séparées par des espaces (comme le japonais ou le chinois) - doc_stride (
int, facultatif) — Si le contexte est trop long pour s’insérer avec la question pour le modèle, il sera divisé en plusieurs fragments avec un certain chevauchement. Cet argument contrôle la taille de ce chevauchement. - handle_impossible_answer (
bool, facultatif) — Indique s'il faut accepter « impossible » comme réponse. - max_answer_len (
int, facultatif) — La longueur maximale des réponses prédites (par exemple, seules les réponses d’une longueur inférieure sont prises en compte). - max_question_len (
int, facultatif) — La longueur maximale de la question après tokenisation. Elle sera tronquée si nécessaire. - max_seq_len (
int, facultatif) — La longueur maximale de la phrase totale (contexte + question) en jetons de chaque fragment transmis au modèle. Le contexte sera divisé en plusieurs fragments (en utilisant docStride comme chevauchement) si nécessaire. - top_k (
int, facultatif) — Le nombre de réponses à retourner (choisies par ordre de probabilité). Notez que nous retournons moins de réponses que top_k s'il n'y a pas suffisamment d'options disponibles dans le contexte.
Retourne
Union[QuestionAnsweringOutputElement, listQuestionAnsweringOutputElement]
When top_k is 1 or not provided, it returns a single QuestionAnsweringOutputElement.
When top_k is greater than 1, it returns a list of QuestionAnsweringOutputElement.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Récupérer la réponse à une question à partir d'un texte donné.
sentence_similarity
< source >( sentence: strother_sentences: listmodel: str | None = None ) → list[float]
Paramètres
- sentence (
str) — La phrase principale à comparer aux autres. - other_sentences (
list[str]) — La liste de phrases à comparer. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de similarité de phrases. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de similarité de phrases recommandé par défaut sera utilisé. Valeur par défaut : None.
Retourne
list[float]
L'embedding représentant le texte d'entrée.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Calculer la similarité sémantique entre une phrase et une liste d'autres phrases en comparant leurs embeddings.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.sentence_similarity(
... "Machine learning is so easy.",
... other_sentences=[
... "Deep learning is so straightforward.",
... "This is so difficult, like rocket science.",
... "I can't believe how much I struggled with this.",
... ],
... )
[0.7785726189613342, 0.45876261591911316, 0.2906220555305481]résumé
< source >( text: strmodel: str | None = Noneclean_up_tokenization_spaces: bool | None = Nonegenerate_parameters: dict[str, typing.Any] | None = Nonetruncation: typing.Optional[ForwardRef('SummarizationTruncationStrategy')] = None ) → SummarizationOutput
Paramètres
- text (
str) — Le texte d'entrée à résumer. - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour la résumation sera utilisé. - clean_up_tokenization_spaces (
bool, facultatif) — Indique s'il faut nettoyer les espaces supplémentaires potentiels dans la sortie texte. - generate_parameters (
dict[str, Any], facultatif) — Paramétrage supplémentaire de l'algorithme de génération de texte. - truncation (
"SummarizationTruncationStrategy", facultatif) — La stratégie de troncature à utiliser.
Retourne
Le texte de résumé généré.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Générer un résumé d'un texte donné à l'aide d'un modèle spécifié.
table_question_answering
< source >( table: dictquery: strmodel: str | None = Nonepadding: typing.Optional[ForwardRef('Padding')] = Nonesequential: bool | None = Nonetruncation: bool | None = None ) → TableQuestionAnsweringOutputElement
Paramètres
- table (
str) — Un tableau de données représenté sous forme de dictionnaire de listes, où les entrées sont les en-têtes et les listes contiennent toutes les valeurs. Toutes les listes doivent avoir la même taille. - query (
str) — La requête en texte brut que vous souhaitez poser à la table. - model (
str) — Le modèle à utiliser pour la tâche de question-réponse sur table. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. - padding (
"Padding", facultatif) — Active et contrôle le bourrage. - sequential (
bool, facultatif) — Indique s'il faut effectuer l'inférence de manière séquentielle ou par lots. Le traitement par lots est plus rapide, mais des modèles comme SQA exigent que l'inférence soit réalisée séquentiellement afin d'extraire les relations au sein des séquences, compte tenu de leur nature conversationnelle. - truncation (
bool, facultatif) — Active et contrôle la troncature.
Retourne
une sortie de question-réponse sur table contenant la réponse, les coordonnées, les cellules et l'agrégateur utilisé.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Récupérer la réponse à une question à partir d'informations fournies dans un tableau.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> query = "How many stars does the transformers repository have?"
>>> table = {"Repository": ["Transformers", "Datasets", "Tokenizers"], "Stars": ["36542", "4512", "3934"]}
>>> client.table_question_answering(table, query, model="google/tapas-base-finetuned-wtq")
TableQuestionAnsweringOutputElement(answer='36542', coordinates=[[0, 1]], cells=['36542'], aggregator='AVERAGE')classification_tabulaire
< source >( table: dictmodel: str | None = None ) → List
Paramètres
- table (
dict[str, Any]) — Ensemble d'attributs à classifier. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de classification tabulaire. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de classification tabulaire recommandé par défaut sera utilisé. Valeur par défaut : None.
Retourne
List
une liste d'étiquettes, une par ligne dans le tableau initial.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Classer une catégorie cible (un groupe) sur la base d'un ensemble d'attributs.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> table = {
... "fixed_acidity": ["7.4", "7.8", "10.3"],
... "volatile_acidity": ["0.7", "0.88", "0.32"],
... "citric_acid": ["0", "0", "0.45"],
... "residual_sugar": ["1.9", "2.6", "6.4"],
... "chlorides": ["0.076", "0.098", "0.073"],
... "free_sulfur_dioxide": ["11", "25", "5"],
... "total_sulfur_dioxide": ["34", "67", "13"],
... "density": ["0.9978", "0.9968", "0.9976"],
... "pH": ["3.51", "3.2", "3.23"],
... "sulphates": ["0.56", "0.68", "0.82"],
... "alcohol": ["9.4", "9.8", "12.6"],
... }
>>> client.tabular_classification(table=table, model="julien-c/wine-quality")
["5", "5", "5"]tabular_regression
< source >( table: dictmodel: str | None = None ) → List
Paramètres
- table (
dict[str, Any]) — Ensemble d'attributs stockés dans une table. Les attributs utilisés pour prédire la cible peuvent être numériques et catégoriels. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de régression tabulaire. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de régression tabulaire recommandé par défaut sera utilisé. Valeur par défaut : None.
Retourne
List
une liste de valeurs numériques cibles prédites.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Prédire une valeur cible numérique à partir d'un ensemble d'attributs/variables dans un tableau.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> table = {
... "Height": ["11.52", "12.48", "12.3778"],
... "Length1": ["23.2", "24", "23.9"],
... "Length2": ["25.4", "26.3", "26.5"],
... "Length3": ["30", "31.2", "31.1"],
... "Species": ["Bream", "Bream", "Bream"],
... "Width": ["4.02", "4.3056", "4.6961"],
... }
>>> client.tabular_regression(table, model="scikit-learn/Fish-Weight")
[110, 120, 130]classification de texte
< source >( text: strmodel: str | None = Nonetop_k: int | None = Nonefunction_to_apply: typing.Optional[ForwardRef('TextClassificationOutputTransform')] = None ) → list[TextClassificationOutputElement]
Paramètres
- text (
str) — Une chaîne de caractères à classifier. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de classification de texte. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de classification de texte recommandé par défaut sera utilisé. Valeur par défaut : None. - top_k (
int, facultatif) — Lorsqu’il est spécifié, limite la sortie aux K classes les plus probables. - function_to_apply (
"TextClassificationOutputTransform", facultatif) — La fonction à appliquer aux sorties du modèle afin de récupérer les scores.
Retourne
list[TextClassificationOutputElement]
une liste d'éléments TextClassificationOutputElement contenant l'étiquette prédite et la probabilité associée.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuer une classification de texte (par exemple, une analyse de sentiments) sur le texte donné.
text_generation
< source >( prompt: strdetails: bool | None = Nonestream: bool | None = Nonemodel: str | None = Noneadapter_id: str | None = Nonebest_of: int | None = Nonedecoder_input_details: bool | None = Nonedo_sample: bool | None = Nonefrequency_penalty: float | None = Nonegrammar: huggingface_hub.inference._generated.types.text_generation.TextGenerationInputGrammarType | None = Nonemax_new_tokens: int | None = Nonerepetition_penalty: float | None = Nonereturn_full_text: bool | None = Noneseed: int | None = Nonestop: list[str] | None = Nonetemperature: float | None = Nonetop_k: int | None = Nonetop_n_tokens: int | None = Nonetop_p: float | None = Nonetruncate: int | None = Nonetypical_p: float | None = Nonewatermark: bool | None = None ) → Union[str, TextGenerationOutput, Iterable[str], Iterable[TextGenerationStreamOutput]]
Paramètres
- prompt (
str) — Texte d'entrée. - details (
bool, facultatif) — Par défaut, text_generation renvoie une chaîne de caractères. Passezdetails=Truesi vous souhaitez une sortie détaillée (jetons, probabilités, graine, raison de fin, etc.). Disponible uniquement pour les modèles exécutés avec le backendtext-generation-inference. - stream (
bool, facultatif) — Par défaut, text_generation renvoie le texte généré complet. Passezstream=Truesi vous souhaitez qu'un flux de jetons soit renvoyé. Disponible uniquement pour les modèles exécutés avec le backendtext-generation-inference. - model (
str, facultatif) — Le modèle à utiliser pour l'inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l'instance. Valeur par défaut : None. - adapter_id (
str, facultatif) — Identifiant de l'adaptateur Lora. - best_of (
int, facultatif) — Génère best_of séquences et renvoie celle qui a les logprobs de jetons les plus élevés. - decoder_input_details (
bool, facultatif) — Retourne les logprobs et les identifiants des jetons d’entrée du décodeur. Vous devez également définirdetails=Truepour que cela soit pris en compte. La valeur par défaut estFalse. - do_sample (
bool, facultatif) — Active l'échantillonnage des logits - frequency_penalty (
float, facultatif) — Nombre compris entre -2,0 et 2,0. Les valeurs positives pénalisent les nouveaux jetons en fonction de leur fréquence existante dans le texte jusqu’à présent, réduisant ainsi la probabilité pour le modèle de répéter la même ligne à l’identique. - grammar (TextGenerationInputGrammarType, facultatif) — Contraintes de grammaire. Peut être un JSONSchema ou une expression régulière.
- max_new_tokens (
int, facultatif) — Nombre maximal de jetons générés. Valeur par défaut : 100. - repetition_penalty (
float, facultatif) — Le paramètre de pénalité de répétition. 1.0 signifie qu’il n’y a pas de pénalité. Voir ce papier pour plus de détails. - return_full_text (
bool, facultatif) — Indique s'il faut préfixer le texte généré par le prompt - seed (
int, facultatif) — Graine d'échantillonnage aléatoire - stop (
list[str], facultatif) — Arrêter la génération de jetons si un membre destopest généré. - temperature (
float, facultatif) — La valeur utilisée pour moduler la distribution des logits. - top_n_tokens (
int, facultatif) — Retourne des informations sur lestop_n_tokensjetons les plus probables à chaque étape de génération, au lieu de seulement le jeton échantillonné. - top_k (
int, *facultatif`) — Le nombre de jetons du vocabulaire ayant la plus haute probabilité à conserver pour le filtrage top-k. - top_p (
float, *optional) -- If set to < 1, only the smallest set of most probable tokens with probabilities that add up totop_p` or higher are kept for generation. - truncate (
int, *facultatif`) — Tronque les jetons d'entrée à la taille donnée. - typical_p (
float, *facultatif`) — Masse du Typical Decoding Voir Typical Decoding for Natural Language Generation pour plus d’informations - watermark (
bool, facultatif) — Filigrane avec A Watermark for Large Language Models
Retourne
Union[str, TextGenerationOutput, Iterable[str], Iterable[TextGenerationStreamOutput]]
Texte généré renvoyé par le serveur :
- si
stream=Falseetdetails=False, le texte généré est renvoyé sous forme destr(par défaut) - si
stream=Trueetdetails=False, le texte généré est renvoyé jeton par jeton en tant qu'Iterable[str] - si
stream=Falseetdetails=True, le texte généré est renvoyé avec plus de détails sous forme de TextGenerationOutput - si
details=Trueetstream=True, le texte généré est renvoyé jeton par jeton sous forme d'un itérable de TextGenerationStreamOutput
Lève
ValidationError ou InferenceTimeoutError ou HfHubHTTPError
ValidationError— Si les valeurs d'entrée ne sont pas valides. Aucun appel HTTP n'est effectué vers le serveur.- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
À partir d'un prompt, générez le texte suivant.
Si vous souhaitez générer une réponse à partir de messages de chat, vous devez utiliser la méthode InferenceClient.chat_completion(). Elle accepte une liste de messages au lieu d'un simple prompt de texte et gère le templating de chat pour vous.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
# Case 1: generate text
>>> client.text_generation("The huggingface_hub library is ", max_new_tokens=12)
'100% open source and built to be easy to use.'
# Case 2: iterate over the generated tokens. Useful for large generation.
>>> for token in client.text_generation("The huggingface_hub library is ", max_new_tokens=12, stream=True):
... print(token)
100
%
open
source
and
built
to
be
easy
to
use
.
# Case 3: get more details about the generation process.
>>> client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True)
TextGenerationOutput(
generated_text='100% open source and built to be easy to use.',
details=TextGenerationDetails(
finish_reason='length',
generated_tokens=12,
seed=None,
prefill=[
TextGenerationPrefillOutputToken(id=487, text='The', logprob=None),
TextGenerationPrefillOutputToken(id=53789, text=' hugging', logprob=-13.171875),
(...)
TextGenerationPrefillOutputToken(id=204, text=' ', logprob=-7.0390625)
],
tokens=[
TokenElement(id=1425, text='100', logprob=-1.0175781, special=False),
TokenElement(id=16, text='%', logprob=-0.0463562, special=False),
(...)
TokenElement(id=25, text='.', logprob=-0.5703125, special=False)
],
best_of_sequences=None
)
)
# Case 4: iterate over the generated tokens with more details.
# Last object is more complete, containing the full generated text and the finish reason.
>>> for details in client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True, stream=True):
... print(details)
...
TextGenerationStreamOutput(token=TokenElement(id=1425, text='100', logprob=-1.0175781, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=16, text='%', logprob=-0.0463562, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=1314, text=' open', logprob=-1.3359375, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=3178, text=' source', logprob=-0.28100586, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=273, text=' and', logprob=-0.5961914, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=3426, text=' built', logprob=-1.9423828, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-1.4121094, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=314, text=' be', logprob=-1.5224609, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=1833, text=' easy', logprob=-2.1132812, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-0.08520508, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=745, text=' use', logprob=-0.39453125, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(
id=25,
text='.',
logprob=-0.5703125,
special=False),
generated_text='100% open source and built to be easy to use.',
details=TextGenerationStreamOutputStreamDetails(finish_reason='length', generated_tokens=12, seed=None)
)
# Case 5: generate constrained output using grammar
>>> response = client.text_generation(
... prompt="I saw a puppy a cat and a raccoon during my bike ride in the park",
... model="HuggingFaceH4/zephyr-orpo-141b-A35b-v0.1",
... max_new_tokens=100,
... repetition_penalty=1.3,
... grammar={
... "type": "json",
... "value": {
... "properties": {
... "location": {"type": "string"},
... "activity": {"type": "string"},
... "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5},
... "animals": {"type": "array", "items": {"type": "string"}},
... },
... "required": ["location", "activity", "animals_seen", "animals"],
... },
... },
... )
>>> json.loads(response)
{
"activity": "bike riding",
"animals": ["puppy", "cat", "raccoon"],
"animals_seen": 3,
"location": "park"
}text_to_image
< source >( prompt: strnegative_prompt: str | None = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Nonemodel: str | None = Nonescheduler: str | None = Noneseed: int | None = Noneextra_body: dict[str, typing.Any] | None = None ) → Image
Paramètres
- prompt (
str) — Le prompt à partir duquel générer une image. - negative_prompt (
str, facultatif) — Un prompt pour guider ce qui ne doit PAS être inclus dans la génération d’image. - height (
int, facultatif) — La hauteur en pixels de l'image de sortie - width (
int, facultatif) — La largeur en pixels de l'image de sortie - num_inference_steps (
int, facultatif) — Le nombre d’étapes de débruitage. Un plus grand nombre d’étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d’une inférence plus lente. - guidance_scale (
float, facultatif) — Une valeur de guidance scale plus élevée encourage le modèle à générer des images étroitement liées au prompt de texte, mais des valeurs trop élevées peuvent provoquer une saturation et d'autres artefacts. - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle texte-vers-image recommandé par défaut sera utilisé. Valeur par défaut : None. - scheduler (
str, facultatif) — Remplace le planificateur par un planificateur compatible. - seed (
int, facultatif) — Graine pour le générateur de nombres aléatoires. - extra_body (
dict[str, Any], facultatif) — Paramètres supplémentaires spécifiques au fournisseur à transmettre au modèle. Consultez la documentation du fournisseur pour les paramètres pris en charge.
Retourne
Image
L'image générée.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Générer une image à partir d'un texte donné en utilisant un modèle spécifié.
Vous devez avoir
PILinstallé si vous souhaitez travailler avec des images (pip install Pillow).
Vous pouvez passer des paramètres spécifiques au fournisseur au modèle en utilisant l'argument
extra_body.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> image = client.text_to_image("An astronaut riding a horse on the moon.")
>>> image.save("astronaut.png")
>>> image = client.text_to_image(
... "An astronaut riding a horse on the moon.",
... negative_prompt="low resolution, blurry",
... model="stabilityai/stable-diffusion-2-1",
... )
>>> image.save("better_astronaut.png")>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="fal-ai", # Use fal.ai provider
... api_key="fal-ai-api-key", # Pass your fal.ai API key
... )
>>> image = client.text_to_image(
... "A majestic lion in a fantasy forest",
... model="black-forest-labs/FLUX.1-schnell",
... )
>>> image.save("lion.png")Exemple d'utilisation d'un fournisseur tiers via Hugging Face Routing. L'utilisation sera facturée sur votre compte Hugging Face.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate", # Use replicate provider
... api_key="hf_...", # Pass your HF token
... )
>>> image = client.text_to_image(
... "An astronaut riding a horse on the moon.",
... model="black-forest-labs/FLUX.1-dev",
... )
>>> image.save("astronaut.png")Exemple d'utilisation du fournisseur Replicate avec des paramètres supplémentaires
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate", # Use replicate provider
... api_key="hf_...", # Pass your HF token
... )
>>> image = client.text_to_image(
... "An astronaut riding a horse on the moon.",
... model="black-forest-labs/FLUX.1-schnell",
... extra_body={"output_quality": 100},
... )
>>> image.save("astronaut.png")text_to_speech
< source >( text: strmodel: str | None = Nonedo_sample: bool | None = Noneearly_stopping: typing.Union[bool, ForwardRef('TextToSpeechEarlyStoppingEnum'), NoneType] = Noneepsilon_cutoff: float | None = Noneeta_cutoff: float | None = Nonemax_length: int | None = Nonemax_new_tokens: int | None = Nonemin_length: int | None = Nonemin_new_tokens: int | None = Nonenum_beam_groups: int | None = Nonenum_beams: int | None = Nonepenalty_alpha: float | None = Nonetemperature: float | None = Nonetop_k: int | None = Nonetop_p: float | None = Nonetypical_p: float | None = Noneuse_cache: bool | None = Noneextra_body: dict[str, typing.Any] | None = None ) → bytes
Paramètres
- text (
str) — Le texte à synthétiser. - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle texte-vers-parole recommandé par défaut sera utilisé. Valeur par défaut : None. - do_sample (
bool, facultatif) — Indique s'il faut utiliser l'échantillonnage plutôt que le décodage glouton lors de la génération de nouveaux jetons. - early_stopping (
Union[bool, "TextToSpeechEarlyStoppingEnum"], facultatif) — Contrôle la condition d’arrêt pour les méthodes basées sur les faisceaux. - epsilon_cutoff (
float, facultatif) — Si défini sur un float strictement compris entre 0 et 1, seuls les jetons dont la probabilité conditionnelle est supérieure à epsilon_cutoff seront échantillonnés. Dans l’article, les valeurs suggérées vont de 3e-4 à 9e-4, en fonction de la taille du modèle. Voir Truncation Sampling as Language Model Desmoothing pour plus de détails. - eta_cutoff (
float, facultatif) — L'échantillonnage Eta est un hybride de l'échantillonnage localement typique et de l'échantillonnage epsilon. S'il est défini sur une valeur float strictement comprise entre 0 et 1, un jeton n'est pris en compte que s'il est supérieur à eta_cutoff ou à sqrt(eta_cutoff)- exp(-entropy(softmax(next_token_logits))). Le second terme correspond intuitivement à la probabilité attendue du jeton suivant, mise à l'échelle par sqrt(eta_cutoff). Dans l'article, les valeurs suggérées vont de 3e-4 à 2e-3, en fonction de la taille du modèle. Consultez Truncation Sampling as Language Model Desmoothing pour plus de détails.
- max_length (
int, facultatif) — La longueur maximale (en jetons) du texte généré, y compris l'entrée. - max_new_tokens (
int, facultatif) — Le nombre maximal de jetons à générer. Prend le pas sur max_length. - min_length (
int, facultatif) — La longueur minimale (en jetons) du texte généré, y compris l'entrée. - min_new_tokens (
int, facultatif) — Le nombre minimal de jetons à générer. Prend le pas sur min_length. - num_beam_groups (
int, facultatif) — Nombre de groupes dans lesquels diviser num_beams afin d’assurer la diversité entre les différents groupes de beams. Voir cet article pour plus de détails. - num_beams (
int, facultatif) — Nombre de faisceaux à utiliser pour la recherche par faisceaux. - penalty_alpha (
float, facultatif) — La valeur équilibre la confiance du modèle et la pénalité de dégénérescence dans le décodage par recherche contrastive. - temperature (
float, facultatif) — La valeur utilisée pour moduler les probabilités du jeton suivant. - top_k (
int, facultatif) — Le nombre de jetons du vocabulaire ayant la plus haute probabilité à conserver pour le filtrage top-k. - top_p (
float, facultatif) — Si défini sur un float < 1, seul l’ensemble minimal de jetons les plus probables, dont les probabilités cumulées atteignent top_p ou plus, est conservé pour la génération. - typical_p (
float, facultatif) — La mesure de typicalité locale évalue à quel point la probabilité conditionnelle de prédire le jeton cible suivant est proche de la probabilité conditionnelle attendue de prédire un jeton aléatoire suivant, étant donné le texte partiel déjà généré. Si définie sur une valeur float < 1, l’ensemble le plus restreint de jetons les plus localement typiques, dont les probabilités cumulées atteignent ou dépassent typical_p, est conservé pour la génération. Consultez cet article pour plus de détails. - use_cache (
bool, facultatif) — Indique si le modèle doit utiliser les attentions clés/valeurs passées pour accélérer le décodage - extra_body (
dict[str, Any], facultatif) — Paramètres supplémentaires spécifiques au fournisseur à transmettre au modèle. Consultez la documentation du fournisseur pour les paramètres pris en charge.
Retourne
bytes
L'audio généré.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Synthétiser un audio d'une voix prononçant un texte donné.
Vous pouvez passer des paramètres spécifiques au fournisseur au modèle en utilisant l'argument
extra_body.
Exemple :
>>> from pathlib import Path
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> audio = client.text_to_speech("Hello world")
>>> Path("hello_world.flac").write_bytes(audio)Exemple d'utilisation d'un fournisseur tiers directement. L'utilisation sera facturée sur votre compte Replicate.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate",
... api_key="your-replicate-api-key", # Pass your Replicate API key directly
... )
>>> audio = client.text_to_speech(
... text="Hello world",
... model="OuteAI/OuteTTS-0.3-500M",
... )
>>> Path("hello_world.flac").write_bytes(audio)Exemple d'utilisation d'un fournisseur tiers via Hugging Face Routing. L'utilisation sera facturée sur votre compte Hugging Face.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate",
... api_key="hf_...", # Pass your HF token
... )
>>> audio =client.text_to_speech(
... text="Hello world",
... model="OuteAI/OuteTTS-0.3-500M",
... )
>>> Path("hello_world.flac").write_bytes(audio)>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate", # Use replicate provider
... api_key="hf_...", # Pass your HF token
... )
>>> audio = client.text_to_speech(
... "Hello, my name is Kororo, an awesome text-to-speech model.",
... model="hexgrad/Kokoro-82M",
... extra_body={"voice": "af_nicole"},
... )
>>> Path("hello.flac").write_bytes(audio)Exemple de génération musicale avec « YuE-s1-7B-anneal-en-cot » sur fal.ai
>>> from huggingface_hub import InferenceClient
>>> lyrics = '''
... [verse]
... In the town where I was born
... Lived a man who sailed to sea
... And he told us of his life
... In the land of submarines
... So we sailed on to the sun
... 'Til we found a sea of green
... And we lived beneath the waves
... In our yellow submarine
... [chorus]
... We all live in a yellow submarine
... Yellow submarine, yellow submarine
... We all live in a yellow submarine
... Yellow submarine, yellow submarine
... '''
>>> genres = "pavarotti-style tenor voice"
>>> client = InferenceClient(
... provider="fal-ai",
... model="m-a-p/YuE-s1-7B-anneal-en-cot",
... api_key=...,
... )
>>> audio = client.text_to_speech(lyrics, extra_body={"genres": genres})
>>> with open("output.mp3", "wb") as f:
... f.write(audio)text_to_video
< source >( prompt: strmodel: str | None = Noneguidance_scale: float | None = Nonenegative_prompt: list[str] | None = Nonenum_frames: float | None = Nonenum_inference_steps: int | None = Noneseed: int | None = Noneextra_body: dict[str, typing.Any] | None = None ) → bytes
Paramètres
- prompt (
str) — Le prompt à partir duquel générer une vidéo. - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle texte-vers-vidéo recommandé par défaut sera utilisé. Valeur par défaut : None. - guidance_scale (
float, facultatif) — Une valeur de guidance scale plus élevée encourage le modèle à générer des vidéos étroitement liées au prompt texte, mais des valeurs trop élevées peuvent provoquer une saturation et d'autres artefacts. - negative_prompt (
list[str], facultatif) — Un ou plusieurs prompts pour guider ce qui ne doit PAS être inclus dans la génération de la vidéo. - num_frames (
float, facultatif) — Le paramètre num_frames détermine le nombre de frames vidéo générées. - num_inference_steps (
int, facultatif) — Le nombre d’étapes de débruitage. Un plus grand nombre d’étapes de débruitage conduit généralement à une vidéo de meilleure qualité, au prix d’une inférence plus lente. - seed (
int, facultatif) — Graine pour le générateur de nombres aléatoires. - extra_body (
dict[str, Any], facultatif) — Paramètres supplémentaires spécifiques au fournisseur à transmettre au modèle. Consultez la documentation du fournisseur pour les paramètres pris en charge.
Retourne
bytes
La vidéo générée.
Générer une vidéo à partir d'un texte donné.
Vous pouvez passer des paramètres spécifiques au fournisseur au modèle en utilisant l'argument
extra_body.
Exemple :
Exemple d'utilisation d'un fournisseur tiers directement. L'utilisation sera facturée sur votre compte fal.ai.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="fal-ai", # Using fal.ai provider
... api_key="fal-ai-api-key", # Pass your fal.ai API key
... )
>>> video = client.text_to_video(
... "A majestic lion running in a fantasy forest",
... model="tencent/HunyuanVideo",
... )
>>> with open("lion.mp4", "wb") as file:
... file.write(video)Exemple d'utilisation d'un fournisseur tiers via Hugging Face Routing. L'utilisation sera facturée sur votre compte Hugging Face.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate", # Using replicate provider
... api_key="hf_...", # Pass your HF token
... )
>>> video = client.text_to_video(
... "A cat running in a park",
... model="genmo/mochi-1-preview",
... )
>>> with open("cat.mp4", "wb") as file:
... file.write(video)token_classification
< source >( text: strmodel: str | None = Noneaggregation_strategy: typing.Optional[ForwardRef('TokenClassificationAggregationStrategy')] = Noneignore_labels: list[str] | None = Nonestride: int | None = None ) → list[TokenClassificationOutputElement]
Paramètres
- text (
str) — Une chaîne de caractères à classifier. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de classification de jetons. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de classification de jetons recommandé par défaut sera utilisé. Valeur par défaut : None. - aggregation_strategy (
"TokenClassificationAggregationStrategy", facultatif) — La stratégie utilisée pour fusionner les jetons en fonction des prédictions du modèle - ignore_labels (
list[str, facultatif) — Une liste d'étiquettes à ignorer - stride (
int, facultatif) — Le nombre de jetons superposés entre les blocs lors de la division du texte d'entrée.
Retourne
list[TokenClassificationOutputElement]
Liste d'éléments TokenClassificationOutputElement contenant le groupe d'entités, le score de confiance, le mot, l'index de début et l'index de fin.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuer la classification de jetons sur le texte donné. Utilisé généralement pour l’analyse de phrases, qu’elle soit grammaticale ou de reconnaissance d’entités nommées (NER), afin de comprendre les mots-clés contenus dans le texte.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.token_classification("My name is Sarah Jessica Parker but you can call me Jessica")
[
TokenClassificationOutputElement(
entity_group='PER',
score=0.9971321225166321,
word='Sarah Jessica Parker',
start=11,
end=31,
),
TokenClassificationOutputElement(
entity_group='PER',
score=0.9773476123809814,
word='Jessica',
start=52,
end=59,
)
]traduction
< source >( text: strmodel: str | None = Nonesrc_lang: str | None = Nonetgt_lang: str | None = Noneclean_up_tokenization_spaces: bool | None = Nonetruncation: typing.Optional[ForwardRef('TranslationTruncationStrategy')] = Nonegenerate_parameters: dict[str, typing.Any] | None = None ) → TranslationOutput
Paramètres
- text (
str) — Une chaîne de caractères à traduire. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de traduction. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de traduction recommandé par défaut sera utilisé. Valeur par défaut : None. - src_lang (
str, facultatif) — La langue source du texte. Obligatoire pour les modèles capables de traduire depuis plusieurs langues. - tgt_lang (
str, facultatif) — Langue cible de la traduction. Obligatoire pour les modèles capables de traduire vers plusieurs langues. - clean_up_tokenization_spaces (
bool, facultatif) — Indique s'il faut nettoyer les espaces supplémentaires potentiels dans la sortie texte. - truncation (
"TranslationTruncationStrategy", facultatif) — La stratégie de troncature à utiliser. - generate_parameters (
dict[str, Any], facultatif) — Paramétrage supplémentaire de l'algorithme de génération de texte.
Retourne
Le texte traduit généré.
Lève
InferenceTimeoutError ou HfHubHTTPError ou ValueError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.ValueError— Si un seul des argumentssrc_langettgt_langest fourni.
Convertir du texte d'une langue à une autre.
Consultez https://huggingface.co/tasks/translation pour plus d’informations sur la manière de choisir le meilleur modèle pour
votre cas d’usage spécifique. Les langues source et cible dépendent généralement du modèle.
Cependant, il est possible de spécifier les langues source et cible pour certains modèles. Si vous travaillez avec l’un de ces modèles,
vous pouvez utiliser les arguments src_lang et tgt_lang pour transmettre les informations pertinentes.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.translation("My name is Wolfgang and I live in Berlin")
'Mein Name ist Wolfgang und ich lebe in Berlin.'
>>> client.translation("My name is Wolfgang and I live in Berlin", model="Helsinki-NLP/opus-mt-en-fr")
TranslationOutput(translation_text='Je m'appelle Wolfgang et je vis à Berlin.')visual_question_answering
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]question: strmodel: str | None = Nonetop_k: int | None = None ) → list[VisualQuestionAnsweringOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — L’entrée visuelle pour le contexte. Elle peut être des octets bruts, un fichier image, une URL vers une image en ligne ou une image PIL. - question (
str) — Question à laquelle il faut répondre. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de question-réponse visuelle. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle de question-réponse visuelle recommandé par défaut sera utilisé. Valeur par défaut : None. - top_k (
int, facultatif) — Le nombre de réponses à retourner (choisies par ordre de probabilité). Notez que nous retournons moins de réponses que top_k s'il n'y a pas suffisamment d'options disponibles dans le contexte.
Retourne
list[VisualQuestionAnsweringOutputElement]
une liste d'éléments VisualQuestionAnsweringOutputElement contenant l'étiquette prédite et la probabilité associée.
Lève
InferenceTimeoutError ou HfHubHTTPError
InferenceTimeoutError— Si le modèle est indisponible ou si la demande expirHfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Répondre à des questions ouvertes à partir d'une image.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.visual_question_answering(
... image="https://huggingface.co/datasets/mishig/sample_images/resolve/main/tiger.jpg",
... question="What is the animal doing?"
... )
[
VisualQuestionAnsweringOutputElement(score=0.778609573841095, answer='laying down'),
VisualQuestionAnsweringOutputElement(score=0.6957435607910156, answer='sitting'),
]zero_shot_classification
< source >( text: strcandidate_labels: listmulti_label: bool | None = Falsehypothesis_template: str | None = Nonemodel: str | None = None ) → list[ZeroShotClassificationOutputElement]
Paramètres
- text (
str) — Le texte d'entrée à classifier. - candidate_labels (
list[str]) — L'ensemble des étiquettes de classes possibles pour classifier le texte. - multi_label (
bool, facultatif) — Indique si plusieurs étiquettes candidates peuvent être vraies. Si la valeur est false, les scores sont normalisés de sorte que la somme des probabilités des étiquettes pour chaque séquence soit égale à 1. Si la valeur est true, les étiquettes sont considérées comme indépendantes et les probabilités sont normalisées pour chaque candidate. - hypothesis_template (
str, facultatif) — La phrase utilisée conjointement aveccandidate_labelspour tenter la classification de texte en remplaçant le marqueur de position par les étiquettes candidates. - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l’instance. S’il n’est pas fourni, le modèle de classification zero-shot recommandé par défaut sera utilisé.
Retourne
list[ZeroShotClassificationOutputElement]
Liste d'éléments ZeroShotClassificationOutputElement contenant les étiquettes prédites et leur niveau de confiance.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Fournissez en entrée un texte et un ensemble d'étiquettes candidates pour classifier le texte d'entrée.
Exemple avec multi_label=False :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> text = (
... "A new model offers an explanation for how the Galilean satellites formed around the solar system's"
... "largest world. Konstantin Batygin did not set out to solve one of the solar system's most puzzling"
... " mysteries when he went for a run up a hill in Nice, France."
... )
>>> labels = ["space & cosmos", "scientific discovery", "microbiology", "robots", "archeology"]
>>> client.zero_shot_classification(text, labels)
[
ZeroShotClassificationOutputElement(label='scientific discovery', score=0.7961668968200684),
ZeroShotClassificationOutputElement(label='space & cosmos', score=0.18570658564567566),
ZeroShotClassificationOutputElement(label='microbiology', score=0.00730885099619627),
ZeroShotClassificationOutputElement(label='archeology', score=0.006258360575884581),
ZeroShotClassificationOutputElement(label='robots', score=0.004559356719255447),
]
>>> client.zero_shot_classification(text, labels, multi_label=True)
[
ZeroShotClassificationOutputElement(label='scientific discovery', score=0.9829297661781311),
ZeroShotClassificationOutputElement(label='space & cosmos', score=0.755190908908844),
ZeroShotClassificationOutputElement(label='microbiology', score=0.0005462635890580714),
ZeroShotClassificationOutputElement(label='archeology', score=0.00047131875180639327),
ZeroShotClassificationOutputElement(label='robots', score=0.00030448526376858354),
]Exemple avec multi_label=True et un hypothesis_template personnalisé :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.zero_shot_classification(
... text="I really like our dinner and I'm very happy. I don't like the weather though.",
... candidate_labels=["positive", "negative", "pessimistic", "optimistic"],
... multi_label=True,
... hypothesis_template="This text is {} towards the weather"
... )
[
ZeroShotClassificationOutputElement(label='negative', score=0.9231801629066467),
ZeroShotClassificationOutputElement(label='pessimistic', score=0.8760990500450134),
ZeroShotClassificationOutputElement(label='optimistic', score=0.0008674879791215062),
ZeroShotClassificationOutputElement(label='positive', score=0.0005250611575320363)
]zero_shot_image_classification
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]candidate_labels: listmodel: str | None = Nonehypothesis_template: str | None = None ) → list[ZeroShotImageClassificationOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The input image to caption. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - candidate_labels (
list[str]) — Les étiquettes candidates pour cette image - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l’instance. S’il n’est pas fourni, le modèle de classification d’images zero-shot recommandé par défaut sera utilisé. - hypothesis_template (
str, facultatif) — La phrase utilisée conjointement aveccandidate_labelspour tenter la classification d’image en remplaçant le marqueur de position par les étiquettes candidates.
Retourne
list[ZeroShotImageClassificationOutputElement]
Liste d'éléments ZeroShotImageClassificationOutputElement contenant les étiquettes prédites et leur niveau de confiance.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Fournissez une image d’entrée et des étiquettes de texte pour prédire les étiquettes de texte de l’image.
Exemple :
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.zero_shot_image_classification(
... "https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg",
... candidate_labels=["dog", "cat", "horse"],
... )
[ZeroShotImageClassificationOutputElement(label='dog', score=0.956),...]Client d'inférence asynchrone
Une version asynchrone du client est également fournie, basée sur asyncio et httpx2.
classe huggingface_hub.AsyncInferenceClient
< source >( model: str | None = Noneprovider: typing.Union[typing.Literal['baseten', 'cerebras', 'cohere', 'deepinfra', 'fal-ai', 'featherless-ai', 'fireworks-ai', 'groq', 'hf-inference', 'novita', 'nscale', 'openai', 'ovhcloud', 'publicai', 'replicate', 'scaleway', 'together', 'wavespeed', 'zai-org'], typing.Literal['auto'], NoneType] = Nonetoken: str | None = Nonetimeout: float | None = Noneheaders: dict[str, str] | None = Nonecookies: dict[str, str] | None = Nonebill_to: str | None = Nonebase_url: str | None = Noneapi_key: str | None = None )
Paramètres
- model (
str,optional) — The model to run inference with. Can be a model id hosted on the Hugging Face Hub, e.g.meta-llama/Meta-Llama-3-8B-Instructor a URL to a deployed Inference Endpoint. Defaults to None, in which case a recommended model is automatically selected for the task. Note: for better compatibility with OpenAI’s client,modelhas been aliased asbase_url. Those 2 arguments are mutually exclusive. If a URL is passed asmodelorbase_urlfor chat completion, the(/v1)/chat/completionssuffix path will be appended to the URL. - provider (
str, facultatif) — Nom du fournisseur à utiliser pour l’inférence. Peut être"baseten","cerebras","cohere","deepinfra","fal-ai","featherless-ai","fireworks-ai","groq","hf-inference","novita","nscale","openai","ovhcloud","publicai","replicate","scaleway","together","wavespeed"ou"zai-org". Valeur par défaut : « auto » : routage automatique, qui privilégie par défaut le fournisseur « fastest » ; vous pouvez passer à l’ordre « cheapest » ou « preferred » sur https://hf.co/settings/inference-providers. Si model est une URL ou sibase_urlest transmis, alorsprovidern’est pas utilisé. - token (
str, facultatif) — Jeton Hugging Face. Par défaut, le jeton enregistré localement est utilisé s’aucun n’est fourni. Remarque : pour une meilleure compatibilité avec le client OpenAI,tokena été aliasé enapi_key. Ces deux arguments sont mutuellement exclusifs et ont exactement le même comportement. - timeout (
float,optional) — Nombre maximal de secondes à attendre une réponse du serveur. La valeur par défaut est None, ce qui signifie qu'il bouclera jusqu'à ce que le serveur soit disponible. - headers (
dict[str, str],optional) — En-têtes supplémentaires à envoyer au serveur. Par défaut, seuls les en-têtes d'autorisation et user-agent sont envoyés. Les valeurs de ce dictionnaire remplacent les valeurs par défaut. - bill_to (
str,optional) — Le compte de facturation à utiliser pour les requêtes. Par défaut, les requêtes sont facturées sur le compte de l’utilisateur. Les requêtes ne peuvent être facturées qu’à une organisation dont l’utilisateur est membre et qui a souscrit à Enterprise Hub. - cookies (
dict[str, str],optional) — Cookies supplémentaires à envoyer au serveur. - base_url (
str,optional) — URL de base pour exécuter l'inférence. Cet argument est dupliqué depuismodelafin que InferenceClient suive le même schéma que le clientopenai.OpenAI. Ne peut pas être utilisé simodelest défini. Valeur par défaut : None. - api_key (
str,optional) — Jeton à utiliser pour l’authentification. Cet argument est dupliqué depuistokenafin que InferenceClient suive le même schéma que le clientopenai.OpenAI. Ne peut pas être utilisé sitokenest défini. Valeur par défaut : None.
Initialiser un nouveau client d'inférence.
InferenceClient vise à offrir une expérience unifiée pour effectuer de l’inférence. Le client peut être utilisé de manière transparente avec l’API d’inférence (gratuite), les Inference Endpoints auto-hébergés ou des Inference Providers tiers.
audio_classification
< source >( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonetop_k: int | None = Nonefunction_to_apply: typing.Optional[ForwardRef('AudioClassificationOutputTransform')] = None ) → list[AudioClassificationOutputElement]
Paramètres
- audio (Union[str, Path, bytes, BinaryIO]) — Le contenu audio à classifier. Il peut s’agir de données audio brutes, d’un fichier audio local ou d’une URL pointant vers un fichier audio.
- model (
str, facultatif) — Le modèle à utiliser pour la classification audio. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour la classification audio sera utilisé. - top_k (
int, facultatif) — Lorsqu’il est spécifié, limite la sortie aux K classes les plus probables. - function_to_apply (
"AudioClassificationOutputTransform", facultatif) — La fonction à appliquer aux sorties du modèle afin de récupérer les scores.
Retourne
list[AudioClassificationOutputElement]
Liste d'éléments AudioClassificationOutputElement contenant les étiquettes prédites et leur confiance.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuez la classification audio sur le contenu audio fourni.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.audio_classification("audio.flac")
[
AudioClassificationOutputElement(score=0.4976358711719513, label='hap'),
AudioClassificationOutputElement(score=0.3677836060523987, label='neu'),
...
]audio_to_audio
< source >( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = None ) → list[AudioToAudioOutputElement]
Paramètres
- audio (Union[str, Path, bytes, BinaryIO]) — Le contenu audio pour le modèle. Il peut s’agir d’octets audio bruts, d’un fichier audio local ou d’une URL pointant vers un fichier audio.
- model (
str, facultatif) — Le modèle peut être n’importe quel modèle qui prend un fichier audio en entrée et renvoie un autre fichier audio. Il peut s’agir d’un identifiant de modèle hébergé sur le Hugging Face Hub ou d’une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour audio_to_audio sera utilisé.
Retourne
list[AudioToAudioOutputElement]
Une liste d'éléments AudioToAudioOutputElement contenant l'étiquette audio, le type de contenu et le contenu audio au format blob.
Lève
InferenceTimeoutError ou HfHubHTTPError
InferenceTimeoutError— Si le modèle est indisponible ou si la demande expirHfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectue plusieurs tâches liées à l'audio-vers-audio en fonction du modèle (par exemple : amélioration de la parole, séparation des sources).
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> audio_output = await client.audio_to_audio("audio.flac")
>>> async for i, item in enumerate(audio_output):
>>> with open(f"output_{i}.flac", "wb") as f:
f.write(item.blob)automatic_speech_recognition
< source >( audio: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Noneextra_body: dict | None = None ) → AutomaticSpeechRecognitionOutput
Paramètres
- audio (Union[str, Path, bytes, BinaryIO]) — Le contenu à transcrire. Il peut s'agir d'octets audio bruts, d'un fichier audio local ou d'une URL vers un fichier audio.
- model (
str, facultatif) — Le modèle à utiliser pour l’ASR. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour l’ASR sera utilisé. - extra_body (
dict, facultatif) — Paramètres supplémentaires spécifiques au fournisseur à transmettre au modèle. Consultez la documentation du fournisseur pour les paramètres pris en charge.
Retourne
Un élément contenant le texte transcrit et, le cas échéant, les segments horodatés.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuer la reconnaissance automatique de la parole (ASR ou audio-vers-texte) sur le contenu audio fourni.
chat_completion
< source >( messages: listmodel: str | None = Nonestream: bool = Falsefrequency_penalty: float | None = Nonelogit_bias: list[float] | None = Nonelogprobs: bool | None = Nonemax_tokens: int | None = Nonen: int | None = Nonepresence_penalty: float | None = Noneresponse_format: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatText, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONSchema, huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputResponseFormatJSONObject, NoneType] = Noneseed: int | None = Nonestop: list[str] | None = Nonestream_options: huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputStreamOptions | None = Nonetemperature: float | None = Nonetool_choice: typing.Union[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputToolChoiceClass, ForwardRef('ChatCompletionInputToolChoiceEnum'), NoneType] = Nonetool_prompt: str | None = Nonetools: list[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputTool] | None = Nonetop_logprobs: int | None = Nonetop_p: float | None = Noneextra_body: dict | None = None ) → ChatCompletionOutput or Iterable of ChatCompletionStreamOutput
Paramètres
- messages (Liste de ChatCompletionInputMessage) — Historique de la conversation composé de paires de rôles et de contenu.
- model (
str, facultatif) — Le modèle à utiliser pour la complétion de chat. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle recommandé par défaut pour la génération de texte basée sur le chat sera utilisé. Voir https://huggingface.co/tasks/text-generation pour plus de détails. Simodelest un identifiant de modèle, il est transmis au serveur en tant que paramètremodel. Si vous souhaitez définir une URL personnalisée tout en définissantmodeldans la charge utile de la requête, vous devez définirbase_urllors de l'initialisation de InferenceClient. - frequency_penalty (
float, facultatif) — Pénalise les nouveaux jetons en fonction de leur fréquence existante dans le texte jusqu'à présent. Plage : [-2,0, 2,0]. Valeur par défaut : 0,0. - logit_bias (
list[float], facultatif) — Ajuste la probabilité d’apparition de jetons spécifiques dans la sortie générée. - logprobs (
bool, facultatif) — Indique s'il faut retourner les logarithmes des probabilités des jetons de sortie ou non. Si la valeur est true, les logarithmes des probabilités de chaque jeton de sortie sont retournés dans le contenu du message. - max_tokens (
int, facultatif) — Nombre maximal de jetons autorisés dans la réponse. Valeur par défaut : 100. - n (
int, facultatif) — Le nombre de complétions à générer pour chaque invite. - presence_penalty (
float, facultatif) — Nombre compris entre -2,0 et 2,0. Les valeurs positives pénalisent les nouveaux jetons en fonction de leur apparition dans le texte jusqu’à présent, augmentant ainsi la probabilité que le modèle aborde de nouveaux sujets. - response_format (
ChatCompletionInputGrammarType(), facultatif) — Contraintes de grammaire. Peut être un JSONSchema ou une expression régulière. - seed (Optionnel
int, optionnel) — Graine pour un flux de contrôle reproductible. Valeur par défaut : None. - stop (
list[str], facultatif) — Jusqu’à quatre chaînes de caractères qui déclenchent la fin de la réponse. Valeur par défaut : None. - stream (
bool, facultatif) — Active le streaming en temps réel des réponses. Valeur par défaut : False. - stream_options (ChatCompletionInputStreamOptions, facultatif) — Options pour les complétions en streaming.
- temperature (
float, facultatif) — Contrôle l’aléatoire des générations. Des valeurs plus faibles garantissent des complétions moins aléatoires. Intervalle : [0, 2]. Valeur par défaut : 1.0. - top_logprobs (
int, facultatif) — Un entier compris entre 0 et 5 qui spécifie le nombre de jetons les plus probables à retourner à chaque position de jeton, chacun avec une probabilité logarithmique associée. logprobs doit être défini sur true si ce paramètre est utilisé. - top_p (
float, facultatif) — Fraction des mots suivants les plus probables à échantillonner. Doit être comprise entre 0 et 1. Valeur par défaut : 1.0. - tool_choice (ChatCompletionInputToolChoiceClass ou
ChatCompletionInputToolChoiceEnum(), facultatif) — L’outil à utiliser pour la complétion. La valeur par défaut est « auto ». - tool_prompt (
str, facultatif) — Un prompt à ajouter avant les outils. - tools (Liste de ChatCompletionInputTool, facultatif) — Une liste d'outils que le modèle peut appeler. Actuellement, seules les fonctions sont prises en charge en tant qu'outil. Utilisez ce paramètre pour fournir une liste de fonctions pour lesquelles le modèle peut générer des entrées JSON.
- extra_body (
dict, facultatif) — Paramètres supplémentaires spécifiques au fournisseur à transmettre au modèle. Consultez la documentation du fournisseur pour les paramètres pris en charge.
Retourne
ChatCompletionOutput ou itérable de ChatCompletionStreamOutput
Texte généré renvoyé par le serveur :
- si
stream=False, le texte généré est renvoyé sous forme de ChatCompletionOutput (par défaut). - si
stream=True, le texte généré est renvoyé jeton par jeton sous forme d'une séquence de ChatCompletionStreamOutput.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Une méthode pour compléter des conversations à l'aide d'un modèle de langage spécifié.
La méthode
client.chat_completionest aliasée enclient.chat.completions.createpour assurer la compatibilité avec le client d’OpenAI. Les entrées et les sorties sont strictement identiques et l’utilisation de l’une ou l’autre syntaxe donnera les mêmes résultats. Consultez le guide d’inférence pour plus de détails sur la compatibilité avec OpenAI.
Vous pouvez passer des paramètres spécifiques au fournisseur au modèle en utilisant l'argument
extra_body.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> messages = [{"role": "user", "content": "What is the capital of France?"}]
>>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-8B-Instruct")
>>> await 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
)
)Exemple utilisant le streaming :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> messages = [{"role": "user", "content": "What is the capital of France?"}]
>>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-8B-Instruct")
>>> async for token in await client.chat_completion(messages, max_tokens=10, stream=True):
... print(token)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content='The', role='assistant'), index=0, finish_reason=None)], created=1710498504)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' capital', role='assistant'), index=0, finish_reason=None)], created=1710498504)
(...)
ChatCompletionStreamOutput(choices=[ChatCompletionStreamOutputChoice(delta=ChatCompletionStreamOutputDelta(content=' may', role='assistant'), index=0, finish_reason=None)], created=1710498504)Exemple utilisant la syntaxe d’OpenAI :
# Must be run in an async context
# instead of `from openai import OpenAI`
from huggingface_hub import AsyncInferenceClient
# instead of `client = OpenAI(...)`
client = AsyncInferenceClient(
base_url=...,
api_key=...,
)
output = await 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)Exemple d’utilisation d’un fournisseur tiers directement avec des paramètres supplémentaires (spécifiques au fournisseur). L’utilisation sera facturée sur votre compte Together AI.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="together", # Use Together AI provider
... api_key="<together_api_key>", # Pass your Together API key directly
... )
>>> client.chat_completion(
... model="meta-llama/Meta-Llama-3-8B-Instruct",
... messages=[{"role": "user", "content": "What is the capital of France?"}],
... extra_body={"safety_model": "Meta-Llama/Llama-Guard-7b"},
... )Exemple d'utilisation d'un fournisseur tiers via Hugging Face Routing. L'utilisation sera facturée sur votre compte Hugging Face.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="novita", # Use Novita provider
... api_key="hf_...", # Pass your HF token
... )
>>> client.chat_completion(
... model="meta-llama/Meta-Llama-3-8B-Instruct",
... messages=[{"role": "user", "content": "What is the capital of France?"}],
... )Exemple utilisant Image + Texte en entrée :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
# provide a remote URL
>>> image_url ="https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
# or a base64-encoded image
>>> image_path = "/path/to/image.jpeg"
>>> with open(image_path, "rb") as f:
... base64_image = base64.b64encode(f.read()).decode("utf-8")
>>> image_url = f"data:image/jpeg;base64,{base64_image}"
>>> client = AsyncInferenceClient("meta-llama/Llama-3.2-11B-Vision-Instruct")
>>> output = await client.chat.completions.create(
... messages=[
... {
... "role": "user",
... "content": [
... {
... "type": "image_url",
... "image_url": {"url": image_url},
... },
... {
... "type": "text",
... "text": "Describe this image in one sentence.",
... },
... ],
... },
... ],
... )
>>> output
The image depicts the iconic Statue of Liberty situated in New York Harbor, New York, on a clear day.Exemple utilisant des outils :
# Must be run in an async context
>>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> messages = [
... {
... "role": "system",
... "content": "Don't make assumptions about what values to plug into functions. Ask for clarification if a user request is ambiguous.",
... },
... {
... "role": "user",
... "content": "What's the weather like the next 3 days in San Francisco, CA?",
... },
... ]
>>> tools = [
... {
... "type": "function",
... "function": {
... "name": "get_current_weather",
... "description": "Get the current weather",
... "parameters": {
... "type": "object",
... "properties": {
... "location": {
... "type": "string",
... "description": "The city and state, e.g. San Francisco, CA",
... },
... "format": {
... "type": "string",
... "enum": ["celsius", "fahrenheit"],
... "description": "The temperature unit to use. Infer this from the users location.",
... },
... },
... "required": ["location", "format"],
... },
... },
... },
... {
... "type": "function",
... "function": {
... "name": "get_n_day_weather_forecast",
... "description": "Get an N-day weather forecast",
... "parameters": {
... "type": "object",
... "properties": {
... "location": {
... "type": "string",
... "description": "The city and state, e.g. San Francisco, CA",
... },
... "format": {
... "type": "string",
... "enum": ["celsius", "fahrenheit"],
... "description": "The temperature unit to use. Infer this from the users location.",
... },
... "num_days": {
... "type": "integer",
... "description": "The number of days to forecast",
... },
... },
... "required": ["location", "format", "num_days"],
... },
... },
... },
... ]
>>> response = await client.chat_completion(
... model="meta-llama/Meta-Llama-3-70B-Instruct",
... messages=messages,
... tools=tools,
... tool_choice="auto",
... max_tokens=500,
... )
>>> response.choices[0].message.tool_calls[0].function
ChatCompletionOutputFunctionDefinition(
arguments={
'location': 'San Francisco, CA',
'format': 'fahrenheit',
'num_days': 3
},
name='get_n_day_weather_forecast',
description=None
)Exemple d'utilisation de response_format :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> messages = [
... {
... "role": "user",
... "content": "I saw a puppy a cat and a raccoon during my bike ride in the park. What did I see and when?",
... },
... ]
>>> response_format = {
... "type": "json",
... "value": {
... "properties": {
... "location": {"type": "string"},
... "activity": {"type": "string"},
... "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5},
... "animals": {"type": "array", "items": {"type": "string"}},
... },
... "required": ["location", "activity", "animals_seen", "animals"],
... },
... }
>>> response = await client.chat_completion(
... messages=messages,
... response_format=response_format,
... max_tokens=500,
... )
>>> response.choices[0].message.content
'{
y": "bike ride",
": ["puppy", "cat", "raccoon"],
_seen": 3,
n": "park"}'Fermez le client.
Cette méthode est appelée automatiquement lors de l'utilisation du client en tant que gestionnaire de contexte.
document_question_answering
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]question: strmodel: str | None = Nonedoc_stride: int | None = Nonehandle_impossible_answer: bool | None = Nonelang: str | None = Nonemax_answer_len: int | None = Nonemax_question_len: int | None = Nonemax_seq_len: int | None = Nonetop_k: int | None = Noneword_boxes: list[list[float] | str] | None = None ) → list[DocumentQuestionAnsweringOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO]) — L’image d’entrée pour le contexte. Elle peut être des octets bruts, un fichier image ou une URL vers une image en ligne. - question (
str) — Question à laquelle il faut répondre. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de question-réponse sur document. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de question-réponse sur document recommandé par défaut sera utilisé. Valeur par défaut : None. - doc_stride (
int, facultatif) — Si les mots du document sont trop longs pour s’insérer avec la question pour le modèle, il sera découpé en plusieurs fragments avec un certain chevauchement. Cet argument contrôle la taille de ce chevauchement. - handle_impossible_answer (
bool, facultatif) — Indique s'il faut accepter « impossible » comme réponse - lang (
str, facultatif) — Langue à utiliser lors de l'exécution de l'OCR. La valeur par défaut est english. - max_answer_len (
int, facultatif) — La longueur maximale des réponses prédites (par exemple, seules les réponses d’une longueur inférieure sont prises en compte). - max_question_len (
int, facultatif) — La longueur maximale de la question après tokenisation. Elle sera tronquée si nécessaire. - max_seq_len (
int, facultatif) — La longueur maximale de la phrase totale (contexte + question) en jetons de chaque fragment transmis au modèle. Le contexte sera divisé en plusieurs fragments (en utilisant doc_stride comme chevauchement) si nécessaire. - top_k (
int, facultatif) — Le nombre de réponses à retourner (sélectionnées par ordre de probabilité). Peut retourner moins de top_k réponses s'il n'y a pas suffisamment d'options disponibles dans le contexte. - word_boxes (
list[Union[list[float], str, facultatif) — Une liste de mots et de boîtes englobantes (normalisées 0->1000). Si fournie, l’inférence ignorera l’étape OCR et utilisera les boîtes englobantes fournies à la place.
Retourne
list[DocumentQuestionAnsweringOutputElement]
une liste d'éléments DocumentQuestionAnsweringOutputElement contenant l'étiquette prédite, la probabilité associée, les identifiants des mots et le numéro de page.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Répondre à des questions sur des images de documents.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.document_question_answering(image="https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png", question="What is the invoice number?")
[DocumentQuestionAnsweringOutputElement(answer='us-001', end=16, score=0.9999666213989258, start=16)]feature_extraction
< source >( text: str | list[str]normalize: bool | None = Noneprompt_name: str | None = Nonetruncate: bool | None = Nonetruncation_direction: typing.Optional[typing.Literal['left', 'right']] = Nonedimensions: int | None = Noneencoding_format: typing.Optional[typing.Literal['float', 'base64']] = Nonemodel: str | None = None ) → np.ndarray
Paramètres
- text (str ou list[str]) — Le texte ou la liste de textes à encoder.
- model (str, facultatif) — Le modèle à utiliser pour la tâche d'extraction de caractéristiques. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle d'extraction de caractéristiques recommandé par défaut sera utilisé. Valeur par défaut : None.
- normalize (bool, facultatif) — Indique s'il faut normaliser les embeddings ou non. Uniquement disponible sur les serveurs alimentés par Text-Embedding-Inference.
- prompt_name (str, facultatif) —
Le nom du prompt qui doit être utilisé pour l’encodage. S’il n’est pas défini, aucun prompt ne sera appliqué.
Doit être une clé du dictionnaire prompts de la configuration Sentence Transformers.
Par exemple, si
prompt_nameest « query » et quepromptsest {“query”: “query: ”,…}, la phrase « What is the capital of France? » sera encodée comme « query: What is the capital of France? » car le texte du prompt sera préfixé avant tout texte à encoder. - truncate (bool, facultatif) — Indique s'il faut tronquer les embeddings ou non. Uniquement disponible sur les serveurs alimentés par Text-Embedding-Inference.
- truncation_direction (Literal[“left”, “right”], facultatif) — Côté de l'entrée à tronquer lorsque truncate=True est passé.
- dimensions (int, facultatif) — Le nombre de dimensions que les embeddings de sortie résultants doivent avoir. Uniquement disponible sur les points de terminaison d'embedding compatibles OpenAI.
- encoding_format (Literal[“float”, “base64”], facultatif) — Le format des embeddings de sortie. Soit “float”, soit “base64”. Uniquement disponible sur les points de terminaison d’embedding compatibles OpenAI.
Retourne
np.ndarray
L'embedding représentant le ou les textes d'entrée sous forme de tableau numpy float32.
Lève
[InferenceTimeoutError] ou [HfHubHTTPError]
- [InferenceTimeoutError] — Si le modèle est indisponible ou si la demande expirée.
- [HfHubHTTPError] — Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Générer des embeddings pour un texte donné ou un lot de textes.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.feature_extraction("Hi, who are you?")
array([[ 2.424802 , 2.93384 , 1.1750331 , ..., 1.240499, -0.13776633, -0.7889173 ],
[-0.42943227, -0.6364878 , -1.693462 , ..., 0.41978157, -2.4336355 , 0.6162071 ],
...,
[ 0.28552425, -0.928395 , -1.2077185 , ..., 0.76810825, -2.1069427 , 0.6236161 ]], dtype=float32)fill_mask
< source >( text: strmodel: str | None = Nonetargets: list[str] | None = Nonetop_k: int | None = None ) → list[FillMaskOutputElement]
Paramètres
- text (
str) — une chaîne de caractères à compléter, doit contenir le jeton [MASK] (consultez la fiche du modèle pour le nom exact du masque). - model (
str, facultatif) — Le modèle à utiliser pour la tâche de fill mask. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de fill mask recommandé par défaut sera utilisé. - targets (
list[str, facultatif) — Lorsqu’il est fourni, le modèle limite les scores aux cibles transmises au lieu de parcourir tout le vocabulaire. Si les cibles fournies ne figurent pas dans le vocabulaire du modèle, elles sont tokenisées et le premier jeton résultant est utilisé (avec un avertissement, et cela peut être plus lent). - top_k (
int, facultatif) — Lorsqu’il est fourni, il remplace le nombre de prédictions à retourner.
Retourne
list[FillMaskOutputElement]
une liste d'éléments FillMaskOutputElement contenant l'étiquette prédite, la probabilité associée, la référence du jeton et le texte complété.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Compléter un trou avec un mot manquant (un jeton, pour être précis).
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.fill_mask("The goal of life is <mask>.")
[
FillMaskOutputElement(score=0.06897063553333282, token=11098, token_str=' happiness', sequence='The goal of life is happiness.'),
FillMaskOutputElement(score=0.06554922461509705, token=45075, token_str=' immortality', sequence='The goal of life is immortality.')
]get_endpoint_info
< source >( model: str | None = None ) → dict[str, Any]
Paramètres
- model (
str, facultatif) — Le modèle à utiliser pour l'inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l'instance. Valeur par défaut : None.
Retourne
dict[str, Any]
Informations sur le point de terminaison.
Obtenir des informations sur le point de terminaison déployé.
Cet endpoint n’est disponible que sur les endpoints alimentés par Text-Generation-Inference (TGI) ou Text-Embedding-Inference (TEI).
Les endpoints alimentés par transformers renvoient une charge utile vide.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient("meta-llama/Meta-Llama-3-70B-Instruct")
>>> await client.get_endpoint_info()
{
'model_id': 'meta-llama/Meta-Llama-3-70B-Instruct',
'model_sha': None,
'model_dtype': 'torch.float16',
'model_device_type': 'cuda',
'model_pipeline_tag': None,
'max_concurrent_requests': 128,
'max_best_of': 2,
'max_stop_sequences': 4,
'max_input_length': 8191,
'max_total_tokens': 8192,
'waiting_served_ratio': 0.3,
'max_batch_total_tokens': 1259392,
'max_waiting_tokens': 20,
'max_batch_size': None,
'validation_workers': 32,
'max_client_batch_size': 4,
'version': '2.0.2',
'sha': 'dccab72549635c7eb5ddb17f43f0b7cdff07c214',
'docker_label': 'sha-dccab72'
}health_check
< source >( model: str | None = None ) → bool
Vérifiez l'état de santé du point de terminaison déployé.
Le contrôle d’intégrité n’est disponible qu’avec les Inference Endpoints propulsés par Text-Generation-Inference (TGI) ou Text-Embedding-Inference (TEI).
image_classification
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonefunction_to_apply: typing.Optional[ForwardRef('ImageClassificationOutputTransform')] = Nonetop_k: int | None = None ) → list[ImageClassificationOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The image to classify. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - model (
str, facultatif) — Le modèle à utiliser pour la classification d’images. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour la classification d’images sera utilisé. - function_to_apply (
"ImageClassificationOutputTransform", facultatif) — La fonction à appliquer aux sorties du modèle afin de récupérer les scores. - top_k (
int, facultatif) — Lorsqu’il est spécifié, limite la sortie aux K classes les plus probables.
Retourne
list[ImageClassificationOutputElement]
une liste d'éléments ImageClassificationOutputElement contenant l'étiquette prédite et la probabilité associée.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuez la classification d'image sur l'image donnée à l'aide du modèle spécifié.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
[ImageClassificationOutputElement(label='Blenheim spaniel', score=0.9779096841812134), ...]image_segmentation
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonemask_threshold: float | None = Noneoverlap_mask_area_threshold: float | None = Nonesubtask: typing.Optional[ForwardRef('ImageSegmentationSubtask')] = Nonethreshold: float | None = None ) → list[ImageSegmentationOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The image to segment. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - model (
str, facultatif) — Le modèle à utiliser pour la segmentation d’images. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour la segmentation d’images sera utilisé. - mask_threshold (
float, facultatif) — Seuil à utiliser pour convertir les masques prédits en valeurs binaires. - overlap_mask_area_threshold (
float, facultatif) — Seuil de chevauchement des masques pour éliminer les petits segments non connectés. - subtask (
"ImageSegmentationSubtask", facultatif) — Tâche de segmentation à effectuer, en fonction des capacités du modèle. - threshold (
float, facultatif) — Seuil de probabilité pour filtrer les masques prédits.
Retourne
list[ImageSegmentationOutputElement]
Une liste d'éléments ImageSegmentationOutputElement contenant les masques segmentés et les attributs associés.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuez la segmentation d'image sur l'image donnée à l'aide du modèle spécifié.
Vous devez avoir
PILinstallé si vous souhaitez travailler avec des images (pip install Pillow).
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.image_segmentation("cat.jpg")
[ImageSegmentationOutputElement(score=0.989008, label='LABEL_184', mask=<PIL.PngImagePlugin.PngImageFile image mode=L size=400x300 at 0x7FDD2B129CC0>), ...]image_to_image
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]prompt: str | None = Nonenegative_prompt: str | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Nonemodel: str | None = Nonetarget_size: huggingface_hub.inference._generated.types.image_to_image.ImageToImageTargetSize | None = None**kwargs ) → Image
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The input image for translation. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - prompt (
str, facultatif) — Le texte de l'invite pour guider la génération de l'image. - negative_prompt (
str, facultatif) — Un prompt pour guider ce qui ne doit PAS être inclus dans la génération d’image. - num_inference_steps (
int, facultatif) — Pour les modèles de diffusion. Le nombre d’étapes de débruitage. Un plus grand nombre d’étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d’une inférence plus lente. - guidance_scale (
float, facultatif) — Pour les modèles de diffusion. Une valeur de guidance scale plus élevée encourage le modèle à générer des images étroitement liées au prompt texte, au détriment de la qualité de l'image. - model (
str, facultatif) — Le modèle à utiliser pour l'inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l'instance. Valeur par défaut : None. - target_size (
ImageToImageTargetSize, facultatif) — La taille en pixels de l'image de sortie. Ce paramètre n'est pris en charge que par certains fournisseurs et pour des modèles spécifiques. Il sera ignoré s'il n'est pas pris en charge.
Retourne
Image
L'image traduite.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuer une traduction d'image en image à l'aide d'un modèle spécifié.
Vous devez avoir
PILinstallé si vous souhaitez travailler avec des images (pip install Pillow).
image_to_text
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = None ) → ImageToTextOutput
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The input image to caption. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - model (
str, facultatif) — Le modèle à utiliser pour l'inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l'instance. Valeur par défaut : None.
Retourne
Le texte généré.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Prend une image en entrée et renvoie du texte.
Les modèles peuvent produire des sorties très différentes selon votre cas d’usage (légende d’images, reconnaissance optique de caractères (OCR), Pix2Struct, etc.). Consultez la fiche du modèle pour en savoir plus sur les spécificités d’un modèle.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.image_to_text("cat.jpg")
'a cat standing in a grassy field '
>>> await client.image_to_text("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
'a dog laying on the grass next to a flower pot 'image_to_video
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Noneprompt: str | None = Nonenegative_prompt: str | None = Nonenum_frames: float | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Noneseed: int | None = Nonetarget_size: huggingface_hub.inference._generated.types.image_to_video.ImageToVideoTargetSize | None = None**kwargs ) → bytes
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The input image to generate a video from. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - model (
str, facultatif) — Le modèle à utiliser pour l'inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l'instance. Valeur par défaut : None. - prompt (
str, facultatif) — Le texte de l'invite pour guider la génération de la vidéo. - negative_prompt (
str, facultatif) — Un prompt pour guider ce qui ne doit PAS être inclus dans la génération de la vidéo. - num_frames (
float, facultatif) — Le paramètre num_frames détermine le nombre de frames vidéo générées. - num_inference_steps (
int, facultatif) — Pour les modèles de diffusion. Le nombre d’étapes de débruitage. Un plus grand nombre d’étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d’une inférence plus lente. - guidance_scale (
float, facultatif) — Pour les modèles de diffusion. Une valeur de guidance scale plus élevée encourage le modèle à générer des vidéos étroitement liées au prompt texte, au détriment de la qualité de l'image. - seed (
int, facultatif) — La graine à utiliser pour la génération de la vidéo. - target_size (
ImageToVideoTargetSize, facultatif) — La taille en pixels des images de la vidéo de sortie. - num_inference_steps (
int, facultatif) — Le nombre d’étapes de débruitage. Un plus grand nombre d’étapes de débruitage conduit généralement à une vidéo de meilleure qualité, au prix d’une inférence plus lente. - seed (
int, facultatif) — Graine pour le générateur de nombres aléatoires.
Retourne
bytes
La vidéo générée.
Générer une vidéo à partir d'une image d'entrée.
Exemples :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> video = await client.image_to_video("cat.jpg", model="Wan-AI/Wan2.2-I2V-A14B", prompt="turn the cat into a tiger")
>>> with open("tiger.mp4", "wb") as f:
... f.write(video)détection d'objets
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]model: str | None = Nonethreshold: float | None = None ) → list[ObjectDetectionOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The image to detect objects on. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - model (
str, facultatif) — Le modèle à utiliser pour la détection d’objets. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour la détection d’objets (DETR) sera utilisé. - threshold (
float, facultatif) — La probabilité nécessaire pour effectuer une prédiction.
Retourne
list[ObjectDetectionOutputElement]
Une liste d'éléments ObjectDetectionOutputElement contenant les boîtes englobantes et les attributs associés.
Lève
InferenceTimeoutError ou HfHubHTTPError ou ValueError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.ValueError— Si la sortie de la requête n'est pas une List.
Effectuez la détection d'objets sur l'image donnée à l'aide du modèle spécifié.
Vous devez avoir
PILinstallé si vous souhaitez travailler avec des images (pip install Pillow).
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.object_detection("people.jpg")
[ObjectDetectionOutputElement(score=0.9486683011054993, label='person', box=ObjectDetectionBoundingBox(xmin=59, ymin=39, xmax=420, ymax=510)), ...]question_answering
< source >( question: strcontext: strmodel: str | None = Nonealign_to_words: bool | None = Nonedoc_stride: int | None = Nonehandle_impossible_answer: bool | None = Nonemax_answer_len: int | None = Nonemax_question_len: int | None = Nonemax_seq_len: int | None = Nonetop_k: int | None = None ) → Union[QuestionAnsweringOutputElement, listQuestionAnsweringOutputElement]
Paramètres
- question (
str) — Question à laquelle il faut répondre. - context (
str) — Le contexte de la question. - model (
str) — Le modèle à utiliser pour la tâche de question-réponse. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. - align_to_words (
bool, facultatif) — Tente d’aligner la réponse sur des mots réels. Améliore la qualité pour les langues séparées par des espaces. Peut nuire aux langues non séparées par des espaces (comme le japonais ou le chinois) - doc_stride (
int, facultatif) — Si le contexte est trop long pour s’insérer avec la question pour le modèle, il sera divisé en plusieurs fragments avec un certain chevauchement. Cet argument contrôle la taille de ce chevauchement. - handle_impossible_answer (
bool, facultatif) — Indique s'il faut accepter « impossible » comme réponse. - max_answer_len (
int, facultatif) — La longueur maximale des réponses prédites (par exemple, seules les réponses d’une longueur inférieure sont prises en compte). - max_question_len (
int, facultatif) — La longueur maximale de la question après tokenisation. Elle sera tronquée si nécessaire. - max_seq_len (
int, facultatif) — La longueur maximale de la phrase totale (contexte + question) en jetons de chaque fragment transmis au modèle. Le contexte sera divisé en plusieurs fragments (en utilisant docStride comme chevauchement) si nécessaire. - top_k (
int, facultatif) — Le nombre de réponses à retourner (choisies par ordre de probabilité). Notez que nous retournons moins de réponses que top_k s'il n'y a pas suffisamment d'options disponibles dans le contexte.
Retourne
Union[QuestionAnsweringOutputElement, listQuestionAnsweringOutputElement]
When top_k is 1 or not provided, it returns a single QuestionAnsweringOutputElement.
When top_k is greater than 1, it returns a list of QuestionAnsweringOutputElement.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Récupérer la réponse à une question à partir d'un texte donné.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.question_answering(question="What's my name?", context="My name is Clara and I live in Berkeley.")
QuestionAnsweringOutputElement(answer='Clara', end=16, score=0.9326565265655518, start=11)sentence_similarity
< source >( sentence: strother_sentences: listmodel: str | None = None ) → list[float]
Paramètres
- sentence (
str) — La phrase principale à comparer aux autres. - other_sentences (
list[str]) — La liste de phrases à comparer. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de similarité de phrases. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de similarité de phrases recommandé par défaut sera utilisé. Valeur par défaut : None.
Retourne
list[float]
L'embedding représentant le texte d'entrée.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Calculer la similarité sémantique entre une phrase et une liste d'autres phrases en comparant leurs embeddings.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.sentence_similarity(
... "Machine learning is so easy.",
... other_sentences=[
... "Deep learning is so straightforward.",
... "This is so difficult, like rocket science.",
... "I can't believe how much I struggled with this.",
... ],
... )
[0.7785726189613342, 0.45876261591911316, 0.2906220555305481]résumé
< source >( text: strmodel: str | None = Noneclean_up_tokenization_spaces: bool | None = Nonegenerate_parameters: dict[str, typing.Any] | None = Nonetruncation: typing.Optional[ForwardRef('SummarizationTruncationStrategy')] = None ) → SummarizationOutput
Paramètres
- text (
str) — Le texte d'entrée à résumer. - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle recommandé par défaut pour la résumation sera utilisé. - clean_up_tokenization_spaces (
bool, facultatif) — Indique s'il faut nettoyer les espaces supplémentaires potentiels dans la sortie texte. - generate_parameters (
dict[str, Any], facultatif) — Paramétrage supplémentaire de l'algorithme de génération de texte. - truncation (
"SummarizationTruncationStrategy", facultatif) — La stratégie de troncature à utiliser.
Retourne
Le texte de résumé généré.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Générer un résumé d'un texte donné à l'aide d'un modèle spécifié.
table_question_answering
< source >( table: dictquery: strmodel: str | None = Nonepadding: typing.Optional[ForwardRef('Padding')] = Nonesequential: bool | None = Nonetruncation: bool | None = None ) → TableQuestionAnsweringOutputElement
Paramètres
- table (
str) — Un tableau de données représenté sous forme de dictionnaire de listes, où les entrées sont les en-têtes et les listes contiennent toutes les valeurs. Toutes les listes doivent avoir la même taille. - query (
str) — La requête en texte brut que vous souhaitez poser à la table. - model (
str) — Le modèle à utiliser pour la tâche de question-réponse sur table. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. - padding (
"Padding", facultatif) — Active et contrôle le bourrage. - sequential (
bool, facultatif) — Indique s'il faut effectuer l'inférence de manière séquentielle ou par lots. Le traitement par lots est plus rapide, mais des modèles comme SQA exigent que l'inférence soit réalisée séquentiellement afin d'extraire les relations au sein des séquences, compte tenu de leur nature conversationnelle. - truncation (
bool, facultatif) — Active et contrôle la troncature.
Retourne
une sortie de question-réponse sur table contenant la réponse, les coordonnées, les cellules et l'agrégateur utilisé.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Récupérer la réponse à une question à partir d'informations fournies dans un tableau.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> query = "How many stars does the transformers repository have?"
>>> table = {"Repository": ["Transformers", "Datasets", "Tokenizers"], "Stars": ["36542", "4512", "3934"]}
>>> await client.table_question_answering(table, query, model="google/tapas-base-finetuned-wtq")
TableQuestionAnsweringOutputElement(answer='36542', coordinates=[[0, 1]], cells=['36542'], aggregator='AVERAGE')classification_tabulaire
< source >( table: dictmodel: str | None = None ) → List
Paramètres
- table (
dict[str, Any]) — Ensemble d'attributs à classifier. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de classification tabulaire. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de classification tabulaire recommandé par défaut sera utilisé. Valeur par défaut : None.
Retourne
List
une liste d'étiquettes, une par ligne dans le tableau initial.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Classer une catégorie cible (un groupe) sur la base d'un ensemble d'attributs.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> table = {
... "fixed_acidity": ["7.4", "7.8", "10.3"],
... "volatile_acidity": ["0.7", "0.88", "0.32"],
... "citric_acid": ["0", "0", "0.45"],
... "residual_sugar": ["1.9", "2.6", "6.4"],
... "chlorides": ["0.076", "0.098", "0.073"],
... "free_sulfur_dioxide": ["11", "25", "5"],
... "total_sulfur_dioxide": ["34", "67", "13"],
... "density": ["0.9978", "0.9968", "0.9976"],
... "pH": ["3.51", "3.2", "3.23"],
... "sulphates": ["0.56", "0.68", "0.82"],
... "alcohol": ["9.4", "9.8", "12.6"],
... }
>>> await client.tabular_classification(table=table, model="julien-c/wine-quality")
["5", "5", "5"]tabular_regression
< source >( table: dictmodel: str | None = None ) → List
Paramètres
- table (
dict[str, Any]) — Ensemble d'attributs stockés dans une table. Les attributs utilisés pour prédire la cible peuvent être numériques et catégoriels. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de régression tabulaire. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de régression tabulaire recommandé par défaut sera utilisé. Valeur par défaut : None.
Retourne
List
une liste de valeurs numériques cibles prédites.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Prédire une valeur cible numérique à partir d'un ensemble d'attributs/variables dans un tableau.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> table = {
... "Height": ["11.52", "12.48", "12.3778"],
... "Length1": ["23.2", "24", "23.9"],
... "Length2": ["25.4", "26.3", "26.5"],
... "Length3": ["30", "31.2", "31.1"],
... "Species": ["Bream", "Bream", "Bream"],
... "Width": ["4.02", "4.3056", "4.6961"],
... }
>>> await client.tabular_regression(table, model="scikit-learn/Fish-Weight")
[110, 120, 130]classification de texte
< source >( text: strmodel: str | None = Nonetop_k: int | None = Nonefunction_to_apply: typing.Optional[ForwardRef('TextClassificationOutputTransform')] = None ) → list[TextClassificationOutputElement]
Paramètres
- text (
str) — Une chaîne de caractères à classifier. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de classification de texte. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de classification de texte recommandé par défaut sera utilisé. Valeur par défaut : None. - top_k (
int, facultatif) — Lorsqu’il est spécifié, limite la sortie aux K classes les plus probables. - function_to_apply (
"TextClassificationOutputTransform", facultatif) — La fonction à appliquer aux sorties du modèle afin de récupérer les scores.
Retourne
list[TextClassificationOutputElement]
une liste d'éléments TextClassificationOutputElement contenant l'étiquette prédite et la probabilité associée.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuer une classification de texte (par exemple, une analyse de sentiments) sur le texte donné.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.text_classification("I like you")
[
TextClassificationOutputElement(label='POSITIVE', score=0.9998695850372314),
TextClassificationOutputElement(label='NEGATIVE', score=0.0001304351753788069),
]text_generation
< source >( prompt: strdetails: bool | None = Nonestream: bool | None = Nonemodel: str | None = Noneadapter_id: str | None = Nonebest_of: int | None = Nonedecoder_input_details: bool | None = Nonedo_sample: bool | None = Nonefrequency_penalty: float | None = Nonegrammar: huggingface_hub.inference._generated.types.text_generation.TextGenerationInputGrammarType | None = Nonemax_new_tokens: int | None = Nonerepetition_penalty: float | None = Nonereturn_full_text: bool | None = Noneseed: int | None = Nonestop: list[str] | None = Nonetemperature: float | None = Nonetop_k: int | None = Nonetop_n_tokens: int | None = Nonetop_p: float | None = Nonetruncate: int | None = Nonetypical_p: float | None = Nonewatermark: bool | None = None ) → Union[str, TextGenerationOutput, AsyncIterable[str], AsyncIterable[TextGenerationStreamOutput]]
Paramètres
- prompt (
str) — Texte d'entrée. - details (
bool, facultatif) — Par défaut, text_generation renvoie une chaîne de caractères. Passezdetails=Truesi vous souhaitez une sortie détaillée (jetons, probabilités, graine, raison de fin, etc.). Disponible uniquement pour les modèles exécutés avec le backendtext-generation-inference. - stream (
bool, facultatif) — Par défaut, text_generation renvoie le texte généré complet. Passezstream=Truesi vous souhaitez qu'un flux de jetons soit renvoyé. Disponible uniquement pour les modèles exécutés avec le backendtext-generation-inference. - model (
str, facultatif) — Le modèle à utiliser pour l'inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l'instance. Valeur par défaut : None. - adapter_id (
str, facultatif) — Identifiant de l'adaptateur Lora. - best_of (
int, facultatif) — Génère best_of séquences et renvoie celle qui a les logprobs de jetons les plus élevés. - decoder_input_details (
bool, facultatif) — Retourne les logprobs et les identifiants des jetons d’entrée du décodeur. Vous devez également définirdetails=Truepour que cela soit pris en compte. La valeur par défaut estFalse. - do_sample (
bool, facultatif) — Active l'échantillonnage des logits - frequency_penalty (
float, facultatif) — Nombre compris entre -2,0 et 2,0. Les valeurs positives pénalisent les nouveaux jetons en fonction de leur fréquence existante dans le texte jusqu’à présent, réduisant ainsi la probabilité pour le modèle de répéter la même ligne à l’identique. - grammar (TextGenerationInputGrammarType, facultatif) — Contraintes de grammaire. Peut être un JSONSchema ou une expression régulière.
- max_new_tokens (
int, facultatif) — Nombre maximal de jetons générés. Valeur par défaut : 100. - repetition_penalty (
float, facultatif) — Le paramètre de pénalité de répétition. 1.0 signifie qu’il n’y a pas de pénalité. Voir ce papier pour plus de détails. - return_full_text (
bool, facultatif) — Indique s'il faut préfixer le texte généré par le prompt - seed (
int, facultatif) — Graine d'échantillonnage aléatoire - stop (
list[str], facultatif) — Arrêter la génération de jetons si un membre destopest généré. - temperature (
float, facultatif) — La valeur utilisée pour moduler la distribution des logits. - top_n_tokens (
int, facultatif) — Retourne des informations sur lestop_n_tokensjetons les plus probables à chaque étape de génération, au lieu de seulement le jeton échantillonné. - top_k (
int, *facultatif`) — Le nombre de jetons du vocabulaire ayant la plus haute probabilité à conserver pour le filtrage top-k. - top_p (
float, *optional) -- If set to < 1, only the smallest set of most probable tokens with probabilities that add up totop_p` or higher are kept for generation. - truncate (
int, *facultatif`) — Tronque les jetons d'entrée à la taille donnée. - typical_p (
float, *facultatif`) — Masse du Typical Decoding Voir Typical Decoding for Natural Language Generation pour plus d’informations - watermark (
bool, facultatif) — Filigrane avec A Watermark for Large Language Models
Retourne
Union[str, TextGenerationOutput, AsyncIterable[str], AsyncIterable[TextGenerationStreamOutput]]
Texte généré renvoyé par le serveur :
- si
stream=Falseetdetails=False, le texte généré est renvoyé sous forme destr(par défaut) - si
stream=Trueetdetails=False, le texte généré est renvoyé jeton par jeton en tant queAsyncIterable[str] - si
stream=Falseetdetails=True, le texte généré est renvoyé avec plus de détails sous forme de TextGenerationOutput - si
details=Trueetstream=True, le texte généré est renvoyé jeton par jeton sous forme d'un itérable de TextGenerationStreamOutput
Lève
ValidationError ou InferenceTimeoutError ou HfHubHTTPError
ValidationError— Si les valeurs d'entrée ne sont pas valides. Aucun appel HTTP n'est effectué vers le serveur.- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
À partir d'un prompt, générez le texte suivant.
Si vous souhaitez générer une réponse à partir de messages de chat, vous devez utiliser la méthode InferenceClient.chat_completion(). Elle accepte une liste de messages au lieu d'un simple prompt de texte et gère le templating de chat pour vous.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
# Case 1: generate text
>>> await client.text_generation("The huggingface_hub library is ", max_new_tokens=12)
'100% open source and built to be easy to use.'
# Case 2: iterate over the generated tokens. Useful for large generation.
>>> async for token in await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, stream=True):
... print(token)
100
%
open
source
and
built
to
be
easy
to
use
.
# Case 3: get more details about the generation process.
>>> await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True)
TextGenerationOutput(
generated_text='100% open source and built to be easy to use.',
details=TextGenerationDetails(
finish_reason='length',
generated_tokens=12,
seed=None,
prefill=[
TextGenerationPrefillOutputToken(id=487, text='The', logprob=None),
TextGenerationPrefillOutputToken(id=53789, text=' hugging', logprob=-13.171875),
(...)
TextGenerationPrefillOutputToken(id=204, text=' ', logprob=-7.0390625)
],
tokens=[
TokenElement(id=1425, text='100', logprob=-1.0175781, special=False),
TokenElement(id=16, text='%', logprob=-0.0463562, special=False),
(...)
TokenElement(id=25, text='.', logprob=-0.5703125, special=False)
],
best_of_sequences=None
)
)
# Case 4: iterate over the generated tokens with more details.
# Last object is more complete, containing the full generated text and the finish reason.
>>> async for details in await client.text_generation("The huggingface_hub library is ", max_new_tokens=12, details=True, stream=True):
... print(details)
...
TextGenerationStreamOutput(token=TokenElement(id=1425, text='100', logprob=-1.0175781, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=16, text='%', logprob=-0.0463562, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=1314, text=' open', logprob=-1.3359375, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=3178, text=' source', logprob=-0.28100586, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=273, text=' and', logprob=-0.5961914, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=3426, text=' built', logprob=-1.9423828, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-1.4121094, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=314, text=' be', logprob=-1.5224609, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=1833, text=' easy', logprob=-2.1132812, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=271, text=' to', logprob=-0.08520508, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(id=745, text=' use', logprob=-0.39453125, special=False), generated_text=None, details=None)
TextGenerationStreamOutput(token=TokenElement(
id=25,
text='.',
logprob=-0.5703125,
special=False),
generated_text='100% open source and built to be easy to use.',
details=TextGenerationStreamOutputStreamDetails(finish_reason='length', generated_tokens=12, seed=None)
)
# Case 5: generate constrained output using grammar
>>> response = await client.text_generation(
... prompt="I saw a puppy a cat and a raccoon during my bike ride in the park",
... model="HuggingFaceH4/zephyr-orpo-141b-A35b-v0.1",
... max_new_tokens=100,
... repetition_penalty=1.3,
... grammar={
... "type": "json",
... "value": {
... "properties": {
... "location": {"type": "string"},
... "activity": {"type": "string"},
... "animals_seen": {"type": "integer", "minimum": 1, "maximum": 5},
... "animals": {"type": "array", "items": {"type": "string"}},
... },
... "required": ["location", "activity", "animals_seen", "animals"],
... },
... },
... )
>>> json.loads(response)
{
"activity": "bike riding",
"animals": ["puppy", "cat", "raccoon"],
"animals_seen": 3,
"location": "park"
}text_to_image
< source >( prompt: strnegative_prompt: str | None = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int | None = Noneguidance_scale: float | None = Nonemodel: str | None = Nonescheduler: str | None = Noneseed: int | None = Noneextra_body: dict[str, typing.Any] | None = None ) → Image
Paramètres
- prompt (
str) — Le prompt à partir duquel générer une image. - negative_prompt (
str, facultatif) — Un prompt pour guider ce qui ne doit PAS être inclus dans la génération d’image. - height (
int, facultatif) — La hauteur en pixels de l'image de sortie - width (
int, facultatif) — La largeur en pixels de l'image de sortie - num_inference_steps (
int, facultatif) — Le nombre d’étapes de débruitage. Un plus grand nombre d’étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d’une inférence plus lente. - guidance_scale (
float, facultatif) — Une valeur de guidance scale plus élevée encourage le modèle à générer des images étroitement liées au prompt de texte, mais des valeurs trop élevées peuvent provoquer une saturation et d'autres artefacts. - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle texte-vers-image recommandé par défaut sera utilisé. Valeur par défaut : None. - scheduler (
str, facultatif) — Remplace le planificateur par un planificateur compatible. - seed (
int, facultatif) — Graine pour le générateur de nombres aléatoires. - extra_body (
dict[str, Any], facultatif) — Paramètres supplémentaires spécifiques au fournisseur à transmettre au modèle. Consultez la documentation du fournisseur pour les paramètres pris en charge.
Retourne
Image
L'image générée.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Générer une image à partir d'un texte donné en utilisant un modèle spécifié.
Vous devez avoir
PILinstallé si vous souhaitez travailler avec des images (pip install Pillow).
Vous pouvez passer des paramètres spécifiques au fournisseur au modèle en utilisant l'argument
extra_body.
Exemple :
# Must be run in an async context
>>> 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")
>>> image = await client.text_to_image(
... "An astronaut riding a horse on the moon.",
... negative_prompt="low resolution, blurry",
... model="stabilityai/stable-diffusion-2-1",
... )
>>> image.save("better_astronaut.png")>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="fal-ai", # Use fal.ai provider
... api_key="fal-ai-api-key", # Pass your fal.ai API key
... )
>>> image = client.text_to_image(
... "A majestic lion in a fantasy forest",
... model="black-forest-labs/FLUX.1-schnell",
... )
>>> image.save("lion.png")Exemple d'utilisation d'un fournisseur tiers via Hugging Face Routing. L'utilisation sera facturée sur votre compte Hugging Face.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate", # Use replicate provider
... api_key="hf_...", # Pass your HF token
... )
>>> image = client.text_to_image(
... "An astronaut riding a horse on the moon.",
... model="black-forest-labs/FLUX.1-dev",
... )
>>> image.save("astronaut.png")Exemple d'utilisation du fournisseur Replicate avec des paramètres supplémentaires
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate", # Use replicate provider
... api_key="hf_...", # Pass your HF token
... )
>>> image = client.text_to_image(
... "An astronaut riding a horse on the moon.",
... model="black-forest-labs/FLUX.1-schnell",
... extra_body={"output_quality": 100},
... )
>>> image.save("astronaut.png")text_to_speech
< source >( text: strmodel: str | None = Nonedo_sample: bool | None = Noneearly_stopping: typing.Union[bool, ForwardRef('TextToSpeechEarlyStoppingEnum'), NoneType] = Noneepsilon_cutoff: float | None = Noneeta_cutoff: float | None = Nonemax_length: int | None = Nonemax_new_tokens: int | None = Nonemin_length: int | None = Nonemin_new_tokens: int | None = Nonenum_beam_groups: int | None = Nonenum_beams: int | None = Nonepenalty_alpha: float | None = Nonetemperature: float | None = Nonetop_k: int | None = Nonetop_p: float | None = Nonetypical_p: float | None = Noneuse_cache: bool | None = Noneextra_body: dict[str, typing.Any] | None = None ) → bytes
Paramètres
- text (
str) — Le texte à synthétiser. - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle texte-vers-parole recommandé par défaut sera utilisé. Valeur par défaut : None. - do_sample (
bool, facultatif) — Indique s'il faut utiliser l'échantillonnage plutôt que le décodage glouton lors de la génération de nouveaux jetons. - early_stopping (
Union[bool, "TextToSpeechEarlyStoppingEnum"], facultatif) — Contrôle la condition d’arrêt pour les méthodes basées sur les faisceaux. - epsilon_cutoff (
float, facultatif) — Si défini sur un float strictement compris entre 0 et 1, seuls les jetons dont la probabilité conditionnelle est supérieure à epsilon_cutoff seront échantillonnés. Dans l’article, les valeurs suggérées vont de 3e-4 à 9e-4, en fonction de la taille du modèle. Voir Truncation Sampling as Language Model Desmoothing pour plus de détails. - eta_cutoff (
float, facultatif) — L'échantillonnage Eta est un hybride de l'échantillonnage localement typique et de l'échantillonnage epsilon. S'il est défini sur une valeur float strictement comprise entre 0 et 1, un jeton n'est pris en compte que s'il est supérieur à eta_cutoff ou à sqrt(eta_cutoff)- exp(-entropy(softmax(next_token_logits))). Le second terme correspond intuitivement à la probabilité attendue du jeton suivant, mise à l'échelle par sqrt(eta_cutoff). Dans l'article, les valeurs suggérées vont de 3e-4 à 2e-3, en fonction de la taille du modèle. Consultez Truncation Sampling as Language Model Desmoothing pour plus de détails.
- max_length (
int, facultatif) — La longueur maximale (en jetons) du texte généré, y compris l'entrée. - max_new_tokens (
int, facultatif) — Le nombre maximal de jetons à générer. Prend le pas sur max_length. - min_length (
int, facultatif) — La longueur minimale (en jetons) du texte généré, y compris l'entrée. - min_new_tokens (
int, facultatif) — Le nombre minimal de jetons à générer. Prend le pas sur min_length. - num_beam_groups (
int, facultatif) — Nombre de groupes dans lesquels diviser num_beams afin d’assurer la diversité entre les différents groupes de beams. Voir cet article pour plus de détails. - num_beams (
int, facultatif) — Nombre de faisceaux à utiliser pour la recherche par faisceaux. - penalty_alpha (
float, facultatif) — La valeur équilibre la confiance du modèle et la pénalité de dégénérescence dans le décodage par recherche contrastive. - temperature (
float, facultatif) — La valeur utilisée pour moduler les probabilités du jeton suivant. - top_k (
int, facultatif) — Le nombre de jetons du vocabulaire ayant la plus haute probabilité à conserver pour le filtrage top-k. - top_p (
float, facultatif) — Si défini sur un float < 1, seul l’ensemble minimal de jetons les plus probables, dont les probabilités cumulées atteignent top_p ou plus, est conservé pour la génération. - typical_p (
float, facultatif) — La mesure de typicalité locale évalue à quel point la probabilité conditionnelle de prédire le jeton cible suivant est proche de la probabilité conditionnelle attendue de prédire un jeton aléatoire suivant, étant donné le texte partiel déjà généré. Si définie sur une valeur float < 1, l’ensemble le plus restreint de jetons les plus localement typiques, dont les probabilités cumulées atteignent ou dépassent typical_p, est conservé pour la génération. Consultez cet article pour plus de détails. - use_cache (
bool, facultatif) — Indique si le modèle doit utiliser les attentions clés/valeurs passées pour accélérer le décodage - extra_body (
dict[str, Any], facultatif) — Paramètres supplémentaires spécifiques au fournisseur à transmettre au modèle. Consultez la documentation du fournisseur pour les paramètres pris en charge.
Retourne
bytes
L'audio généré.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Synthétiser un audio d'une voix prononçant un texte donné.
Vous pouvez passer des paramètres spécifiques au fournisseur au modèle en utilisant l'argument
extra_body.
Exemple :
# Must be run in an async context
>>> from pathlib import Path
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> audio = await client.text_to_speech("Hello world")
>>> Path("hello_world.flac").write_bytes(audio)Exemple d'utilisation d'un fournisseur tiers directement. L'utilisation sera facturée sur votre compte Replicate.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate",
... api_key="your-replicate-api-key", # Pass your Replicate API key directly
... )
>>> audio = client.text_to_speech(
... text="Hello world",
... model="OuteAI/OuteTTS-0.3-500M",
... )
>>> Path("hello_world.flac").write_bytes(audio)Exemple d'utilisation d'un fournisseur tiers via Hugging Face Routing. L'utilisation sera facturée sur votre compte Hugging Face.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate",
... api_key="hf_...", # Pass your HF token
... )
>>> audio =client.text_to_speech(
... text="Hello world",
... model="OuteAI/OuteTTS-0.3-500M",
... )
>>> Path("hello_world.flac").write_bytes(audio)>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate", # Use replicate provider
... api_key="hf_...", # Pass your HF token
... )
>>> audio = client.text_to_speech(
... "Hello, my name is Kororo, an awesome text-to-speech model.",
... model="hexgrad/Kokoro-82M",
... extra_body={"voice": "af_nicole"},
... )
>>> Path("hello.flac").write_bytes(audio)Exemple de génération musicale avec « YuE-s1-7B-anneal-en-cot » sur fal.ai
>>> from huggingface_hub import InferenceClient
>>> lyrics = '''
... [verse]
... In the town where I was born
... Lived a man who sailed to sea
... And he told us of his life
... In the land of submarines
... So we sailed on to the sun
... 'Til we found a sea of green
... And we lived beneath the waves
... In our yellow submarine
... [chorus]
... We all live in a yellow submarine
... Yellow submarine, yellow submarine
... We all live in a yellow submarine
... Yellow submarine, yellow submarine
... '''
>>> genres = "pavarotti-style tenor voice"
>>> client = InferenceClient(
... provider="fal-ai",
... model="m-a-p/YuE-s1-7B-anneal-en-cot",
... api_key=...,
... )
>>> audio = client.text_to_speech(lyrics, extra_body={"genres": genres})
>>> with open("output.mp3", "wb") as f:
... f.write(audio)text_to_video
< source >( prompt: strmodel: str | None = Noneguidance_scale: float | None = Nonenegative_prompt: list[str] | None = Nonenum_frames: float | None = Nonenum_inference_steps: int | None = Noneseed: int | None = Noneextra_body: dict[str, typing.Any] | None = None ) → bytes
Paramètres
- prompt (
str) — Le prompt à partir duquel générer une vidéo. - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle texte-vers-vidéo recommandé par défaut sera utilisé. Valeur par défaut : None. - guidance_scale (
float, facultatif) — Une valeur de guidance scale plus élevée encourage le modèle à générer des vidéos étroitement liées au prompt texte, mais des valeurs trop élevées peuvent provoquer une saturation et d'autres artefacts. - negative_prompt (
list[str], facultatif) — Un ou plusieurs prompts pour guider ce qui ne doit PAS être inclus dans la génération de la vidéo. - num_frames (
float, facultatif) — Le paramètre num_frames détermine le nombre de frames vidéo générées. - num_inference_steps (
int, facultatif) — Le nombre d’étapes de débruitage. Un plus grand nombre d’étapes de débruitage conduit généralement à une vidéo de meilleure qualité, au prix d’une inférence plus lente. - seed (
int, facultatif) — Graine pour le générateur de nombres aléatoires. - extra_body (
dict[str, Any], facultatif) — Paramètres supplémentaires spécifiques au fournisseur à transmettre au modèle. Consultez la documentation du fournisseur pour les paramètres pris en charge.
Retourne
bytes
La vidéo générée.
Générer une vidéo à partir d'un texte donné.
Vous pouvez passer des paramètres spécifiques au fournisseur au modèle en utilisant l'argument
extra_body.
Exemple :
Exemple d'utilisation d'un fournisseur tiers directement. L'utilisation sera facturée sur votre compte fal.ai.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="fal-ai", # Using fal.ai provider
... api_key="fal-ai-api-key", # Pass your fal.ai API key
... )
>>> video = client.text_to_video(
... "A majestic lion running in a fantasy forest",
... model="tencent/HunyuanVideo",
... )
>>> with open("lion.mp4", "wb") as file:
... file.write(video)Exemple d'utilisation d'un fournisseur tiers via Hugging Face Routing. L'utilisation sera facturée sur votre compte Hugging Face.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="replicate", # Using replicate provider
... api_key="hf_...", # Pass your HF token
... )
>>> video = client.text_to_video(
... "A cat running in a park",
... model="genmo/mochi-1-preview",
... )
>>> with open("cat.mp4", "wb") as file:
... file.write(video)token_classification
< source >( text: strmodel: str | None = Noneaggregation_strategy: typing.Optional[ForwardRef('TokenClassificationAggregationStrategy')] = Noneignore_labels: list[str] | None = Nonestride: int | None = None ) → list[TokenClassificationOutputElement]
Paramètres
- text (
str) — Une chaîne de caractères à classifier. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de classification de jetons. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de classification de jetons recommandé par défaut sera utilisé. Valeur par défaut : None. - aggregation_strategy (
"TokenClassificationAggregationStrategy", facultatif) — La stratégie utilisée pour fusionner les jetons en fonction des prédictions du modèle - ignore_labels (
list[str, facultatif) — Une liste d'étiquettes à ignorer - stride (
int, facultatif) — Le nombre de jetons superposés entre les blocs lors de la division du texte d'entrée.
Retourne
list[TokenClassificationOutputElement]
Liste d'éléments TokenClassificationOutputElement contenant le groupe d'entités, le score de confiance, le mot, l'index de début et l'index de fin.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Effectuer la classification de jetons sur le texte donné. Utilisé généralement pour l’analyse de phrases, qu’elle soit grammaticale ou de reconnaissance d’entités nommées (NER), afin de comprendre les mots-clés contenus dans le texte.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.token_classification("My name is Sarah Jessica Parker but you can call me Jessica")
[
TokenClassificationOutputElement(
entity_group='PER',
score=0.9971321225166321,
word='Sarah Jessica Parker',
start=11,
end=31,
),
TokenClassificationOutputElement(
entity_group='PER',
score=0.9773476123809814,
word='Jessica',
start=52,
end=59,
)
]traduction
< source >( text: strmodel: str | None = Nonesrc_lang: str | None = Nonetgt_lang: str | None = Noneclean_up_tokenization_spaces: bool | None = Nonetruncation: typing.Optional[ForwardRef('TranslationTruncationStrategy')] = Nonegenerate_parameters: dict[str, typing.Any] | None = None ) → TranslationOutput
Paramètres
- text (
str) — Une chaîne de caractères à traduire. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de traduction. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S'il n'est pas fourni, le modèle de traduction recommandé par défaut sera utilisé. Valeur par défaut : None. - src_lang (
str, facultatif) — La langue source du texte. Obligatoire pour les modèles capables de traduire depuis plusieurs langues. - tgt_lang (
str, facultatif) — Langue cible de la traduction. Obligatoire pour les modèles capables de traduire vers plusieurs langues. - clean_up_tokenization_spaces (
bool, facultatif) — Indique s'il faut nettoyer les espaces supplémentaires potentiels dans la sortie texte. - truncation (
"TranslationTruncationStrategy", facultatif) — La stratégie de troncature à utiliser. - generate_parameters (
dict[str, Any], facultatif) — Paramétrage supplémentaire de l'algorithme de génération de texte.
Retourne
Le texte traduit généré.
Lève
InferenceTimeoutError ou HfHubHTTPError ou ValueError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.ValueError— Si un seul des argumentssrc_langettgt_langest fourni.
Convertir du texte d'une langue à une autre.
Consultez https://huggingface.co/tasks/translation pour plus d’informations sur la manière de choisir le meilleur modèle pour
votre cas d’usage spécifique. Les langues source et cible dépendent généralement du modèle.
Cependant, il est possible de spécifier les langues source et cible pour certains modèles. Si vous travaillez avec l’un de ces modèles,
vous pouvez utiliser les arguments src_lang et tgt_lang pour transmettre les informations pertinentes.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.translation("My name is Wolfgang and I live in Berlin")
'Mein Name ist Wolfgang und ich lebe in Berlin.'
>>> await client.translation("My name is Wolfgang and I live in Berlin", model="Helsinki-NLP/opus-mt-en-fr")
TranslationOutput(translation_text='Je m'appelle Wolfgang et je vis à Berlin.')visual_question_answering
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]question: strmodel: str | None = Nonetop_k: int | None = None ) → list[VisualQuestionAnsweringOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — L’entrée visuelle pour le contexte. Elle peut être des octets bruts, un fichier image, une URL vers une image en ligne ou une image PIL. - question (
str) — Question à laquelle il faut répondre. - model (
str, facultatif) — Le modèle à utiliser pour la tâche de question-réponse visuelle. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. S’il n’est pas fourni, le modèle de question-réponse visuelle recommandé par défaut sera utilisé. Valeur par défaut : None. - top_k (
int, facultatif) — Le nombre de réponses à retourner (choisies par ordre de probabilité). Notez que nous retournons moins de réponses que top_k s'il n'y a pas suffisamment d'options disponibles dans le contexte.
Retourne
list[VisualQuestionAnsweringOutputElement]
une liste d'éléments VisualQuestionAnsweringOutputElement contenant l'étiquette prédite et la probabilité associée.
Lève
InferenceTimeoutError ou HfHubHTTPError
InferenceTimeoutError— Si le modèle est indisponible ou si la demande expirHfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Répondre à des questions ouvertes à partir d'une image.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.visual_question_answering(
... image="https://huggingface.co/datasets/mishig/sample_images/resolve/main/tiger.jpg",
... question="What is the animal doing?"
... )
[
VisualQuestionAnsweringOutputElement(score=0.778609573841095, answer='laying down'),
VisualQuestionAnsweringOutputElement(score=0.6957435607910156, answer='sitting'),
]zero_shot_classification
< source >( text: strcandidate_labels: listmulti_label: bool | None = Falsehypothesis_template: str | None = Nonemodel: str | None = None ) → list[ZeroShotClassificationOutputElement]
Paramètres
- text (
str) — Le texte d'entrée à classifier. - candidate_labels (
list[str]) — L'ensemble des étiquettes de classes possibles pour classifier le texte. - multi_label (
bool, facultatif) — Indique si plusieurs étiquettes candidates peuvent être vraies. Si la valeur est false, les scores sont normalisés de sorte que la somme des probabilités des étiquettes pour chaque séquence soit égale à 1. Si la valeur est true, les étiquettes sont considérées comme indépendantes et les probabilités sont normalisées pour chaque candidate. - hypothesis_template (
str, facultatif) — La phrase utilisée conjointement aveccandidate_labelspour tenter la classification de texte en remplaçant le marqueur de position par les étiquettes candidates. - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l’instance. S’il n’est pas fourni, le modèle de classification zero-shot recommandé par défaut sera utilisé.
Retourne
list[ZeroShotClassificationOutputElement]
Liste d'éléments ZeroShotClassificationOutputElement contenant les étiquettes prédites et leur niveau de confiance.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Fournissez en entrée un texte et un ensemble d'étiquettes candidates pour classifier le texte d'entrée.
Exemple avec multi_label=False :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> text = (
... "A new model offers an explanation for how the Galilean satellites formed around the solar system's"
... "largest world. Konstantin Batygin did not set out to solve one of the solar system's most puzzling"
... " mysteries when he went for a run up a hill in Nice, France."
... )
>>> labels = ["space & cosmos", "scientific discovery", "microbiology", "robots", "archeology"]
>>> await client.zero_shot_classification(text, labels)
[
ZeroShotClassificationOutputElement(label='scientific discovery', score=0.7961668968200684),
ZeroShotClassificationOutputElement(label='space & cosmos', score=0.18570658564567566),
ZeroShotClassificationOutputElement(label='microbiology', score=0.00730885099619627),
ZeroShotClassificationOutputElement(label='archeology', score=0.006258360575884581),
ZeroShotClassificationOutputElement(label='robots', score=0.004559356719255447),
]
>>> await client.zero_shot_classification(text, labels, multi_label=True)
[
ZeroShotClassificationOutputElement(label='scientific discovery', score=0.9829297661781311),
ZeroShotClassificationOutputElement(label='space & cosmos', score=0.755190908908844),
ZeroShotClassificationOutputElement(label='microbiology', score=0.0005462635890580714),
ZeroShotClassificationOutputElement(label='archeology', score=0.00047131875180639327),
ZeroShotClassificationOutputElement(label='robots', score=0.00030448526376858354),
]Exemple avec multi_label=True et un hypothesis_template personnalisé :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.zero_shot_classification(
... text="I really like our dinner and I'm very happy. I don't like the weather though.",
... candidate_labels=["positive", "negative", "pessimistic", "optimistic"],
... multi_label=True,
... hypothesis_template="This text is {} towards the weather"
... )
[
ZeroShotClassificationOutputElement(label='negative', score=0.9231801629066467),
ZeroShotClassificationOutputElement(label='pessimistic', score=0.8760990500450134),
ZeroShotClassificationOutputElement(label='optimistic', score=0.0008674879791215062),
ZeroShotClassificationOutputElement(label='positive', score=0.0005250611575320363)
]zero_shot_image_classification
< source >( image: typing.Union[bytes, typing.BinaryIO, str, pathlib.Path, ForwardRef('Image'), bytearray, memoryview]candidate_labels: listmodel: str | None = Nonehypothesis_template: str | None = None ) → list[ZeroShotImageClassificationOutputElement]
Paramètres
- image (
Union[str, Path, bytes, BinaryIO, PIL.Image.Image]) — The input image to caption. It can be raw bytes, an image file, a URL to an online image, or a PIL Image. - candidate_labels (
list[str]) — Les étiquettes candidates pour cette image - model (
str, facultatif) — Le modèle à utiliser pour l’inférence. Peut être un identifiant de modèle hébergé sur le Hugging Face Hub ou une URL vers un Inference Endpoint déployé. Ce paramètre remplace le modèle défini au niveau de l’instance. S’il n’est pas fourni, le modèle de classification d’images zero-shot recommandé par défaut sera utilisé. - hypothesis_template (
str, facultatif) — La phrase utilisée conjointement aveccandidate_labelspour tenter la classification d’image en remplaçant le marqueur de position par les étiquettes candidates.
Retourne
list[ZeroShotImageClassificationOutputElement]
Liste d'éléments ZeroShotImageClassificationOutputElement contenant les étiquettes prédites et leur niveau de confiance.
Lève
InferenceTimeoutError ou HfHubHTTPError
- InferenceTimeoutError — Si le modèle est indisponible ou si la demande expirée.
HfHubHTTPError— Si la requête échoue avec un code d'état d'erreur HTTP autre que HTTP 503.
Fournissez une image d’entrée et des étiquettes de texte pour prédire les étiquettes de texte de l’image.
Exemple :
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.zero_shot_image_classification(
... "https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg",
... candidate_labels=["dog", "cat", "horse"],
... )
[ZeroShotImageClassificationOutputElement(label='dog', score=0.956),...]InferenceTimeoutError
Erreur levée lorsqu'un modèle est indisponible ou que la demande expir