Pular para o conteúdo principal

Módulo de tensores do ONNX Runtime

Este módulo está disponível a partir da versão 20260402.

Esta página descreve as funções relacionadas a tensor e os métodos de objeto mais usados do módulo onnxruntime.

Criação e conversão​

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

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

Cria um tensor ORT comum.

  • type é o nome do tipo de elemento.
  • shape é o array de dimensões.
  • data é opcional; quando omitido, cria um tensor vazio.
  • Para tensores numéricos, é possível passar um escalar para preencher todo o tensor com o mesmo valor.
  • Para um tensor string, é possível passar uma única string para preencher todo o tensor com ela.

onnxruntime.tensor_from_bytes(type, shape, bytes)​

tensor, mensagem_de_erro = onnxruntime.tensor_from_bytes("float32", {1, 3}, bytes_brutos)

Cria um tensor a partir de bytes brutos contíguos.

  • Aceita apenas tipos numéricos e bool.
  • O comprimento em bytes deve corresponder exatamente a shape e type.

onnxruntime.tensor_from_cv_mat(mat[, opts])​

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

Converte um cv.mat em um tensor.

Descrição:

  • Primeiro é necessário executar require("image.cv").
  • opts.type é o tipo de elemento do tensor de destino.

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

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

Recorta uma região quadrilateral de um cv.mat usando transformação de perspectiva e produz diretamente um tensor ORT.

  • Primeiro é necessário executar require("image.cv").
  • quad pode receber diretamente quatro pontos ou uma tabela com o campo points.
  • As opções comuns são praticamente as mesmas de tensor_from_image(); campos adicionais comuns incluem content_width, content_height e border_type.
  • É adequado para retificar e transformar em tensor uma única caixa antes do reconhecimento OCR.

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

tensor_batch, mensagem_de_erro = 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 vários quadriláteros em lote e os combina automaticamente em um tensor batch.

  • Primeiro é necessário executar require("image.cv").
  • quads deve ser um array não vazio; cada item pode conter points.
  • content_width e content_height de cada item substituem os campos de mesmo nome em opts global.
  • O valor retornado é combinado em um batch automaticamente por meio de stack() ou concat(), conforme o rank do resultado, sendo adequado ao processamento de várias caixas de OCR.

onnxruntime.tensor_from_image(image[, opts])​

tensor, informações_de_pré_processamento = onnxruntime.tensor_from_image(objeto_de_imagem, {
    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",
})

Converte diretamente um objeto de imagem no tensor de entrada aceito pelo ONNX Runtime.

Campos de configuração comuns:

  • 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: aceita "top_left"; nos demais casos, adiciona bordas centralizadas
  • pad_color
  • interpolation: "bilinear", "nearest"
  • alpha_mode: "ignore", "white", "black", "premultiply"
  • crop = {x, y, width, height}
  • add_batch

Em caso de sucesso, o segundo valor retornado é uma tabela de informações de pré-processamento que contém:

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

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

Converte um conjunto de imagens em um tensor batch.

  • As dimensões das imagens originais podem ser diferentes.
  • É possível formar um batch desde que o shape de saída processado e o data_type sejam iguais para todas as imagens.
  • O segundo valor retornado é um array de metadados na mesma ordem das entradas.

onnxruntime.image_from_tensor(tensor[, opts])​

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

Reconstrói um tensor 2D / 3D / 4D como objeto de imagem, sendo adequado para depurar entradas e saídas do modelo.

Campos de configuração comuns:

  • layout
  • channel_order
  • batch_index: baseado em 1; o padrão é o batch 1.
  • scale
  • mean
  • std
  • clamp
  • value_range: "0_255" ou "0_1"

Descrição:

  • Aceita apenas tensores 2D / 3D / 4D.
  • O número de canais deve ser 1 ou 3.

Métodos do objeto tensor​

Informações básicas​

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

Descrição:

  • to_table() expande o conteúdo em uma tabela Lua.
  • bytes() aceita apenas tensores numéricos e bool.

Leitura, escrita e cópia​

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

