Transformers.js - JavaScript向け機械学習

Transformers.js により、ブラウザとサーバーサイドランタイム (Node.js、Bun、Deno) 全体で最先端の機械学習モデルを JavaScript で直接実行できます。Python サーバーは不要です。

このスキルを使用する場合

次の場合にこのスキルを使用してください:

• JavaScript でテキスト分析、生成、翻訳用の ML モデルを実行する必要がある
• 画像分類、物体検出、またはセグメンテーションを実行する
• 音声認識または音声処理を実装する
• マルチモーダル AI アプリケーション (テキストから画像へ、画像からテキストへなど) を構築する
• バックエンドなしでクライアント側でブラウザ内でモデルを実行する

インストール

NPM インストール

npm install @huggingface/transformers

ブラウザ使用法 (CDN)

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

コア概念

1. Pipeline API

Pipeline API は、モデルを使用する最も簡単な方法です。前処理、モデル推論、後処理をまとめます:

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

// 特定のタスク用のパイプラインを作成
const pipe = await pipeline('sentiment-analysis');

// パイプラインを使用
const result = await pipe('I love transformers!');
// 出力: [{ label: 'POSITIVE', score: 0.999817686 }]

// 重要: メモリを解放するために、完了時に常に dispose を使用してください
await pipe.dispose();

⚠️ メモリ管理: すべてのパイプラインは、メモリリークを防ぐために完了時に pipe.dispose() で破棄する必要があります。異なる環境でのクリーンアップパターンについては、Code Examples の例を参照してください。

2. モデル選択

2 番目の引数としてカスタムモデルを指定できます:

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

モデルの検索:

Hugging Face Hub で利用可能な Transformers.js モデルを参照:

• すべてのモデル: https://huggingface.co/models?library=transformers.js&sort=trending
• タスク別: pipeline_tag パラメータを追加
  • テキスト生成: https://huggingface.co/models?pipeline_tag=text-generation&library=transformers.js&sort=trending
  • 画像分類: https://huggingface.co/models?pipeline_tag=image-classification&library=transformers.js&sort=trending
  • 音声認識: https://huggingface.co/models?pipeline_tag=automatic-speech-recognition&library=transformers.js&sort=trending

ヒント: タスク タイプでフィルタリングし、トレンディング/ダウンロードで並べ替え、パフォーマンス メトリクスと使用例についてモデル カードを確認してください。

3. デバイス選択

モデルを実行する場所を選択:

// CPU で実行 (WASM のデフォルト)
const pipe = await pipeline('sentiment-analysis', 'model-id');

// GPU で実行 (WebGPU)
const pipe = await pipeline('sentiment-analysis', 'model-id', {
  device: 'webgpu',
});

4. 量子化オプション

モデルの精度とパフォーマンスを制御:

// 量子化されたモデルを使用 (高速、小型)
const pipe = await pipeline('sentiment-analysis', 'model-id', {
  dtype: 'q4',  // オプション: 'fp32', 'fp16', 'q8', 'q4'
});

サポートされているタスク

注: 以下のすべての例は基本的な使用法を示しています。

自然言語処理

テキスト分類

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

固有表現認識 (NER)

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

質問応答

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.'
});

テキスト生成

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
});

ストリーミングとチャット: 詳細は Text Generation Guide を参照:

• TextStreamer によるトークンごとのストリーミング出力
• システム/ユーザー/アシスタント ロール付きチャット/会話形式
• 生成パラメータ (温度、top_k、top_p)
• ブラウザと Node.js の例
• React コンポーネントと API エンドポイント

翻訳

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'
});

要約

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

ゼロショット分類

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

コンピュータビジョン

画像分類

const classifier = await pipeline('image-classification');
const result = await classifier('https://example.com/image.jpg');
// またはローカルファイル
const result = await classifier(imageUrl);

物体検出

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

画像セグメンテーション

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

深度推定

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

ゼロショット画像分類

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

