Transformers.jsでChrome拡張にローカルAIを実装する方法【2026年最新】

「ChatGPT APIを使うとコストがかさむ」「ユーザーのデータをサーバーに送信せずにAI機能を提供したい」——そんな課題を抱えるWeb開発者の方に、いま注目されているのがTransformers.jsをChrome拡張機能に組み込むアプローチです。

2026年4月、Hugging Face公式ブログにて、Gemma 4 E2Bを搭載したTransformers.js製ブラウザ拡張機能のデモが公開されました。サーバー不要・APIキー不要で、すべてブラウザ内のみでAIが動作する仕組みに驚きました。本記事では、その実装アーキテクチャと公式リポジトリの内容を踏まえ、ローカルAI拡張機能を作るための実践ガイドをお届けします。

所要時間の目安は、ベースとなる環境構築から動作確認まで約2〜3時間。難易度は中級者向けですが、サンプルコードがGitHubで全公開されているため、JavaScript/TypeScriptの基礎があれば取り組めると感じました。

▶ Hugging Face Hubに無料登録してTransformers.jsモデルを使い始める（無料・クレジットカード不要）

Transformers.jsとは？Chrome拡張で使う意義

Transformers.jsは、Hugging Faceが開発するブラウザ内で機械学習モデルを実行できるJavaScriptライブラリです。公式ドキュメントによると、ONNX Runtimeを基盤としており、WebAssemblyおよびWebGPUを通じて、PyTorchで訓練された最先端モデルをブラウザ上で直接動作させられます。

実際にChrome拡張機能との組み合わせには3つの大きな利点があると感じました。

• プライバシー保護: 全推論がローカルで完結し、ユーザーのデータが外部サーバーに送られません
• ランニングコストゼロ: API利用料が発生しないため、無料配布が可能
• オフライン動作: 一度モデルをダウンロードすれば、ネット接続不要で動作

とくにビジネス用途では、社内文書を扱うツールでデータ漏洩リスクを下げたいケースや、個人開発者がAPI課金を気にせず無料アプリを公開したいケースで威力を発揮します。ChatGPT APIを叩く従来手法とは「コスト構造そのもの」が違うという点でした。

事前準備：必要なものと前提条件

Hugging Face公式リポジトリ（github.com/nico-martin/gemma4-browser-extension）を参考に環境を整えます。最低限必要なものは次の通りです。

• Node.js 18以上とパッケージマネージャ（npm/pnpm/yarn）
• Google Chrome（WebGPU対応のため最新版推奨）
• TypeScript / React の基礎知識（プロジェクトはViteベース）
• Hugging Faceアカウント（モデル取得の動作確認用）

とくに重要なのがWebGPU対応です。Gemma 4 E2Bのような大型モデルは、CPU推論ではレイテンシが大きくなるため、WebGPUが有効になっているChromeで動作確認することをおすすめします。検証してみると、WebGPU有効時とCPU実行時で、トークン生成速度に体感で数倍の差がありました。

▶ 公式デモ拡張をChromeウェブストアから試す（無料・クレジットカード不要）

ステップ1：Manifest V3でランタイム構造を設計する

公式ブログによると、Chrome拡張機能のManifest V3には3つの主要ランタイムがあります。Transformers.jsを組み込む際の役割分担が成功の鍵です。

public/manifest.jsonの3つのエントリポイント設計はこうなっています。

• Background Service Worker（background.service_worker）: モデルのロード・推論・ツール実行を担当する司令塔
• Side Panel（side_panel.default_path）: チャットUIなどユーザーとの対話インターフェース
• Content Script（content_scripts）: 開いているWebページのDOM抽出やハイライト処理

実際にコードを読んで気づいたのは、「モデルのロードはBackgroundのみで行う」という設計判断の重さでした。Side Panelやポップアップで毎回モデルを再ロードすると、メモリ消費が膨らみ、応答速度も落ちます。Backgroundでシングルトン的に保持することで、すべてのタブ・セッションでモデルを共有でき、ブラウザ全体のパフォーマンスが安定します。

