Zum Hauptinhalt springen

ONNX-Runtime-Modul (onnxruntime)

Dieses Modul ist in Versionen nach 20260402 verfügbar
Unterstützt nur iOS 13 und höher

Das Modul onnxruntime lädt und führt ONNX-Modelle direkt auf dem Gerät aus. Es eignet sich für Text, Embeddings, Klassifikation, Detection und allgemeine Tensor-Inferenz.

Modul laden​

local ort = require("onnxruntime")

Dieses Modul wird bei Bedarf geladen und ist im Gegensatz zu coreml kein integriertes globales Modul.

Nach erfolgreichem require("onnxruntime") werden außerdem zwei Gruppen von Bridge-Schnittstellen in das integrierte Modul coreml eingefügt:

  • coreml.multi_array_from_ort_tensor(tensor[, data_type])
  • multi_array:to_ort_tensor([data_type])

Beide Konvertierungen kopieren direkt auf der nativen Ebene und durchlaufen keine Lua-Tabelle.

Funktionen auf Modulebene​

Laufzeit und grundlegende Informationen​

  • onnxruntime.version()
  • onnxruntime.providers()
  • onnxruntime.configure(opts)

Hinweise:

  • providers() gibt die im aktuellen ORT-Lauf tatsächlich verfügbaren Execution Provider zurück.
  • configure() setzt globale Laufzeitstandardwerte und muss vor dem Erstellen jeder Session aufgerufen werden.

Tensor-, Bild- und numerische Hilfen​

  • onnxruntime.tensor(type, shape[, data])
  • onnxruntime.tensor_from_bytes(type, shape, bytes)
  • onnxruntime.tensor_from_cv_mat(mat[, opts])
  • onnxruntime.tensor_from_quad(mat, quad[, opts])
  • onnxruntime.tensor_from_quads(mat, quads[, opts])
  • onnxruntime.tensor_from_image(image[, opts])
  • onnxruntime.tensor_from_images(images[, opts])
  • onnxruntime.image_from_tensor(tensor[, opts])
  • onnxruntime.clamp(tensor, min, max)
  • onnxruntime.sigmoid(tensor)
  • onnxruntime.exp(tensor)
  • onnxruntime.where(condition, x, y)
  • onnxruntime.matmul(lhs, rhs)
  • onnxruntime.concat(tensors[, axis])
  • onnxruntime.stack(tensors[, axis])

Hinweise:

  • clamp(), sigmoid(), exp() und matmul() entsprechen den gleichnamigen tensor:-Methoden, wobei der Tensor als erstes Argument übergeben wird.
  • where() unterstützt die Mischung aus Skalaren, Booleans und Tensoren und erzeugt das Ergebnis nach den Broadcast-Regeln.
  • Details zur Bildvorverarbeitung, OpenCV-Bridge und zu image_from_tensor() finden sich im Tensor-Modul.

Hilfen für Detection, Decoding und Nachverarbeitung​

  • onnxruntime.nms(boxes, scores[, opts])
  • onnxruntime.box_points(rotated_boxes)
  • onnxruntime.xywh_to_xyxy(boxes)
  • onnxruntime.xyxy_to_xywh(boxes)
  • onnxruntime.rotated_iou(lhs_box, rhs_box)
  • onnxruntime.rotated_nms(boxes, scores[, opts])
  • onnxruntime.create_decoder(schema)
  • onnxruntime.decode_yolo(output[, opts])
  • onnxruntime.decode_yolo_obb(output[, opts])
  • onnxruntime.decode_matrix_candidates(output, schema[, opts])
  • onnxruntime.decode_dense_detection(output, opts)
  • onnxruntime.records_from_boxes(boxes, scores, class_ids[, keep_indices])
  • onnxruntime.obb_records_from_rows(rows, scores, class_ids[, angles[, keep_indices[, opts]]])
  • onnxruntime.points_to_records(points[, opts])
  • onnxruntime.threshold_masks(masks, threshold)
  • onnxruntime.crop_masks_by_boxes(masks, boxes)
  • onnxruntime.resize_masks(masks, width, height[, opts])
  • onnxruntime.mask_iou(lhs_mask, rhs_mask)
  • onnxruntime.mask_to_polygon(mask[, opts])
  • onnxruntime.proto_masks(proto, coeffs, boxes, image_width, image_height[, opts])
  • onnxruntime.project_masks(proto, coeffs, boxes, image_width, image_height[, opts])
  • onnxruntime.db_postprocess(score_map[, opts])
  • onnxruntime.tracker([opts])
  • onnxruntime.reshape_keypoints(points[, keypoint_count[, keypoint_dim|opts]])
  • onnxruntime.scale_boxes(boxes, transform)
  • onnxruntime.clip_boxes(boxes, clip_width, clip_height)
  • onnxruntime.scale_points(points, transform[, opts])
  • onnxruntime.scale_keypoints(points, transform[, opts])
  • onnxruntime.clip_keypoints(points, clip_width, clip_height[, opts])
  • onnxruntime.ctc_greedy_decode(logits[, opts])
  • onnxruntime.sample_logits(logits[, opts])

