Saltar al contenido principal

Módulo de tensores de ONNX Runtime

Este módulo solo está disponible a partir de las versiones posteriores a 20260402

Esta página describe las funciones y los métodos de objeto relacionados con tensor más utilizados del módulo onnxruntime.

Creación y conversión​

onnxruntime.tensor(type, shape[, data])​

tensor, mensaje_error = onnxruntime.tensor("float32", {1, 3}, {1, 2, 3})

Crea un tensor ORT normal.

  • type es el nombre del tipo de elemento
  • shape es el arreglo de forma
  • data puede omitirse; si se omite, se crea un tensor vacío
  • Un tensor numérico puede recibir un escalar, que se usará para llenar todo el tensor con el mismo valor
  • Un tensor string puede recibir una sola cadena, que se usará para llenar todo el tensor con la misma cadena

onnxruntime.tensor_from_bytes(type, shape, bytes)​

tensor, mensaje_error = onnxruntime.tensor_from_bytes("float32", {1, 3}, cadena_bytes_crudos)

Crea un tensor a partir de bytes crudos contiguos.

  • Solo admite tipos numéricos y bool
  • La longitud de los bytes debe coincidir exactamente con shape y type

onnxruntime.tensor_from_cv_mat(mat[, opts])​

tensor, mensaje_error = onnxruntime.tensor_from_cv_mat(mat, {
    layout = "hwc",
    channel_order = "rgb",
    type = "uint8",
})

Convierte un cv.mat en un tensor.

Nota:

  • Primero se debe ejecutar require("image.cv")
  • opts.type es el tipo de elemento del tensor de destino

onnxruntime.tensor_from_quad(mat, quad[, opts])​

tensor, mensaje_error = onnxruntime.tensor_from_quad(mat, {
    {x = 0, y = 0},
    {x = 100, y = 0},
    {x = 100, y = 32},
    {x = 0, y = 32},
}, {
    width = 100,
    height = 32,
    layout = "hwc",
    channel_order = "rgb",
    type = "uint8",
})

Realiza un recorte en perspectiva de una región cuadrilateral de un cv.mat y obtiene directamente un tensor ORT.

  • Primero se debe ejecutar require("image.cv")
  • quad puede recibir directamente cuatro puntos o una tabla que contenga el campo points
  • Las opciones habituales son básicamente las mismas que en tensor_from_image(); otros campos habituales son content_width, content_height y border_type
  • Es adecuado para enderezar y tensorizar un solo recuadro antes del reconocimiento OCR

onnxruntime.tensor_from_quads(mat, quads[, opts])​

lote_tensores, mensaje_error = onnxruntime.tensor_from_quads(mat, {
    {
        points = quad1,
        content_width = 96,
        content_height = 32,
    },
    {
        points = quad2,
        content_width = 80,
        content_height = 32,
    },
}, {
    width = 96,
    height = 32,
    resize_mode = "top_left_letterbox",
    border_type = "replicate",
})

Recorta varios cuadriláteros y los concatena automáticamente en un tensor batch.

  • Primero se debe ejecutar require("image.cv")
  • quads debe ser un arreglo no vacío; cada elemento puede contener points
  • content_width y content_height de cada elemento sobrescriben los campos del mismo nombre de las opciones globales opts
  • Según el rank del resultado, el valor devuelto usa automáticamente stack() o concat() para formar el batch; es adecuado para procesar varios recuadros OCR

onnxruntime.tensor_from_image(image[, opts])​

tensor, información_preprocesamiento = onnxruntime.tensor_from_image(objeto_imagen, {
    width = 224,
    height = 224,
    layout = "nchw",
    channel_order = "rgb",
    data_type = "float32",
    scale = 1 / 255,
    mean = {0.485, 0.456, 0.406},
    std = {0.229, 0.224, 0.225},
    resize_mode = "letterbox",
})

Convierte directamente un objeto de imagen en un tensor de entrada utilizable por ONNX Runtime.

Campos de configuración habituales:

  • width / height
  • layout: "nchw", "nhwc", "chw", "hwc"
  • channel_order: "rgb", "bgr", "gray", "grey", "grayscale"
  • data_type
  • scale
  • mean
  • std
  • resize_mode: "stretch", "letterbox", "center_crop"
  • letterbox_mode: admite "top_left"; en los demás casos el relleno se distribuye centrado
  • pad_color
  • interpolation: "bilinear", "nearest"
  • alpha_mode: "ignore", "white", "black", "premultiply"
  • crop = {x, y, width, height}
  • add_batch

