wllama 評価: llama.cpp をブラウザ内に持ち込む Wasm バインディングの実力と境界
WebAssembly binding for llama.cpp - Enabling on-browser LLM inference
ひと目でわかる
- これは何？
- wllama は llama.cpp を WebAssembly に変換し、バックエンドなしでブラウザ内推論を可能にする TypeScript バインディングだ。WebGPU 対応と 2GB のファイルサイズ制限という二つの事実が、採用判断の分かれ目になる。
- 誰に向いている？
- サーバーを持たずにブラウザ内で完結する推論を試したい開発者、特に小規模モデルを扱うプロトタイプには向いている。一方、2GB を超えるモデルを単一ファイルで扱いたい場合や、COOP/COEP ヘッダを設定できないホスティング環境では前提が崩れる。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 2 日前です。
- 何の言語で書かれている？
- 主に TypeScript です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
wllama が埋めるのはサーバーとブラウザの間の隙間
LLM を動かすには通常、GPU を積んだサーバーとその前段の API が必要になる。wllama はこの前提を外し、llama.cpp を WebAssembly に変換してブラウザ内で推論を完結させる。README によれば、WebAssembly SIMD を使ってブラウザ上で直接推論でき、バックエンドも GPU も不要とされている。対象読者は、モデルの重みを手元の端末から出したくないアプリケーション、あるいはサーバー運用コストを避けたい小規模なツールを作る開発者だ。npm パッケージ @wllama/wllama として公開されており、TypeScript で書かれている。ライセンスは MIT。
推論は Worker の中で動き、UI スレッドを止めない
wllama のアーキテクチャで重要なのは、推論が Worker 内で実行される点だ。README は「Inference is done inside a worker, does not block UI render」と明記しており、生成中も画面の描画が止まらない。モデルの読み込みは loadModelFromHF で Hugging Face Hub から、あるいは loadModelFromUrl で任意の URL から行う。読み込み進捗は progressCallback で loaded と total を受け取れる。API 面では createChatCompletion が OpenAI 互換の形で提供され、messages、max_tokens、temperature、top_k、top_p といったパラメータをそのまま渡せる。スレッド数はブラウザの対応状況に応じて単一スレッド版とマルチスレッド版を自動で切り替える。強制的に単一スレッドにしたい場合は LoadModelConfig に n_threads: 1 を指定する。
WebGPU は既定で全レイヤを GPU に載せる
V3 系で WebGPU 対応が入り、V3.1 以降は自動で有効になる。README によれば、既定ではすべてのレイヤが GPU にオフロードされる。VRAM に収まらない場合は LoadModelParams の n_gpu_layers で調整する。例として n_gpu_layers: 4 を指定すると 4 レイヤだけが GPU に載り、0 にすると GPU 推論を無効化できる。Firefox や Safari で動かすための互換モードもあり、wllama.setCompat('default', 'firefox_safari') を呼ぶことで利用できるが、README はこのモードで性能が著しく低下すると述べている。ここは設計上のトレードオフとして率直に書かれている数少ない箇所だ。
2GB の壁と分割という回避策
wllama の最も明確な制約はファイルサイズだ。README は ArrayBuffer のサイズ制限を理由に最大ファイルサイズを 2GB としている。これを超えるモデルは分割して読み込む必要がある。分割には llama.cpp のリリースページから入手できる llama-gguf-split を使い、次のように実行する。
./llama-gguf-split --split-max-size 512M ./my_model.gguf ./my_model
README は 512MB 程度のチャンクに分割することを推奨している。理由は二つあり、並列ダウンロードによる速度向上と、一部の out-of-memory 問題の回避だ。量子化についても指示があり、Q4、Q5、Q6 が性能、ファイルサイズ、品質のバランス点とされ、imatrix を使う IQ 系は推論が遅く品質も低くなりうるとして推奨されていない。
マルチスレッドを有効にするにはヘッダ設定が要る
マルチスレッドビルドを有効にするには、Cross-Origin-Embedder-Policy と Cross-Origin-Opener-Policy のヘッダを配信側で付与する必要がある。README はこの制約を limitations として明示し、ffmpeg.wasm の議論を参照先に挙げている。つまり静的ホスティングサービスや、ヘッダを自由に設定できない環境では、自動切り替えの恩恵を受けられず単一スレッドで動くことになる。ここは見落としやすい。ローカルで動いても本番の CDN でヘッダが落ちていれば性能は別物になる。
Wasm バイナリはリポジトリに同梱されていない
npm からインストールする場合は問題にならないが、git リポジトリから使う場合は Wasm バイナリが事前ビルドされていない。README は Docker が必要だと述べ、次の手順を示している。
git submodule add https://github.com/ngxson/wllama.git wllama git submodule update --init --recursive cd wllama npm ci npm run build:wasm && npm run build
CDN から Wasm を読む WasmFromCDN も用意されているが、README 自身が「not recommended」と書いており、Wasm ファイルをプロジェクトに埋め込めない場合の最終手段という位置づけだ。セルフホストでビルドする場合、Emscripten ツールチェーンを含む Docker イメージの取得とビルド時間が継続的なコストになる。npm 依存はランタイムに存在しないと README は述べており、バンドルサイズの観点では有利だ。
transformers.js との違いはバックエンドの有無ではなく重みの形式
ブラウザ内推論の代替として transformers.js が挙げられる。両者を分けるのは API の形ではなく、モデルの読み込み経路だ。transformers.js は Hugging Face の ONNX 形式を前提とし、モデル変換のパイプラインが整っている。対して wllama は llama.cpp の GGUF を直接読み、llama-gguf-split による分割や量子化の選択がそのまま活きる。すでに GGUF のモデル資産と量子化の知見を持っているチームにとっては、wllama のほうが既存のワークフローに接続しやすい。逆に、ONNX への変換済みモデルしか持たない場合は transformers.js のほうが素直だ。どちらが優れているという話ではなく、手元のモデル形式がどちらに合うかで決まる。
導入前に確かめるべき三つのこと
最初に確認すべきはモデルサイズだ。2GB を超えるなら llama-gguf-split での分割が前提になり、分割後のファイルを並列に取得できる配信構成も必要になる。次に、配信先で COOP と COEP のヘッダを付与できるかどうか。これができないとマルチスレッドは効かない。最後に、WebGPU を使うなら n_gpu_layers を実機で調整する。既定では全レイヤが GPU に載るため、VRAM が足りない環境では読み込み自体が失敗しうる。README は n_gpu_layers: 0 で無効化できるとしているので、まず単一スレッドかつ GPU 無効で動作を確認し、そこからレイヤ数を上げていく順序が現実的だ。V3 系ではマルチモーダルとツール呼び出しも入っているが、これらは examples/multimodal と examples/tools にそれぞれ実例があり、対応状況はモデル側の能力に依存する。
編集部の結論
サーバーを持たずにブラウザ内で完結する推論を試したい開発者、特に小規模モデルを扱うプロトタイプには向いている。一方、2GB を超えるモデルを単一ファイルで扱いたい場合や、COOP/COEP ヘッダを設定できないホスティング環境では前提が崩れる。採用前に確認すべきは、対象モデルのサイズと分割の可否、そして配信先で Cross-Origin-Embedder-Policy と Cross-Origin-Opener-Policy を付与できるかどうかだ。
コミュニティノート