メインコンテンツまでスキップ

CoreML 汎用推論器オブジェクトのメソッド

coreml_model_request_object は、coreml.new_model_request(...) / coreml.session(...) が返す推論オブジェクトです。
用意した入力 feature をモデルに渡し、出力名ごとに構成された結果を返します。

このオブジェクトの役割は次のものに限られます。

  • 推論の実行
  • 非同期結果の読み取り
  • モデルの入出力シグネチャの照会
  • 現在の request の実行構成の照会

テキストのトークン化、画像の前処理、業務上の後処理は行わないため、これらは Lua 層で構成する必要があります。

これらのメソッドは 20260319 以降のバージョンで使用できます

推論メソッド​

:predict(inputs[, opts])​

結果, エラー情報 = 汎用推論器オブジェクト:predict(入力マッピングテーブル)

または

送信済みか, エラー情報 = 汎用推論器オブジェクト:predict(入力マッピングテーブル, {
    async = 非同期か,
    multi_array_output = "table" または "MLMultiArray",
    uses_cpu_only = 今回CPUのみを使用するか,
})

単一サンプルのモデル推論を一回実行します。

  • inputs は入力名ごとに構成されたテーブルである必要があります
  • 同期モードでは結果テーブルを直接返します
  • 非同期モードでは true のみを返します。後から :is_done() と :results() を使用して結果を取得します
  • multi_array_output は、モデル出力内の MLMultiArray をネイティブテンソルのまま保持するか、Lua テーブルに変換するかを制御します
  • uses_cpu_only は今回の推論にのみ影響し、オブジェクトのデフォルト構成は変更しません

:run(inputs[, opts])​

run() は predict() の別名であり、動作は同じです。

:predict_batch(batch_inputs[, opts])​

バッチ結果, エラー情報 = 汎用推論器オブジェクト:predict_batch({
    { input_ids = ids1 },
    { input_ids = ids2 },
}, {
    async = false,
    multi_array_output = "MLMultiArray",
})

batch 推論を実行します。iOS 12+ が必要です。

  • batch_inputs は配列である必要があり、配列内の各要素は「入力名ごとに構成された入力テーブル」です
  • 同期モードでは batch 結果の配列を返します。各要素は引き続き単一サンプルの出力規則に従って構成されます
  • 非同期モードでは true を返します。後から :results() で取得します
  • opts のフィールドは predict() と同じです

:run_batch(batch_inputs[, opts])​

run_batch() は predict_batch() の別名であり、動作は同じです。

:results([opts])​

結果, エラー情報 = 汎用推論器オブジェクト:results()

または

結果, エラー情報 = 汎用推論器オブジェクト:results({
    multi_array_output = "table" または "MLMultiArray",
})

直近の非同期推論の結果を読み取ります。

  • 直近の非同期呼び出しが predict() の場合は、単一サンプルの結果テーブルを返します
  • 直近の非同期呼び出しが predict_batch() の場合は、batch 結果の配列を返します
  • multi_array_output はデフォルトで直近の推論呼び出しの設定を引き継ぎます
  • 非同期タスクがまだ終了していない場合は、nil, "not yet" を返します
  • 読み取り可能な成功結果がない場合は、nil, "unknown" を返します

:is_done()​

完了したか = 汎用推論器オブジェクト:is_done()

直近の非同期推論が完了したかどうかを確認します。predict(..., { async = true }) または predict_batch(..., { async = true }) の実行後にのみ意味があります。

実行構成とメタデータ​

:metadata()​

メタデータ = 汎用推論器オブジェクト:metadata()

モデルに組み込まれた metadata を返します。デバッグ、汎用ラッパー、モデル情報の表示に適しています。

:uses_cpu_only()​

デフォルトでCPUのみを使用するか = 汎用推論器オブジェクト:uses_cpu_only()

この request の作成時に保存されたデフォルトの CPUOnly 構成を返します。

:compute_units()​

計算ユニット設定 = 汎用推論器オブジェクト:compute_units()

この request に現在記録されている compute_units 文字列を返します。

  • iOS 12+ では、作成時に記録された小文字の文字列を返します
  • 一般的な戻り値には "all"、"cpu_only"、"cpu"、"cpu_and_gpu"、"gpu"、"cpu_and_neural_engine"、"ane"、"neural_engine" があります
  • 作成時に uses_cpu_only = true を渡した場合は、"cpu_only" を返します
  • iOS 11 では nil を返します

入出力シグネチャのメソッド​

:input_count() / :output_count()​

入力 / 出力 feature の数を返します。

:input_features() / :output_features()​

名前をキーとする feature 記述テーブルを返します。

現在実際に返されるフィールドは次のように簡潔です。

  • type
  • optional
  • feature の型が multi_array の場合は、shape と data_type も含まれます

:input_info(name_or_index) / :output_info(name_or_index)​

入力 / 出力名または 1-based の番号で、個別の feature 情報を読み取ります。

  • 戻り値のフィールドは input_features() / output_features() とほぼ同じです
  • name も含まれます
  • 番号によるアクセスでは、input_names() / output_names() と同じ並び順を使用します

:input_names() / :output_names()​

安定した順序の入力 / 出力名リストを返します。

  • 名前は辞書順で並べられます
  • output_names() の順序は、同期推論の戻り値における数値インデックスの順序と一致します

:class_labels()​

モデルで宣言されたクラスタベルを返します。iOS 14+ が必要です。

ライフサイクルと型判定​

:close()​

基盤となる request の状態を破棄します。閉じた後は、他のメソッドを呼び出さないでください。

:is_model_request() / :is_session()​

オブジェクトレベルの型判定インターフェースであり、両者は同じ意味の別名です。

説明​

  • predict() / run() の戻り値は常にテーブルです
  • 結果には数値インデックスと出力名インデックスの両方でアクセスできます
  • predict_batch() / run_batch() は batch 結果の配列を返します。配列内の各要素には、引き続き「数値インデックス + 出力名インデックス」の二通りでアクセスできます
  • 新しい汎用推論器では、MLMultiArray はデフォルトでネイティブテンソルオブジェクトのまま保持されるため、後処理を続けるのに適しています
  • データの内容を確認するだけの場合や、従来形式のスクリプトとの互換性が必要な場合は、multi_array_output = "table" を明示的に渡せます

結果へのアクセス例：

out[1]
out.text_features
batch_out[1].text_features

例​

local req = assert(coreml.new_model_request(XXT_HOME_PATH.."/models/demo.mlmodelc"))

local out = assert(req:predict({
    input_ids = ids,
}, {
    multi_array_output = "MLMultiArray",
}))

print(out[1])
print(out.text_features)
print(req:output_names())