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

Модуль ONNX Runtime (onnxruntime)

Модуль доступен в версиях после 20260402.
Поддерживаются только системы iOS 13 и новее.

Модуль onnxruntime напрямую загружает и запускает ONNX-модели на устройстве; он подходит для текста, эмбеддингов, классификации, обнаружения и других задач инференса с тензорами.

Загрузка модуля​

local ort = require("onnxruntime")

Это модуль, загружаемый по требованию, а не встроенный глобальный модуль, как coreml.

После успешного выполнения require("onnxruntime") во встроенный модуль coreml также добавляются два мостовых интерфейса:

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

Обе конвертации выполняют прямое копирование на уровне native, не проходя через Lua table.

Функции уровня модуля​

Среда выполнения и основные сведения​

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

Описание:

  • providers() возвращает список Execution Provider, фактически доступных в текущей среде выполнения ORT.
  • configure() задаёт глобальные значения по умолчанию; его необходимо вызвать до создания любой session.

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

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

Описание:

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

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

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

Описание:

  • Для tensor_from_quad() / tensor_from_quads() сначала требуется require("image.cv"); функции удобны для непосредственного создания тензоров после обрезки четырёхугольника для OCR.
  • box_points() принимает tensor повёрнутой рамки формы [5], [1, 5] или [N, 5], а не пять отдельных скалярных параметров.
  • create_decoder() возвращает объект decoder с поддержкой :decode(), :task() и :schema().
  • tracker() возвращает объект tracker с поддержкой :update(), :reset(), :state() и :close().
  • records_from_boxes(), obb_records_from_rows() и points_to_records() преобразуют результаты tensor в record table, более удобную для использования на стороне Lua.
  • proto_masks() и project_masks() сейчас используют одну реализацию; последний является лишь псевдонимом.
  • mask_iou() напрямую вычисляет IoU двух mask. Функция также принимает третий аргумент opts, которому можно передать compare_size = true либо явно задать width / height.
  • db_postprocess() подходит для постобработки обнаружения текста DB / DBNet; каждый возвращаемый элемент содержит score, points и box.
  • decode_dense_detection() требует непустой массив положительных целых чисел opts.strides, а также decode_width и decode_height; сейчас поддерживается только box_encoding = "grid_center_log_wh".
  • ctc_greedy_decode() поддерживает blank_index, merge_repeated, apply_softmax, return_probabilities и charset.
  • ctc_greedy_decode() всегда возвращает indices; text возвращается только при передаче charset; confidence — только при включении apply_softmax или return_probabilities; probabilities и probability_confidence — только при включении return_probabilities.
  • nms() / rotated_nms() возвращают int64 tensor с индексами 1-based.
  • sample_logits() поддерживает argmax, temperature, top_k, top_p, min_p и seed.
  • Для 1D logits sample_logits() возвращает один индекс, а для batched logits — int64 tensor.

Структурированные значения​

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

Подходит для обработки входов и выходов, являющихся не только tensor, например optional, sequence, map и sparse tensor.

Текущее поведение можно обобщить так:

  • onnxruntime.value(x) Если x уже является ORT tensor / value / sequence / map / sparse tensor, он возвращается без изменений; Lua table обрабатывается как sequence, а скаляр оборачивается в tensor.
  • onnxruntime.optional(value, type_info) Второй параметр обязателен; type_info может быть строкой или таблицей сведений о типе, возвращённой session:input_info(...) / output_info(...); пустой optional обозначается как onnxruntime.optional(nil, type_info).
  • onnxruntime.map(key_type, value_type, pairs) Сейчас key_type поддерживает только "string" и "int64".
  • onnxruntime.sparse_tensor(type, dense_shape, indices, values) Сейчас поддерживаются только числовые / bool разреженные тензоры, создаваемые в формате COO; indices может быть плоским массивом или массивом координат.
  • onnxruntime.sparse_tensor_from_dense(tensor) Сейчас string tensor не поддерживается.

Распространённые методы объектов:

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

Сеансы и инференс​

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

Объект session отвечает за загрузку модели, получение сведений о входах и выходах, выполнение инференса и IOBinding. См. модуль сеансов.

Поддерживаемые типы данных​

Интерфейс тензоров поддерживает следующие названия типов элементов:

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

Описание:

  • tensor_from_bytes() и copy_from_bytes() поддерживают только числовые типы и bool.
  • bytes() не поддерживает string tensor.
  • tensor:to("string") сейчас поддерживает только string -> string.

Сведения о Provider​

onnxruntime.providers() возвращает список provider, видимых среде выполнения, но параметры session сейчас нативно обрабатывают и поддерживают следующие строки provider:

  • "cpu"
  • "coreml"

Описание:

  • provider / providers также принимают псевдонимы CPUExecutionProvider и CoreMLExecutionProvider; внутри они нормализуются к "cpu" и "coreml".
  • Если provider явно не задан или список provider пуст, на этапе создания session автоматически добавляется CPU provider.
  • Если список provider содержит "coreml" и fallback_to_cpu = true, реализация также может добавить CPU как путь отката.
  • Передача providers = {"coreml", "cpu"} означает сначала попробовать CoreML, затем CPU.

Интеграция с CoreML​

Для повторного использования токенизатора coreml или процесса предварительной обработки MLMultiArray рекомендуется такая комбинация:

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

Либо существующий MLMultiArray можно напрямую преобразовать в ORT tensor:

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