WebLLM を使ってブラウザ上で LLM を動かそうとしたとき、「モデルが読み込めない」「WASM ファイルが見つからない」といったエラーに遭遇したことはありませんか？

実は、WebLLM の読み込みエラーの多くは、CORS 設定・MIME 型・パス指定という 3 つの要因が絡み合って発生します。これらは一見すると複雑に思えますが、正しい原因を特定できれば、確実に解決できるんです。

この記事では、WebLLM が読み込めない原因を体系的に整理し、それぞれの解決策を具体的なコード例とともにお伝えします。初めて WebLLM に触れる方でも理解できるよう、エラーメッセージの読み方から実際の修正手順まで、段階的に解説していきますね。

背景

WebLLM におけるリソース読み込みの仕組み

WebLLM は、ブラウザ上で LLM（大規模言語モデル）を動作させるための画期的なライブラリです。その動作には、複数のファイルが必要になります。

具体的には以下の 3 種類のリソースを読み込む必要があります。

#	リソース種類	説明	ファイル例
1	モデルウェイト	学習済みパラメータデータ	*.bin, *.safetensors
2	WASM ライブラリ	推論ロジックの実行環境	*.wasm
3	設定ファイル	モデル構成情報	config.json, tokenizer.json

これらのファイルは通常、CDN（Content Delivery Network）や Hugging Face などの外部サーバーから読み込まれます。

リソース読み込み時に必要な技術要素

WebLLM がこれらのファイルを正しく読み込むためには、以下の 3 つの技術要素が正しく設定されている必要があるんです。

mermaidCopy codeflowchart LR
  browser["ブラウザ"] -->|リクエスト| server["Webサーバー"]
  server -->|CORS<br/>ヘッダー確認| cors_check{{"CORS<br/>チェック"}}
  cors_check -->|OK| mime_check{{"MIME型<br/>チェック"}}
  cors_check -->|NG| cors_error["CORSエラー"]
  mime_check -->|OK| path_check{{"パス<br/>チェック"}}
  mime_check -->|NG| mime_error["MIME型エラー"]
  path_check -->|OK| success["読み込み成功"]
  path_check -->|NG| path_error["404エラー"]

図で理解できる要点：

• ブラウザからのリクエストは 3 段階のチェックを通過する必要がある
• CORS チェック → MIME 型チェック → パスチェックの順で検証される
• いずれか 1 つでも失敗すると、対応するエラーが発生する

これら 3 つの要素が 1 つでも欠けていると、WebLLM は正しく動作しません。次のセクションでは、各要素で発生しうる課題について詳しく見ていきましょう。

課題

WebLLM の読み込みエラーは、主に以下の 3 つのカテゴリに分類できます。それぞれについて、具体的なエラーメッセージと発生原因を解説します。

CORS エラー：クロスオリジン制約による読み込み失敗

エラーコード

Error: CORS error

エラーメッセージ例

textCopy codeCross-Origin Request Blocked: The Same Origin Policy disallows
reading the remote resource at https://example.com/model.bin.
(Reason: CORS header 'Access-Control-Allow-Origin' missing).

発生条件

CORS エラーは、以下の状況で発生します。

• あなたの Web アプリケーション（https:​/​​/​myapp.com）から、異なるドメイン（https:​/​​/​cdn.example.com）上のモデルファイルを読み込もうとした場合
• サーバー側でAccess-Control-Allow-Originヘッダーが設定されていない場合
• プリフライトリクエスト（OPTIONS メソッド）に対するレスポンスが適切でない場合

原因の詳細

CORS（Cross-Origin Resource Sharing）は、ブラウザのセキュリティ機能です。同一オリジンポリシーにより、異なるドメイン間でのリソース共有は制限されています。

WebLLM で外部 CDN からモデルをロードする場合、その CDN が CORS ヘッダーを返さないと、ブラウザがリクエストをブロックしてしまうんです。

MIME 型エラー：WASM ファイルの型指定ミス

エラーコード

TypeError: Failed to execute 'compile' on 'WebAssembly'

エラーメッセージ例

textCopy codewasm streaming compile failed: TypeError: Failed to execute
'compile' on 'WebAssembly': Incorrect response MIME type.
Expected 'application/wasm'.

発生条件

MIME 型エラーは次のケースで発生します。