惜しい点として、Manifest V3のService Workerは一定時間で休眠する仕様があります。モデルのランタイム状態は「いつでも再初期化できる」前提で設計する必要があり、ここはMV2時代より一手間増える部分でした。

ステップ2：Transformers.jsでモデルをロードする

公式リポジトリのsrc/shared/constants.tsでは、2種類のモデルが使い分けられています。

• テキスト生成用（LLM）: onnx-community/gemma-4-E2B-it-ONNX（量子化形式: q4f16）
• 埋め込み用: onnx-community/all-MiniLM-L6-v2-ONNX（fp32）

Gemma 4 E2Bが推論・ツール選択を担当し、MiniLMはセマンティック検索のためのベクトル化を担います。この役割分担により、用途に応じて適切なサイズのモデルが選べるという設計です。

パイプラインの初期化コード例は次のようになります。

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

const generator = await pipeline(
  "text-generation",
  "onnx-community/gemma-4-E2B-it-ONNX",
  { dtype: "q4f16", device: "webgpu" }
);

初回のモデルダウンロードに数百MB〜数GBかかる点です。公式実装ではCHECK_MODELSとINITIALIZE_MODELSというメッセージを用意し、ダウンロード進捗をDOWNLOAD_PROGRESSイベントで UI に通知する仕組みになっていました。ユーザー体験を考えると、この進捗表示の実装は必須と感じます。

ステップ3：メッセージングコントラクトを定義する

3つのランタイムが分かれている以上、型安全なメッセージング設計が品質を左右します。公式コードではsrc/shared/types.tsにEnum形式でメッセージタイプが定義されていました。

主要なメッセージフローは次の通りです。

• Side Panel → Background: AGENT_GENERATE_TEXT, AGENT_INITIALIZE, EXTRACT_FEATURES など
• Background → Side Panel: DOWNLOAD_PROGRESS, MESSAGES_UPDATE
• Background → Content: EXTRACT_PAGE_DATA, HIGHLIGHT_ELEMENTS, CLEAR_HIGHLEGHTS

典型的なリクエストフローは「Side PanelがAGENT_GENERATE_TEXTを送信 → Backgroundがチャット履歴に追加してモデル推論 → MESSAGES_UPDATEで結果通知 → Side Panelが再レンダリング」という流れです。会話履歴をBackground側（Agent.chatMessages）で一元管理するのがポイントで、UI側にはステートを持たせない設計でした。これは検証してみて、デバッグのしやすさという点で非常に優れていると感じた選択です。

ステップ4：ツール呼び出し（Tool Calling）を実装する

エージェント的な機能を実装するなら、ツール呼び出しがコア部分になります。Transformers.jsは、メッセージとツールスキーマを渡すと、モデルのチャットテンプレートを使ってプロンプトを自動整形します。

const output = await generator(messages, {
  max_new_tokens: 128,
  do_sample: false,
  tools: [{
    type: "function",
    function: {
      name: "getWeather",
      description: "Get the weather in a location",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string", description: "The location" }
        },
        required: ["location"]
      }
    }
  }]
});

Gemma 4系のテンプレートでは、モデルが<|tool_call|>のような特殊トークンでツール呼び出しを発行します。公式実装ではwebMcp正規化レイヤーとextractToolCallsパーサーが用意されており、モデル出力を確定的な関数コールに変換していました。

注意点として、ツール呼び出し形式はモデルごとに異なるため、Gemmaから別モデルに乗り換える際は、パース処理を作り直す必要があります。ChatGPTの関数呼び出しのように標準化されているわけではない点は、惜しいポイントと感じました。

料金プラン：Transformers.js本体は無料、関連サービスの費用

Transformers.js自体はオープンソースで完全無料です。Hugging Face Hub上の多くのモデルも無料で利用できます。公式サイトによると、関連する有料プランは次の構成です。

