Saltar al contenido principal

Módulo ONNX Runtime (onnxruntime)

Este módulo solo está disponible a partir de la versión 20260402
Solo admite sistemas iOS 13 y posteriores

El módulo onnxruntime permite cargar y ejecutar directamente modelos ONNX en el dispositivo, y resulta adecuado para inferencia de texto, embeddings, clasificación, detección y tensores de uso general.

Cargar el módulo​

local ort = require("onnxruntime")

Es un módulo que se carga bajo demanda; a diferencia de coreml, no es un módulo global integrado.

Después de ejecutar correctamente require("onnxruntime"), también inyecta dos grupos de interfaces puente en el módulo integrado coreml:

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

Ambas conversiones copian directamente en la capa nativa y no pasan por una tabla Lua.

Funciones de nivel de módulo​

Entorno de ejecución e información básica​

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

Explicación:

  • providers() devuelve la lista de Execution Provider realmente disponible en el entorno ORT actual
  • configure() establece los valores predeterminados globales del entorno; debe llamarse antes de crear cualquier session

Asistentes para tensores, imágenes y valores numéricos​

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

Explicación:

  • clamp(), sigmoid(), exp() y matmul() equivalen a los métodos tensor: del mismo nombre; la diferencia es que reciben tensor como primer parámetro
  • where() permite mezclar escalares, valores booleanos y tensor, y genera el resultado según las reglas de broadcasting
  • Consulta los detalles del preprocesamiento de imágenes, el puente OpenCV y image_from_tensor() en el módulo de tensores

Asistentes de detección, decodificación y posprocesamiento​

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

Explicación:

  • tensor_from_quad() / tensor_from_quads() requieren primero require("image.cv") y sirven para generar directamente tensores después de recortar cuadriláteros para OCR
  • box_points() recibe un tensor de cajas rotadas con forma [5], [1, 5] o [N, 5], no cinco parámetros escalares separados
  • create_decoder() devuelve un objeto decoder compatible con :decode(), :task() y :schema()
  • tracker() devuelve un objeto tracker compatible con :update(), :reset(), :state() y :close()
  • records_from_boxes(), obb_records_from_rows() y points_to_records() organizan los resultados tensor en tablas record más fáciles de consumir desde Lua
  • proto_masks() y project_masks() usan actualmente la misma implementación; el segundo es solo un alias
  • mask_iou() calcula directamente la intersección sobre unión de dos mask y también admite un tercer parámetro opts, con compare_size = true o width / height explícitos
  • db_postprocess() es adecuado para el posprocesamiento de detección de texto de tipo DB / DBNet; cada elemento devuelto incluye score, points y box
  • decode_dense_detection() requiere que opts.strides sea una matriz no vacía de enteros positivos y también necesita decode_width y decode_height; actualmente solo admite box_encoding = "grid_center_log_wh"
  • ctc_greedy_decode() admite blank_index, merge_repeated, apply_softmax, return_probabilities y charset
  • ctc_greedy_decode() siempre devuelve indices; solo devuelve text si se proporciona charset; confidence solo aparece al activar apply_softmax o return_probabilities; probabilities y probability_confidence solo aparecen al activar return_probabilities
  • nms() / rotated_nms() devuelven un tensor int64 con índices 1-based
  • sample_logits() admite argmax, temperature, top_k, top_p, min_p y seed
  • sample_logits() devuelve un índice individual para logits 1D y un tensor int64 para logits por lotes

Valores estructurados​

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

Son adecuados para entradas y salidas que no sean solo tensor, como optional, sequence, map y sparse tensor.

El comportamiento actual puede resumirse así:

  • onnxruntime.value(x): si x ya es un ORT tensor, value, sequence, map o sparse tensor, lo devuelve sin cambios; si es una tabla Lua, la trata como sequence; en caso contrario, envuelve el escalar en un tensor
  • onnxruntime.optional(value, type_info): el segundo parámetro es obligatorio; type_info puede ser una cadena o la tabla de información de tipos devuelta por session:input_info(...) / output_info(...); un optional vacío se representa como onnxruntime.optional(nil, type_info)
  • onnxruntime.map(key_type, value_type, pairs): actualmente key_type solo admite "string" o "int64"
  • onnxruntime.sparse_tensor(type, dense_shape, indices, values): actualmente solo admite tensores dispersos numéricos / bool, construidos en formato COO; indices puede ser una matriz plana o una matriz de coordenadas
  • onnxruntime.sparse_tensor_from_dense(tensor): actualmente no admite tensor string

Métodos habituales de los objetos:

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

Sesiones e inferencia​

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

El objeto session se encarga de cargar el modelo, consultar la información de entradas y salidas, ejecutar la inferencia y gestionar IOBinding. Consulta el módulo de sesiones.

Tipos de datos admitidos​

La interfaz de tensores admite actualmente los siguientes nombres de tipos de elemento:

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

Explicación:

  • tensor_from_bytes() y copy_from_bytes() solo admiten tipos numéricos y bool
  • bytes() no admite tensor string
  • tensor:to("string") actualmente solo admite string -> string

Proveedores​

onnxruntime.providers() devuelve la lista de providers visibles para el entorno, pero las cadenas de provider que las opciones de session procesan y admiten de forma nativa son:

  • "cpu"
  • "coreml"

Explicación:

  • provider / providers también aceptan alias como CPUExecutionProvider y CoreMLExecutionProvider, que internamente se normalizan a "cpu" y "coreml"
  • Si no se especifica un provider o la lista está vacía, la creación de la session añade automáticamente el provider CPU
  • Si la lista incluye "coreml" y fallback_to_cpu = true, la implementación también puede añadir CPU como ruta de respaldo
  • Si se pasa providers = {"coreml", "cpu"}, se intenta primero CoreML y luego CPU

Integración con CoreML​

Para reutilizar el tokenizador coreml o el flujo de preprocesamiento de MLMultiArray, se recomienda esta combinación:

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

También se puede convertir directamente un MLMultiArray existente en un tensor ORT:

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