• WASM ファイル（.wasm）がapplication​/​wasm以外の MIME 型で配信されている場合
• サーバーが WASM 拡張子を認識せず、application​/​octet-streamやtext​/​plainで返している場合
• WebAssembly.instantiateStreaming()を使用している場合（この関数は正しい MIME 型を要求します）

原因の詳細

WebAssembly API のinstantiateStreaming関数は、パフォーマンス向上のため、ストリーミング形式で WASM ファイルをコンパイルします。この関数は、HTTP レスポンスの Content-Type ヘッダーがapplication​/​wasmであることを厳密にチェックするんです。

多くの Web サーバーは、デフォルトで WASM 拡張子の正しい MIME 型を知りません。その結果、誤った型で配信されてしまうことがあります。

パス問題：リソースの配置場所エラー

エラーコード

Error 404: Not Found

エラーメッセージ例

textCopy codeFailed to load model: No URL found for model ID
'Llama-3-8B-Instruct-q4f32_1-MLC'

textCopy codeGET https://example.com/models/llama.wasm 404 (Not Found)

発生条件

パス関連のエラーは、以下の場合に発生します。

• モデル ID がmodel_listに登録されていない場合
• 指定した URL が実際のファイル配置場所と一致していない場合
• 相対パスと絶対パスを誤って使用している場合
• ファイル名の大文字・小文字が一致していない場合（Linux や macOS では区別される）

原因の詳細

WebLLM では、モデル ID と実際のファイル URL を紐付ける必要があります。

以下の図は、モデル ID 解決の流れを示しています。

mermaidCopy codeflowchart TD
  start["アプリケーション"] -->|モデルID指定| engine["WebLLM Engine"]
  engine -->|ID検索| config["AppConfig"]
  config -->|model_list確認| found{{"モデルID<br/>存在する?"}}
  found -->|YES| url["URL取得"]
  found -->|NO| error1["ModelNotFoundError"]
  url -->|HTTP GET| server["サーバー"]
  server -->|ファイル確認| exists{{"ファイル<br/>存在する?"}}
  exists -->|YES| load_success["読み込み成功"]
  exists -->|NO| error2["404 Not Found"]

図で理解できる要点：

• モデル ID はAppConfigのmodel_listに登録されている必要がある
• ID が見つかっても、実際のファイルがサーバー上に存在しなければエラーになる
• 2 段階のチェック（ID 存在確認とファイル存在確認）を通過する必要がある

この仕組みを理解していないと、「コードでは正しい ID を指定しているのに読み込めない」という状況に陥ってしまいます。

次のセクションでは、これらの課題に対する具体的な解決策を見ていきましょう。

解決策

CORS 問題の解決方法

CORS エラーを解決するには、サーバー側の設定が最も確実な方法です。開発環境と本番環境、それぞれの対処法を見ていきます。

サーバー側での CORS 設定

Nginx での設定

Nginx サーバーの設定ファイル（通常は​/​etc​/​nginx​/​nginx.confまたは​/​etc​/​nginx​/​sites-available​/​default）に以下を追加します。

nginxCopy codeserver {
    listen 80;
    server_name example.com;

    # CORSヘッダーの設定
    add_header 'Access-Control-Allow-Origin' '*';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'Content-Type';

    location /models/ {
        alias /var/www/models/;
    }
}

このコードは、すべてのオリジンからのアクセスを許可します。

セキュリティ上の注意点：本番環境では*（ワイルドカード）ではなく、具体的なドメインを指定してください。

nginxCopy code# 本番環境での推奨設定
add_header 'Access-Control-Allow-Origin' 'https://myapp.com';

設定後は、Nginx をリロードします。

bashCopy codesudo systemctl reload nginx

Apache での設定

Apache の場合は、.htaccessファイルまたはメイン設定ファイル（​/​etc​/​apache2​/​apache2.conf）に以下を追加します。

apacheCopy code# mod_headersモジュールの有効化が必要
<IfModule mod_headers.c>
    Header set Access-Control-Allow-Origin "*"
    Header set Access-Control-Allow-Methods "GET, POST, OPTIONS"
    Header set Access-Control-Allow-Headers "Content-Type"
</IfModule>

本番環境では、特定のドメインのみを許可しましょう。