音声処理

自動音声認識

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

音声分類

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

テキスト音声合成

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

マルチモーダル

画像からテキスト (画像キャプション)

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

ドキュメント質問応答

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

ゼロショット物体検出

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

機能抽出 (埋め込み)

const extractor = await pipeline('feature-extraction');
const embeddings = await extractor('This is a sentence to embed.');
// 戻り値: 形状 [1, sequence_length, hidden_size] のテンソル

// 文埋め込みの場合 (平均プーリング)
const extractor = await pipeline('feature-extraction', 'onnx-community/all-MiniLM-L6-v2-ONNX');
const embeddings = await extractor('Text to embed', { pooling: 'mean', normalize: true });

モデルの検索と選択

Hugging Face Hub の閲覧

Hugging Face Hub で互換性のある Transformers.js モデルを発見:

ベース URL (すべてのモデル):

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

pipeline_tag パラメータを使用してタスク別にフィルタリング:

タスク	URL
テキスト生成	https://huggingface.co/models?pipeline_tag=text-generation&library=transformers.js&sort=trending
テキスト分類	https://huggingface.co/models?pipeline_tag=text-classification&library=transformers.js&sort=trending
翻訳	https://huggingface.co/models?pipeline_tag=translation&library=transformers.js&sort=trending
要約	https://huggingface.co/models?pipeline_tag=summarization&library=transformers.js&sort=trending
質問応答	https://huggingface.co/models?pipeline_tag=question-answering&library=transformers.js&sort=trending
画像分類	https://huggingface.co/models?pipeline_tag=image-classification&library=transformers.js&sort=trending
物体検出	https://huggingface.co/models?pipeline_tag=object-detection&library=transformers.js&sort=trending
画像セグメンテーション	https://huggingface.co/models?pipeline_tag=image-segmentation&library=transformers.js&sort=trending
音声認識	https://huggingface.co/models?pipeline_tag=automatic-speech-recognition&library=transformers.js&sort=trending
音声分類	https://huggingface.co/models?pipeline_tag=audio-classification&library=transformers.js&sort=trending
画像からテキスト	https://huggingface.co/models?pipeline_tag=image-to-text&library=transformers.js&sort=trending
機能抽出	https://huggingface.co/models?pipeline_tag=feature-extraction&library=transformers.js&sort=trending
ゼロショット分類	https://huggingface.co/models?pipeline_tag=zero-shot-classification&library=transformers.js&sort=trending

ソートオプション:

• &sort=trending - 最近最も人気がある
• &sort=downloads - 全体でダウンロード数が多い
• &sort=likes - コミュニティで最も好評
• &sort=modified - 最近更新された

適切なモデルの選択

モデルを選択する際に、次の要因を考慮してください:

1. モデルサイズ

• 小 (< 100MB): 高速、ブラウザに適している、精度は限定的
• 中 (100MB - 500MB): バランスの取れたパフォーマンス、ほとんどのユースケースに適している
• 大 (> 500MB): 高精度、遅い、Node.js または強力なデバイスに適している

2. 量子化 モデルはしばしば異なる量子化レベルで利用可能です:

• fp32 - 完全精度 (最大、最も正確)
• fp16 - 半精度 (より小型、それでも正確)
• q8 - 8 ビット量子化 (はるかに小型、わずかな精度の損失)
• q4 - 4 ビット量子化 (最小、顕著な精度の損失)

3. タスク互換性 モデルカードで次の確認:

• サポートされているタスク (一部のモデルは複数のタスクをサポート)
• 入出力形式
• 言語サポート (多言語対応 vs 英語のみ)
• ライセンス制限

4. パフォーマンスメトリクス モデルカードには通常次のが表示されます:

• 精度スコア
• ベンチマーク結果
• 推論速度
• メモリ要件

例: テキスト生成モデルの検索

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

// 2. ブラウズしてモデルを選択 (例: onnx-community/gemma-3-270m-it-ONNX)

