Pular para o conteúdo principal

Módulo de sessions do ONNX Runtime

Este módulo está disponível a partir da versão 20260402.

O objeto session é responsável por carregar modelos ONNX, consultar informações de entrada e saída e executar inferência.

Configuração do runtime​

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

Descrição:

  • Deve ser chamado antes da criação de qualquer session.
  • Depois que já existir uma session ativa, chamar novamente causará um erro.

Campos aceitos:

  • log_severity_level
  • log_id
  • use_global_thread_pools
  • global_intra_op_num_threads
  • global_inter_op_num_threads

Criar uma session​

onnxruntime.session(model_path[, opts])​

session, mensagem_de_erro = onnxruntime.session(caminho_do_modelo, opções)

Carrega um modelo ONNX a partir de um caminho de arquivo.

onnxruntime.session_from_bytes(model_bytes[, opts])​

session, mensagem_de_erro = onnxruntime.session_from_bytes(bytes_do_modelo, opções)

Cria uma session a partir de bytes na memória.

Opções da session​

Campos gerais​

  • providers ou provider Pode ser uma única string ou um array de strings; atualmente processa e aceita nativamente "cpu" e "coreml", além dos aliases CPUExecutionProvider e CoreMLExecutionProvider.
  • fallback_to_cpu Booleano; o padrão é 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 Pode ser "disable", "basic", "extended" ou "all".
  • execution_mode Pode ser "sequential" ou "parallel".
  • deterministic_compute
  • disable_per_session_threads
  • enable_cpu_mem_arena
  • enable_mem_pattern
  • custom_op_libraries

Informações adicionais:

  • free_dimension_overrides deve receber uma tabela de array; cada item tem a estrutura { by = "name"|"denotation", key = "...", value = inteiro }.
  • config_entries deve ser uma table de chave string -> valor string.
  • custom_op_libraries pode ser uma única string de caminho, um array de caminhos ou um handle retornado por load_custom_op_library(); o array também pode misturar caminhos e handles.
  • Se providers não for especificado explicitamente ou a lista de providers estiver vazia, a implementação adicionará CPU por padrão.
  • Quando a lista de providers contém "coreml" e fallback_to_cpu = true, uma falha na inicialização do provider CoreML pode fazer o sistema retornar automaticamente para CPU.
  • Se você escrever explicitamente providers = {"coreml", "cpu"}, a ordem indica CoreML primeiro e CPU depois.

Campos relacionados ao provider CoreML​

Quando providers contém "coreml", também podem ser usados:

  • coreml_compute_units Recomenda-se usar "all", "cpu_only", "cpu_and_gpu" e "cpu_and_neural_engine"; o analisador também é compatível com aliases como CPUOnly, CPUAndGPU, CPUAndNeuralEngine e 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

Informações adicionais:

  • coreml_flags, coreml_use_cpu_only, coreml_use_cpu_and_gpu e coreml_only_enable_device_with_ane são campos mantidos por compatibilidade com a forma antiga.
  • Os campos novos e antigos podem ser combinados, mas a criação da session falhará diretamente se seus significados entrarem em conflito.
  • coreml_only_enable_device_with_ane não pode ser usado junto com configurações mutuamente exclusivas como coreml_compute_units = "cpu_only" / "cpu_and_gpu".

Métodos do objeto session​

Informações básicas​

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

Informações de tipo​

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

O valor retornado é uma tabela de informações de tipo, com campos comuns como:

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

Descrição:

  • tensor / sparse tensor contêm data_type, shape e symbolic_shape.
  • sequence / optional contêm um element aninhado.
  • map contém key_type e um value aninhado.

Informações de memória​

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

O valor retornado pode ser acessado por ordem ou por nome. Cada item normalmente contém:

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

Metadados e 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)

Descrição:

  • end_profiling() retorna o caminho do arquivo de saída do profiling.
  • set_ep_dynamic_options() converte todas as chaves e valores da table recebida em strings antes de passá-las ao ORT.
  • register_custom_op_library() recria a session interna com base nas opções da session atual.
  • path_or_handle pode ser um caminho ou um handle retornado por load_custom_op_library().

Executar inferência​

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

saídas, mensagem_de_erro = session:run({
    input_ids = tensor_de_entrada,
    attention_mask = tensor_de_máscara,
}, {
    "logits",
}, run_options)

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

saídas, mensagem_de_erro = session:run_into({
    x = tensor_de_entrada,
}, {
    y = tensor_de_saída_reutilizado,
}, run_options)

session:run_with_iobinding(binding[, run_options])​

saídas, mensagem_de_erro = session:run_with_iobinding(binding, run_options)

Regras de entrada:

  • inputs pode ser um array ordenado ou um dicionário organizado por nome de entrada.
  • Arrays ordenados são associados na ordem das entradas do modelo e depois também podem substituir um overridable initializer.
  • Na forma de dicionário, as chaves devem coincidir com um nome de entrada ou de overridable initializer.
  • Uma entrada optional pode ser omitida ou receber onnxruntime.optional(nil, type_info).

Regras de saída:

  • O valor retornado é uma table.
  • A mesma saída pode ser acessada por índice numérico ou por nome.
  • Se run_into() reutilizar um tensor existente para alguma saída, o item correspondente na tabela retornada será o próprio objeto original.

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 aceitos:

  • tag
  • log_severity_level
  • log_verbosity_level

Métodos do 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, mensagem_de_erro = session:create_io_binding()

binding:bind_input(name, value)​

Vincula um valor de entrada. Um optional vazio não é aceito aqui.

binding:bind_output(name[, spec_or_tensor])​

Há três formas:

  • binding:bind_output("y") Vincula à memória da CPU; depois, obtenha o valor com get_outputs().
  • binding:bind_output("y", existing_tensor) Escreve diretamente em um tensor existente.
  • binding:bind_output("y", {type = "float32", shape = {1, 2}}) A interface cria e retorna um tensor de saída.

Também é aceito:

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

Outros métodos​

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

Exemplo​

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