モデルローダー API

1. はじめに

導入およびユースケースについては、explainer.md を参照してください。

説明のため、この API と例では TF Lite flatbuffer 形式を使用します。

2. API

enum MLModelFormat {
  // Tensorflow-lite flatbuffer。
  "tflite" 
};

enum MLDevicePreference {
  // バックエンドに最も適切なデバイスを選択させる。
  "auto",
  // バックエンドはモデル推論に GPU を使用する。GPU でサポートされていない
  // 演算子がある場合は、CPU にフォールバックする。
  "gpu",
  // バックエンドはモデル推論に CPU を使用する。
  "cpu"
};

enum MLPowerPreference {
  // バックエンドに最も適切な振る舞いを選択させる。
  "auto",
  // 消費電力よりも実行速度を優先する。
  "high-performance",
  // 実行速度などの他の考慮事項よりも
  // 消費電力を優先する。
  "low-power",
};

dictionary MLContextOptions {
  // 使用するデバイスの優先種類。
  MLDevicePreference devicePreference = "auto";

  // 消費電力に関連する優先設定。
  MLPowerPreference powerPreference = "auto";

  // モデルローダー API のモデル形式。
  MLModelFormat modelFormat = "tflite";
  
  // 使用するスレッド数。
  // "0" はバックエンドが自動的に決定できることを意味する。
  unsigned long numThreads = 0;
};

[Exposed=Window]
interface ML {
  Promise<MLContext> createContext(optional MLContextOptions options = {});
};

enum MLDataType {
  // "Unknown" は "unsupported" を意味しない。バックエンドはここに明示的に
  // 列挙されている型よりも多くの型をサポートできる（例: TfLite には複素数がある）。
  // 最初からバックエンドの詳細を過度に公開しないように、
  // それらを "unknown" として扱う。
  "unknown",
  "int64",
  "uint64",
  "float64",
  "int32",
  "uint32",
  "float32",
  "int16",
  "uint16",
  "float16",
  "int8",
  "uint8",
  "bool",
};

dictionary MLTensor {
  required ArrayBufferView data;
  required sequence<unsigned long> dimensions;
};

dictionary MLTensorInfo {
  required DOMString name;
  required MLDataType type;
  required sequence<unsigned long> dimensions;
};

[SecureContext, Exposed=Window]
interface MLModel {
  Promise<record<DOMString, MLTensor>> compute(record<DOMString, MLTensor> inputs);      
  sequence<MLTensorInfo> inputs();
  sequence<MLTensorInfo> outputs();
};

[Exposed=Window]
interface MLModelLoader {
  constructor(MLContext context);
  Promise<MLModel> load(ArrayBuffer modelBuffer);
};

3. 例

// まず、MLContext を作成する。これは WebNN API と一貫している。そして、
// “numThread” と "modelFormat" という 2 つの新しいフィールドを追加する。
const context = await navigator.ml.createContext(
                                     { devicePreference: "cpu",
                                       powerPreference: "low-power",
                                       numThread: 0,   // デフォルトの 0 は
                                                       // "自動的に決定" を意味する。
                                       modelFormat: "tflite" });
// 次に、ML コンテキストを使用してモデルローダーを作成する。
loader = new MLModelLoader(context);
// 最初のバージョンでは、ArrayBuffer からのモデル読み込みのみをサポートする。
// これで大半のユースケースをカバーできると考えている。Web 開発者は
// たとえば fetch API によってモデルをダウンロードできる。将来、本当に必要であれば
// 新しい "load" 関数を追加できる。
const modelUrl = 'https://path/to/model/file';
const modelBuffer = await fetch(modelUrl)
                            .then(response => response.arrayBuffer());
// モデルを読み込む。
model = await loader.load(modelBuffer);
// `model.compute` 関数を使用して、いくつかの入力からモデルの出力を取得する。
// この関数の使用例には次のようなものが含まれる。
// 1. モデルの入力テンソルが 1 つだけの場合、名前を指定せずに
// そのテンソルを単に入力できる（ユーザーが望む場合は、この入力テンソルを
// 名前で指定することもできる）。
z = await model.compute({ data: new Float32Array([10]), 
                          dimensions: [1]) });
// 2. 複数の入力テンソルがある場合、ユーザーは入力テンソルの名前を
// それぞれの名前で指定する必要がある。
z = await model.compute({ x: { data: new Float32Array([10]), 
                               dimensions: [1] },
                          y: { data: new Float32Array([20]), 
                               dimensions: [1] } });
// 3. クライアントは出力テンソルも指定できる。これは WebNN API と
// 一貫しており、たとえば出力テンソルが GPU バッファである場合に有用である。
// この場合、関数は空の promise を返す。指定される出力テンソルの次元は、
// モデルの出力テンソルの次元と一致していなければならない。
z_buffer = ml.tensor({data: new Float64Array(1), 
                      dimensions: [1] });
await model.compute({ data: new Float32Array([10]), 
                      dimensions: [1] },
                    z_buffer);
// 出力テンソルについて、
// 入力引数と同様に、出力テンソルが 1 つだけの場合、`compute` 関数は
// ケース 1 と 2 ではテンソルを返し、ケース 3 では出力テンソルの名前を
// 指定する必要はない。しかし、複数の出力テンソルがある場合、ケース 1 と 2 の
// 出力はテンソル名からテンソルへのマップになり、ケース 3 では出力引数も
// テンソル名からテンソルへのマップでなければならない。
// ケース 1 と 2 では、実際の出力データの配置場所はコンテキストに依存する。
// CPU コンテキストであれば、出力テンソルのバッファは RAM バッファになり、
// GPU コンテキストであれば、出力テンソルのバッファは GPU バッファになる。