apacheCopy code# 特定ドメインのみ許可
<IfModule mod_headers.c>
    Header set Access-Control-Allow-Origin "https://myapp.com"
</IfModule>

mod_headers モジュールが有効になっているか確認してください。

bashCopy codesudo a2enmod headers
sudo systemctl restart apache2

開発環境での対処法

開発中は、プロキシサーバーを使用する方法が便利です。

Vite でのプロキシ設定

vite.config.tsファイルに以下を追加します。

typescriptCopy codeimport { defineConfig } from 'vite';

export default defineConfig({
  server: {
    proxy: {
      '/models': {
        target: 'https://huggingface.co',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/models/, ''),
      },
    },
  },
});

このコードは、​/​modelsへのリクエストを Hugging Face にプロキシします。changeOrigin: trueにより、ホストヘッダーがターゲット URL に書き換えられるんです。

Next.js でのプロキシ設定

Next.js の場合は、API Routes を使用します。

pages​/​api​/​proxy-model.tsファイルを作成します。

typescriptCopy codeimport type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // クエリパラメータからURLを取得
  const { url } = req.query

  if (!url || typeof url !== 'string') {
    return res.status(400).json({ error: 'URL parameter is required' })
  }

次に、実際のプロキシ処理を実装します。

typescriptCopy code  try {
    // 外部リソースを取得
    const response = await fetch(url)

    if (!response.ok) {
      return res.status(response.status).json({
        error: 'Failed to fetch resource'
      })
    }

最後に、CORS ヘッダーを付与してレスポンスを返します。

typescriptCopy code    // レスポンスヘッダーの設定
    res.setHeader('Access-Control-Allow-Origin', '*')
    res.setHeader('Content-Type', response.headers.get('Content-Type') || '')

    // バイナリデータを転送
    const buffer = await response.arrayBuffer()
    res.send(Buffer.from(buffer))

  } catch (error) {
    res.status(500).json({ error: 'Internal server error' })
  }
}

このコードは、外部リソースを取得し、CORS ヘッダーを追加して返す API エンドポイントを作成します。クライアント側からは、このエンドポイント経由でモデルをロードできるようになりますね。

MIME 型問題の解決方法

MIME 型エラーを解決するには、サーバーが WASM ファイルを正しい型で配信するよう設定する必要があります。

Nginx での設定

Nginx のmime.typesファイル（通常は​/​etc​/​nginx​/​mime.types）に以下を追加します。

nginxCopy codetypes {
    # 既存のMIME型定義
    text/html                             html htm shtml;
    text/css                              css;
    # ... その他の定義 ...

    # WASMのMIME型を追加
    application/wasm                      wasm;
}

または、設定ファイル内で直接指定することもできます。

