Transformers.js - Machine Learning pour JavaScript

Transformers.js permet d'exécuter des modèles de machine learning de pointe directement en JavaScript dans les navigateurs et les runtimes côté serveur (Node.js, Bun, Deno), sans serveur Python requis.

Quand utiliser cette compétence

Utilisez cette compétence quand vous avez besoin de :

• Exécuter des modèles ML pour l'analyse, la génération ou la traduction de texte en JavaScript
• Effectuer la classification d'images, la détection d'objets ou la segmentation
• Implémenter la reconnaissance vocale ou le traitement audio
• Construire des applications IA multimodales (texte vers image, image vers texte, etc.)
• Exécuter des modèles côté client dans le navigateur sans backend

Installation

Installation NPM

npm install @huggingface/transformers

Utilisation dans le navigateur (CDN)

<script type="module">
  import { pipeline } from 'https://cdn.jsdelivr.net/npm/@huggingface/transformers';
</script>

Concepts fondamentaux

1. Pipeline API

L'API pipeline est le moyen le plus simple d'utiliser les modèles. Elle regroupe le prétraitement, l'inférence du modèle et le post-traitement :

import { pipeline } from '@huggingface/transformers';

// Créer un pipeline pour une tâche spécifique
const pipe = await pipeline('sentiment-analysis');

// Utiliser le pipeline
const result = await pipe('I love transformers!');
// Output: [{ label: 'POSITIVE', score: 0.999817686 }]

// IMPORTANT: Toujours disposer quand c'est terminé pour libérer la mémoire
await pipe.dispose();

⚠️ Gestion de la mémoire : Tous les pipelines doivent être disposés avec pipe.dispose() quand c'est terminé pour éviter les fuites mémoire. Voir les exemples dans Exemples de code pour les modèles de nettoyage dans différents environnements.

2. Sélection du modèle

Vous pouvez spécifier un modèle personnalisé comme deuxième argument :

const pipe = await pipeline(
  'sentiment-analysis',
  'Xenova/bert-base-multilingual-uncased-sentiment'
);

Trouver les modèles :

Parcourez les modèles compatibles avec Transformers.js sur le Hub Hugging Face :

• Tous les modèles : https://huggingface.co/models?library=transformers.js&sort=trending
• Par tâche : Ajouter le paramètre pipeline_tag
  • Génération de texte : https://huggingface.co/models?pipeline_tag=text-generation&library=transformers.js&sort=trending
  • Classification d'images : https://huggingface.co/models?pipeline_tag=image-classification&library=transformers.js&sort=trending
  • Reconnaissance vocale : https://huggingface.co/models?pipeline_tag=automatic-speech-recognition&library=transformers.js&sort=trending

Conseil : Filtrez par type de tâche, triez par tendances/téléchargements, et vérifiez les fiches de modèle pour les métriques de performance et les exemples d'utilisation.

3. Sélection de l'appareil

Choisissez où exécuter le modèle :

// Exécuter sur CPU (défaut pour WASM)
const pipe = await pipeline('sentiment-analysis', 'model-id');

// Exécuter sur GPU (WebGPU)
const pipe = await pipeline('sentiment-analysis', 'model-id', {
  device: 'webgpu',
});

4. Options de quantification

Contrôlez la précision du modèle par rapport à la performance :

// Utiliser un modèle quantifié (plus rapide, plus petit)
const pipe = await pipeline('sentiment-analysis', 'model-id', {
  dtype: 'q4',  // Options: 'fp32', 'fp16', 'q8', 'q4'
});

Tâches supportées

Remarque : Tous les exemples ci-dessous montrent l'utilisation basique.

Traitement du langage naturel

Classification de texte

const classifier = await pipeline('text-classification');
const result = await classifier('This movie was amazing!');

Reconnaissance d'entités nommées (NER)

const ner = await pipeline('token-classification');
const entities = await ner('My name is John and I live in New York.');

Réponse à des questions

const qa = await pipeline('question-answering');
const answer = await qa({
  question: 'What is the capital of France?',
  context: 'Paris is the capital and largest city of France.'
});

Génération de texte

const generator = await pipeline('text-generation', 'onnx-community/gemma-3-270m-it-ONNX');
const text = await generator('Once upon a time', {
  max_new_tokens: 100,
  temperature: 0.7
});

Pour la diffusion et le chat : Voir Guide de génération de texte pour :

