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

ONNX Runtime セッションモジュール

このモジュールは 20260402 以降のバージョンでのみ使用できます

セッションオブジェクトは、ONNX モデルの読み込み、入出力情報の参照、および推論の実行を処理します。

ランタイム設定​

onnxruntime.configure(opts)​

assert(onnxruntime.configure({
    log_severity_level = 2,
    log_id = "my-runtime",
    use_global_thread_pools = false,
    global_intra_op_num_threads = 0,
    global_inter_op_num_threads = 0,
}))

説明：

  • セッションを作成する前に必ず呼び出してください
  • アクティブなセッションがすでに存在する状態で再度呼び出すと、エラーになります

サポートされるフィールド：

  • log_severity_level
  • log_id
  • use_global_thread_pools
  • global_intra_op_num_threads
  • global_inter_op_num_threads

セッションの作成​

onnxruntime.session(model_path[, opts])​

セッションオブジェクト, エラー情報 = onnxruntime.session(モデルパス, オプション)

ファイルパスから ONNX モデルを読み込みます。

onnxruntime.session_from_bytes(model_bytes[, opts])​

セッションオブジェクト, エラー情報 = onnxruntime.session_from_bytes(モデルバイト列, オプション)

メモリ上のバイト列からセッションを作成します。

セッションオプション​

共通フィールド​

  • providers または provider 単一の文字列または文字列配列を渡せます。現在ネイティブに処理され、サポートされるのは "cpu" と "coreml" です。CPUExecutionProvider、CoreMLExecutionProvider などの別名も受け付けます
  • fallback_to_cpu ブール型で、デフォルトは true です
  • intra_op_num_threads
  • inter_op_num_threads
  • log_id
  • session_log_severity_level
  • session_log_verbosity_level
  • optimized_model_path
  • profile_file_prefix
  • free_dimension_overrides
  • config_entries
  • graph_optimization_level "disable"、"basic"、"extended"、"all" から選択できます
  • execution_mode "sequential"、"parallel" から選択できます
  • deterministic_compute
  • disable_per_session_threads
  • enable_cpu_mem_arena
  • enable_mem_pattern
  • custom_op_libraries

補足説明：

  • free_dimension_overrides には配列テーブルを渡す必要があり、各要素の構造は { by = "name"|"denotation", key = "...", value = 整数 } です
  • config_entries は「文字列キー -> 文字列値」のテーブルである必要があります
  • custom_op_libraries には、単一のパス文字列、パス配列、または load_custom_op_library() が返すハンドルを指定できます。配列内でパスとハンドルを混在させることもできます
  • providers を明示的に指定していない場合、または Provider の一覧が空の場合、現在の実装ではデフォルトで CPU Provider が追加されます
  • Provider の一覧に "coreml" が含まれ、fallback_to_cpu = true の場合、CoreML Provider の初期化に失敗すると CPU に自動的にフォールバックできます
  • providers = {"coreml", "cpu"} と明示的に指定した場合、この順序は CoreML、CPU の順に試行することを示します

CoreML provider 関連フィールド​

providers に "coreml" が含まれる場合は、次のフィールドも使用できます。

  • coreml_compute_units "all"、"cpu_only"、"cpu_and_gpu"、"cpu_and_neural_engine" の使用を推奨します。パーサーは CPUOnly、CPUAndGPU、CPUAndNeuralEngine、MLComputeUnits... などの別名にも対応しています
  • coreml_create_mlprogram
  • coreml_require_static_input_shapes
  • coreml_enable_on_subgraph
  • coreml_flags
  • coreml_use_cpu_only
  • coreml_use_cpu_and_gpu
  • coreml_only_enable_device_with_ane

補足説明：

  • coreml_flags、coreml_use_cpu_only、coreml_use_cpu_and_gpu、coreml_only_enable_device_with_ane は、いずれも従来の記述方法との互換性を維持するためのフィールドです
  • 新旧のフィールドは混在できますが、表す意味が互いに矛盾する場合、セッションの作成時にエラーになります
  • coreml_only_enable_device_with_ane は、coreml_compute_units = "cpu_only" / "cpu_and_gpu" などの排他的な設定と同時に使用できません

セッションオブジェクトのメソッド​

基本情報​

  • session:input_names()
  • session:output_names()
  • session:overridable_initializer_names()
  • session:input_count()
  • session:output_count()
  • session:overridable_initializer_count()

型情報​

  • session:input_info(name_or_index)
  • session:output_info(name_or_index)
  • session:overridable_initializer_info(name_or_index)

