Huggingface.js documentation

🤗 Hugging Face Inference

Huggingface.js

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

🤗 Hugging Face Inference

Un wrapper propulsé par Typescript qui 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.

Premiers pas

Installer

Nœud

npm install @huggingface/inference

pnpm add @huggingface/inference

yarn add @huggingface/inference

Deno

// esm.sh
import { InferenceClient } from "https://esm.sh/@huggingface/inference";
// or npm:
import { InferenceClient } from "npm:@huggingface/inference";

Initialiser

import { InferenceClient } from '@huggingface/inference';

const hf = new InferenceClient('your access token');

❗Note importante : Passez toujours un jeton d'accès. Rejoignez Hugging Face puis rendez-vous sur jetons d'accès pour générer votre jeton d'accès gratuitement.

Votre jeton d'accès doit être conservé en secret. Si vous devez le protéger dans des applications front-end, nous vous suggérons de configurer un serveur proxy qui stocke le jeton d'accès.

Utilisation des fournisseurs d'inférence

Vous pouvez envoyer des requêtes d'inférence à des fournisseurs tiers avec le client d'inférence.

Actuellement, nous prenons en charge les fournisseurs suivants :

Pour envoyer des requêtes à un fournisseur tiers, vous devez passer le paramètre provider à la fonction d’inférence. La valeur par défaut du paramètre provider est « auto », ce qui sélectionne le premier des fournisseurs disponibles pour le modèle, triés selon l’ordre de préférence défini dans https://hf.co/settings/inference-providers.

const accessToken = "hf_..."; // Either a HF access token, or an API key from the third-party provider (Replicate in this example)

const client = new InferenceClient(accessToken);
await client.textToImage({
  provider: "replicate",
  model:"black-forest-labs/Flux.1-dev",
  inputs: "A black forest cake"
})

Vous devez également vous assurer que votre requête est authentifiée avec un jeton d’accès. Lorsque l’authentification est effectuée avec un jeton d’accès Hugging Face, la requête est acheminée via https://huggingface.co. Lorsque l’authentification est effectuée avec une clé de fournisseur tiers, la requête est envoyée directement à l’API d’inférence de ce fournisseur.

Seul un sous-ensemble de modèles est pris en charge lors de la demande auprès de fournisseurs tiers. Vous pouvez consulter la liste des modèles pris en charge par tâche de pipeline ici :

❗Note importante : Pour être compatible, l'API tierce doit respecter la forme « standard » de l'API que nous attendons sur les pages de modèles HF pour chaque type de tâche de pipeline. Ce n'est pas un problème pour les LLM, car tout le monde a convergé vers l'API OpenAI de toute façon, mais cela peut être plus délicat pour d'autres tâches comme « text-to-image » ou « automatic-speech-recognition », pour lesquelles il n'existe pas d'API standard. Faites-le-nous savoir si vous avez besoin d'aide ou si nous pouvons vous faciliter la tâche !

👋Vous souhaitez ajouter un autre fournisseur ? Contactez-nous si vous souhaitez ajouter la prise en charge d’un autre fournisseur d’inférence, et/ou faites-en la demande sur https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49

Tree-shaking

Vous pouvez importer directement les fonctions dont vous avez besoin depuis le module, au lieu d'utiliser la classe InferenceClient.

import { textGeneration } from "@huggingface/inference";

await textGeneration({
  accessToken: "hf_...",
  model: "model_or_endpoint",
  inputs: ...,
  parameters: ...
})

Cela permettra à votre bundler d'effectuer du tree-shaking.

Gestion des erreurs

Le package d'inférence fournit des types d'erreurs spécifiques pour vous aider à gérer efficacement différents scénarios d'erreurs.

Types d'erreurs

Le package définit plusieurs types d'erreurs qui étendent la classe de base Error :

InferenceClientError : classe d'erreur de base pour toutes les erreurs d'Inference de Hugging Face
InferenceClientInputError : levée en cas de problème avec les paramètres d’entrée
InferenceClientProviderApiError : levée en cas d’erreurs au niveau de l’API provenant des fournisseurs
InferenceClientHubApiError : levée en cas d’erreurs au niveau de l’API provenant du Hugging Face Hub
InferenceClientProviderOutputError : levée lorsque le format des réponses API des fournisseurs pose problème

