Chuyển tới nội dung chính

Mô-đun ONNX Runtime

Mô-đun này có sẵn trong các phiên bản phát hành sau 20260402
Chỉ hỗ trợ trên iOS 13 và các phiên bản sau

Module onnxruntime tải và chạy các mô hình ONNX trực tiếp trên thiết bị, phù hợp cho các luồng xử lý văn bản, embedding, phân loại, phát hiện, và các luồng tensor tổng quát.

Tải mô-đun​

local ort = require("onnxruntime")

Khác với coreml, đây không phải là mô-đun toàn cục được tích hợp sẵn; nó được tải theo nhu cầu.

Sau khi require("onnxruntime") thành công, nó cũng sẽ chèn hai cầu nối sao chép bản địa vào các API coreml đã có:

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

Cả hai quá trình chuyển đổi này đều là sao chép ở lớp bản địa và không đi qua các bảng của Lua.

Các hàm cấp mô-đun​

Thông tin runtime và thông tin cơ bản​

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

Ghi chú:

  • providers() trả về các nhà cung cấp thực sự có sẵn trong runtime ORT hiện tại
  • configure() thiết lập các giá trị mặc định toàn cục của runtime và phải được gọi trước khi tạo bất kỳ session nào

Các tensor, hình ảnh và các công cụ hỗ trợ số​

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

Ghi chú:

  • clamp(), sigmoid(), exp(), và matmul() tương đương với các phương thức tensor: cùng tên, với tensor được truyền làm tham số đầu tiên
  • where() hỗ trợ trộn các scalar, boolean, và tensor, và áp dụng các quy tắc phát sóng
  • Các chi tiết về tiền xử lý hình ảnh, cầu nối OpenCV, và image_from_tensor() được mô tả trong Module Tensor

Các công cụ hỗ trợ phát hiện, giải mã và xử lý sau​

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

Ghi chú:

  • tensor_from_quad() / tensor_from_quads() yêu cầu require("image.cv") trước tiên và hữu ích khi các luồng OCR cần cắt trực tiếp các vùng tứ giác vào tensor
  • box_points() nhận một tensor hình chữ nhật xoay có hình dạng [5], [1, 5], hoặc [N, 5]; nó không nhận năm tham số scalar riêng biệt
  • create_decoder() trả về một đối tượng giải mã với :decode(), :task(), và :schema()
  • tracker() trả về một đối tượng theo dõi với :update(), :reset(), :state(), và :close()
  • records_from_boxes(), obb_records_from_rows(), và points_to_records() chuyển đổi các đầu ra tensor thành các bảng ghi dễ sử dụng của Lua
  • proto_masks() và project_masks() hiện tại chia sẻ cùng một phần triển khai; project_masks() là một đồng nghĩa
  • mask_iou() tính toán giao-over-union giữa hai mask trực tiếp, và cũng chấp nhận một tham số opts thứ ba với compare_size = true, hoặc width / height cụ thể
  • db_postprocess() được thiết kế cho việc xử lý sau phát hiện văn bản kiểu DB / DBNet; mỗi phát hiện trả về bao gồm score, points, và box
  • decode_dense_detection() yêu cầu opts.strides, và nó phải là một mảng không rỗng các số nguyên dương; nó cũng yêu cầu decode_width và decode_height, và hiện tại chỉ hỗ trợ box_encoding = "grid_center_log_wh"
  • ctc_greedy_decode() hỗ trợ blank_index, merge_repeated, apply_softmax, return_probabilities, và charset
  • ctc_greedy_decode() luôn trả về indices; text chỉ xuất hiện khi charset được cung cấp; confidence chỉ xuất hiện khi apply_softmax hoặc return_probabilities được kích hoạt; probabilities và probability_confidence chỉ xuất hiện khi return_probabilities được kích hoạt
  • nms() và rotated_nms() trả về các tensor int64 với chỉ số bắt đầu từ 1
  • sample_logits() hỗ trợ argmax, temperature, top_k, top_p, min_p, và seed
  • sample_logits() trả về một chỉ số scalar cho logits 1D, và một tensor int64 cho logits được nhóm

Các giá trị cấu trúc​

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

Những công cụ này hữu ích khi đầu vào hoặc đầu ra của mô hình không phải là các tensor đơn giản — ví dụ như các tùy chọn, chuỗi, bảng, hoặc tensor rải rác.

Hành vi hiện tại có thể được tóm tắt như sau:

  • onnxruntime.value(x) Nếu x đã là một tensor ORT / giá trị / chuỗi / bảng / tensor rải rác, nó sẽ được trả về nguyên vẹn; nếu x là một bảng của Lua, nó sẽ trở thành một sequence; ngược lại, scalar sẽ được bọc trong một tensor
  • onnxruntime.optional(value, type_info) Tham số thứ hai là bắt buộc; type_info có thể là một chuỗi hoặc một bảng thông tin loại như kết quả của session:input_info(...) / output_info(...); một tùy chọn trống được viết là onnxruntime.optional(nil, type_info)
  • onnxruntime.map(key_type, value_type, pairs) Hiện tại, key_type chỉ hỗ trợ "string" hoặc "int64"
  • onnxruntime.sparse_tensor(type, dense_shape, indices, values) Hiện tại chỉ hỗ trợ các tensor rải rác số hoặc bool, được xây dựng dưới dạng COO; indices có thể là phẳng hoặc lồng ghép
  • onnxruntime.sparse_tensor_from_dense(tensor) Hiện tại không hỗ trợ các tensor string

Các phương thức đối tượng phổ biến:

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

Session và suy diễn​

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

Các đối tượng session xử lý việc tải mô hình, kiểm tra đầu vào/đầu ra, thực thi suy diễn, và IOBinding. Xem Mô-đun Session.

Các loại dữ liệu được hỗ trợ​

Các API tensor hiện tại hỗ trợ các tên loại sau:

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

Ghi chú:

  • tensor_from_bytes() và copy_from_bytes() chỉ hỗ trợ các tensor số và bool
  • bytes() không có sẵn cho các tensor string
  • tensor:to("string") hiện tại chỉ hỗ trợ string -> string

Ghi chú về nhà cung cấp​

onnxruntime.providers() trả về những gì runtime báo cáo là có sẵn, nhưng các chuỗi nhà cung cấp hiện tại được nhận diện bởi trình phân tích tùy chọn session là:

  • "cpu"
  • "coreml"

Ghi chú:

  • provider / providers cũng chấp nhận các đồng nghĩa như CPUExecutionProvider và CoreMLExecutionProvider; chúng được chuẩn hóa nội bộ thành "cpu" và "coreml"
  • Nếu không chỉ định nhà cung cấp nào, hoặc danh sách nhà cung cấp là trống, việc tạo session sẽ tự động thêm nhà cung cấp CPU
  • Nếu danh sách nhà cung cấp chứa "coreml" và fallback_to_cpu = true, phần triển khai cũng có thể thêm CPU như một đường dẫn dự phòng
  • Nếu bạn truyền providers = {"coreml", "cpu"}, session sẽ thử CoreML trước và CPU sau

Làm việc với CoreML​

Nếu bạn muốn tái sử dụng tokenizer coreml hoặc một luồng tiền xử lý MLMultiArray, một mô hình phổ biến là:

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

Hoặc chuyển đổi trực tiếp một MLMultiArray hiện có thành một tensor ORT:

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