• Sortie token par token en diffusion avec TextStreamer
• Format chat/conversation avec rôles système/utilisateur/assistant
• Paramètres de génération (température, top_k, top_p)
• Exemples pour navigateur et Node.js
• Composants React et points de terminaison API

Traduction

const translator = await pipeline('translation', 'Xenova/nllb-200-distilled-600M');
const output = await translator('Hello, how are you?', {
  src_lang: 'eng_Latn',
  tgt_lang: 'fra_Latn'
});

Résumé

const summarizer = await pipeline('summarization');
const summary = await summarizer(longText, {
  max_length: 100,
  min_length: 30
});

Classification sans exemples

const classifier = await pipeline('zero-shot-classification');
const result = await classifier('This is a story about sports.', ['politics', 'sports', 'technology']);

Vision par ordinateur

Classification d'images

const classifier = await pipeline('image-classification');
const result = await classifier('https://example.com/image.jpg');
// Ou avec fichier local
const result = await classifier(imageUrl);

Détection d'objets

const detector = await pipeline('object-detection');
const objects = await detector('https://example.com/image.jpg');
// Retourne: [{ label: 'person', score: 0.95, box: { xmin, ymin, xmax, ymax } }, ...]

Segmentation d'images

const segmenter = await pipeline('image-segmentation');
const segments = await segmenter('https://example.com/image.jpg');

Estimation de profondeur

const depthEstimator = await pipeline('depth-estimation');
const depth = await depthEstimator('https://example.com/image.jpg');

Classification d'images sans exemples

const classifier = await pipeline('zero-shot-image-classification');
const result = await classifier('image.jpg', ['cat', 'dog', 'bird']);

Traitement audio

Reconnaissance vocale automatique

const transcriber = await pipeline('automatic-speech-recognition');
const result = await transcriber('audio.wav');
// Retourne: { text: 'transcribed text here' }

Classification audio

const classifier = await pipeline('audio-classification');
const result = await classifier('audio.wav');

Synthèse vocale

const synthesizer = await pipeline('text-to-speech', 'Xenova/speecht5_tts');
const audio = await synthesizer('Hello, this is a test.', {
  speaker_embeddings: speakerEmbeddings
});

Multimodal

Image vers texte (Image captioning)

const captioner = await pipeline('image-to-text');
const caption = await captioner('image.jpg');

Réponse à des questions sur un document

const docQA = await pipeline('document-question-answering');
const answer = await docQA('document-image.jpg', 'What is the total amount?');

Détection d'objets sans exemples

const detector = await pipeline('zero-shot-object-detection');
const objects = await detector('image.jpg', ['person', 'car', 'tree']);

Extraction de caractéristiques (Embeddings)

const extractor = await pipeline('feature-extraction');
const embeddings = await extractor('This is a sentence to embed.');
// Retourne: tenseur de forme [1, sequence_length, hidden_size]

// Pour les embeddings de phrases (moyenne pooling)
const extractor = await pipeline('feature-extraction', 'onnx-community/all-MiniLM-L6-v2-ONNX');
const embeddings = await extractor('Text to embed', { pooling: 'mean', normalize: true });

Trouver et choisir des modèles

Parcourir le Hub Hugging Face

Découvrez les modèles compatibles avec Transformers.js sur le Hub Hugging Face :

URL de base (tous les modèles) :

https://huggingface.co/models?library=transformers.js&sort=trending

Filtrer par tâche en utilisant le paramètre pipeline_tag :

Options de tri :

• &sort=trending - Plus populaires récemment
• &sort=downloads - Plus téléchargés globalement
• &sort=likes - Plus aimés par la communauté
• &sort=modified - Récemment mis à jour

Choisir le bon modèle

Considérez ces facteurs lors de la sélection d'un modèle :

1. Taille du modèle

• Petit (< 100MB) : Rapide, approprié pour les navigateurs, précision limitée
• Moyen (100MB - 500MB) : Performance équilibrée, bon pour la plupart des cas d'usage
• Grand (> 500MB) : Haute précision, plus lent, meilleur pour Node.js ou appareils puissants

2. Quantification Les modèles sont souvent disponibles à différents niveaux de quantification :

• fp32 - Précision complète (plus grand, plus précis)
• fp16 - Demi-précision (plus petit, toujours précis)
• q8 - Quantifié 8-bit (beaucoup plus petit, perte de précision légère)
• q4 - Quantifié 4-bit (plus petit, perte de précision notable)

3. Compatibilité des tâches Vérifiez la fiche du modèle pour :