// 3. モデルカードで次を確認:
//    - モデルサイズ: 約 270M パラメータ
//    - 量子化: q4 利用可能
//    - 言語: 英語
//    - ユースケース: 指示に従う会話

// 4. モデルを使用:
import { pipeline } from '@huggingface/transformers';

const generator = await pipeline(
  'text-generation',
  'onnx-community/gemma-3-270m-it-ONNX',
  { dtype: 'q4' } // 量子化バージョンを使用して推論を高速化
);

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

await generator.dispose();

モデル選択のヒント

1. 小さく始める: まず小さいモデルでテストし、必要に応じてアップグレードしてください
2. ONNX サポートを確認: モデルに ONNX ファイルがあることを確認してください (モデル リポジトリで onnx フォルダを探してください)
3. モデルカードを読む: モデルカードには使用例、制限事項、ベンチマークが含まれています
4. ローカルでテストする: 自分の環境で推論速度とメモリ使用量をベンチマークしてください
5. ライブラリでフィルタリング: library=transformers.js を使用して互換性のあるモデルを見つけてください: https://huggingface.co/models?library=transformers.js
6. バージョンピン: 本番環境では安定性のために特定のコミットを使用:

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

高度な設定

環境設定 (env)

env オブジェクトは、Transformers.js の実行、キャッシング、モデル読み込みを包括的に制御します。

クイック概要:

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

// バージョンを確認
console.log(env.version); // 例: '4.x'

// 一般的な設定
env.allowRemoteModels = true;  // Hugging Face Hub から読み込み
env.allowLocalModels = false;  // ファイルシステムから読み込み
env.localModelPath = '/models/'; // ローカルモデルディレクトリ
env.useFSCache = true;         // ディスクにモデルをキャッシュ (Node.js)
env.useBrowserCache = true;    // ブラウザにモデルをキャッシュ
env.cacheDir = './.cache';     // キャッシュディレクトリの位置
// オプション: ログレベルをオーバーライド (デフォルトは LogLevel.WARNING)
env.logLevel = LogLevel.INFO;

// オプション: 認可ヘッダー、リトライ、中止シグナルなどのカスタム fetch
env.fetch = (url, options) =>
  fetch(url, {
    ...options,
    headers: {
      ...options?.headers,
      Authorization: `Bearer ${HF_TOKEN}`,
    },
  });

設定パターン:

// 開発: リモートモデルで高速イテレーション
env.allowRemoteModels = true;
env.useFSCache = true;

// 本番: ローカルモデルのみ
env.allowRemoteModels = false;
env.allowLocalModels = true;
env.localModelPath = '/app/models/';

// カスタム CDN
env.remoteHost = 'https://cdn.example.com/models';

// キャッシングを無効化 (テスト)
env.useFSCache = false;
env.useBrowserCache = false;

すべての設定オプション、キャッシング戦略、キャッシュ管理、モデルの事前ダウンロードなどの完全なドキュメントについては、以下を参照してください:

→ Configuration Reference

ModelRegistry (v4)

ModelRegistry により、パイプラインをロードする前にモデルアセットの可視性と制御が得られます。ダウンロードサイズを見積もり、キャッシュステータスを確認し、利用可能な dtype を検査し、特定のタスク/モデル/オプションチュープルのキャッシュされたアーティファクトをクリアします。

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

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

// このパイプラインに必要なファイルをリスト
const files = await ModelRegistry.get_pipeline_files(task, modelId, modelOptions);

// アセットがすでにキャッシュされているかを確認
const cached = await ModelRegistry.is_pipeline_cached(task, modelId, modelOptions);

// このモデルで利用可能な精度形式を検査
const dtypes = await ModelRegistry.get_available_dtypes(modelId);

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

本番環境パターンと完全な API カバレッジについては、ModelRegistry Reference を参照してください。

スタンドアロン トークナイズ (@huggingface/tokenizers)