Hinweise:

  • tensor_from_quad() / tensor_from_quads() erfordern zunächst require("image.cv") und eignen sich zum direkten Erzeugen von Tensoren nach dem Zuschneiden von OCR-Vierecken.
  • box_points() erhält einen Tensor für Rotationsboxen mit der Form [5], [1, 5] oder [N, 5], nicht fünf getrennte Skalarargumente.
  • create_decoder() gibt ein Decoderobjekt mit :decode(), :task() und :schema() zurück.
  • tracker() gibt ein Trackerobjekt mit :update(), :reset(), :state() und :close() zurück.
  • records_from_boxes(), obb_records_from_rows() und points_to_records() bereiten Tensorergebnisse als für Lua besser nutzbare Record-Tabellen auf.
  • proto_masks() und project_masks() verwenden derzeit dieselbe Implementierung; letzteres ist nur ein Alias.
  • mask_iou() berechnet direkt die Intersection-over-Union zweier Masken. Das dritte Argument opts wird ebenfalls unterstützt und kann compare_size = true oder explizit width / height enthalten.
  • db_postprocess() eignet sich für die Nachverarbeitung von Texterkennung wie DB / DBNet; jedes zurückgegebene Detection-Element enthält score, points und box.
  • decode_dense_detection() erfordert ein nicht leeres Array positiver Ganzzahlen in opts.strides sowie decode_width und decode_height; derzeit wird nur box_encoding = "grid_center_log_wh" unterstützt.
  • ctc_greedy_decode() unterstützt blank_index, merge_repeated, apply_softmax, return_probabilities und charset.
  • ctc_greedy_decode() gibt immer indices zurück; text nur bei übergebenem charset; confidence nur bei aktiviertem apply_softmax oder return_probabilities; probabilities und probability_confidence nur bei aktiviertem return_probabilities.
  • nms() / rotated_nms() geben einen int64-Tensor mit 1-basierten Indizes zurück.
  • sample_logits() unterstützt argmax, temperature, top_k, top_p, min_p und seed.
  • Für 1D-Logits gibt sample_logits() einen einzelnen Index zurück, für gebatchte Logits einen int64-Tensor.

Strukturierte Werte​

  • onnxruntime.value(value)
  • onnxruntime.optional(value, type_info)
  • onnxruntime.sequence(items)
  • onnxruntime.map(key_type, value_type, pairs)
  • onnxruntime.sparse_tensor(type, dense_shape, indices, values)
  • onnxruntime.sparse_tensor_from_dense(tensor)

Geeignet für Ein-/Ausgaben, die nicht nur aus Tensoren bestehen, etwa Optional, Sequence, Map und Sparse Tensor.

