Перейти к основному содержимому

Модуль сеансов ONNX Runtime

Модуль доступен в версиях после 20260402.

Объект session отвечает за загрузку 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])​

объект_session, сообщение_об_ошибке = onnxruntime.session(путь_к_модели, параметры)

Загружает ONNX-модель по пути к файлу.

onnxruntime.session_from_bytes(model_bytes[, opts])​

объект_session, сообщение_об_ошибке = onnxruntime.session_from_bytes(байты_модели, параметры)

Создаёт session из байтов в памяти.

Параметры 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​

Основные сведения​

  • 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() возвращает путь к файлу профилирования.
  • set_ep_dynamic_options() преобразует key/value переданной table в строки и передаёт их в 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])