Cuando tiene éxito, el segundo valor devuelto es una tabla de información de preprocesamiento que contiene:

  • src_width / src_height
  • crop_x / crop_y / crop_width / crop_height
  • dst_width / dst_height
  • resized_width / resized_height
  • layout
  • channel_order
  • resize_mode
  • scale_x / scale_y / ratio
  • offset_x / offset_y
  • pad_left / pad_top / pad_right / pad_bottom

onnxruntime.tensor_from_images(images[, opts])​

lote_tensores, metadatos_lote = onnxruntime.tensor_from_images({img1, img2}, {
    width = 640,
    height = 640,
    layout = "nchw",
})

Convierte un grupo de imágenes en un tensor batch.

  • Las dimensiones de las imágenes originales pueden ser diferentes
  • Siempre que la forma de salida analizada de cada imagen coincida con data_type, se pueden concatenar en un batch
  • El segundo valor devuelto es un arreglo de metadatos en el mismo orden que la entrada

onnxruntime.image_from_tensor(tensor[, opts])​

objeto_imagen, mensaje_error = onnxruntime.image_from_tensor(tensor, {
    layout = "nchw",
    channel_order = "rgb",
    batch_index = 1,
    scale = 1 / 255,
    mean = {0.485, 0.456, 0.406},
    std = {0.229, 0.224, 0.225},
    value_range = "0_1",
})

Restaura un tensor 2D / 3D / 4D como objeto de imagen, lo que resulta adecuado para depurar las entradas y salidas del modelo.

Campos de configuración habituales:

  • layout
  • channel_order
  • batch_index: basado en 1; por defecto es el batch número 1
  • scale
  • mean
  • std
  • clamp
  • value_range: "0_255" o "0_1"

Nota:

  • Solo admite tensores 2D / 3D / 4D
  • El número de canales solo puede ser 1 o 3

Métodos del objeto tensor​

Información básica​

  • tensor:shape()
  • tensor:rank()
  • tensor:size()
  • tensor:type()
  • tensor:to_table()
  • tensor:bytes()

Nota:

  • to_table() expande el contenido en una tabla Lua
  • bytes() solo admite tensores numéricos y bool

Lectura, escritura y copia​

  • tensor:get(index1[, index2, ...])
  • tensor:set(index1[, index2, ...], value)
  • tensor:fill(value_or_table)
  • tensor:clone()
  • tensor:copy_from_bytes(raw_bytes)
  • tensor:to(type)

Nota:

  • Al pasar un escalar a fill(), se llena todo el tensor; al pasar una tabla, el número de elementos debe coincidir exactamente
  • copy_from_bytes() solo admite tensores numéricos y bool; la longitud de los bytes debe coincidir exactamente
  • La semántica de los índices de get() / set() es basada en 1
  • tensor:to("string") actualmente solo admite string -> string

Forma e indexación​

  • tensor:reshape(shape)
  • tensor:transpose([axes])
  • tensor:flatten([start_dim[, end_dim]])
  • tensor:squeeze([dim])
  • tensor:unsqueeze(dim)
  • tensor:slice(dim, start, stop[, step])
  • tensor:select(dim, index)
  • tensor:gather(dim, indices)

Nota:

  • Tanto start como stop de slice() son basados en 1 e incluyen la posición final
  • step de slice() debe ser un entero positivo
  • select() elimina la dimensión seleccionada
  • indices de gather() puede ser un arreglo Lua o un tensor de forma [N]; la semántica de índices también es basada en 1
  • Todos estos métodos devuelven objetos tensor nuevos

Operaciones numéricas​

  • tensor:add(other)
  • tensor:sub(other)
  • tensor:mul(other)
  • tensor:div(other)
  • tensor:clamp(min, max)
  • tensor:sigmoid()
  • tensor:exp()
  • tensor:matmul(other)
  • tensor:dot(other)

Nota:

  • other puede ser un escalar o un tensor con la misma forma
  • matmul() actualmente admite combinaciones de tensores de rank 1 / rank 2
  • El tipo de resultado devuelto por sigmoid() / exp() / matmul() se promueve a un tipo de resultado de punto flotante
  • Ninguna de las operaciones anteriores admite tensores string

Reducción, ordenación y probabilidad​

  • tensor:argmax([axis])
  • tensor:sum([axis])
  • tensor:mean([axis])
  • tensor:max([axis])
  • tensor:min([axis])
  • tensor:softmax([axis])
  • tensor:normalize([axis])
  • tensor:sort([axis[, descending]])
  • tensor:topk(k[, axis])