• Les tâches supportées (certains modèles supportent plusieurs tâches)
• Les formats d'entrée/sortie
• Support linguistique (multilingue vs. anglais uniquement)
• Restrictions de licence

4. Métriques de performance Les fiches de modèle affichent généralement :

• Les scores de précision
• Les résultats de benchmark
• La vitesse d'inférence
• Les exigences en mémoire

Exemple : Trouver un modèle de génération de texte

// 1. Visiter : https://huggingface.co/models?pipeline_tag=text-generation&library=transformers.js&sort=trending

// 2. Parcourir et sélectionner un modèle (par ex., onnx-community/gemma-3-270m-it-ONNX)

// 3. Vérifier la fiche du modèle pour :
//    - Taille du modèle : ~270M paramètres
//    - Quantification : q4 disponible
//    - Langue : Anglais
//    - Cas d'usage : Chat qui suit les instructions

// 4. Utiliser le modèle :
import { pipeline } from '@huggingface/transformers';

const generator = await pipeline(
  'text-generation',
  'onnx-community/gemma-3-270m-it-ONNX',
  { dtype: 'q4' } // Utiliser version quantifiée pour inférence plus rapide
);

const output = await generator('Explain quantum computing in simple terms.', {
  max_new_tokens: 100
});

await generator.dispose();

Conseils pour la sélection de modèle

1. Commencer par petit : Tester d'abord avec un petit modèle, puis mettre à niveau si nécessaire
2. Vérifier le support ONNX : S'assurer que le modèle a des fichiers ONNX (chercher le dossier onnx dans le repo du modèle)
3. Lire les fiches de modèle : Les fiches contiennent des exemples d'utilisation, les limitations et les benchmarks
4. Tester localement : Comparer la vitesse d'inférence et l'utilisation de mémoire dans votre environnement
5. Filtrer par bibliothèque : Utiliser library=transformers.js pour trouver les modèles compatibles : https://huggingface.co/models?library=transformers.js
6. Épingler la version : Utiliser des commits git spécifiques en production pour la stabilité :

   const pipe = await pipeline('task', 'model-id', { revision: 'abc123' });

Configuration avancée

Configuration de l'environnement (env)

L'objet env fournit un contrôle complet sur l'exécution de Transformers.js, la mise en cache et le chargement de modèles.

Aperçu rapide :

import { env, LogLevel } from '@huggingface/transformers';

// Voir la version
console.log(env.version); // par ex., '4.x'

// Paramètres courants
env.allowRemoteModels = true;  // Charger depuis le Hub Hugging Face
env.allowLocalModels = false;  // Charger depuis le système de fichiers
env.localModelPath = '/models/'; // Répertoire des modèles locaux
env.useFSCache = true;         // Mettre en cache les modèles sur disque (Node.js)
env.useBrowserCache = true;    // Mettre en cache les modèles dans le navigateur
env.cacheDir = './.cache';     // Emplacement du répertoire de cache
// Optionnel : remplacer le niveau de journalisation (défaut LogLevel.WARNING)
env.logLevel = LogLevel.INFO;

// Optionnel : fetch personnalisé pour les en-têtes d'authentification, les tentatives, les signaux d'annulation, etc.
env.fetch = (url, options) =>
  fetch(url, {
    ...options,
    headers: {
      ...options?.headers,
      Authorization: `Bearer ${HF_TOKEN}`,
    },
  });

Modèles de configuration :

// Développement : Itération rapide avec modèles distants
env.allowRemoteModels = true;
env.useFSCache = true;

// Production : Modèles locaux uniquement
env.allowRemoteModels = false;
env.allowLocalModels = true;
env.localModelPath = '/app/models/';

// CDN personnalisé
env.remoteHost = 'https://cdn.example.com/models';

// Désactiver la mise en cache (tests)
env.useFSCache = false;
env.useBrowserCache = false;

Pour la documentation complète de toutes les options de configuration, les stratégies de mise en cache, la gestion du cache, le pré-téléchargement de modèles, et plus, voir :

→ Référence de configuration

ModelRegistry (v4)

ModelRegistry vous donne une visibilité et un contrôle sur les actifs du modèle avant de charger un pipeline. Utilisez-le pour estimer la taille de téléchargement, vérifier l'état du cache, inspecter les dtypes disponibles, et effacer les artefacts mis en cache pour un tuple tâche/modèle/options spécifique.

import { ModelRegistry } from '@huggingface/transformers';

const task = 'feature-extraction';
const modelId = 'onnx-community/all-MiniLM-L6-v2-ONNX';
const modelOptions = { dtype: 'fp32' };