トークナイズのみのワークフローの場合は、@huggingface/tokenizers を使用してください。完全なモデル推論パイプラインをロードせずに高速なトークナイズ/エンコーディングが必要な場合に便利な、個別の軽量パッケージです。

npm install @huggingface/tokenizers

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

テンソルの操作

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

// より細かく制御するためにトークナイザーとモデルを個別にロード
const tokenizer = await AutoTokenizer.from_pretrained('bert-base-uncased');
const model = await AutoModel.from_pretrained('bert-base-uncased');

// 入力をトークナイズ
const inputs = await tokenizer('Hello world!');

// モデルを実行
const outputs = await model(inputs);

バッチ処理

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

// 複数のテキストを処理
const results = await classifier([
  'I love this!',
  'This is terrible.',
  'It was okay.'
]);

ランタイム固有の考慮事項

WebGPU 使用法

WebGPU はブラウザとサーバーサイドランタイム (サポートされている場合) に GPU アクセラレーションを提供:

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

注: サポートされている場合は webgpu を使用し、現在のランタイムでサポートされていない場合は WASM/CPU にフォールバック。

WASM パフォーマンス

WASM はランタイム間で最も互換性のある実行バックエンド:

// 量子化を使用してブラウザ向けに最適化
const pipe = await pipeline('sentiment-analysis', 'model-id', {
  dtype: 'q8'  // さらに小さいサイズの場合は 'q4'
});

進捗追跡と読み込みインジケータ

モデルは大きくなる可能性があり (数 MB から数 GB)、複数のファイルで構成されています。pipeline() 関数にコールバックを渡すことで、ダウンロードの進行状況を追跡:

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