Nota:

  • Si no se pasa un eje a argmax(), devuelve un único índice basado en 1
  • argmax(axis) devuelve un tensor int64; la semántica de índices también es basada en 1
  • sort() devuelve { values = tensor, indices = tensor }
  • topk() devuelve { values = tensor, indices = tensor }
  • Los índices devueltos por sort() / topk() son basados en 1

Puente con OpenCV​

  • tensor:to_cv_mat([opts])
mat, mensaje_error = tensor:to_cv_mat({
    layout = "hwc",
    channel_order = "rgb",
    coreml_data_type = "uint8",
})

Nota:

  • Primero se debe ejecutar require("image.cv")
  • Algunos tipos de tensor no se pueden asignar directamente a cv.mat; en ese caso se debe pasar explícitamente coreml_data_type

Utilidades de tensores a nivel de módulo​

Utilidades numéricas básicas​

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

Nota:

  • clamp(), sigmoid(), exp() y matmul() comparten la misma implementación que los métodos tensor: correspondientes
  • where() admite mezclar escalares / valores booleanos / tensores y calcula el resultado según las reglas de broadcasting

Utilidades adicionales de posprocesamiento​

  • onnxruntime.mask_iou(lhs_mask, rhs_mask)
  • onnxruntime.db_postprocess(score_map[, opts])

Nota:

  • mask_iou() calcula directamente la intersección sobre unión de dos máscaras
  • mask_iou() también admite un tercer parámetro opts, al que se puede pasar compare_size = true o especificar width / height como dimensiones de comparación tras la alineación
  • db_postprocess() es adecuado para el posprocesamiento de detección de texto de tipo DB / DBNet; la entrada admite [H, W], [C, H, W] o [N, C, H, W]
  • db_postprocess() devuelve un arreglo de detecciones, cuyos elementos incluyen score, points y box; meta / image_meta pueden reutilizar directamente los metadatos devueltos por la tensorización de imágenes

onnxruntime.nms(boxes, scores[, opts])​

NMS para recuadros rectangulares normales.

Opciones habituales:

  • iou_threshold
  • score_threshold
  • top_k
  • class_aware
  • class_ids

El valor devuelto es un tensor int64, con índices basados en 1.

onnxruntime.box_points(rotated_boxes)​

Convierte un recuadro rotado [cx, cy, w, h, theta] en las coordenadas de sus cuatro vértices.

  • La entrada puede ser un tensor de forma [5], [1, 5] o [N, 5]
  • Para un solo recuadro devuelve una tabla Lua de puntos; para varios recuadros devuelve un arreglo de tablas de puntos

onnxruntime.xywh_to_xyxy(boxes)​

Convierte un recuadro rectangular de [cx, cy, w, h] a [x1, y1, x2, y2].

onnxruntime.xyxy_to_xywh(boxes)​

Convierte un recuadro rectangular de [x1, y1, x2, y2] a [cx, cy, w, h].

onnxruntime.rotated_iou(box1, box2)​

Calcula el IoU de dos recuadros rotados.

onnxruntime.rotated_nms(boxes, scores[, opts])​

NMS para recuadros rotados. El valor devuelto también es un tensor int64, con índices basados en 1.

  • boxes debe ser un tensor de recuadros rotados con forma [N, 5]
  • scores puede ser un arreglo Lua o un tensor de forma [N] / [N, 1]

onnxruntime.create_decoder(schema)​

Crea un objeto decoder reutilizable.

  • El objeto decoder admite :decode(output[, opts]), :task() y :schema()
  • Es adecuado para fijar primero el schema de las salidas de detección / OBB / clasificación y reutilizarlo varias veces

onnxruntime.decode_yolo(output[, opts])​

Decodifica directamente según la lógica integrada de detección YOLO y devuelve una lista de registros de detección.

onnxruntime.decode_yolo_obb(output[, opts])​

Decodifica directamente según la lógica integrada YOLO OBB y devuelve una lista de registros de detección de recuadros rotados.

onnxruntime.decode_matrix_candidates(output, schema[, opts])​

Divide la salida matricial en una tabla de tensores candidatos según el schema. Los campos habituales incluyen:

  • boxes
  • scores
  • class_ids
  • keep_indices
  • selected_rows
  • angles (solo para schemas relacionados con OBB y otros)

onnxruntime.decode_dense_detection(output, opts)​

Decodifica la salida del dense detection head en:

  • boxes
  • scores
  • labels