nginxCopy codehttp {
    include mime.types;

    # WASMのMIME型を追加
    types {
        application/wasm wasm;
    }

    default_type application/octet-stream;

Nginx をリロードして設定を反映させます。

bashCopy codesudo nginx -t  # 設定ファイルの文法チェック
sudo systemctl reload nginx

Apache での設定

Apache の場合は、httpd.confまたは.htaccessに以下を追加してください。

apacheCopy code# WASMファイルのMIME型を設定
AddType application/wasm .wasm

設定後、Apache を再起動します。

bashCopy codesudo systemctl restart apache2

設定の確認方法

MIME 型が正しく設定されているか、ブラウザの開発者ツールで確認できます。

以下の手順で確認しましょう。

#	ステップ	操作内容
1	開発者ツールを開く	F12 キーまたは右クリック →「検証」
2	Network タブを選択	リクエスト一覧を表示
3	WASM ファイルをクリック	該当の.wasmファイルを探す
4	Headers タブを確認	Content-Typeの値を確認
5	値の検証	application​/​wasmであることを確認

Content-Typeがapplication​/​wasmになっていれば、設定は正しく動作しています。

クライアント側での回避策

サーバー設定を変更できない場合は、クライアント側でinstantiateStreamingの代わりにinstantiateを使用する方法もあります。

ただし、この方法はパフォーマンスが低下するため、推奨されません。

typescriptCopy code// 非推奨：MIME型チェックを回避
const response = await fetch('model.wasm');
const buffer = await response.arrayBuffer();
const module = await WebAssembly.instantiate(buffer);

typescriptCopy code// 推奨：正しいMIME型で配信
const module = await WebAssembly.instantiateStreaming(
  fetch('model.wasm')
);

可能な限り、サーバー側で MIME 型を正しく設定することをお勧めします。

パス問題の解決方法

パスエラーを解決するには、モデル ID と URL の対応関係を正しく設定することが重要です。

モデル設定の基本

WebLLM でカスタムモデルを使用する場合、AppConfigでモデル情報を定義します。

typescriptCopy codeimport * as webllm from '@mlc-ai/web-llm';

// モデル設定の型定義
interface ModelRecord {
  model: string; // モデルファイルのURL
  model_id: string; // モデルを識別するID
  model_lib: string; // WASMライブラリのURL
}

次に、実際の設定を作成します。

typescriptCopy code// カスタムモデル設定
const appConfig: webllm.AppConfig = {
  model_list: [
    {
      model:
        'https://huggingface.co/mlc-ai/Llama-3-8B-Instruct-q4f32_1-MLC',
      model_id: 'Llama-3-8B-Instruct-q4f32_1-MLC',
      model_lib:
        'https://cdn.example.com/models/Llama-3-8B-Instruct-q4f32_1-ctx4k_cs1k-webgpu.wasm',
    },
  ],
};

この設定により、モデル ID とファイルの場所が紐付けられます。

エンジンの初期化

設定した AppConfig を使用してエンジンを初期化しましょう。

typescriptCopy code// エンジン作成時にAppConfigを渡す
const engine = await webllm.CreateMLCEngine(
  'Llama-3-8B-Instruct-q4f32_1-MLC', // model_idを指定
  {
    appConfig: appConfig,

    // 読み込み進捗のコールバック
    initProgressCallback: (progress) => {
      console.log(`Loading: ${progress.text}`);
      console.log(`Progress: ${progress.progress * 100}%`);
    },
  }
);

このコードは、指定したモデル ID に対応する URL からファイルをダウンロードし、エンジンを初期化します。initProgressCallbackを設定すると、読み込みの進捗状況を確認できますね。

プリビルトモデルの使用

MLC が公式に提供するプリビルトモデルを使用する場合は、さらにシンプルです。

typescriptCopy code// プリビルトモデルの一覧から選択
const selectedModel = 'Llama-3-8B-Instruct-q4f32_1-MLC';

// AppConfigの指定不要
const engine = await webllm.CreateMLCEngine(selectedModel);

プリビルトモデルは、WebLLM が内部的に管理しているため、URL を指定する必要がありません。

パスエラーのデバッグ方法

404 エラーが発生した場合、以下の手順で原因を特定できます。

まず、ブラウザの開発者ツールで Network タブを開きます。

typescriptCopy code// デバッグ用のログ出力
const appConfig: webllm.AppConfig = {
  model_list: [
    {
      model: 'https://example.com/models/llama.bin',
      model_id: 'my-custom-model',
      model_lib: 'https://example.com/wasm/llama.wasm',
    },
  ],
};

// エラーハンドリング付きで初期化
try {
  const engine = await webllm.CreateMLCEngine(
    'my-custom-model',
    { appConfig }
  );
} catch (error) {
  console.error('Failed to load model:', error);
  // Networkタブで失敗したURLを確認
}

Network タブで、どの URL で 404 エラーが発生したかを確認してください。

次に、その URL にブラウザで直接アクセスして、ファイルが存在するか確認します。

よくあるパスの間違い

以下は、よくあるパス設定のミスです。

#	間違い例	問題点	正しい例
1	models​/​llama.bin	相対パスで曖昧	https:​/​​/​example.com​/​models​/​llama.bin
2	https:​/​​/​example.com​/​Models​/​	大文字・小文字の不一致	https:​/​​/​example.com​/​models​/​
3	file:​/​​/​​/​path​/​to​/​model	ローカルファイルパス	https:​/​​/​example.com​/​models​/​llama.bin
4	トレイリングスラッシュあり/なし混在	URL 末尾の不一致	統一する

絶対 URL を使用し、大文字・小文字を正確に指定することで、多くのパスエラーを防げます。

具体例

実際のプロジェクトで遭遇しやすいシナリオを 3 つ取り上げ、解決までの手順を示します。

ケース 1：Hugging Face のモデルが読み込めない

状況

Hugging Face 上のカスタムモデルを WebLLM で読み込もうとしたところ、以下のエラーが発生しました。

textCopy codeError: CORS header 'Access-Control-Allow-Origin' missing
Failed to load https://huggingface.co/username/model-name/resolve/main/model.bin

原因分析

Hugging Face は、新しい CDN ドメイン（https:​/​​/​cdn-lfs-us-1.hf.co）に移行していますが、古い URL を使用していた場合、CORS エラーが発生することがあります。

また、プライベートリポジトリの場合は、認証が必要になります。

解決手順

ステップ 1：正しい URL を使用する

Hugging Face の最新の CDN URL を確認します。

typescriptCopy code// 古い（非推奨）
const oldUrl =
  'https://huggingface.co/username/model-name/resolve/main/model.bin';

// 新しい（推奨）
const newUrl =
  'https://cdn-lfs-us-1.hf.co/repos/xx/yy/zzz/model.bin';

実際の CDN URL は、Hugging Face のリポジトリページで「Download」リンクを右クリックして確認できます。

ステップ 2：AppConfig の更新

取得した URL を AppConfig に設定しましょう。

typescriptCopy codeconst appConfig: webllm.AppConfig = {
  model_list: [
    {
      model:
        'https://cdn-lfs-us-1.hf.co/repos/xx/yy/zzz/model.bin',
      model_id: 'my-huggingface-model',
      model_lib:
        webllm.modelLibURLPrefix +
        webllm.modelVersion +
        '/Llama-3-8B-Instruct-q4f32_1-ctx4k_cs1k-webgpu.wasm',
    },
  ],
};

model_libには、互換性のある既存の WASM ライブラリを指定できます。

ステップ 3：プライベートリポジトリの場合

プライベートモデルを使用する場合は、プロキシ経由でアクセスします。

バックエンド API を作成します（例：Express.js）。

javascriptCopy codeconst express = require('express')
const fetch = require('node-fetch')
const app = express()

app.get('/api/model-proxy', async (req, res) => {
  const { url } = req.query

  // Hugging Face APIトークンを使用
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${process.env.HF_TOKEN}`
    }
  })

レスポンスに CORS ヘッダーを追加して返します。

javascriptCopy code  // CORSヘッダーを追加
  res.set('Access-Control-Allow-Origin', '*')
  res.set('Content-Type', response.headers.get('Content-Type'))

  const buffer = await response.buffer()
  res.send(buffer)
})

app.listen(3000, () => console.log('Proxy server running on port 3000'))

このプロキシサーバーを経由することで、認証が必要なモデルも安全に読み込めるようになります。

ケース 2：ローカル開発環境で WASM が読み込めない

状況

ローカルの開発サーバー（http:​/​​/​localhost:3000）で WebLLM を実行したところ、以下のエラーが発生しました。

textCopy codeTypeError: Failed to execute 'compile' on 'WebAssembly':
Incorrect response MIME type. Expected 'application/wasm'.

原因分析

開発サーバー（Vite、Webpack Dev Server 等）が、.wasmファイルを正しい MIME 型で配信していないことが原因です。

デフォルトでは、多くの開発サーバーは WASM 拡張子を認識しません。

解決手順

Vite の場合

vite.config.tsを編集して MIME 型を設定します。

typescriptCopy codeimport { defineConfig } from 'vite'

export default defineConfig({
  server: {
    headers: {
      // WASMファイルのMIME型を設定
      'Content-Type': 'application/wasm'
    },

さらに、WASM ファイルを静的アセットとして扱う設定を追加します。

typescriptCopy code    // WASMファイルの配信設定
    fs: {
      strict: false
    }
  },
  assetsInclude: ['**/*.wasm']
})

この設定により、.wasmファイルが正しい MIME 型で配信されるようになりますね。

Webpack Dev Server の場合

webpack.config.jsに MIME 型の設定を追加しましょう。

javascriptCopy codemodule.exports = {
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
    },

    // MIMEマッピングの追加
    setupMiddlewares: (middlewares, devServer) => {
      devServer.app.use((req, res, next) => {
        if (req.path.endsWith('.wasm')) {
          res.setHeader('Content-Type', 'application/wasm');
        }
        next();
      });
      return middlewares;
    },
  },
};

このミドルウェアは、.wasm拡張子のリクエストに対して正しい Content-Type ヘッダーを設定します。

Next.js の場合

Next.js では、next.config.jsにヘッダー設定を追加します。

javascriptCopy codemodule.exports = {
  async headers() {
    return [
      {
        // WASMファイルに対するヘッダー設定
        source: '/:path*.wasm',
        headers: [
          {
            key: 'Content-Type',
            value: 'application/wasm',
          },
        ],
      },
    ];
  },
};

この設定により、publicディレクトリ内の.wasmファイルが正しく配信されます。

ケース 3：本番環境へのデプロイ後に 404 エラー

状況

開発環境では正常に動作していた WebLLM アプリを本番環境（Vercel、Netlify など）にデプロイしたところ、モデルが読み込めなくなりました。

textCopy codeGET https://myapp.com/models/llama-model.bin 404 (Not Found)

原因分析

静的サイトホスティングサービスでは、ファイルサイズの制限があることが多いです。

#	サービス名	ファイルサイズ制限	デプロイサイズ制限
1	Vercel	最大 50MB/ファイル	最大 250MB
2	Netlify	最大 200MB/ファイル	最大 500MB
3	GitHub Pages	推奨 100MB 以下	推奨 1GB 以下

LLM モデルは数 GB 単位になることもあるため、これらの制限を超えてしまいます。

解決手順

ステップ 1：外部 CDN の使用

大容量ファイルは、外部のストレージサービスに配置しましょう。

以下は、主要なストレージサービスの比較表です。

#	サービス	無料枠	CORS 対応	推奨用途
1	AWS S3	5GB/月	○	本番環境
2	Google Cloud Storage	5GB/月	○	本番環境
3	Cloudflare R2	10GB/月	○	本番環境
4	Hugging Face	無制限	○	開発・公開モデル

AWS S3 を使用する場合の設定例を示します。

S3 バケットの CORS 設定（JSON 形式）です。

jsonCopy code[
  {
    "AllowedOrigins": ["https://myapp.com"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedHeaders": ["*"],
    "MaxAgeSeconds": 3600
  }
]

この設定により、指定したドメインからのアクセスが許可されます。

ステップ 2：WebLLM の設定更新

S3 の URL を AppConfig に設定しましょう。

typescriptCopy codeconst appConfig: webllm.AppConfig = {
  model_list: [
    {
      // S3バケットのURL
      model:
        'https://my-bucket.s3.amazonaws.com/models/llama-model.bin',
      model_id: 'production-llama-model',

      // WASMライブラリもS3に配置
      model_lib:
        'https://my-bucket.s3.amazonaws.com/wasm/llama.wasm',
    },
  ],
};

URL は、S3 バケットの公開 URL を使用してください。

ステップ 3：環境変数の活用

開発環境と本番環境で異なる URL を使い分けるため、環境変数を使用します。

.env.developmentファイルを作成します。

envCopy codeVITE_MODEL_BASE_URL=http://localhost:3000/models

.env.productionファイルも作成します。

envCopy codeVITE_MODEL_BASE_URL=https://my-bucket.s3.amazonaws.com/models

TypeScript コードで環境変数を参照します。

typescriptCopy codeconst MODEL_BASE_URL = import.meta.env.VITE_MODEL_BASE_URL;

const appConfig: webllm.AppConfig = {
  model_list: [
    {
      model: `${MODEL_BASE_URL}/llama-model.bin`,
      model_id: 'llama-model',
      model_lib: `${MODEL_BASE_URL}/llama.wasm`,
    },
  ],
};

この方法により、環境ごとに適切な URL が自動的に選択されます。

ステップ 4：デプロイの確認

デプロイ後、以下の点を確認しましょう。

typescriptCopy code// デバッグ用のログ出力
console.log('Model URL:', appConfig.model_list[0].model);
console.log('WASM URL:', appConfig.model_list[0].model_lib);

// エラーハンドリング
try {
  const engine = await webllm.CreateMLCEngine(
    'llama-model',
    {
      appConfig,
      initProgressCallback: (progress) => {
        console.log(`Loading: ${progress.text}`);
      },
    }
  );
  console.log('Engine loaded successfully!');
} catch (error) {
  console.error('Failed to load engine:', error);
}

ブラウザのコンソールでログを確認し、URL が正しく解決されているかチェックしてください。

エラーが解決しない場合の追加チェック

以下のチェックリストを確認しましょう。

#	チェック項目	確認方法	期待される結果
1	S3 バケットのパブリックアクセス	AWS コンソールで確認	パブリック読み取り許可
2	CORS ヘッダー	Network タブで確認	Access-Control-Allow-Originが設定されている
3	Content-Type	Network タブで確認	.wasmはapplication​/​wasm
4	ファイルの存在	URL に直接アクセス	ダウンロードが開始される
5	HTTPS プロトコル	URL のスキームを確認	https:​/​​/​で始まる

すべての項目をクリアすれば、本番環境でも正常に動作するはずです。

まとめ

WebLLM が読み込めない問題は、CORS・MIME 型・パスという 3 つの要素に起因することがほとんどです。それぞれの原因を正しく理解し、適切な解決策を適用することで、確実に問題を解決できます。

本記事で解説した内容を振り返りましょう。

重要ポイントの整理

CORS 問題の解決では、サーバー側でAccess-Control-Allow-Originヘッダーを設定することが最も確実な方法です。開発環境ではプロキシを活用し、本番環境では外部 CDN の CORS 設定を適切に行いましょう。

MIME 型問題の解決では、Web サーバーが WASM ファイルをapplication​/​wasmとして配信するよう設定します。Nginx、Apache、各種開発サーバーそれぞれに対応する設定方法を理解することが重要ですね。

パス問題の解決では、AppConfigでモデル ID と URL を正確に紐付けることが鍵となります。絶対 URL を使用し、環境変数で開発・本番環境を切り替えることで、柔軟な運用が可能になります。

トラブルシューティングの基本フロー

エラーが発生したら、以下の順序で原因を特定していきましょう。

#	ステップ	確認内容	ツール
1	エラーメッセージの確認	CORS か MIME 型か 404 か	ブラウザコンソール
2	Network タブの確認	失敗したリクエストの URL・ヘッダー	開発者ツール
3	URL の直接アクセス	ファイルが実際に存在するか	ブラウザアドレスバー
4	サーバー設定の確認	CORS・MIME 型が正しく設定されているか	サーバー設定ファイル
5	コードの検証	AppConfig が正しく記述されているか	エディタ

この流れに沿って診断すれば、多くの問題は短時間で解決できるはずです。

本番環境へのデプロイ前チェックリスト

本番環境へデプロイする前に、以下の項目を確認してください。

• モデルファイルが外部 CDN（S3、GCS、Cloudflare R2 など）に配置されている
• CDN の CORS 設定が完了し、本番ドメインが許可されている
• WASM ファイルの MIME 型がapplication​/​wasmで配信される設定になっている
• 環境変数で開発・本番の URL が適切に切り替わることを確認した
• ブラウザの開発者ツールで Network タブを確認し、すべてのリソースが 200 OK で読み込まれることを確認した
• WebGPU 対応ブラウザ（Chrome、Edge 等の最新版）でテストした
• 初回読み込み時の進捗表示が正常に動作することを確認した

これらをクリアすれば、安心して本番環境にデプロイできますね。

さらなる学習のために

WebLLM のトラブルシューティングを深く理解するには、以下のトピックも学習することをお勧めします。

ブラウザのセキュリティモデルについて理解を深めると、CORS や Content Security Policy（CSP）がなぜ必要なのか、根本から理解できるようになります。

WebAssembly の仕組みを学ぶことで、MIME 型の重要性やストリーミングコンパイルの最適化手法が分かるようになるでしょう。

HTTP プロトコルとヘッダーの知識を身につければ、サーバー設定やキャッシング戦略を自在にコントロールできるようになります。

これらの知識は、WebLLM だけでなく、モダンな Web アプリケーション開発全般に役立つはずです。

エラーに直面したときこそ、技術を深く理解する絶好のチャンスです。この記事が、皆さんの WebLLM 開発の一助となれば幸いです。

関連リンク

• WebLLM 公式ドキュメント
• WebLLM GitHub リポジトリ
• MDN - CORS（Cross-Origin Resource Sharing）
• MDN - WebAssembly
• Nginx 公式ドキュメント - MIME Types
• Apache 公式ドキュメント - mod_headers
• Hugging Face Model Hub
• AWS S3 - CORS 設定