// 各ファイルの進行状況を追跡
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`);
  }
}

// パイプラインにコールバックを渡す
const classifier = await pipeline('sentiment-analysis', null, {
  progress_callback: onProgress
});

進捗情報プロパティ:

interface ProgressInfo {
  status: 'initiate' | 'download' | 'progress' | 'progress_total' | 'done' | 'ready';
  name: string;      // モデル ID またはパス
  file?: string;     // 処理中のファイル (ファイルごとのイベント)
  progress?: number; // パーセンテージ (0-100, 'progress' および 'progress_total')
  loaded?: number;   // ダウンロード済みバイト ('progress' ステータスのみ)
  total?: number;    // 総バイト数 ('progress' ステータスのみ)
}

ブラウザ UI、React コンポーネント、CLI プログレスバー、リトライロジックを含む完全な例については、以下を参照:

→ Pipeline Options - Progress Callback

エラーハンドリング

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);
  }
}

パフォーマンスのコツ

1. パイプラインの再利用: パイプラインを一度作成し、複数の推論に再利用
2. 量子化を使用: 推論を高速化するために q8 または q4 から始める
3. バッチ処理: 可能な場合、複数の入力を一緒に処理
4. キャッシュモデル: モデルは自動的にキャッシュされます (Caching Reference を参照 ブラウザ Cache API、Node.js ファイルシステムキャッシュ、およびカスタム実装の詳細)
5. 大規模モデルに WebGPU を使用: GPU アクセラレーションの恩恵を受けるモデルに WebGPU を使用
6. コンテキストを削減: テキスト生成の場合、メモリの問題を避けるために max_new_tokens を制限
7. リソースをクリーンアップ: 完了時に pipe.dispose() を呼び出してメモリを解放

メモリ管理

重要: メモリリークを防ぐために、完了時に常に pipe.dispose() を呼び出してください。

const pipe = await pipeline('sentiment-analysis');
const result = await pipe('Great product!');
await pipe.dispose();  // ✓ メモリを解放 (100MB - 数 GB/モデル)

破棄するべき場合:

• アプリケーションシャットダウンまたはコンポーネントのアンマウント時
• 異なるモデルを読み込む前
• 長時間実行するアプリでのバッチ処理後

モデルは大量のメモリを消費し、GPU/CPU リソースを保持します。破棄はブラウザのメモリ制限とサーバーの安定性にとって重要です。

詳細なパターン (React クリーンアップ、サーバー、ブラウザ) については、Code Examples を参照

トラブルシューティング

モデルが見つからない

• モデルが Hugging Face Hub に存在することを確認
• モデル名の綴りを確認
• モデルに ONNX ファイルがあることを確認 (モデルリポジトリで onnx フォルダを探してください)

メモリの問題

• より小さいモデルまたは量子化されたバージョン (dtype: 'q4') を使用
• バッチサイズを削減
• max_length でシーケンス長を制限

WebGPU エラー

• ブラウザの互換性を確認 (Chrome 113+、Edge 113+)
• fp32 が失敗する場合は dtype: 'fp16' を試す
• WebGPU が利用できない場合は WASM にフォールバック

リファレンスドキュメント

このスキル

• Pipeline Options - progress_callback、device、dtype などで pipeline() を設定
• Configuration Reference - キャッシングとモデル読み込みのグローバル env 設定
• ModelRegistry Reference - ファイル、キャッシュステータス、dtype を検査し、パイプラインをロードする前にキャッシュをクリア
• Caching Reference - ブラウザ Cache API、Node.js ファイルシステムキャッシュ、およびカスタムキャッシュ実装
• Text Generation Guide - ストリーミング、チャット形式、生成パラメータ
• Model Architectures - サポートされているモデルと選択のヒント
• Code Examples - 異なるランタイムの実装例

公式 Transformers.js

• 公式ドキュメント: https://huggingface.co/docs/transformers.js
• API リファレンス: https://huggingface.co/docs/transformers.js/api/pipelines
• モデルハブ: https://huggingface.co/models?library=transformers.js
• GitHub: https://github.com/huggingface/transformers.js
• 例: https://github.com/huggingface/transformers.js-examples

ベストプラクティス

1. 常にパイプラインを破棄: 完了時に pipe.dispose() を呼び出す - メモリリークの防止に重要
2. パイプラインから始める: きめ細かい制御が必要でない限り、Pipeline API を使用
3. ローカルで最初にテスト: デプロイ前に小さな入力でモデルをテスト
4. モデルサイズを監視: Web アプリケーションのモデルダウンロード サイズを認識
5. 読み込み状態を処理: UX を向上させるために進捗インジケータを表示
6. バージョンピン: 本番環境の安定性のために特定のモデルバージョンをピン留め
7. エラーバウンダリ: パイプライン呼び出しを常に try-catch ブロックでラップ
8. 段階的拡張: サポートされていないブラウザのフォールバックを提供
9. モデルを再利用: 一度読み込み、何度も使用 - パイプラインを不必要に再作成しない
10. グレースフルシャットダウン: サーバーで SIGTERM/SIGINT 時にモデルを破棄

クイックリファレンス: タスク ID

タスク	タスク ID
テキスト分類	text-classification または sentiment-analysis
トークン分類	token-classification または ner
質問応答	question-answering
マスク埋め込み	fill-mask
要約	summarization
翻訳	translation
テキスト生成	text-generation
テキスト対テキスト生成	text2text-generation
ゼロショット分類	zero-shot-classification
画像分類	image-classification
画像セグメンテーション	image-segmentation
物体検出	object-detection
深度推定	depth-estimation
画像から画像へ	image-to-image
ゼロショット画像分類	zero-shot-image-classification
ゼロショット物体検出	zero-shot-object-detection
自動音声認識	automatic-speech-recognition
音声分類	audio-classification
テキスト音声合成	text-to-speech または text-to-audio
画像からテキスト	image-to-text
ドキュメント質問応答	document-question-answering
機能抽出	feature-extraction
文類似度	sentence-similarity

---

このスキルにより、別々の ML サーバーや Python 環境を必要とせずに、最先端の機械学習機能を JavaScript アプリケーションに統合できます。