Descrição:

  • Ao receber um escalar, fill() preenche todo o tensor; ao receber uma tabela, a quantidade de elementos deve corresponder exatamente.
  • copy_from_bytes() aceita apenas tensores numéricos e bool, e o comprimento em bytes deve corresponder exatamente.
  • Os índices de get() / set() são baseados em 1.
  • tensor:to("string") atualmente aceita apenas string -> string.

Shape e índices​

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

Descrição:

  • start e stop de slice() são baseados em 1 e incluem a posição final.
  • O step de slice() deve ser um inteiro positivo.
  • select() remove a dimensão selecionada.
  • indices de gather() pode ser um array Lua ou um tensor com shape [N]; os índices também são baseados em 1.
  • Todos esses métodos retornam novos objetos tensor.

Operações 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)

Descrição:

  • other pode ser um escalar ou um tensor com o mesmo shape.
  • matmul() atualmente aceita combinações de tensores rank-1 / rank-2.
  • O valor retornado por sigmoid() / exp() / matmul() é promovido para um tipo de resultado de ponto flutuante.
  • Nenhuma dessas operações aceita tensor string.

Redução, ordenação e probabilidades​

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

Descrição:

  • Sem um eixo, argmax() retorna um único índice baseado em 1.
  • argmax(axis) retorna um tensor int64; seus índices também são baseados em 1.
  • sort() retorna { values = tensor, indices = tensor }.
  • topk() retorna { values = tensor, indices = tensor }.
  • Os índices retornados por sort() / topk() são baseados em 1.

Ponte OpenCV​

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

Descrição:

  • Primeiro é necessário executar require("image.cv").
  • Alguns tipos de tensor não podem ser mapeados diretamente para cv.mat; nesse caso, passe coreml_data_type explicitamente.

Auxiliares de tensor do módulo​

Auxiliares numéricos básicos​

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

Descrição:

  • clamp(), sigmoid(), exp() e matmul() compartilham a implementação com os métodos tensor: correspondentes.
  • where() aceita uma combinação de escalares, booleanos e tensores e calcula o resultado segundo as regras de broadcasting.

Auxiliares adicionais de pós-processamento​

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

Descrição:

  • mask_iou() calcula diretamente a interseção sobre união de duas masks.
  • mask_iou() também aceita o terceiro argumento opts, com compare_size = true ou width / height explícitos como dimensões de comparação alinhadas.
  • db_postprocess() é adequado ao pós-processamento de detecção de texto do tipo DB / DBNet; a entrada aceita [H, W], [C, H, W] ou [N, C, H, W].
  • db_postprocess() retorna um array de detecções, em que cada item contém score, points e box; meta / image_meta pode reutilizar diretamente os metadados retornados pela transformação da imagem em tensor.

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

NMS de caixas retangulares comuns.

Opções comuns:

  • iou_threshold
  • score_threshold
  • top_k
  • class_aware
  • class_ids

O valor retornado é um tensor int64, com índices baseados em 1.

onnxruntime.box_points(rotated_boxes)​

Converte uma caixa rotacionada [cx, cy, w, h, theta] em coordenadas de quatro vértices.

  • A entrada pode ser um tensor com shape [5], [1, 5] ou [N, 5].
  • Para uma única caixa, retorna uma tabela Lua de pontos; para várias caixas, retorna um array de tabelas de pontos.

onnxruntime.xywh_to_xyxy(boxes)​

Converte caixas retangulares de [cx, cy, w, h] para [x1, y1, x2, y2].

onnxruntime.xyxy_to_xywh(boxes)​

Converte caixas retangulares de [x1, y1, x2, y2] para [cx, cy, w, h].

onnxruntime.rotated_iou(box1, box2)​

Calcula o IoU de duas caixas rotacionadas.

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

NMS de caixas rotacionadas. O valor retornado também é um tensor int64, com índices baseados em 1.

  • boxes deve ser um tensor de caixas rotacionadas com shape [N, 5].
  • scores pode ser um array Lua ou um tensor com shape [N] / [N, 1].

onnxruntime.create_decoder(schema)​

Cria um objeto decoder reutilizável.

  • O objeto decoder aceita :decode(output[, opts]), :task() e :schema().
  • É adequado para fixar previamente o schema de saídas de detecção / OBB / classificação e reutilizá-lo várias vezes.

onnxruntime.decode_yolo(output[, opts])​