Exemple d'utilisation

import { InferenceClient } from "@huggingface/inference";
import {
  InferenceClientError,
  InferenceClientInputError,
  InferenceClientProviderApiError,
  InferenceClientProviderOutputError,
  InferenceClientHubApiError,
} from "@huggingface/inference";

const client = new InferenceClient();

try {
  const result = await client.textGeneration({
    model: "gpt2",
    inputs: "Hello, I'm a language model",
  });
} catch (error) {
  if (error instanceof InferenceClientProviderApiError) {
    // Handle API errors (e.g., rate limits, authentication issues)
    console.error("Provider API Error:", error.message);
    console.error("HTTP Request details:", error.httpRequest);
    console.error("HTTP Response details:", error.httpResponse);
  } else if (error instanceof InferenceClientHubApiError) {
    // Handle API errors (e.g., rate limits, authentication issues)
    console.error("Hub API Error:", error.message);
    console.error("HTTP Request details:", error.httpRequest);
    console.error("HTTP Response details:", error.httpResponse);
  } else if (error instanceof InferenceClientProviderOutputError) {
    // Handle malformed responses from providers
    console.error("Provider Output Error:", error.message);
  } else if (error instanceof InferenceClientInputError) {
    // Handle invalid input parameters
    console.error("Input Error:", error.message);
  } else {
    // Handle unexpected errors
    console.error("Unexpected error:", error);
  }
}

/// Catch all errors from @huggingface/inference
try {
  const result = await client.textGeneration({
    model: "gpt2",
    inputs: "Hello, I'm a language model",
  });
} catch (error) {
  if (error instanceof InferenceClientError) {
    // Handle errors from @huggingface/inference
    console.error("Error from InferenceClient:", error);
  } else {
    // Handle unexpected errors
    console.error("Unexpected error:", error);
  }
}

Détails de l'erreur

InferenceClientProviderApiError

Cette erreur se produit lorsque des problèmes surviennent avec la requête API lors de l'inférence chez le fournisseur sélectionné.

Elle possède plusieurs propriétés :

message : un message d'erreur descriptif
httpRequest : Détails de la requête échouée (URL, méthode, en-têtes)
httpResponse : Détails de la réponse, y compris le code de statut et le corps

InferenceClientHubApiError

Cette erreur se produit lorsque des problèmes surviennent lors de la requête à l'API du Hugging Face Hub.

Elle possède plusieurs propriétés :

message : un message d'erreur descriptif
httpRequest : Détails de la requête échouée (URL, méthode, en-têtes)
httpResponse : Détails de la réponse, y compris le code de statut et le corps

InferenceClientProviderOutputError

Cette erreur se produit lorsqu'un fournisseur renvoie une réponse dans un format inattendu.

InferenceClientInputError

Cette erreur se produit lorsque les paramètres d’entrée sont invalides ou manquants. Le message d’erreur décrit ce qui ne va pas avec l’entrée.

Traitement du langage naturel

Génération de texte

Génère du texte à partir d'un prompt d'entrée.

await hf.textGeneration({
  model: 'mistralai/Mixtral-8x7B-v0.1',
  provider: "together",
  inputs: 'The answer to the universe is'
})

for await (const output of hf.textGenerationStream({
  model: "mistralai/Mixtral-8x7B-v0.1",
  provider: "together",
  inputs: 'repeat "one two three four"',
  parameters: { max_new_tokens: 250 }
})) {
  console.log(output.token.text, output.generated_text);
}

Chat Completion

Générer une réponse de modèle à partir d'une liste de messages constituant une conversation.

// Non-streaming API
const out = await hf.chatCompletion({
  model: "Qwen/Qwen3-32B",
  provider: "cerebras",
  messages: [{ role: "user", content: "Hello, nice to meet you!" }],
  max_tokens: 512,
  temperature: 0.1,
});

// Streaming API
let out = "";
for await (const chunk of hf.chatCompletionStream({
  model: "Qwen/Qwen3-32B",
  provider: "cerebras",
  messages: [
    { role: "user", content: "Can you help me solve an equation?" },
  ],
  max_tokens: 512,
  temperature: 0.1,
})) {
  if (chunk.choices && chunk.choices.length > 0) {
    out += chunk.choices[0].delta.content;
  }
}

Extraction de caractéristiques

