webnn

WebNN

手順

Step 1: ブラウザー統合の対象を特定する

1. ワークスペースを調べて、ブラウザーのエントリーポイント、UI ハンドラー、ワーカーのエントリーファイル、および既存のモデル読み込みまたは推論の抽象化レイヤーを特定します。
2. Node ランタイムが利用可能な場合は、node scripts/find-webnn-targets.mjs . を実行して、フロントエンドの候補ファイルと既存の WebNN マーカーを一覧表示します。
3. Node ランタイムが利用できない場合は、最も近い package.json、HTML のエントリーポイント、フレームワークのブートストラップファイル、ワーカーのエントリーファイルを手動で確認し、ブラウザーアプリの境界を特定します。
4. ワークスペースに複数のフロントエンドアプリがある場合は、アクティブなルート、コンポーネント、またはユーザーが指定した機能の対象となるアプリを優先します。
5. 一覧を確認しても有力なフロントエンドの候補が複数残る場合は、作業を停止し、どのアプリに WebNN 統合を追加するか尋ねます。
6. プロジェクトがブラウザー向けの Web アプリではない場合は、作業を停止し、このスキルが適用されないことを説明します。

Step 2: WebNN の実行可能性を確認し、ランタイムの構成を選択する

1. コードを書く前に references/webnn-reference.md を読みます。
2. WebNN のグラフを直接扱うフローと、既存のブラウザー ML ランタイムをラップするアダプターのどちらを選ぶか決める際は、references/examples.md を読みます。
3. ネイティブサポート、プレビューフラグ、デバイスの動作、またはバックエンドの違いが重要な場合は、references/compatibility.md を読みます。
4. コンテキストの作成、グラフのビルド、テンソルの読み戻し、またはデバイスの選択に失敗する場合は、references/troubleshooting.md を読みます。
5. この機能がセキュアコンテキストと、Window または Worker コンテキスト（DedicatedWorker、SharedWorker、ServiceWorker）で実行されることを確認します。
6. 機能をサーバー上で実行する必要がある場合、モデルをトレーニングする必要がある場合、またはクラウド推論に依存する場合は、作業を停止し、プラットフォームが適合しないことを説明します。
7. デバイスに関する意図を慎重に選択します。スループットを高めるには powerPreference: "high-performance"、電力効率の高いアクセラレーションには powerPreference: "low-power"、利用範囲を最大化するために CPU 推論を優先するには accelerated: false を使用します。
8. accelerated と powerPreference は保証ではなく、優先設定として扱います。ブラウザーのバックエンドでは、グラフが分割されたり、演算子ごとにフォールバックしたりすることがあります。
9. アプリケーションがグラフ構築を担う場合、または小規模で決定的なグラフの処理経路を維持できる場合は、MLGraphBuilder を直接扱うフローを選択します。
10. アプリケーションがすでに既存のローカルランタイムを通じてモデルを読み込んでおり、推論スタック全体を書き換えずに WebNN アクセラレーションを優先することが目的の場合に限り、そのランタイムをラップするアダプターを選択します。
11. プロジェクトで TypeScript を使用している場合は、プロジェクトで使用する WebNN API の型定義を追加するか、既存の型定義を維持します。

Step 3: ガード付きランタイムアダプターを実装する

1. assets/webnn-runtime.template.ts を読み、ワークスペースのフレームワーク、状態モデル、ファイル構成に合わせて調整します。
2. UI コンポーネント内にチェックを散在させず、window.isSecureContext、navigator.ml、要求された実行コンテキストを基にサポート状況の判定を一元化します。
3. アプリがローカル推論の初期化準備を整えた境界でのみ、MLContext を作成します。
4. 製品上の明確な優先設定がある場合は、accelerated と powerPreference を明示的に指定します。製品上の根拠がない調整は省略します。
5. この機能が WebNN の演算を直接実行する場合は MLGraphBuilder を通じてグラフをビルドします。既存のモデル実行において、そのランタイムがすでにモデルの読み込みと前処理・後処理を担っている場合は、アプリ既存のローカルランタイムアダプターを通じて実行します。
6. リクエスト間で入力と出力の形状が変わらない場合は、コンパイル済みグラフと再利用可能なテンソルを再利用します。
7. グラフを直接実行する場合は、context.writeTensor()、context.dispatch()、await context.readTensor() の順に使用します。
8. context.lost を監視し、ブラウザーによって実行状態が無効になった場合は、コンテキスト、グラフ、テンソルを再構築します。
9. 機能が破棄されるとき、またはルートで不要になったときは、テンソル、グラフ、コンテキストを破棄します。 ステップ 4：UX とフォールバック動作を組み込む
10. 未対応ブラウザー、セキュアコンテキストの要件を満たさない場合、ランタイムの準備中、ネイティブ実行の準備完了、明示的なフォールバック実行という状態をそれぞれ表示します。
11. 機能を引き続き利用できるようにする必要がある場合は、未対応ブラウザーや未対応デバイス向けに WebNN を使わない経路を用意します。
12. フォールバックは明示的で、製品として承認されたものにします。機能をローカルで維持する必要がある場合、リモートモデルプロバイダーに黙って切り替えてはいけません。
13. デバイスの選択は意図として示し、そのデバイスですべての操作が実行されると約束するものではないことを明確にします。
14. アプリケーションがすでにワーカーに適したアーキテクチャを採用している場合、時間のかかるモデルの準備や繰り返しの推論はメインスレッドの外で実行します。
15. すべてのユーザーデータの取り扱いを、製品のローカル処理に関する約束およびプライバシー要件に沿ったものにします。

ステップ 5：動作を検証する

1. node scripts/find-webnn-targets.mjs . を実行し、想定するアプリの境界と WebNN マーカーが、編集した統合対象を引き続き指し示すことを確認します。
2. ランタイムの問題を詳しく調査する前に、セキュアコンテキストと navigator.ml の検出を確認します。
3. WebNN を直接使用する経路では、コンテキストの作成、単純なグラフの構築、入力の書き込み、ディスパッチ、出力の読み取りを行うスモークテストを実行します。
4. 想定する accelerated と powerPreference の設定をテストし、アクセラレートされたコンテキストを作成できない場合でもフォールバック動作が利用できることを確認します。
5. 演算子の対応状況やテンソルのデータ型のサポートがグラフ設計に影響する場合は、context.opSupportLimits() を使用します。
6. アプリが破棄済みのテンソル、グラフ、コンテキストを再利用しないことを確認します。
7. 対象環境が Chromium のプレビュー用フラグや特定のマイルストーンに依存する場合、ランタイムの失敗をアプリケーションのバグと判断する前に、references/compatibility.md で必要なブラウザーの状態を確認します。
8. 編集後に、ワークスペースのビルド、型チェック、またはテストを実行します。

エラー処理

• navigator.ml が見つからない場合は、アプリケーションコードを変更する前に、references/compatibility.md でセキュアコンテキストの要件とブラウザーの対応状況を確認します。
• アクセラレートまたは高パフォーマンスのリクエストで createContext() が失敗した場合は、製品で承認されたフォールバック計画に従う場合に限り再試行し、失敗の理由を表示します。
• build() または dispatch() が失敗した場合は、機能を書き換える前に、演算子、形状、デバイスの不一致について references/examples.md と references/troubleshooting.md を確認します。
• context.lost が解決された場合、現在のコンテキスト、グラフ、テンソルを無効として扱い、次の推論を試みる前に再作成します。
• 製品にリモート推論の仕様しかない場合は、そこで中止し、このスキルが直接適用されないことを説明します。