Aller au contenu principal

Module ONNX Runtime (onnxruntime)

Ce module est disponible à partir des versions postérieures au 20260402
Prend uniquement en charge les systèmes iOS 13 et versions ultérieures

Le module onnxruntime sert à charger et exécuter directement des modèles ONNX sur l’appareil. Il convient aux scénarios d’inférence de texte, d’Embedding, de classification, de détection et de tenseurs génériques.

Charger le module​

local ort = require("onnxruntime")

Il s’agit d’un module chargé à la demande, contrairement à coreml, qui est un module global intégré.

Après l’exécution réussie de require("onnxruntime"), deux groupes d’interfaces de pont sont également injectés dans le module coreml intégré :

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

Ces deux conversions effectuent une copie directe au niveau natif, sans passer par une table Lua.

Fonctions au niveau du module​

Exécution et informations de base​

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

Description :

  • providers() renvoie la liste des Execution Provider réellement disponibles dans le runtime ORT actuel
  • configure() sert à définir les valeurs par défaut globales du runtime et doit être appelé avant la création de toute session

Tenseurs, images et fonctions numériques auxiliaires​

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

Description :

  • clamp(), sigmoid(), exp() et matmul() sont équivalentes aux méthodes tensor: du même nom ; elles transmettent simplement le tensor comme premier paramètre
  • where() accepte un mélange de scalaires, de valeurs booléennes et de tensors, puis produit le résultat selon les règles de broadcasting
  • pour les détails du prétraitement d’image, du pont OpenCV et de image_from_tensor(), consultez le module des tenseurs

Détection, décodage et fonctions auxiliaires de post-traitement​

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

Description :

  • tensor_from_quad() / tensor_from_quads() nécessitent d’abord require("image.cv") et conviennent à la génération directe d’un tenseur après le recadrage quadrilatéral OCR
  • box_points() reçoit un tensor de boîtes tournées de forme [5], [1, 5] ou [N, 5], et non cinq paramètres scalaires séparés
  • create_decoder() renvoie un objet decoder prenant en charge :decode(), :task() et :schema()
  • tracker() renvoie un objet tracker prenant en charge :update(), :reset(), :state() et :close()
  • records_from_boxes(), obb_records_from_rows() et points_to_records() organisent les résultats tensoriels en tables de records mieux adaptées à leur utilisation côté Lua
  • proto_masks() et project_masks() utilisent actuellement la même implémentation ; le second n’est qu’un alias
  • mask_iou() sert à calculer directement l’intersection sur union de deux masques ; il accepte également un troisième paramètre opts, auquel on peut transmettre compare_size = true ou fournir explicitement width / height
  • db_postprocess() convient au post-traitement de détection de texte de type DB / DBNet ; chaque élément de détection renvoyé contient score, points et box
  • decode_dense_detection() exige que opts.strides soit un tableau non vide d’entiers positifs, ainsi que decode_width et decode_height ; il ne prend actuellement en charge que box_encoding = "grid_center_log_wh"
  • ctc_greedy_decode() prend en charge blank_index, merge_repeated, apply_softmax, return_probabilities et charset
  • ctc_greedy_decode() renvoie toujours indices ; text n’est renvoyé que si charset est fourni ; confidence n’est renvoyé que si apply_softmax ou return_probabilities est activé ; probabilities et probability_confidence ne sont renvoyés que si return_probabilities est activé
  • nms() / rotated_nms() renvoient un tensor int64, avec une sémantique d’index 1-based
  • sample_logits() prend en charge argmax, temperature, top_k, top_p, min_p et seed
  • pour des logits 1D, sample_logits() renvoie un indice unique ; pour des logits par batch, elle renvoie un tensor int64

Valeurs structurées​

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

Ces fonctions servent à traiter des entrées et sorties qui ne sont pas de purs tensors, par exemple des optional, sequence, map et sparse tensor.

Le comportement actuel peut être résumé ainsi :

  • onnxruntime.value(x)
    Si x est déjà un ORT tensor, value, sequence, map ou sparse tensor, la valeur est renvoyée telle quelle ; si x est une table Lua, elle est traitée comme une sequence ; sinon, le scalaire est enveloppé dans un tensor
  • onnxruntime.optional(value, type_info)
    Le deuxième paramètre est obligatoire ; type_info peut être une chaîne ou recevoir directement la table d’informations de type renvoyée par session:input_info(...) / output_info(...) ; un optional vide est représenté par onnxruntime.optional(nil, type_info)
  • onnxruntime.map(key_type, value_type, pairs)
    Actuellement, key_type accepte uniquement "string" ou "int64"
  • onnxruntime.sparse_tensor(type, dense_shape, indices, values)
    Actuellement, seuls les sparse tensors numériques et bool sont pris en charge et construits selon le format COO ; indices peut être un tableau aplati ou un tableau de coordonnées
  • onnxruntime.sparse_tensor_from_dense(tensor)
    Les tensors string ne sont actuellement pas pris en charge

Méthodes d’objet courantes :

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

Session et inférence​

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

L’objet session est responsable du chargement du modèle, de la consultation des informations d’entrée et de sortie, de l’exécution de l’inférence et de IOBinding. Consultez le module des sessions.

Types de données pris en charge​

L’interface tensor actuelle prend en charge les noms de types d’éléments suivants :

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

Description :

  • tensor_from_bytes() et copy_from_bytes() prennent uniquement en charge les types numériques et bool
  • bytes() ne prend pas en charge les tensors string
  • tensor:to("string") ne prend actuellement en charge que string -> string

Description des Provider​

onnxruntime.providers() renvoie la liste des providers visibles par le runtime, mais les chaînes de provider traitées et prises en charge nativement dans les options de session actuelles sont :

  • "cpu"
  • "coreml"

Description :

  • provider / providers acceptent également des alias tels que CPUExecutionProvider et CoreMLExecutionProvider, qui sont normalisés en interne en "cpu" et "coreml"
  • si aucun provider n’est spécifié explicitement ou si la liste des providers est vide, la création de la session ajoute automatiquement le provider CPU
  • si la liste des providers contient "coreml" et que fallback_to_cpu = true, l’implémentation peut également ajouter CPU comme chemin de repli
  • si vous transmettez providers = {"coreml", "cpu"}, CoreML sera essayé en priorité, puis CPU

Utilisation conjointe avec CoreML​

Pour réutiliser le tokenizer coreml ou le flux de prétraitement MLMultiArray, il est recommandé de les combiner ainsi :

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

Ou bien, convertissez directement un MLMultiArray existant en tensor ORT :

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