Cette tâche lit du texte et produit des valeurs flottantes brutes, généralement consommées dans le cadre d'une base de données sémantique ou d'une recherche sémantique.

await hf.featureExtraction({
  model: "sentence-transformers/distilbert-base-nli-mean-tokens",
  inputs: "That is a happy person",
});

Fill Mask

Tente de combler un trou avec un mot manquant (un jeton, pour être précis).

await hf.fillMask({
  model: 'bert-base-uncased',
  inputs: '[MASK] world!'
})

Résumé

Résume un texte long en un texte plus court. Attention, certains modèles ont une longueur d'entrée maximale.

await hf.summarization({
  model: 'facebook/bart-large-cnn',
  inputs:
    'The tower is 324 metres (1,063 ft) tall, about the same height as an 81-storey building, and the tallest structure in Paris. Its base is square, measuring 125 metres (410 ft) on each side. During its construction, the Eiffel Tower surpassed the Washington Monument to become the tallest man-made structure in the world, a title it held for 41 years until the Chrysler Building in New York City was finished in 1930.',
  parameters: {
    max_length: 100
  }
})

Question-réponse

Répond aux questions en fonction du contexte que vous fournissez.

await hf.questionAnswering({
  model: 'deepset/roberta-base-squad2',
  inputs: {
    question: 'What is the capital of France?',
    context: 'The capital of France is Paris.'
  }
})

Réponses aux questions sur les tableaux

await hf.tableQuestionAnswering({
  model: 'google/tapas-base-finetuned-wtq',
  inputs: {
    query: 'How many stars does the transformers repository have?',
    table: {
      Repository: ['Transformers', 'Datasets', 'Tokenizers'],
      Stars: ['36542', '4512', '3934'],
      Contributors: ['651', '77', '34'],
      'Programming language': ['Python', 'Python', 'Rust, Python and NodeJS']
    }
  }
})

Classification de texte

Souvent utilisée pour l'analyse de sentiments, cette méthode attribue des étiquettes au texte fourni, accompagnées d'un score de probabilité pour chaque étiquette.

await hf.textClassification({
  model: 'distilbert-base-uncased-finetuned-sst-2-english',
  inputs: 'I like you. I love you.'
})

Classification de jetons

Utilisé 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.

await hf.tokenClassification({
  model: 'dbmdz/bert-large-cased-finetuned-conll03-english',
  inputs: 'My name is Sarah Jessica Parker but you can call me Jessica'
})

Traduction

Convertit le texte d'une langue à une autre.

await hf.translation({
  model: 't5-base',
  inputs: 'My name is Wolfgang and I live in Berlin'
})

await hf.translation({
  model: 'facebook/mbart-large-50-many-to-many-mmt',
  inputs: textToTranslate,
  parameters: {
  "src_lang": "en_XX",
  "tgt_lang": "fr_XX"
 }
})

Classification en zéro tir

Vérifie à quel point un texte d'entrée correspond à un ensemble d'étiquettes que vous fournissez.

await hf.zeroShotClassification({
  model: 'facebook/bart-large-mnli',
  inputs: [
    'Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!'
  ],
  parameters: { candidate_labels: ['refund', 'legal', 'faq'] }
})

Similarité de phrases

Calculer la similarité sémantique entre un texte et une liste d'autres phrases.

await hf.sentenceSimilarity({
  model: 'sentence-transformers/paraphrase-xlm-r-multilingual-v1',
  inputs: {
    source_sentence: 'That is a happy person',
    sentences: [
      'That is a happy dog',
      'That is a very happy person',
      'Today is a sunny day'
    ]
  }
})

Classement de texte

Classez les documents selon leur pertinence par rapport à une requête.

await hf.textRanking({
  model: 'cross-encoder/ettin-reranker-68m-v1',
  inputs: {
    query: 'Which planet is known as the Red Planet?',
    texts: [
      "Venus is often called Earth's twin because of its similar size and proximity.",
      'Mars, known for its reddish appearance, is often referred to as the Red Planet.',
      'Jupiter, the largest planet in our solar system, has a prominent red spot.',
      'Saturn, famous for its rings, is sometimes mistaken for the Red Planet.'
    ]
  }
})

Audio

Reconnaissance automatique de la parole

Transcrit le discours à partir d'un fichier audio.

