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 de la classification d'images, de la détection d'objets ou de 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 des 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!');
// Sortie : [{ label: 'POSITIVE', score: 0.999817686 }]

// IMPORTANT : Toujours disposer quand c'est fini 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 fini pour éviter les fuites mémoire. Consultez les exemples dans Code Examples pour les patterns 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 des modèles :

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

• 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 tendance/téléchargements, et consultez les fiches modèles pour les métriques de performance et les exemples d'utilisation.

3. Sélection du dispositif

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 quantization

Contrôlez la précision vs. la performance du modèle :

// 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

Note : 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 le streaming et le chat : Consultez Text Generation Guide pour :

• Sortie en streaming token par token 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 endpoints 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 zero-shot

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 un 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 zero-shot

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 (légende d'image)

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

Réponse à des questions sur documents

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

Détection d'objets zero-shot

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 Hugging Face Hub

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

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 en tout
• &sort=likes - Plus aimés par la communauté
• &sort=modified - Mis à jour récemment

Choisir le bon modèle

Prenez en compte ces facteurs lors de la sélection d'un modèle :

1. Taille du modèle

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

2. Quantization 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, légère perte de précision)
• q4 - Quantifié 4-bit (plus petit, perte de précision notable)

3. Compatibilité des tâches Consultez la fiche modèle pour :

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

4. Métriques de performance Les fiches modèles montrent généralement :

• Les scores de précision
• Les résultats des benchmarks
• La vitesse d'inférence
• Les exigences de 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 (ex. onnx-community/gemma-3-270m-it-ONNX)

// 3. Vérifier la fiche modèle pour :
//    - Taille du modèle : ~270M paramètres
//    - Quantization : q4 disponible
//    - Langue : Anglais
//    - Cas d'usage : Chat suivant 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 la version quantifiée pour une 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èles

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

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

Configuration avancée

Configuration d'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); // ex. '4.x'

// Paramètres courants
env.allowRemoteModels = true;  // Charger depuis Hugging Face Hub
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 est LogLevel.WARNING)
env.logLevel = LogLevel.INFO;

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

Patterns 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 sur 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, consultez :

→ Configuration Reference

ModelRegistry (v4)

ModelRegistry vous donne une visibilité et un contrôle sur les ressources du modèle avant de charger un pipeline. Utilisez-le pour estimer la taille du téléchargement, vérifier l'état du cache, inspecter les dtypes disponibles et effacer les artefacts en cache pour un tuple task/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 ressources 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 patterns de production et la couverture complète de l'API, consultez ModelRegistry Reference.

Tokenization autonome (@huggingface/tokenizers)

Pour les flux de travail de tokenization uniquement, utilisez @huggingface/tokenizers. C'est un paquet léger séparé utile quand vous avez besoin d'une tokenization/encodage rapide sans charger des pipelines d'inférence de modèle complets.

npm install @huggingface/tokenizers

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

Travailler avec les tenseurs

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

// Charger tokenizer et 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 l'entrée
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 aux runtimes

Utilisation de WebGPU

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

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

Note : Utilisez webgpu quand disponible et basculez vers WASM/CPU quand non supporté dans le runtime actuel.

Performance WASM

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

// Optimisé pour les navigateurs avec quantization
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 se composer de plusieurs fichiers. Suivez la progression du téléchargement en passant un callback à la fonction pipeline() :

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

// Suivre la progression pour 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} terminé`);
  }
}

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

Propriétés de ProgressInfo :

interface ProgressInfo {
  status: 'initiate' | 'download' | 'progress' | 'progress_total' | 'done' | 'ready';
  name: string;      // ID ou chemin du modèle
  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 le statut 'progress')
  total?: number;    // Octets totaux (uniquement pour le statut 'progress')
}

Pour des exemples complets incluant les UIs navigateur, les composants React, les barres de progression CLI et la logique de nouvelle tentative, consultez :

→ Pipeline Options - 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('Téléchargement du modèle échoué. Vérifiez la connexion Internet.');
  } else if (error.message.includes('ONNX')) {
    console.error('Exécution du modèle échouée. Vérifiez la compatibilité du modèle.');
  } else {
    console.error('Erreur inconnue :', error);
  }
}

Conseils de performance

1. Réutiliser les pipelines : Créer le pipeline une fois, réutiliser pour plusieurs inférences
2. Utiliser la quantization : Commencer avec q8 ou q4 pour une inférence plus rapide
3. Traitement par lots : Traiter plusieurs entrées ensemble quand possible
4. Mettre en cache les modèles : Les modèles sont automatiquement en cache (consultez Caching Reference pour les détails sur le Cache API navigateur, le 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 fini pour libérer la mémoire

Gestion de la mémoire

IMPORTANT : Toujours appeler pipe.dispose() quand c'est fini 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 (100 MB - plusieurs GB par modèle)

Quand disposer :

• Arrêt de l'application ou démontage du 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 des ressources GPU/CPU. La disposition est critique pour les limites de mémoire du navigateur et la stabilité du serveur.

Pour les patterns détaillés (nettoyage React, serveurs, navigateur), consultez Code Examples

Dépannage

Modèle non trouvé

• Vérifier que le modèle existe sur Hugging Face Hub
• Vérifier l'orthographe du nom du modèle
• Assurer que le modèle a des fichiers ONNX (chercher le dossier onnx dans le dépôt 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 la séquence avec max_length

Erreurs WebGPU

• Vérifier la compatibilité du navigateur (Chrome 113+, Edge 113+)
• Essayer dtype: 'fp16' si fp32 échoue
• Basculer vers WASM si WebGPU non disponible

Documentation de référence

Cette compétence

• Pipeline Options - Configurer pipeline() avec progress_callback, device, dtype, etc.
• Configuration Reference - Configuration globale env pour la mise en cache et le chargement de modèles
• ModelRegistry Reference - Inspecter les fichiers, l'état du cache, les dtypes et effacer le cache avant de charger les pipelines
• Caching Reference - Cache API navigateur, cache du système de fichiers Node.js et implémentations de cache personnalisées
• Text Generation Guide - Streaming, format chat et paramètres de génération
• Model Architectures - Modèles supportés et conseils de sélection
• Code Examples - Implémentations du monde réel pour différents runtimes

Transformers.js officiel

• Documentation officielle : 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 fini - 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 fin
3. Tester localement d'abord : Tester les modèles avec de petites entrées avant de déployer
4. Surveiller les tailles de modèles : Être conscient des tailles de téléchargement de modèles 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èles spécifiques pour la stabilité en production
7. Limites d'erreurs : Toujours wrapper les appels de pipeline dans des blocs try-catch
8. Amélioration progressive : Fournir des fallbacks 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âches

Cette compétence vous permet d'intégrer directement des capacités de machine learning de pointe dans les applications JavaScript sans avoir besoin de serveurs ML séparés ou d'environnements Python.