// Lister les fichiers requis pour ce pipeline
const files = await ModelRegistry.get_pipeline_files(task, modelId, modelOptions);

// Vérifier si les actifs sont déjà en cache
const cached = await ModelRegistry.is_pipeline_cached(task, modelId, modelOptions);

// Inspecter les formats de précision disponibles pour ce modèle
const dtypes = await ModelRegistry.get_available_dtypes(modelId);

console.log({ files: files.length, cached, dtypes });

Pour les modèles de production et la couverture complète de l'API, voir Référence ModelRegistry.

Tokenisation autonome (@huggingface/tokenizers)

Pour les workflows de tokenisation uniquement, utilisez @huggingface/tokenizers. C'est un package léger séparé utile quand vous avez besoin d'une tokenisation/encodage rapide sans charger les pipelines d'inférence du modèle complet.

npm install @huggingface/tokenizers

import { Tokenizer } from '@huggingface/tokenizers';

Travailler avec des tenseurs

import { AutoTokenizer, AutoModel } from '@huggingface/transformers';

// Charger le tokenizer et le modèle séparément pour plus de contrôle
const tokenizer = await AutoTokenizer.from_pretrained('bert-base-uncased');
const model = await AutoModel.from_pretrained('bert-base-uncased');

// Tokenizer input
const inputs = await tokenizer('Hello world!');

// Exécuter le modèle
const outputs = await model(inputs);

Traitement par lots

const classifier = await pipeline('sentiment-analysis');

// Traiter plusieurs textes
const results = await classifier([
  'I love this!',
  'This is terrible.',
  'It was okay.'
]);

Considérations spécifiques au runtime

Utilisation de WebGPU

WebGPU fournit une accélération GPU dans les navigateurs et les runtimes côté serveur (quand supportés) :

const pipe = await pipeline('text-generation', 'onnx-community/gemma-3-270m-it-ONNX', {
  device: 'webgpu',
  dtype: 'fp32'
});

Remarque : Utilisez webgpu quand c'est disponible et retombez sur WASM/CPU quand ce n'est pas supporté dans le runtime actuel.

Performance WASM

WASM est le backend d'exécution le plus compatible sur les runtimes :

// Optimisé pour les navigateurs avec quantification
const pipe = await pipeline('sentiment-analysis', 'model-id', {
  dtype: 'q8'  // ou 'q4' pour une taille encore plus petite
});

Suivi de la progression et indicateurs de chargement

Les modèles peuvent être volumineux (allant de quelques MB à plusieurs GB) et composés de plusieurs fichiers. Suivez la progression de téléchargement en passant un callback à la fonction pipeline() :

import { pipeline } from '@huggingface/transformers';

// Suivre la progression de chaque fichier
const fileProgress = {};

function onProgress(info) {
  if (info.status === 'progress_total') {
    console.log(`Total: ${info.progress.toFixed(1)}%`);
    return;
  }

  console.log(`${info.status}: ${info.file ?? ''}`);

  if (info.status === 'progress') {
    fileProgress[info.file] = info.progress;
    console.log(`${info.file}: ${info.progress.toFixed(1)}%`);
  }

  if (info.status === 'done') {
    console.log(`✓ ${info.file} complete`);
  }
}

// Passer le callback au pipeline
const classifier = await pipeline('sentiment-analysis', null, {
  progress_callback: onProgress
});

Propriétés de l'info de progression :

interface ProgressInfo {
  status: 'initiate' | 'download' | 'progress' | 'progress_total' | 'done' | 'ready';
  name: string;      // ID de modèle ou chemin
  file?: string;     // Fichier en cours de traitement (événements par fichier)
  progress?: number; // Pourcentage (0-100, pour 'progress' et 'progress_total')
  loaded?: number;   // Octets téléchargés (uniquement pour 'progress' status)
  total?: number;    // Total d'octets (uniquement pour 'progress' status)
}

Pour des exemples complets incluant les UIs de navigateur, les composants React, les barres de progression CLI et la logique de retry, voir :

→ Options de pipeline - Progress Callback

Gestion des erreurs

try {
  const pipe = await pipeline('sentiment-analysis', 'model-id');
  const result = await pipe('text to analyze');
} catch (error) {
  if (error.message.includes('fetch')) {
    console.error('Model download failed. Check internet connection.');
  } else if (error.message.includes('ONNX')) {
    console.error('Model execution failed. Check model compatibility.');
  } else {
    console.error('Unknown error:', error);
  }
}

