Zum Hauptinhalt springen

ONNX-Runtime-Session-Modul

Dieses Modul ist in Versionen nach 20260402 verfügbar

Sessionobjekte laden ONNX-Modelle, prüfen Ein-/Ausgabeinformationen und führen Inferenz aus.

Laufzeitkonfiguration​

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

Hinweise:

  • Muss vor dem Erstellen jeder Session aufgerufen werden.
  • Nach dem Erstellen einer aktiven Session führt ein weiterer Aufruf zu einem Fehler.

Unterstützte Felder:

  • log_severity_level
  • log_id
  • use_global_thread_pools
  • global_intra_op_num_threads
  • global_inter_op_num_threads

Session erstellen​

onnxruntime.session(model_path[, opts])​

session, err = onnxruntime.session(model_path, opts)

Lädt ein ONNX-Modell aus einem Dateipfad.

onnxruntime.session_from_bytes(model_bytes[, opts])​

session, err = onnxruntime.session_from_bytes(model_bytes, opts)

Erstellt eine Session aus im Speicher befindlichen Modellbytes.

Session-Optionen​

Allgemeine Felder​

  • providers oder provider Akzeptiert eine einzelne Zeichenkette oder ein Zeichenkettenarray; nativ unterstützt werden derzeit "cpu" und "coreml", außerdem Aliase wie CPUExecutionProvider und CoreMLExecutionProvider.
  • fallback_to_cpu Boolean, Standardwert 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 Einer von "disable", "basic", "extended" oder "all".
  • execution_mode Einer von "sequential" oder "parallel".
  • deterministic_compute
  • disable_per_session_threads
  • enable_cpu_mem_arena
  • enable_mem_pattern
  • custom_op_libraries

Zusätzliche Hinweise:

  • free_dimension_overrides muss als Array-Tabelle übergeben werden; jedes Element hat die Form { by = "name"|"denotation", key = "...", value = integer }.
  • config_entries muss eine Tabelle Zeichenkette -> Zeichenkette sein.
  • custom_op_libraries kann ein einzelner Pfad, ein Pfadarray oder ein von load_custom_op_library() zurückgegebenes Handle sein; Arrays dürfen Pfade und Handles mischen.
  • Ohne explizites providers oder bei leerer Providerliste ergänzt die aktuelle Implementierung standardmäßig den CPU-Provider.
  • Enthält die Providerliste "coreml" und ist fallback_to_cpu = true, kann nach fehlgeschlagener CoreML-Initialisierung automatisch auf CPU zurückgefallen werden.
  • providers = {"coreml", "cpu"} bedeutet, dass CoreML zuerst und CPU danach versucht wird.

Felder des CoreML-Providers​

Wenn providers "coreml" enthält, sind zusätzlich folgende Felder verfügbar:

  • coreml_compute_units Empfohlen werden "all", "cpu_only", "cpu_and_gpu" und "cpu_and_neural_engine"; der Parser akzeptiert auch Aliase wie CPUOnly, CPUAndGPU, CPUAndNeuralEngine und 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

Zusätzliche Hinweise:

  • coreml_flags, coreml_use_cpu_only, coreml_use_cpu_and_gpu und coreml_only_enable_device_with_ane sind Felder zur Kompatibilität mit älteren Schreibweisen.
  • Neue und alte Felder können gemischt werden; bei widersprüchlicher Bedeutung schlägt die Session-Erstellung sofort fehl.
  • coreml_only_enable_device_with_ane darf nicht mit sich ausschließenden Einstellungen wie coreml_compute_units = "cpu_only" / "cpu_and_gpu" kombiniert werden.

Methoden des Sessionobjekts​

Grundlegende Informationen​

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

Typinformationen​

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

Der Rückgabewert ist eine Typinformationstabelle; häufige Felder sind:

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

Hinweise:

  • Tensor / Sparse Tensor enthalten data_type, shape und symbolic_shape.
  • Sequence / Optional enthalten das verschachtelte Feld element.
  • Map enthält key_type und das verschachtelte Feld value.

Speicherinformationen​

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

Der Rückgabewert kann sowohl der Reihe nach als auch nach Namen gelesen werden. Ein Element enthält typischerweise:

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

Metadaten und Lebenszyklus​

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

Hinweise:

  • end_profiling() gibt den Pfad der Profiling-Ausgabedatei zurück.
  • set_ep_dynamic_options() wandelt alle Schlüssel/Werte der übergebenen Tabelle in Zeichenketten um und übergibt sie an ORT.
  • register_custom_op_library() erstellt auf Grundlage der aktuellen Session-Optionen eine interne Session neu.
  • path_or_handle kann ein Pfad oder ein von load_custom_op_library() zurückgegebenes Handle sein.

Inferenz ausführen​

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

outputs, err = session:run({
    input_ids = input_tensor,
    attention_mask = mask_tensor,
}, {
    "logits",
}, run_options)

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

outputs, err = session:run_into({
    x = input_tensor,
}, {
    y = output_tensor,
}, run_options)

session:run_with_iobinding(binding[, run_options])​

outputs, err = session:run_with_iobinding(binding, run_options)

Eingaberegeln:

  • inputs kann ein geordnetes Array oder ein nach Eingabenamen organisiertes Dictionary sein.
  • Ein geordnetes Array wird der Eingabereihenfolge des Modells zugeordnet und kann anschließend auch überschreibbare Initializer abdecken.
  • In der Dictionary-Form müssen die Schlüssel mit Eingabenamen oder Namen überschreibbarer Initializer übereinstimmen.
  • Optionale Eingaben können weggelassen oder als onnxruntime.optional(nil, type_info) übergeben werden.

Ausgaberegeln:

  • Der Rückgabewert ist eine Tabelle.
  • Eine Ausgabe kann sowohl über einen numerischen Index als auch über ihren Namen abgerufen werden.
  • Wenn run_into() einen vorhandenen Tensor für eine Ausgabe wiederverwendet, verweist der entsprechende Tabelleneintrag auf genau dieses Objekt.

Run Options​

onnxruntime.run_options([opts])​

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

Unterstützte Felder:

  • tag
  • log_severity_level
  • log_verbosity_level

Objektmethoden:

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

binding:bind_input(name, value)​

Bindet einen Eingabewert. Ein leeres Optional wird hier nicht akzeptiert.

binding:bind_output(name[, spec_or_tensor])​

Drei Formen werden unterstützt:

  • binding:bind_output("y") Bindet an CPU-Speicher; später über get_outputs() abrufen.
  • binding:bind_output("y", existing_tensor) Schreibt direkt in einen vorhandenen Tensor.
  • binding:bind_output("y", {type = "float32", shape = {1, 2}}) Erstellt über die Schnittstelle einen Ausgabetensor und gibt ihn zurück.

Ebenfalls unterstützt:

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

Weitere Methoden​

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

Beispiel​

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