Aller au contenu principal

Module des sessions ONNX Runtime

Ce module est disponible à partir des versions postérieures au 20260402

L’objet session sert à charger un modèle ONNX, à consulter les informations de ses entrées et sorties et à exécuter l’inférence.

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

Description :

  • doit être appelé avant la création de toute session
  • un appel effectué alors qu’une session est déjà active renvoie une erreur

Champs pris en charge :

  • log_severity_level
  • log_id
  • use_global_thread_pools
  • global_intra_op_num_threads
  • global_inter_op_num_threads

Création d’une session​

onnxruntime.session(model_path[, opts])​

objet_session, message_erreur = onnxruntime.session(chemin_modele, options)

Charge un modèle ONNX depuis un chemin de fichier.

onnxruntime.session_from_bytes(model_bytes[, opts])​

objet_session, message_erreur = onnxruntime.session_from_bytes(octets_modele, options)

Crée une session à partir d’octets en mémoire.

Options de session​

Champs généraux​

  • providers ou provider
    Peut recevoir une chaîne unique ou un tableau de chaînes ; les valeurs actuellement traitées et prises en charge nativement sont "cpu" et "coreml", ainsi que les alias CPUExecutionProvider et CoreMLExecutionProvider
  • fallback_to_cpu
    Type booléen, true par défaut
  • 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
    Accepte éventuellement "disable", "basic", "extended" ou "all"
  • execution_mode
    Accepte éventuellement "sequential" ou "parallel"
  • deterministic_compute
  • disable_per_session_threads
  • enable_cpu_mem_arena
  • enable_mem_pattern
  • custom_op_libraries

Informations complémentaires :

  • free_dimension_overrides doit recevoir un tableau, chaque élément ayant la structure { by = "name"|"denotation", key = "...", value = entier }
  • config_entries doit être une table de la forme « clé chaîne -> valeur chaîne »
  • custom_op_libraries peut être une chaîne contenant un seul chemin, un tableau de chemins ou un handle renvoyé par load_custom_op_library() ; le tableau peut également mélanger chemins et handles
  • si providers n’est pas spécifié explicitement ou si la liste des providers est vide, l’implémentation actuelle ajoute par défaut le provider CPU
  • lorsque la liste des providers contient "coreml" et que fallback_to_cpu = true, l’échec de l’initialisation du provider CoreML peut déclencher automatiquement un repli sur CPU
  • si vous écrivez explicitement providers = {"coreml", "cpu"}, l’ordre indique qu’il faut essayer CoreML, puis CPU

Champs liés au provider CoreML​

Lorsque providers contient "coreml", les champs suivants peuvent également être utilisés :

  • coreml_compute_units
    Il est recommandé d’utiliser "all", "cpu_only", "cpu_and_gpu" ou "cpu_and_neural_engine" ; l’analyseur accepte aussi les alias CPUOnly, CPUAndGPU, CPUAndNeuralEngine et 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

Informations complémentaires :

  • coreml_flags, coreml_use_cpu_only, coreml_use_cpu_and_gpu et coreml_only_enable_device_with_ane sont des champs conservés pour la compatibilité avec les anciennes écritures
  • les anciens et les nouveaux champs peuvent être mélangés, mais la création de la session renvoie directement une erreur si leurs significations sont contradictoires
  • coreml_only_enable_device_with_ane ne peut pas être utilisé avec des configurations mutuellement exclusives telles que coreml_compute_units = "cpu_only" / "cpu_and_gpu"

Méthodes de l’objet session​

Informations de base​

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

Informations de type​

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

La valeur renvoyée est une table d’informations de type dont les champs courants comprennent :

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

Description :

  • les tensor / sparse tensor contiennent data_type, shape et symbolic_shape
  • les sequence / optional contiennent un element imbriqué
  • les map contiennent key_type et un value imbriqué

Informations mémoire​

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

La valeur renvoyée peut être consultée dans l’ordre ou par nom. Chaque élément contient généralement :

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

Métadonnées et cycle de vie​

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

Description :

  • end_profiling() renvoie le chemin du fichier de sortie du profiling
  • set_ep_dynamic_options() convertit toutes les clés et valeurs de la table reçue en chaînes avant de les transmettre à ORT
  • register_custom_op_library() reconstruit la session interne sur la base des options de la session actuelle
  • path_or_handle peut être un chemin ou un handle renvoyé par load_custom_op_library()

Exécuter l’inférence​

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

tableau_sortie, message_erreur = session:run({
    input_ids = tenseur_entree,
    attention_mask = tenseur_masque,
}, {
    "logits",
}, run_options)

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

tableau_sortie, message_erreur = session:run_into({
    x = tenseur_entree,
}, {
    y = tenseur_sortie_reutilise,
}, run_options)

session:run_with_iobinding(binding[, run_options])​

tableau_sortie, message_erreur = session:run_with_iobinding(binding, run_options)

Règles des entrées :

  • inputs peut être un tableau ordonné ou un dictionnaire organisé par nom d’entrée
  • le tableau ordonné est mis en correspondance selon l’ordre des entrées du modèle ; il peut ensuite continuer à remplacer les overridable initializer
  • sous forme de dictionnaire, les clés doivent correspondre à un nom d’entrée ou d’overridable initializer
  • une entrée optional peut être omise ou recevoir onnxruntime.optional(nil, type_info)

Règles des sorties :

  • la valeur renvoyée est une table
  • une même sortie peut être consultée par index numérique ou par nom de sortie
  • avec run_into(), si une sortie réutilise un tensor existant, l’élément correspondant de la table renvoyée est l’objet lui-même

Run Options​

onnxruntime.run_options([opts])​

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

Champs pris en charge :

  • tag
  • log_severity_level
  • log_verbosity_level

Méthodes d’objet :

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

binding:bind_input(name, value)​

Lie une valeur d’entrée. Les optional vides ne sont pas acceptés ici.

binding:bind_output(name[, spec_or_tensor])​

Trois formes sont prises en charge :

  • binding:bind_output("y")
    Lie la sortie à la mémoire CPU, puis la récupère avec get_outputs()
  • binding:bind_output("y", existing_tensor)
    Écrit directement dans un tensor existant
  • binding:bind_output("y", {type = "float32", shape = {1, 2}})
    L’interface crée un tensor de sortie et le renvoie

Est également pris en charge :

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

Autres méthodes​

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

Exemple​

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