Das aktuelle Verhalten lässt sich wie folgt zusammenfassen:

  • onnxruntime.value(x) Wenn x bereits ein ORT-Tensor, Value, eine Sequence, Map oder ein Sparse Tensor ist, wird es unverändert zurückgegeben; eine Lua-Tabelle wird als sequence behandelt, andernfalls wird der Skalar in einen Tensor verpackt.
  • onnxruntime.optional(value, type_info) Das zweite Argument ist erforderlich; type_info kann eine Zeichenkette oder direkt die von session:input_info(...) / output_info(...) zurückgegebene Typinformationstabelle sein. Ein leeres Optional wird mit onnxruntime.optional(nil, type_info) dargestellt.
  • onnxruntime.map(key_type, value_type, pairs) key_type unterstützt derzeit nur "string" oder "int64".
  • onnxruntime.sparse_tensor(type, dense_shape, indices, values) Derzeit werden nur numerische / bool Sparse Tensor unterstützt, die im COO-Format erstellt werden; indices kann ein flaches Array oder ein Koordinatenarray sein.
  • onnxruntime.sparse_tensor_from_dense(tensor) string-Tensoren werden derzeit nicht unterstützt.

Häufig verwendete Objektmethoden:

  • value:type() / value:has_value() / value:get()
  • sequence:length() / sequence:get(i) / sequence:items()
  • map:get(key) / map:set(key, value) / map:keys() / map:pairs()
  • sparse_tensor:dense_shape() / sparse_tensor:values() / sparse_tensor:indices() / sparse_tensor:format() / sparse_tensor:to_dense()

Sessions und Inferenz​

  • onnxruntime.session(model_path[, opts])
  • onnxruntime.session_from_bytes(model_bytes[, opts])
  • onnxruntime.run_options([opts])
  • onnxruntime.load_custom_op_library(path)

Das Sessionobjekt lädt Modelle, fragt Ein-/Ausgabeinformationen ab, führt Inferenz aus und unterstützt IOBinding. Einzelheiten enthält das Session-Modul.

Unterstützte Datentypen​

Die Tensor-Schnittstellen unterstützen derzeit folgende Elementtypnamen:

  • "float32" / "float"
  • "float16"
  • "bfloat16"
  • "uint8"
  • "uint16"
  • "uint32"
  • "uint64"
  • "int8"
  • "int16"
  • "int32"
  • "int64"
  • "double" / "float64"
  • "bool"
  • "string"

Hinweise:

  • tensor_from_bytes() und copy_from_bytes() unterstützen nur numerische und bool-Typen.
  • bytes() unterstützt keine string-Tensoren.
  • tensor:to("string") unterstützt derzeit nur string -> string.

Hinweise zu Providern​

onnxruntime.providers() gibt die zur Laufzeit sichtbaren Provider zurück. Die in den aktuellen Session-Optionen nativ verarbeiteten und unterstützten Provider-Zeichenketten sind jedoch:

  • "cpu"
  • "coreml"

Hinweise:

  • provider / providers akzeptieren auch Aliase wie CPUExecutionProvider und CoreMLExecutionProvider, die intern zu "cpu" und "coreml" normalisiert werden.
  • Wenn kein Provider angegeben ist oder die Providerliste leer ist, ergänzt die Session-Erstellung automatisch den CPU-Provider.
  • Enthält die Providerliste "coreml" und ist fallback_to_cpu = true, kann die Implementierung CPU als Rückfallpfad ergänzen.
  • providers = {"coreml", "cpu"} bedeutet, dass zuerst CoreML und anschließend CPU versucht wird.

Zusammenspiel mit CoreML​

Wenn der coreml-Tokenizer oder die MLMultiArray-Vorverarbeitung wiederverwendet werden soll, wird folgende Kombination empfohlen:

local ort = require("onnxruntime")

local tokenizer = assert(coreml.new_text_tokenizer({
    type = "wordpiece",
    vocab_path = XXT_HOME_PATH.."/models/demo/vocab.txt",
    context_length = 52,
}))

local input_ids = assert(tokenizer:encode("hello", {
    output = "ort_tensor",
}))

Oder ein vorhandenes MLMultiArray direkt in einen ORT-Tensor umwandeln:

local ort = require("onnxruntime")
local tensor = assert(multi_array:to_ort_tensor("int64"))