Decodifica diretamente segundo a lógica de detecção YOLO integrada e retorna uma lista de records de detecção.

onnxruntime.decode_yolo_obb(output[, opts])​

Decodifica diretamente segundo a lógica YOLO OBB integrada e retorna uma lista de records de detecção de caixas rotacionadas.

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

Divide a saída matricial em uma tabela de tensores candidatos segundo o schema; os campos retornados normalmente incluem:

  • boxes
  • scores
  • class_ids
  • keep_indices
  • selected_rows
  • angles (apenas em schemas relacionados a OBB)

onnxruntime.decode_dense_detection(output, opts)​

Decodifica a saída do dense detection head em:

  • boxes
  • scores
  • labels

boxes / scores / labels são tensores.

  • A entrada aceita [R, C] ou [N, R, C].
  • opts.strides é obrigatório e deve ser um array não vazio de inteiros positivos.
  • decode_width e decode_height também são obrigatórios.
  • Atualmente, aceita apenas box_encoding = "grid_center_log_wh".
  • Outros campos comuns incluem box_offset, score_offset, class_offset, num_classes e score_threshold.
  • Quando a saída é fornecida em batch, o valor retornado é um array Lua organizado por batch.

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

Organiza os tensores de caixas [N, 4], scores e classes em uma lista Lua de records; cada item normalmente contém:

  • 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 os dados de linhas OBB em uma lista Lua de records.

  • opts aceita x_index, y_index, width_index e height_index.

onnxruntime.points_to_records(points[, opts])​

Organiza tensores de pontos / keypoints com shape [N, P, D] ou [N, P*D] em uma table Lua.

  • opts aceita point_count / keypoint_count.
  • opts aceita point_dim / keypoint_dim.

Auxiliares de masks​

onnxruntime.threshold_masks(masks, threshold)​

Converte um tensor mask contínuo em uma lista de tabelas mask Lua por limiarização. Cada mask contém:

  • width
  • height
  • bits
  • pixel_count
  • bounds

onnxruntime.crop_masks_by_boxes(masks, boxes)​

Recorta a lista de masks limiarizadas usando caixas [N, 4].

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

Redimensiona a lista de masks para as dimensões especificadas.

  • Atualmente, aceita apenas opts.interpolation = "nearest".

onnxruntime.mask_to_polygon(mask[, opts])​

Converte uma mask binária individual em uma lista de pontos poligonais.

  • opts.epsilon / opts.approx_epsilon podem ser usados para simplificação aproximada.

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

Projeta a mask protótipo, os coeficientes da mask e as caixas de detecção de volta para as dimensões da imagem de destino.

  • project_masks() é seu alias.
  • O valor retornado é uma lista de tabelas mask Lua, não um tensor.

Auxiliares de keypoints e geometria​

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

Descrição:

  • reshape_keypoints() organiza dados entre [N, K*D] e [N, K, D].
  • scale_points() interpreta por padrão um layout de pontos comuns; scale_keypoints() interpreta por padrão um layout de keypoints.
  • A table relacionada a transform usa os mesmos campos dos metadados de pré-processamento de imagem; campos comuns incluem scale_x, scale_y, pad_left e pad_top.

onnxruntime.tracker([opts])​

Cria um objeto tracker reutilizável com suporte a:

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

Campos de configuração comuns:

  • iou_threshold
  • max_age
  • min_hits

onnxruntime.ctc_greedy_decode(logits[, opts])​

Retorna uma estrutura como:

  • indices

  • text

  • confidence

  • A entrada aceita [T, C] ou [N, T, C].

  • Aceita blank_index, merge_repeated, apply_softmax, return_probabilities e charset.

  • Sempre retorna indices.

  • text só aparece quando charset é fornecido.

  • confidence só aparece quando apply_softmax ou return_probabilities está habilitado.

  • probabilities e probability_confidence só aparecem adicionalmente quando return_probabilities está habilitado.

  • Quando a entrada é um batch, retorna um array de resultados por batch.

onnxruntime.sample_logits(logits[, opts])​

Aceita os seguintes parâmetros de amostragem:

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

Logits 1D retornam um único índice; logits com várias linhas retornam um tensor int64, com índices baseados em 1.

Exemplo​

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