Перейти к основному содержимому

Модуль тензоров ONNX Runtime

Модуль доступен в версиях после 20260402.

На этой странице описаны наиболее часто используемые функции и методы объектов tensor модуля onnxruntime.

Создание и преобразование​

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

тензор, сообщение_об_ошибке = onnxruntime.tensor("float32", {1, 3}, {1, 2, 3})

Создаёт обычный ORT tensor.

  • type — название типа элемента.
  • shape — массив размеров.
  • data можно опустить; в этом случае создаётся пустой тензор.
  • Для числового tensor можно передать скаляр, чтобы заполнить весь тензор одним значением.
  • Для string tensor можно передать одну строку, чтобы заполнить весь тензор одинаковой строкой.

onnxruntime.tensor_from_bytes(type, shape, bytes)​

тензор, сообщение_об_ошибке = onnxruntime.tensor_from_bytes("float32", {1, 3}, исходные_байты)

Создаёт tensor из последовательных необработанных байтов.

  • Поддерживаются только числовые типы и bool.
  • Длина массива байтов должна точно соответствовать shape и type.

onnxruntime.tensor_from_cv_mat(mat[, opts])​

тензор, сообщение_об_ошибке = onnxruntime.tensor_from_cv_mat(mat, {
    layout = "hwc",
    channel_order = "rgb",
    type = "uint8",
})

Преобразует cv.mat в tensor.

Описание:

  • Сначала необходимо выполнить require("image.cv").
  • opts.type задаёт тип элементов целевого tensor.

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

тензор, сообщение_об_ошибке = 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",
})

Выполняет перспективную обрезку четырёхугольной области из cv.mat и напрямую возвращает ORT tensor.

  • Сначала необходимо выполнить require("image.cv").
  • quad можно передать как четыре точки или как таблицу с полем points.
  • Обычные opts почти совпадают с tensor_from_image(); дополнительные часто используемые поля — content_width, content_height, border_type.
  • Подходит для выравнивания одной рамки и преобразования её в tensor перед OCR.

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

пакетный_тензор, сообщение_об_ошибке = 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",
})

Пакетно обрезает несколько четырёхугольников и автоматически объединяет их в batch tensor.

  • Сначала необходимо выполнить require("image.cv").
  • quads должен быть непустым массивом; каждый элемент может содержать points.
  • content_width и content_height элемента переопределяют одноимённые поля глобального opts.
  • Возвращаемые значения автоматически объединяются в batch через stack() или concat() в зависимости от rank; это удобно для пакетной обработки нескольких рамок OCR.

onnxruntime.tensor_from_image(image[, opts])​

тензор, сведения_о_предобработке = onnxruntime.tensor_from_image(объект_изображения, {
    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",
})

Напрямую преобразует объект изображения во входной tensor для ONNX Runtime.

Часто используемые поля конфигурации:

  • 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: поддерживается "top_left"; в остальных случаях поля добавляются по центру.
  • pad_color
  • interpolation："bilinear"、"nearest"
  • alpha_mode："ignore"、"white"、"black"、"premultiply"
  • crop = {x, y, width, height}
  • add_batch

При успехе вторым возвращаемым значением является таблица сведений о предварительной обработке, содержащая:

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

пакетный_тензор, пакетные_метаданные = onnxruntime.tensor_from_images({img1, img2}, {
    width = 640,
    height = 640,
    layout = "nchw",
})

Пакетно преобразует группу изображений в tensor.

  • Размеры исходных изображений могут различаться.
  • Изображения можно объединить в batch, если shape результата каждой после разбора совпадает с data_type.
  • Второе возвращаемое значение — массив метаданных в порядке входных изображений.

onnxruntime.image_from_tensor(tensor[, opts])​

объект_изображения, сообщение_об_ошибке = onnxruntime.image_from_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",
})

Преобразует 2D / 3D / 4D tensor обратно в объект изображения; удобно для отладки входов и выходов модели.

Часто используемые поля конфигурации:

  • layout
  • channel_order
  • batch_index: 1-based, по умолчанию batch с индексом 1.
  • scale
  • mean
  • std
  • clamp
  • value_range: "0_255" или "0_1"

Описание:

  • Поддерживаются только 2D / 3D / 4D tensor.
  • Поддерживается только 1 или 3 канала.

Методы объекта tensor​

