跳至主要內容

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,
}))

說明：

  • 必須在建立任何 session 之前呼叫
  • 一旦已有活動 session，繼續呼叫會報錯

支援字段：

  • 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(模型位元組字串, 選項)

從記憶體位元組建立會話。

Session 選項​

通用字段​

  • 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 必須是“字串鍵 -> 字串值”的 table
  • 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 都是兼容舊寫法的字段
  • 新舊字段可以混用，但如果表達的含義互相衝突，session 建立會直接報錯
  • 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() 會把傳入 table 的 key/value 都轉成字串再傳給 ORT
  • register_custom_op_library() 會在目前 session 選項基礎上重建內部 session
  • 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)

輸出規則：

  • 回傳值是一個 table
  • 同一個輸出既可以用數字索引訪問，也可以用輸出名訪問
  • run_into() 如果某個輸出復用了已有 tensor，返回表裡對應項就是原物件本身

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) 直接寫入已有 tensor
  • binding:bind_output("y", {type = "float32", shape = {1, 2}}) 由介面建立一個輸出 tensor 並返回

也支援：

  • 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])