Saltar al contenido principal

Módulo de sesiones de ONNX Runtime

Este módulo solo está disponible a partir de la versión 20260402

El objeto session carga modelos ONNX, consulta la información de entradas y salidas y ejecuta inferencias.

Configuración del entorno​

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

Explicación:

  • Debe llamarse antes de crear cualquier session
  • Si ya existe una session activa, una llamada posterior produce un error

Campos admitidos:

  • log_severity_level
  • log_id
  • use_global_thread_pools
  • global_intra_op_num_threads
  • global_inter_op_num_threads

Crear una sesión​

onnxruntime.session(model_path[, opts])​

objeto_de_sesión, mensaje_de_error = onnxruntime.session(ruta_del_modelo, opciones)

Carga un modelo ONNX desde una ruta de archivo.

onnxruntime.session_from_bytes(model_bytes[, opts])​

objeto_de_sesión, mensaje_de_error = onnxruntime.session_from_bytes(bytes_del_modelo, opciones)

Crea una sesión a partir de bytes en memoria.

Opciones de Session​

Campos generales​

  • providers o provider: puede recibir una cadena individual o una matriz de cadenas; admite de forma nativa "cpu" y "coreml", además de alias como CPUExecutionProvider y CoreMLExecutionProvider
  • fallback_to_cpu: tipo booleano, true de forma predeterminada
  • 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: puede ser "disable", "basic", "extended" o "all"
  • execution_mode: puede ser "sequential" o "parallel"
  • deterministic_compute
  • disable_per_session_threads
  • enable_cpu_mem_arena
  • enable_mem_pattern
  • custom_op_libraries

Explicaciones adicionales:

  • free_dimension_overrides recibe una tabla matriz; cada elemento tiene la estructura { by = "name"|"denotation", key = "...", value = entero }
  • config_entries debe ser una table con la relación clave de cadena -> valor de cadena
  • custom_op_libraries puede ser una cadena de ruta, una matriz de rutas o un handle devuelto por load_custom_op_library(); la matriz también puede mezclar rutas y handles
  • Si no se especifica providers o la lista está vacía, la implementación actual añade el provider CPU de forma predeterminada
  • Si la lista incluye "coreml" y fallback_to_cpu = true, tras fallar la inicialización del provider CoreML se puede volver automáticamente a CPU
  • Si se escribe explícitamente providers = {"coreml", "cpu"}, el orden indica CoreML primero y CPU después

Campos relacionados con el provider CoreML​

Cuando providers incluye "coreml", también se pueden usar:

  • coreml_compute_units: se recomienda "all", "cpu_only", "cpu_and_gpu" o "cpu_and_neural_engine"; el analizador también admite alias como CPUOnly, CPUAndGPU, CPUAndNeuralEngine y 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

Explicaciones adicionales:

  • coreml_flags, coreml_use_cpu_only, coreml_use_cpu_and_gpu y coreml_only_enable_device_with_ane son campos compatibles con la forma antigua
  • Los campos nuevos y antiguos se pueden mezclar, pero si expresan significados contradictorios, la creación de la session produce un error directamente
  • coreml_only_enable_device_with_ane no se puede usar junto con configuraciones mutuamente excluyentes como coreml_compute_units = "cpu_only" / "cpu_and_gpu"

Métodos del objeto Session​

Información básica​

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

Información de tipos​

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

El valor devuelto es una tabla de información de tipos con campos habituales:

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

Explicación:

  • tensor / sparse tensor incluyen data_type, shape y symbolic_shape
  • sequence / optional incluyen un element anidado
  • map incluye key_type y un value anidado

Información de memoria​

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

El valor devuelto se puede consultar por orden o por nombre. Cada elemento suele incluir:

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

Metadatos y ciclo de vida​

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

Explicación:

  • end_profiling() devuelve la ruta del archivo de salida del profiling
  • set_ep_dynamic_options() convierte todas las claves y valores de la table recibida en cadenas antes de pasarlas a ORT
  • register_custom_op_library() reconstruye la session interna usando las opciones de la session actual
  • path_or_handle puede ser una ruta o un handle devuelto por load_custom_op_library()

Ejecutar inferencia​

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

tabla_de_salida, mensaje_de_error = session:run({
    input_ids = tensor_de_entrada,
    attention_mask = tensor_de_máscara,
}, {
    "logits",
}, run_options)

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

tabla_de_salida, mensaje_de_error = session:run_into({
    x = tensor_de_entrada,
}, {
    y = tensor_de_salida_reutilizado,
}, run_options)

session:run_with_iobinding(binding[, run_options])​

tabla_de_salida, mensaje_de_error = session:run_with_iobinding(binding, run_options)

Reglas de entrada:

  • inputs puede ser una matriz secuencial o un diccionario organizado por nombre de entrada
  • La matriz secuencial se asocia según el orden de entradas del modelo y después puede seguir sobrescribiendo overridable initializer
  • En la forma de diccionario, las claves deben coincidir con el nombre de entrada o el nombre de overridable initializer
  • Una entrada optional se puede omitir o pasar como onnxruntime.optional(nil, type_info)

Reglas de salida:

  • El valor devuelto es una table
  • La misma salida se puede consultar por índice numérico o por nombre
  • Si run_into() reutiliza un tensor existente para una salida, el elemento correspondiente de la tabla devuelta es el propio objeto

Run Options​

onnxruntime.run_options([opts])​

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

Campos admitidos:

  • tag
  • log_severity_level
  • log_verbosity_level

Métodos del objeto:

  • 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, mensaje_de_error = session:create_io_binding()

binding:bind_input(name, value)​

Vincula un valor de entrada. Aquí no se acepta un optional vacío.

binding:bind_output(name[, spec_or_tensor])​

Admite tres formas:

  • binding:bind_output("y"): vincula a memoria CPU y después se recupera mediante get_outputs()
  • binding:bind_output("y", existing_tensor): escribe directamente en un tensor existente
  • binding:bind_output("y", {type = "float32", shape = {1, 2}}): la interfaz crea un tensor de salida y lo devuelve

También admite:

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

Otros métodos​

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

Ejemplo​

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