Основные сведения​

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

Описание:

  • to_table() разворачивает содержимое в Lua-таблицу.
  • bytes() поддерживает только числовые и bool tensor.

Чтение, запись и копирование​

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

Описание:

  • При передаче скаляра в fill() заполняется весь тензор; при передаче таблицы число элементов должно точно совпадать.
  • copy_from_bytes() поддерживает только числовые и bool tensor; длина байтов должна точно совпадать.
  • Индексы get() / set() имеют семантику 1-based.
  • tensor:to("string") сейчас поддерживает только string -> string.

Формы и индексы​

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

Описание:

  • start и stop функции slice() являются 1-based и включают конечную позицию.
  • step функции slice() должен быть положительным целым числом.
  • select() удаляет выбранное измерение.
  • indices функции gather() может быть Lua-массивом или tensor формы [N]; индексы также имеют семантику 1-based.
  • Все эти методы возвращают новые объекты tensor.

Числовые операции​

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

Описание:

  • other может быть скаляром или tensor с такой же формой.
  • matmul() сейчас поддерживает комбинации tensor rank-1 / rank-2.
  • Возвращаемые значения sigmoid() / exp() / matmul() повышаются до типа результата с плавающей точкой.
  • Ни одна из этих операций не поддерживает string tensor.

Редукция, сортировка и вероятности​

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

Описание:

  • argmax() без оси возвращает один индекс 1-based.
  • argmax(axis) возвращает int64 tensor с индексами 1-based.
  • sort() возвращает { values = tensor, indices = tensor }.
  • topk() возвращает { values = tensor, indices = tensor }.
  • Индексы, возвращаемые sort() / topk(), имеют базу 1.

Мост OpenCV​

  • tensor:to_cv_mat([opts])
mat, сообщение_об_ошибке = tensor:to_cv_mat({
    layout = "hwc",
    channel_order = "rgb",
    coreml_data_type = "uint8",
})

Описание:

  • Сначала необходимо выполнить require("image.cv").
  • Некоторые типы tensor нельзя напрямую сопоставить с cv.mat; в этом случае явно передайте coreml_data_type.

Вспомогательные функции тензоров уровня модуля​

Основные числовые функции​

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

Описание:

  • clamp(), sigmoid(), exp() и matmul() используют ту же реализацию, что и соответствующие методы tensor:.
  • where() поддерживает совместное использование скаляров, логических значений и tensor и вычисляет результат по правилам broadcasting.

Дополнительные функции постобработки​

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

Описание:

  • mask_iou() напрямую вычисляет IoU двух mask.
  • mask_iou() также принимает третий параметр opts: можно передать compare_size = true либо явно задать width / height как размеры выровненного сравнения.
  • db_postprocess() подходит для постобработки обнаружения текста DB / DBNet; вход поддерживает [H, W], [C, H, W] или [N, C, H, W].
  • db_postprocess() возвращает массив обнаружений, каждый элемент содержит score, points и box; meta / image_meta можно напрямую повторно использовать как метаданные, возвращённые при преобразовании изображения в tensor.

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

NMS обычных прямоугольных рамок.

Часто используемые параметры:

  • iou_threshold
  • score_threshold
  • top_k
  • class_aware
  • class_ids

Возвращается int64 tensor с индексами 1-based.

onnxruntime.box_points(rotated_boxes)​

Преобразует повёрнутую рамку [cx, cy, w, h, theta] в координаты четырёх вершин.

  • Входом может быть tensor формы [5], [1, 5] или [N, 5].
  • Для одной рамки возвращается Lua-таблица точек, для нескольких — массив таких таблиц.

onnxruntime.xywh_to_xyxy(boxes)​

Преобразует прямоугольную рамку из [cx, cy, w, h] в [x1, y1, x2, y2].

onnxruntime.xyxy_to_xywh(boxes)​

Преобразует прямоугольную рамку из [x1, y1, x2, y2] в [cx, cy, w, h].

onnxruntime.rotated_iou(box1, box2)​

Вычисляет IoU двух повёрнутых рамок.

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

NMS повёрнутых рамок. Возвращается int64 tensor с индексами 1-based.

  • boxes должен быть tensor повёрнутых рамок формы [N, 5].
  • scores может быть Lua-массивом или tensor формы [N] / [N, 1].