boxes / scores / labels son tensores.

  • La entrada admite [R, C] o [N, R, C]
  • opts.strides es obligatorio y debe ser un arreglo no vacío de enteros positivos
  • decode_width y decode_height también son obligatorios
  • Actualmente solo admite box_encoding = "grid_center_log_wh"
  • Otros campos habituales incluyen box_offset, score_offset, class_offset, num_classes y score_threshold
  • Cuando se pasa una salida batched, el valor devuelto es un arreglo Lua organizado por batch

onnxruntime.records_from_boxes(boxes, scores, class_ids[, keep_indices])​

Organiza los tensores de recuadros [N, 4], puntuaciones, clases, etc. en una lista de registros Lua. Cada elemento suele incluir:

  • box
  • score
  • class_id
  • row_index
  • x1 / y1 / x2 / y2
  • width / height
  • cx / cy

onnxruntime.obb_records_from_rows(rows, scores, class_ids[, angles[, keep_indices[, opts]]])​

Organiza los datos de filas OBB en una lista de registros Lua.

  • opts admite x_index, y_index, width_index y height_index

onnxruntime.points_to_records(points[, opts])​

Organiza un tensor de puntos / puntos clave con forma [N, P, D] o [N, P*D] en una tabla Lua.

  • opts admite point_count / keypoint_count
  • opts admite point_dim / keypoint_dim

Utilidades de máscaras​

onnxruntime.threshold_masks(masks, threshold)​

Aplica un umbral a un tensor de máscaras continuas y lo convierte en una lista de tablas de máscaras Lua. Cada máscara contiene:

  • width
  • height
  • bits
  • pixel_count
  • bounds

onnxruntime.crop_masks_by_boxes(masks, boxes)​

Recorta la lista de máscaras umbralizadas según recuadros [N, 4].

onnxruntime.resize_masks(masks, width, height[, opts])​

Redimensiona la lista de máscaras a las dimensiones especificadas.

  • Actualmente solo admite opts.interpolation = "nearest"

onnxruntime.mask_to_polygon(mask[, opts])​

Convierte una máscara binaria individual en una secuencia de puntos poligonales.

  • opts.epsilon / opts.approx_epsilon se pueden usar para simplificar de forma aproximada

onnxruntime.proto_masks(proto, coeffs, boxes, image_width, image_height[, opts])​

Proyecta la máscara prototipo, los coeficientes de máscara y los recuadros de detección a las dimensiones de la imagen de destino.

  • project_masks() es su alias
  • El valor devuelto es una lista de tablas de máscaras Lua, no un tensor

Utilidades de puntos clave y geometría​

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

Nota:

  • reshape_keypoints() admite reorganizar entre [N, K*D] y [N, K, D]
  • scale_points() interpreta por defecto el diseño de puntos normales; scale_keypoints() interpreta por defecto el diseño de puntos clave
  • La tabla relacionada con transform se alinea con los campos de metadatos del preprocesamiento de imágenes; los campos habituales incluyen scale_x, scale_y, pad_left y pad_top

onnxruntime.tracker([opts])​

Crea un objeto tracker reutilizable que admite:

  • tracker:update(detections[, timestamp])
  • tracker:reset()
  • tracker:state()
  • tracker:close()

Campos de configuración habituales:

  • iou_threshold
  • max_age
  • min_hits

onnxruntime.ctc_greedy_decode(logits[, opts])​

Devuelve una estructura con la forma:

  • indices

  • text

  • confidence

  • La entrada admite [T, C] o [N, T, C]

  • Admite blank_index, merge_repeated, apply_softmax, return_probabilities y charset

  • Siempre devuelve indices

  • Solo incluye text cuando se ha pasado charset

  • Solo incluye confidence cuando se ha habilitado apply_softmax o return_probabilities

  • Solo incluye adicionalmente probabilities y probability_confidence cuando se ha habilitado return_probabilities

  • Cuando la entrada es un batch, devuelve un arreglo de resultados por batch

onnxruntime.sample_logits(logits[, opts])​

Admite los siguientes parámetros de muestreo:

  • argmax
  • temperature
  • top_k
  • top_p
  • min_p
  • seed

Los logits 1D devuelven un único índice; los logits de varias filas devuelven un tensor int64, cuya semántica de índices es basada en 1.

Ejemplo​

local ort = require("onnxruntime")

local tensor = assert(ort.tensor("float32", {2, 3}, {
    1, 9, 3,
    8, 2, 7,
}))

local sliced = assert(tensor:slice(2, 2, 3))
print(sliced:to_table()[1]) -- 9

local topk = assert(tensor:topk(2, 2))
print(topk.values:to_table()[1])  -- 9
print(topk.indices:to_table()[1]) -- 2