Démonstration

await hf.automaticSpeechRecognition({
  model: 'facebook/wav2vec2-large-960h-lv60-self',
  data: readFileSync('test/sample1.flac')
})

Classification audio

Attribue des étiquettes à l'audio fourni, accompagnées d'un score de probabilité pour chaque étiquette.

Démonstration

await hf.audioClassification({
  model: 'superb/hubert-large-superb-er',
  data: readFileSync('test/sample1.flac')
})

Texte en parole

Génère une parole naturelle à partir d'une entrée textuelle.

Tutoriel interactif

await hf.textToSpeech({
  model: 'espnet/kan-bayashi_ljspeech_vits',
  inputs: 'Hello world!'
})

Audio vers Audio

Génère un ou plusieurs audios à partir d'un audio d'entrée, couramment utilisé pour l'amélioration de la parole et la séparation des sources.

await hf.audioToAudio({
  model: 'speechbrain/sepformer-wham',
  data: readFileSync('test/sample1.flac')
})

Vision par ordinateur

Classification d'images

Attribue des étiquettes à une image donnée, accompagnées d'un score de probabilité pour chaque étiquette.

Démonstration

await hf.imageClassification({
  data: readFileSync('test/cheetah.png'),
  model: 'google/vit-base-patch16-224'
})

Détection d'objets

Détecte les objets dans une image et renvoie des étiquettes avec les boîtes englobantes correspondantes et les scores de probabilité.

Démonstration

await hf.objectDetection({
  data: readFileSync('test/cats.png'),
  model: 'facebook/detr-resnet-50'
})

Segmentation d'images

Détecte les segments au sein d'une image et renvoie des étiquettes avec les boîtes englobantes correspondantes et les scores de probabilité.

await hf.imageSegmentation({
  data: readFileSync('test/cats.png'),
  model: 'facebook/detr-resnet-50-panoptic'
})

Image vers texte

Extrait du texte d'une image donnée, couramment utilisé pour la légende d'images ou la reconnaissance optique de caractères.

await hf.imageToText({
  data: readFileSync('test/cats.png'),
  model: 'nlpconnect/vit-gpt2-image-captioning'
})

Texte vers image

Crée une image à partir d'un prompt texte.

Démonstration

await hf.textToImage({
  model: 'black-forest-labs/FLUX.1-dev',
  inputs: 'a picture of a green bird'
})

Image vers image

Image-to-image est la tâche qui consiste à transformer une image source afin qu’elle corresponde aux caractéristiques d’une image cible ou d’un domaine d’images cible.

Tutoriel interactif

await hf.imageToImage({
  inputs: new Blob([readFileSync("test/stormtrooper_depth.png")]),
  parameters: {
    prompt: "elmo's lecture",
  },
  model: "lllyasviel/sd-controlnet-depth",
});

Classification d'images en zéro tir

Vérifie à quel point une image d'entrée correspond à un ensemble d'étiquettes que vous fournissez.

await hf.zeroShotImageClassification({
  model: 'openai/clip-vit-large-patch14-336',
  inputs: {
    image: await (await fetch('https://placekitten.com/300/300')).blob()
  },
  parameters: {
    candidate_labels: ['cat', 'dog']
  }
})

Multimodal

Réponse à des questions visuelles

Le Visual Question Answering est la tâche de répondre à des questions ouvertes à partir d'une image. Ils produisent des réponses en langage naturel à des questions en langage naturel.

Démonstration

await hf.visualQuestionAnswering({
  model: 'dandelin/vilt-b32-finetuned-vqa',
  inputs: {
    question: 'How many cats are lying down?',
    image: await (await fetch('https://placekitten.com/300/300')).blob()
  }
})

Question-réponse sur documents

Les modèles de réponse à des questions sur des documents prennent en entrée une paire (document, question) et renvoient une réponse en langage naturel.

Démonstration

await hf.documentQuestionAnswering({
  model: 'impira/layoutlm-document-qa',
  inputs: {
    question: 'Invoice number?',
    image: await (await fetch('https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png')).blob(),
  }
})

Données tabulaires

Régression tabulaire

La régression tabulaire est la tâche qui consiste à prédire une valeur numérique à partir d'un ensemble d'attributs.