onnxruntime.create_decoder(schema)​

Создаёт повторно используемый объект decoder.

  • Объект decoder поддерживает :decode(output[, opts]), :task() и :schema().
  • Удобно сначала зафиксировать schema выходов обнаружения / OBB / классификации, а затем использовать её многократно.

onnxruntime.decode_yolo(output[, opts])​

Декодирует по встроенной логике обнаружения YOLO и возвращает список detection record.

onnxruntime.decode_yolo_obb(output[, opts])​

Декодирует по встроенной логике YOLO OBB и возвращает список detection record повёрнутых рамок.

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

Разбирает матричный выход по schema в таблицу тензоров-кандидатов; обычно возвращаются поля:

  • boxes
  • scores
  • class_ids
  • keep_indices
  • selected_rows
  • angles (только для соответствующих schema, например OBB)

onnxruntime.decode_dense_detection(output, opts)​

Декодирует выход dense detection head в:

  • boxes
  • scores
  • labels

boxes / scores / labels являются tensor.

  • Вход поддерживает [R, C] или [N, R, C].
  • opts.strides обязателен и должен быть непустым массивом положительных целых чисел.
  • decode_width и decode_height также обязательны.
  • Сейчас поддерживается только box_encoding = "grid_center_log_wh".
  • Другие часто используемые поля: box_offset, score_offset, class_offset, num_classes, score_threshold.
  • При передаче batched-выхода возвращается Lua-массив, организованный по batch.

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

Преобразует tensor рамок [N, 4], оценок и классов в список Lua record; каждый элемент обычно содержит:

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

Преобразует данные строк OBB в список Lua record.

  • opts поддерживает x_index, y_index, width_index, height_index.

onnxruntime.points_to_records(points[, opts])​

Преобразует tensor точек / ключевых точек формы [N, P, D] или [N, P*D] в Lua table.

  • opts поддерживает point_count / keypoint_count.
  • opts поддерживает point_dim / keypoint_dim.

Вспомогательные функции масок​

onnxruntime.threshold_masks(masks, threshold)​

Преобразует непрерывный mask tensor по порогу в список Lua mask table. Каждая mask содержит:

  • width
  • height
  • bits
  • pixel_count
  • bounds

onnxruntime.crop_masks_by_boxes(masks, boxes)​

Обрезает список масок после пороговой обработки по рамкам [N, 4].

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

Масштабирует список масок до указанного размера.

  • Сейчас поддерживается только opts.interpolation = "nearest".

onnxruntime.mask_to_polygon(mask[, opts])​

Преобразует одну бинарную mask в список точек многоугольника.

  • Для приближённого упрощения можно использовать opts.epsilon / opts.approx_epsilon.

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

Проецирует прототип mask, коэффициенты mask и рамки обнаружений обратно в размер целевого изображения.

  • project_masks() является её псевдонимом.
  • Возвращается список Lua mask table, а не tensor.

Вспомогательные функции ключевых точек и геометрии​

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

Описание:

  • reshape_keypoints() преобразует данные между формами [N, K*D] и [N, K, D].
  • scale_points() по умолчанию разбирает обычную раскладку точек; scale_keypoints() — раскладку ключевых точек.
  • Связанная с transform table соответствует полям метаданных предварительной обработки изображения; часто используются scale_x, scale_y, pad_left, pad_top.

onnxruntime.tracker([opts])​

Создаёт повторно используемый объект tracker с поддержкой:

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

Часто используемые поля конфигурации:

  • iou_threshold
  • max_age
  • min_hits

onnxruntime.ctc_greedy_decode(logits[, opts])​

Возвращает структуру вида:

  • indices

  • text

  • confidence

  • Вход поддерживает [T, C] или [N, T, C].

  • Поддерживаются blank_index, merge_repeated, apply_softmax, return_probabilities, charset.

  • indices возвращается всегда.

  • text возвращается только при передаче charset.

  • confidence возвращается только при включении apply_softmax или return_probabilities.

  • probabilities и probability_confidence добавляются только при включении return_probabilities.

  • Для batch-входа возвращается массив результатов batch.

onnxruntime.sample_logits(logits[, opts])​

Поддерживаются следующие параметры выборки:

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

Для 1D logits возвращается один индекс; для нескольких строк logits — int64 tensor с индексами 1-based.

Пример​

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