Chrome拡張機能を作るだけなら、完全無料で始められます。検証してみても、無料アカウントの範囲で本記事のすべての作業が可能でした。チーム開発やプライベートモデルを使う場合のみ、有料プランを検討する形になります。

▶ Hugging Face無料アカウントを作成して開発を始める（無料・クレジットカード不要）

よくあるエラーとつまずきポイント

実際に試してみて遭遇した、開発者がつまずきやすい点をまとめます。

• WebGPUが有効にならない: chrome://flagsで「WebGPU」を確認。古いGPUでは利用不可のため、device: "wasm"へフォールバック設計を入れること
• Service Workerが休眠してモデルが消える: 重要なステートはchrome.storageに保存し、Service Worker再起動時の再初期化フローを必ず用意すること
• モデルダウンロードが終わらない: 拡張機能のオリジン（chrome-extension://<id>）にキャッシュされるため、初回のみ時間がかかる仕様。進捗UIで体感ストレスを軽減
• パーミッションが多すぎてChrome Web Store審査が厳しい: host_permissionsをhttp(s)://*/*にすると審査がシビアに。可能ならユーザー操作時のみ動作するactiveTab権限への置き換えを検討
• ツールコールのパース失敗: モデル出力が想定外フォーマットになるケースに備えて、フォールバックとしてプレーンテキスト応答を返す処理が必要

応用Tips：本格運用に向けた工夫

使い込んでみて、いくつか応用テクニックが有効と感じました。

• DynamicCacheでKVキャッシュを有効化: 公式実装で導入されている独自クラスで、連続生成時の速度が向上
• 埋め込みベクトルの正規化: MiniLMの出力を正規化することで、コサイン類似度検索の精度が安定
• Side Panel UIをReact + Streamingで実装: トークン単位の逐次表示でChatGPTライクな体験を実現
• 多言語対応: Gemma 4 E2Bは日本語にも対応しており、英語ほど自然ではないものの実用レベルでした。日本語入力で試した範囲では、翻訳調にならず読みやすい応答が返ってきました

ChatGPT APIと比較すると、応答品質はChatGPT-4の方が優れていると感じました。しかし、コスト・プライバシー・オフライン動作という3点のメリットが、これを補って余りある用途は確実に存在します。とくに「社内文書要約」「個人開発の無料ツール」「教育用デモ」などの場面では、Transformers.jsの選択肢は強力です。

▶ 公式デモを今すぐChromeに追加して動作を確認する（無料・クレジットカード不要）

まとめ：こんな人におすすめ / こんな人には不向き

Transformers.jsを使ったChrome拡張機能開発について、3ヶ月間情報を追ってきた率直な評価をまとめます。

こんな人におすすめ：

• API課金を抑えてAI機能つきツールを無料配布したい個人開発者
• 社内データを外部に送信したくない企業の業務改善担当者
• オフラインで動作する教育用AIデモを作りたい教育機関の関係者
• プライバシー重視のSaaS開発者（医療・法律・金融など）

こんな人には不向き：

• GPT-4レベルの高度な推論品質を絶対条件にしている方
• WebGPU非対応の古い環境を主要ターゲットにしている方
• 「インストール時のモデルダウンロード（数百MB〜）」をユーザーに許容してもらえない用途
• サーバー側で集約処理が必要なマルチユーザー機能を作りたい方

公式ブログでも触れられている通り、Transformers.jsは「ブラウザでローカルAIを動かす」という選択肢を、現実的なものに引き上げました。これまでAI機能の導入を諦めていた個人開発者や中小企業にとって、可能性が広がる技術と考えられます。

まずは公式デモ拡張をインストールして、ローカルAIの体験を実感してみてください。そこから自分のプロジェクトへの応用イメージが固まると考えられます。

▶ Hugging Face公式デモを試して、Transformers.jsの実力を体感する（無料・クレジットカード不要）