Transformers.jsのdtype・device・キャッシュを整理｜モデル読込失敗を減らす

モデル読込で迷わない：Transformers.jsのdtype・device・キャッシュ ブラウザAI・モデル配布
カテゴリー
ブラウザAI・モデル配布
公開日
2026.09.09

はじめに

Transformers.jsのモデル読込で混同しやすいのがdtype、device、キャッシュです。

  • dtype：どの精度・量子化のモデルファイルを読むか
  • device：どの実行基盤で計算するか
  • キャッシュ：取得したモデルやWASMを再利用するか

この記事では、感情分析パイプラインを例に、WebGPUを試して失敗時はWASMへ戻る読込処理を作ります。「q4なら必ず速い」「WebGPUならどのdtypeでも動く」といった決め付けを避けるのが目的です。

準備

mkdir transformers-loader
cd transformers-loader
npm init -y
npm install @huggingface/transformers@4.2.0
npm install --save-dev vite

最小のローダー

import { env, pipeline } from "@huggingface/transformers";

env.useBrowserCache = true;
env.useWasmCache = true;

const attempts = [
  { device: "webgpu", dtype: "fp16" },
  { device: "webgpu", dtype: "q4" },
  { device: "wasm", dtype: "q8" },
];

export async function loadClassifier(onProgress = console.log) {
  const errors = [];

  for (const options of attempts) {
    try {
      const classifier = await pipeline(
        "sentiment-analysis",
        "Xenova/distilbert-base-uncased-finetuned-sst-2-english",
        { ...options, progress_callback: onProgress },
      );
      return { classifier, options };
    } catch (error) {
      errors.push({ options, message: String(error) });
    }
  }

  throw new AggregateError(
    errors.map((item) => new Error(`${JSON.stringify(item.options)}: ${item.message}`)),
    "利用できるモデル構成がありません",
  );
}

モデルリポジトリに指定したdtypeのONNXファイルがなければ、その組み合わせは失敗します。アプリ側の候補を増やす前に、対象リポジトリのonnxフォルダーを確認してください。

実行する

import { loadClassifier } from "./loader.js";

const status = document.querySelector("#status");

try {
  const { classifier, options } = await loadClassifier((event) => {
    if (event.status === "progress") {
      status.textContent = `${event.file}: ${Math.round(event.progress)}%`;
    }
  });

  const result = await classifier("This library is useful.");
  status.textContent = `${options.device}/${options.dtype}: ${JSON.stringify(result)}`;
} catch (error) {
  status.textContent = String(error);
}

進捗イベントの形は処理段階で異なるため、progressが存在するときだけ丸めます。

モジュールごとにdtypeを変える場合

複数のONNXサブモデルを持つモデルでは、オブジェクト形式を受け付ける場合があります。

const transcriber = await pipeline(
  "automatic-speech-recognition",
  "onnx-community/whisper-tiny",
  {
    device: "webgpu",
    dtype: {
      encoder_model: "fp32",
      decoder_model_merged: "q4",
    },
  },
);

キーはモデル構成によって異なります。別モデルのキーをコピーせず、対象リポジトリのファイル名と設定を確認します。1つのdtype文字列で十分なモデルに、無理にオブジェクトを指定する必要はありません。

キャッシュと更新の考え方

ブラウザ環境では利用可能ならCache APIが使われます。useBrowserCacheはモデル、useWasmCacheはONNX RuntimeのWASMバイナリとファクトリーの再利用に関係します。

キャッシュは2回目を速くしますが、初回ダウンロード容量は減りません。また、モデルを同じリポジトリ名のまま更新すると再現性が崩れます。本番ではコミットリビジョンを固定できる配信方法、モデルのハッシュ、更新時のキャッシュキー変更を検討します。

ローカルモデルだけを許可する構成は次のようにします。

env.allowRemoteModels = false;
env.localModelPath = "/models/";

この設定後、必要な設定ファイル、Tokenizer、ONNXファイルを同一オリジンへ正しく配置します。配布物のライセンスもモデルカードで確認します。

動作確認

  • 1回目に進捗が表示され、分類結果が返る
  • 再読込後にキャッシュが使われる
  • WebGPUを無効にしてWASM候補へ進む
  • 存在しないdtypeを先頭にして次候補へ進む
  • オフライン初回は明確に失敗する
  • 採用したdevice/dtypeを画面またはログに残す

Cache Storageの削除は利用者データへ影響するため、テスト用プロファイルまたは専用オリジンで確認します。

制約

量子化は容量を減らせますが、モデル品質、対応演算、速度への影響はモデルと端末次第です。フォールバック候補を多数並べると、失敗するたびに別ファイルを取得して待ち時間と通信量が増える可能性があります。対象端末を決め、実測した少数の組み合わせに絞ります。

トラブル対処

  • 404になる：モデルリポジトリのonnxフォルダーに指定dtypeのファイルがあるか確認します。
  • 以前のモデルが使われる：開発用originのCache Storageとcache keyを確認します。
  • WebGPUで失敗：WASM候補へ切り替え、採用されたdeviceとdtypeを画面へ出します。

まとめ

dtypeはモデル表現、deviceは実行場所、キャッシュは取得物の再利用です。3つを分けて設定し、成功した構成を記録すれば、端末差のあるブラウザAIでも原因を追いやすくなります。

参考リンク

タイトルとURLをコピーしました