본문으로 건너뛰기

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로 자동 fallback할 수 있습니다.
  • 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])