戻り値は型情報テーブルで、一般的なフィールドは次のとおりです。

  • name
  • onnx_type
  • is_sparse
  • data_type
  • type
  • has_shape
  • shape
  • symbolic_shape
  • element
  • key_type
  • value

説明：

  • tensor / sparse tensor には data_type、shape、symbolic_shape が含まれます
  • sequence / optional には、ネストされた element が含まれます
  • map には key_type と、ネストされた value が含まれます

メモリ情報​

  • session:memory_info_for_inputs()
  • session:memory_info_for_outputs()

戻り値には順序でも名前でもアクセスできます。個々の項目には通常、次のフィールドが含まれます。

  • name
  • id
  • mem_type
  • allocator_type
  • device_type
  • device_mem_type
  • vendor_id

メタデータとライフサイクル​

  • session:metadata()
  • session:close()
  • session:end_profiling()
  • session:profiling_start_time_ns()
  • session:set_ep_dynamic_options(opts)
  • session:register_custom_op_library(path_or_handle)

説明：

  • end_profiling() は profiling の出力ファイルパスを返します
  • set_ep_dynamic_options() は、渡されたテーブルの key/value をすべて文字列に変換してから ORT に渡します
  • register_custom_op_library() は、現在のセッションオプションに基づいて内部セッションを再構築します
  • path_or_handle には、パスまたは load_custom_op_library() が返すハンドルを指定できます

推論の実行​

session:run(inputs[, output_names[, run_options]])​

出力テーブル, エラー情報 = session:run({
    input_ids = 入力テンソル,
    attention_mask = マスクテンソル,
}, {
    "logits",
}, run_options)

session:run_into(inputs, outputs[, run_options])​

出力テーブル, エラー情報 = session:run_into({
    x = 入力テンソル,
}, {
    y = 再利用する出力テンソル,
}, run_options)

session:run_with_iobinding(binding[, run_options])​

出力テーブル, エラー情報 = session:run_with_iobinding(binding, run_options)

入力規則：

  • inputs には、順序配列または入力名をキーとする辞書を指定できます
  • 順序配列はモデルの入力順に対応し、その後に overridable initializer を続けることもできます
  • 辞書形式の場合、キーは入力名または overridable initializer 名と一致する必要があります
  • optional 入力は省略するか、onnxruntime.optional(nil, type_info) を渡すことができます

出力規則：

  • 戻り値はテーブルです
  • 同じ出力に数値インデックスと出力名のどちらでもアクセスできます
  • run_into() で既存のテンソルを出力に再利用した場合、戻り値のテーブル内の対応項目は元のオブジェクトそのものです

Run Options​

onnxruntime.run_options([opts])​

local run_options = assert(onnxruntime.run_options({
    tag = "session-run",
    log_severity_level = 2,
    log_verbosity_level = 1,
}))

サポートされるフィールド：

  • tag
  • log_severity_level
  • log_verbosity_level

オブジェクトメソッド：

  • run_options:tag([value])
  • run_options:log_severity_level([value])
  • run_options:log_verbosity_level([value])
  • run_options:terminate()
  • run_options:reset_terminate()

IOBinding​

session:create_io_binding()​

binding, エラー情報 = session:create_io_binding()

binding:bind_input(name, value)​

入力値をバインドします。ここでは空の optional を受け付けません。

binding:bind_output(name[, spec_or_tensor])​

三つの形式をサポートします。

  • binding:bind_output("y") CPU メモリにバインドし、後で get_outputs() を使用して取得します
  • binding:bind_output("y", existing_tensor) 既存のテンソルに直接書き込みます
  • binding:bind_output("y", {type = "float32", shape = {1, 2}}) インターフェースで出力テンソルを作成して返します

次の形式にも対応しています。

  • binding:bind_output("y", {mode = "device"})

その他のメソッド​

  • binding:clear_inputs()
  • binding:clear_outputs()
  • binding:synchronize_inputs()
  • binding:synchronize_outputs()
  • binding:get_outputs()

例​

local ort = require("onnxruntime")

local session = assert(ort.session(XXT_HOME_PATH.."/models/demo/model.onnx", {
    providers = {"coreml", "cpu"},
    fallback_to_cpu = true,
    coreml_compute_units = "all",
}))

local x = assert(ort.tensor("float32", {1, 2}, {1.0, 2.0}))
local bias = assert(ort.tensor("float32", {1, 2}, {0.5, -0.5}))
local run_options = assert(ort.run_options({tag = "demo"}))

local outputs = assert(session:run({
    x = x,
    bias = bias,
}, {"y"}, run_options))

print(outputs.y:to_table()[1])