await hf.tabularRegression({
  model: "scikit-learn/Fish-Weight",
  inputs: {
    data: {
      "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"]
    },
  },
})

Classification de données tabulaires

La classification tabulaire est la tâche qui consiste à classer une catégorie cible (un groupe) sur la base d'un ensemble d'attributs.

await hf.tabularClassification({
  model: "vvmnnnkv/wine-quality",
  inputs: {
    data: {
      "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"]
    },
  },
})

Vous pouvez utiliser tout fournisseur compatible avec l'API de complétion de chat avec la méthode chatCompletion.

// Chat Completion Example
const MISTRAL_KEY = process.env.MISTRAL_KEY;
const hf = new InferenceClient(MISTRAL_KEY, {
  endpointUrl: "https://api.mistral.ai",
});
const stream = hf.chatCompletionStream({
  model: "mistral-tiny",
  messages: [{ role: "user", content: "Complete the equation one + one = , just the answer" }],
});
let out = "";
for await (const chunk of stream) {
  if (chunk.choices && chunk.choices.length > 0) {
    out += chunk.choices[0].delta.content;
    console.log(out);
  }
}

Utilisation des points de terminaison d'inférence

Les exemples présentés ci-dessus utilisent des fournisseurs d’inférence. Bien que ceux-ci s’avèrent très utiles pour le prototypage et les tests rapides, une fois que vous êtes prêt à déployer votre modèle en production, vous devrez utiliser une infrastructure dédiée. C’est là qu’interviennent les Inference Endpoints. Ils vous permettent de déployer n’importe quel modèle et de l’exposer sous forme d’API privée. Une fois le déploiement effectué, vous obtenez une URL à laquelle vous pouvez vous connecter :

import { InferenceClient } from '@huggingface/inference';

const hf = new InferenceClient("hf_xxxxxxxxxxxxxx", {
	endpointUrl: "https://j3z5luu0ooo76jnl.us-east-1.aws.endpoints.huggingface.cloud/v1/",
});

const response = await hf.chatCompletion({
	messages: [
		{
			role: "user",
			content: "What is the capital of France?",
		},
	],
});

console.log(response.choices[0].message.content);

Par défaut, tous les appels à l’endpoint d’inférence attendent que le modèle soit chargé. Lorsque le scaling to 0 est activé sur l’endpoint, cela peut entraîner un temps d’attente non négligeable. Si vous préférez désactiver ce comportement et gérer vous-même les erreurs HTTP 500 renvoyées par l’endpoint, vous pouvez procéder ainsi :

const hf = new InferenceClient("hf_xxxxxxxxxxxxxx", {
	endpointUrl: "https://j3z5luu0ooo76jnl.us-east-1.aws.endpoints.huggingface.cloud/v1/",
});

const response = await hf.chatCompletion(
	{
		messages: [
			{
				role: "user",
				content: "What is the capital of France?",
			},
		],
	},
	{
		retry_on_error: false,
	}
);

Utilisation de points de terminaison locaux

Vous pouvez utiliser InferenceClient pour exécuter des complétions de chat avec des serveurs d’inférence locaux (llama.cpp, vllm, litellm server, TGI, mlx, etc.) fonctionnant sur votre propre machine. L’API doit être compatible avec l’API OpenAI.

import { InferenceClient } from '@huggingface/inference';

const hf = new InferenceClient(undefined, {
	endpointUrl: "http://localhost:8080",
});

const response = await hf.chatCompletion({
	messages: [
		{
			role: "user",
			content: "What is the capital of France?",
		},
	],
});

console.log(response.choices[0].message.content);

De manière similaire au client JS d'OpenAI, InferenceClient peut être utilisé pour exécuter une inférence de Chat Completion avec n'importe quel point de terminaison compatible avec l'API REST d'OpenAI.

Exécution des tests

HF_TOKEN="your access token" pnpm run test

Trouver des modèles appropriés

Nous disposons d’un projet de documentation informatif intitulé Tasks qui répertorie les modèles disponibles pour chaque tâche et explique en détail le fonctionnement de chaque tâche.

Il contient également des démonstrations, des exemples de sorties et d'autres ressources si vous souhaitez approfondir l'aspect machine learning.

Dépendances

@huggingface/tasks : Typages uniquement

Update on GitHub

←🤗 Bibliothèques JS de Hugging Face Référence de l'API→