Conseils de performance

1. Réutiliser les pipelines : Créer un pipeline une fois, réutiliser pour plusieurs inférences
2. Utiliser la quantification : Commencer avec q8 ou q4 pour une inférence plus rapide
3. Traiter par lots : Traiter plusieurs entrées ensemble quand c'est possible
4. Mettre en cache les modèles : Les modèles sont automatiquement en cache (voir Référence de mise en cache pour les détails sur l'API Cache des navigateurs, la mise en cache du système de fichiers Node.js, et les implémentations personnalisées)
5. WebGPU pour les grands modèles : Utiliser WebGPU pour les modèles qui bénéficient de l'accélération GPU
6. Élaguer le contexte : Pour la génération de texte, limiter max_new_tokens pour éviter les problèmes de mémoire
7. Nettoyer les ressources : Appeler pipe.dispose() quand c'est terminé pour libérer la mémoire

Gestion de la mémoire

IMPORTANT : Toujours appeler pipe.dispose() quand c'est terminé pour éviter les fuites mémoire.

const pipe = await pipeline('sentiment-analysis');
const result = await pipe('Great product!');
await pipe.dispose();  // ✓ Libérer la mémoire (100MB - plusieurs GB par modèle)

Quand disposer :

• Arrêt de l'application ou démontage de composant
• Avant de charger un modèle différent
• Après traitement par lots dans les applications longue durée

Les modèles consomment une mémoire significative et retiennent les ressources GPU/CPU. La disposition est critique pour les limites de mémoire du navigateur et la stabilité du serveur.

Pour des modèles détaillés (React cleanup, serveurs, navigateur), voir Exemples de code

Dépannage

Modèle non trouvé

• Vérifier que le modèle existe sur le Hub Hugging Face
• Vérifier l'orthographe du nom du modèle
• S'assurer que le modèle a des fichiers ONNX (chercher le dossier onnx dans le repo du modèle)

Problèmes de mémoire

• Utiliser des modèles plus petits ou des versions quantifiées (dtype: 'q4')
• Réduire la taille du lot
• Limiter la longueur de séquence avec max_length

Erreurs WebGPU

• Vérifier la compatibilité du navigateur (Chrome 113+, Edge 113+)
• Essayer dtype: 'fp16' si fp32 échoue
• Retomber sur WASM si WebGPU n'est pas disponible

Documentation de référence

Cette compétence

• Options de pipeline - Configurer pipeline() avec progress_callback, device, dtype, etc.
• Référence de configuration - Configuration globale env pour la mise en cache et le chargement de modèles
• Référence ModelRegistry - Inspecter les fichiers, l'état du cache, les dtypes, et effacer le cache avant de charger les pipelines
• Référence de mise en cache - API Cache des navigateurs, mise en cache du système de fichiers Node.js, et implémentations de cache personnalisées
• Guide de génération de texte - Diffusion, format chat et paramètres de génération
• Architectures de modèles - Modèles supportés et conseils de sélection
• Exemples de code - Implémentations du monde réel pour différents runtimes

Transformers.js officiel

• Docs officielles : https://huggingface.co/docs/transformers.js
• Référence API : https://huggingface.co/docs/transformers.js/api/pipelines
• Hub de modèles : https://huggingface.co/models?library=transformers.js
• GitHub : https://github.com/huggingface/transformers.js
• Exemples : https://github.com/huggingface/transformers.js-examples

Bonnes pratiques

1. Toujours disposer les pipelines : Appeler pipe.dispose() quand c'est terminé - critique pour éviter les fuites mémoire
2. Commencer avec les pipelines : Utiliser l'API pipeline sauf si vous avez besoin d'un contrôle plus fin
3. Tester localement d'abord : Tester les modèles avec des entrées petites avant de déployer
4. Surveiller les tailles de modèle : Être conscient des tailles de téléchargement de modèle pour les applications web
5. Gérer les états de chargement : Afficher les indicateurs de progression pour une meilleure UX
6. Épingler la version : Épingler les versions de modèle spécifiques pour la stabilité en production
7. Limites d'erreur : Toujours envelopper les appels de pipeline dans des blocs try-catch
8. Amélioration progressive : Fournir des alternatives pour les navigateurs non supportés
9. Réutiliser les modèles : Charger une fois, utiliser plusieurs fois - ne pas recréer les pipelines inutilement
10. Arrêt gracieux : Disposer les modèles sur SIGTERM/SIGINT dans les serveurs

Référence rapide : IDs de tâche