Pular para o conteúdo principal

Módulo ONNX Runtime (onnxruntime)

Este módulo está disponível a partir da versão 20260402.
Compatível apenas com iOS 13 ou posterior.

O módulo onnxruntime carrega e executa modelos ONNX diretamente no dispositivo, sendo adequado para texto, embeddings, classificação, detecção e vários cenários de inferência com tensores.

Carregar o módulo​

local ort = require("onnxruntime")

Este é um módulo carregado sob demanda; ao contrário de coreml, não é um módulo global integrado.

Depois que require("onnxruntime") é executado com sucesso, duas interfaces de ponte também são injetadas no módulo integrado coreml:

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

Ambas as conversões copiam os dados diretamente na camada nativa, sem passar por uma tabela Lua.

Funções do módulo​

Informações básicas e do runtime​

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

Descrição:

  • providers() retorna a lista de Execution Providers realmente disponíveis no runtime ORT atual.
  • configure() define os valores padrão globais do runtime e deve ser chamado antes da criação de qualquer session.

Auxiliares de tensores, imagens e 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])

Descrição:

  • clamp(), sigmoid(), exp() e matmul() são equivalentes aos métodos tensor: de mesmo nome; a diferença é que o tensor é passado como primeiro argumento.
  • where() aceita uma combinação de escalares, booleanos e tensores e gera o resultado seguindo as regras de broadcasting.
  • Para detalhes sobre pré-processamento de imagens, a ponte OpenCV e image_from_tensor(), consulte o módulo de tensores.

Auxiliares de detecção, decodificação e pós-processamento​

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

Descrição:

  • tensor_from_quad() / tensor_from_quads() exigem primeiro require("image.cv") e são adequados para gerar diretamente tensores após o recorte quadrilateral de OCR.
  • box_points() recebe um tensor de caixa rotacionada com forma [5], [1, 5] ou [N, 5], não cinco parâmetros escalares separados.
  • create_decoder() retorna um objeto decoder com suporte a :decode(), :task() e :schema().
  • tracker() retorna um objeto tracker com suporte a :update(), :reset(), :state() e :close().
  • records_from_boxes(), obb_records_from_rows() e points_to_records() organizam os resultados tensor em tabelas de records mais adequadas ao consumo no lado Lua.
  • proto_masks() e project_masks() usam atualmente a mesma implementação; a segunda é apenas um alias.
  • mask_iou() calcula diretamente a interseção sobre união de duas masks. Também aceita um terceiro argumento opts, com compare_size = true ou width / height explícitos.
  • db_postprocess() é adequado ao pós-processamento de detecção de texto do tipo DB / DBNet; cada item retornado contém score, points e box.
  • decode_dense_detection() exige que opts.strides seja um array não vazio de inteiros positivos e também exige decode_width e decode_height; atualmente aceita apenas box_encoding = "grid_center_log_wh".
  • ctc_greedy_decode() aceita blank_index, merge_repeated, apply_softmax, return_probabilities e charset.
  • ctc_greedy_decode() sempre retorna indices; text só é retornado quando charset é fornecido; confidence só é retornado quando apply_softmax ou return_probabilities está habilitado; probabilities e probability_confidence só são retornados quando return_probabilities está habilitado.
  • nms() / rotated_nms() retornam um tensor int64, com índices baseados em 1.
  • sample_logits() aceita argmax, temperature, top_k, top_p, min_p e seed.
  • Para logits 1D, sample_logits() retorna um único índice; para logits em batch, retorna um tensor int64.

Valores estruturados​

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

São adequados para entradas e saídas que não são apenas tensores, como optional, sequence, map e sparse tensor.

O comportamento atual pode ser resumido assim:

  • onnxruntime.value(x) Se x já for um ORT tensor / value / sequence / map / sparse tensor, é retornado sem alterações; se x for uma tabela Lua, será tratado como sequence; caso contrário, o escalar será encapsulado em um tensor.
  • onnxruntime.optional(value, type_info) O segundo argumento é obrigatório; type_info pode ser uma string ou a tabela de informações de tipo retornada por session:input_info(...) / output_info(...); um optional vazio é representado por onnxruntime.optional(nil, type_info).
  • onnxruntime.map(key_type, value_type, pairs) Atualmente, key_type aceita apenas "string" ou "int64".
  • onnxruntime.sparse_tensor(type, dense_shape, indices, values) Atualmente, aceita apenas tensores esparsos numéricos / bool, construídos no formato COO; indices pode ser um array plano ou um array de coordenadas.
  • onnxruntime.sparse_tensor_from_dense(tensor) Atualmente, não aceita tensor string.

Métodos de objeto comuns:

  • 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 e inferência​

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

O objeto session é responsável por carregar o modelo, consultar informações de entrada e saída, executar inferência e usar IOBinding. Consulte o módulo de sessions.

Tipos de dados compatíveis​

Atualmente, a interface de tensores aceita os seguintes nomes de tipos de elementos:

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

Descrição:

  • tensor_from_bytes() e copy_from_bytes() aceitam apenas tipos numéricos e bool.
  • bytes() não aceita tensor string.
  • tensor:to("string") atualmente aceita apenas string -> string.

Sobre os Providers​

onnxruntime.providers() retorna a lista de providers visíveis no runtime, mas as strings de provider processadas e aceitas nativamente nas opções de session são:

  • "cpu"
  • "coreml"

Descrição:

  • provider / providers também aceitam aliases como CPUExecutionProvider e CoreMLExecutionProvider, normalizados internamente para "cpu" e "coreml".
  • Se nenhum provider for especificado explicitamente ou a lista de providers estiver vazia, a criação da session adicionará automaticamente o provider CPU.
  • Se a lista contiver "coreml" e fallback_to_cpu = true, a implementação também poderá adicionar CPU como fallback.
  • Se você passar providers = {"coreml", "cpu"}, a ordem indica que CoreML será tentado antes de CPU.

Integração com CoreML​

Se você quiser reutilizar o tokenizador coreml ou o fluxo de pré-processamento MLMultiArray, recomenda-se esta combinação:

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 converta diretamente um MLMultiArray existente em um tensor ORT:

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