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

Mô-đun tensor ONNX Runtime

Mô-đun này có sẵn trong các phiên bản phát hành sau 20260402

Trang này tài liệu hóa các hàm và phương thức đối tượng liên quan đến tensor được sử dụng phổ biến nhất trong module onnxruntime.

Tạo và chuyển đổi​

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

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

Tạo một tensor ORT thông thường.

  • type là tên loại phần tử
  • shape là hình dạng của tensor
  • data là tùy chọn; khi bỏ qua, tạo một tensor rỗng
  • Tensor số chấp nhận một scalar, điền toàn bộ tensor với giá trị giống nhau
  • Tensor string chấp nhận một chuỗi duy nhất, điền toàn bộ tensor với chuỗi đó

onnxruntime.tensor_from_bytes(type, shape, bytes)​

tensor, err = onnxruntime.tensor_from_bytes("float32", {1, 3}, raw_bytes)

Tạo một tensor từ các byte nguyên bản liên tục.

  • Chỉ hỗ trợ các loại số và bool
  • Độ dài byte phải chính xác khớp với shape và type được cung cấp

onnxruntime.tensor_from_cv_mat(mat[, opts])​

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

Chuyển đổi một cv.mat thành một tensor.

Ghi chú:

  • require("image.cv") trước tiên
  • opts.type kiểm soát loại phần tử mục tiêu của tensor

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

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

Thực hiện cắt góc nhìn từ một cv.mat bằng một vùng tứ giác và chuyển đổi kết quả trực tiếp thành một tensor ORT.

  • Yêu cầu require("image.cv")
  • quad có thể được truyền trực tiếp dưới dạng bốn điểm, hoặc dưới dạng một bảng có trường points
  • Các tùy chọn phổ biến opts chủ yếu khớp với tensor_from_image(), với các trường thường dùng như content_width, content_height, và border_type
  • Có ích cho việc điều chỉnh OCR và tensor hóa một hộp văn bản đơn

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

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

Thực hiện cắt góc nhìn cho nhiều tứ giác và tự động đóng gói kết quả vào một tensor batch.

  • Yêu cầu require("image.cv")
  • quads phải là một mảng không rỗng; mỗi mục có thể bao gồm points
  • content_width và content_height của từng mục thay thế các trường tương ứng trong opts
  • Giá trị trả về được đóng gói bằng stack() hoặc concat() tùy thuộc vào cấp độ của tensor, tiện lợi cho tiền xử lý batch OCR

onnxruntime.tensor_from_image(image[, opts])​

tensor, meta = onnxruntime.tensor_from_image(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",
})

Chuyển đổi một đối tượng hình ảnh trực tiếp thành một tensor đầu vào ONNX Runtime.

Các tùy chọn phổ biến:

  • width / height
  • layout: "nchw", "nhwc", "chw", hoặc "hwc"
  • channel_order: "rgb", "bgr", "gray", "grey", hoặc "grayscale"
  • data_type
  • scale
  • mean
  • std
  • resize_mode: "stretch", "letterbox", hoặc "center_crop"
  • letterbox_mode: hỗ trợ "top_left"; nếu không, letterboxing sẽ được căn giữa
  • pad_color
  • interpolation: "bilinear" hoặc "nearest"
  • alpha_mode: "ignore", "white", "black", hoặc "premultiply"
  • crop = {x, y, width, height}
  • add_batch

Trên thành công, giá trị trả về thứ hai là một bảng dữ liệu tiền xử lý. Các trường phổ biến bao gồ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])​

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

Chuyển đổi một batch hình ảnh thành một tensor.

  • Kích thước hình ảnh nguồn có thể khác nhau
  • Batch có thể được tạo thành miễn là mỗi hình ảnh giải quyết đến cùng một hình dạng và data_type đầu ra
  • Giá trị trả về thứ hai là một mảng dữ liệu được đồng bộ với thứ tự đầu vào

onnxruntime.image_from_tensor(tensor[, opts])​

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

Chuyển đổi một tensor 2D / 3D / 4D trở lại một đối tượng hình ảnh. Có ích cho việc kiểm tra đầu vào và đầu ra của mô hình.

Các tùy chọn phổ biến:

  • layout
  • channel_order
  • batch_index: dựa trên 1, mặc định 1
  • scale
  • mean
  • std
  • clamp
  • value_range: "0_255" hoặc "0_1"

Ghi chú:

  • Chỉ hỗ trợ tensor 2D / 3D / 4D
  • Số lượng kênh phải là 1 hoặc 3

Phương thức đối tượng tensor​

Thông tin cơ bản​

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

Ghi chú:

  • to_table() mở rộng nội dung tensor thành một bảng Lua
  • bytes() chỉ hỗ trợ tensor số và bool

Đọc, viết và sao chép​

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

Ghi chú:

  • fill() chấp nhận một giá trị điền scalar hoặc một bảng Lua mà số lượng phần tử phải khớp chính xác
  • copy_from_bytes() chỉ hỗ trợ tensor số và bool, và độ dài byte phải khớp chính xác
  • get() / set() sử dụng dựa trên 1 trong ngữ cảnh chỉ số
  • tensor:to("string") hiện tại chỉ hỗ trợ string -> string

Hình dạng và chỉ số​

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

Ghi chú:

  • slice() sử dụng dựa trên 1 cho start và stop, và stop là bao gồm
  • slice() yêu cầu step là dương
  • select() loại bỏ chiều được chọn
  • gather() chấp nhận một bảng Lua hoặc một tensor hình dạng-[N] làm indices, vẫn sử dụng dựa trên 1 trong ngữ cảnh chỉ số
  • Các phương thức này trả về các đối tượng tensor mới

Các phép toán số học​

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

Ghi chú:

  • other có thể là một scalar hoặc một tensor có hình dạng khớp
  • matmul() hiện tại hỗ trợ các tổ hợp tensor cấp 1 / cấp 2
  • sigmoid(), exp(), và matmul() nâng cao kết quả thành một loại kết quả số thực
  • Các phép toán này không hỗ trợ tensor string

Các phép giảm, sắp xếp và xác suất​

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

Ghi chú:

  • argmax() không có chiều sẽ trả về một chỉ số dựa trên 1 duy nhất
  • argmax(axis) trả về một tensor int64, cũng có dựa trên 1 trong chỉ số
  • sort() trả về { values = tensor, indices = tensor }
  • topk() trả về { values = tensor, indices = tensor }
  • sort() và topk() đều trả về chỉ số dựa trên 1

Cổng kết nối OpenCV​

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

Ghi chú:

  • require("image.cv") trước tiên
  • Một số loại tensor không thể được ánh xạ trực tiếp sang cv.mat; trong những trường hợp đó, truyền coreml_data_type rõ ràng

Các hàm trợ giúp tensor cấp mô-đun​

Các hàm trợ giúp số học cơ bản​

  • 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() dùng chung một phần triển khai như các phương thức tương ứng tensor:
  • where() hỗ trợ sự kết hợp scalar / boolean / tensor và tuân theo quy tắc phát sóng

Các hàm trợ giúp xử lý hậu kỳ bổ sung​

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

Ghi chú:

  • mask_iou() tính toán giao / hợp giữa hai mask trực tiếp
  • mask_iou() cũng chấp nhận một trường opts thứ ba với compare_size = true, hoặc width / height cụ thể cho kích thước so sánh
  • db_postprocess() được thiết kế cho xử lý sau cùng kiểu DB / DBNet phát hiện văn bản; đầu vào có thể là [H, W], [C, H, W], hoặc [N, C, H, W]
  • db_postprocess() trả về một mảng phát hiện, mỗi mục bao gồm score, points, và box; meta / image_meta có thể tái sử dụng dữ liệu tiền xử lý trả về bởi tensor hóa hình ảnh

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

NMS hộp chữ nhật song song.

Các tùy chọn phổ biến:

  • iou_threshold
  • score_threshold
  • top_k
  • class_aware
  • class_ids

Trả về một tensor int64 với dựa trên 1 trong chỉ số.

onnxruntime.box_points(rotated_boxes)​

Chuyển đổi các hộp chữ nhật xoay [cx, cy, w, h, theta] thành bốn điểm góc.

  • Đầu vào có thể là một tensor hình dạng [5], [1, 5], hoặc [N, 5]
  • Một hộp chữ nhật đơn trả về một danh sách điểm Lua; nhiều hộp chữ nhật trả về một mảng các danh sách điểm

onnxruntime.xywh_to_xyxy(boxes)​

Chuyển đổi các hộp từ [cx, cy, w, h] thành [x1, y1, x2, y2].

onnxruntime.xyxy_to_xywh(boxes)​

Chuyển đổi các hộp từ [x1, y1, x2, y2] thành [cx, cy, w, h].

onnxruntime.rotated_iou(box1, box2)​

Tính IoU giữa hai hộp chữ nhật xoay.

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

NMS hộp chữ nhật xoay. Giá trị trả về cũng là một tensor int64 với dựa trên 1 trong chỉ số.

  • boxes phải có hình dạng [N, 5]
  • scores có thể là một bảng số Lua hoặc một tensor hình dạng [N] / [N, 1]

onnxruntime.create_decoder(schema)​

Tạo một đối tượng giải mã có thể sử dụng lại.

  • Các đối tượng giải mã hỗ trợ :decode(output[, opts]), :task(), và :schema()
  • Điều này hữu ích khi một schema phát hiện / OBB / phân loại nên được định nghĩa một lần và sử dụng lại

onnxruntime.decode_yolo(output[, opts])​

Giải mã đầu ra với đường dẫn phát hiện YOLO nội bộ và trả về các bản ghi phát hiện.

onnxruntime.decode_yolo_obb(output[, opts])​

Giải mã đầu ra với đường dẫn phát hiện OBB YOLO nội bộ và trả về các bản ghi phát hiện xoay.

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

Chia một đầu ra ma trận thành các tensor ứng viên theo một schema. Bảng trả về thường bao gồm:

  • boxes
  • scores
  • class_ids
  • keep_indices
  • selected_rows
  • angles (cho các schema liên quan đến OBB)

onnxruntime.decode_dense_detection(output, opts)​

Giải mã đầu ra đầu phát hiện dày thành:

  • boxes
  • scores
  • labels

Ba trường này đều là tensor.

  • Đầu vào có thể có hình dạng [R, C] hoặc [N, R, C]
  • opts.strides là bắt buộc, và phải là một mảng không rỗng các số nguyên dương
  • decode_width và decode_height cũng là bắt buộc
  • Hiện tại chỉ hỗ trợ box_encoding = "grid_center_log_wh"
  • Các trường phổ biến khác bao gồm box_offset, score_offset, class_offset, num_classes, và score_threshold
  • Đầu ra batched trả về một mảng các kết quả per-batch

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

Chuyển đổi [N, 4] boxes, scores, và class IDs thành các bảng ghi Lua. Mỗi bản ghi thường bao gồ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]]])​

Chuyển đổi các tensor hàng OBB thành các bảng ghi Lua.

  • opts hỗ trợ x_index, y_index, width_index, và height_index

onnxruntime.points_to_records(points[, opts])​

Chuyển đổi các tensor điểm / điểm quan trọng [N, P, D] hoặc [N, P*D] thành các bảng Lua.

  • opts hỗ trợ point_count / keypoint_count
  • opts hỗ trợ point_dim / keypoint_dim

Hàm trợ giúp mask​

onnxruntime.threshold_masks(masks, threshold)​

Ngưỡng hóa các tensor mask dày thành các bảng mask Lua. Mỗi mask bao gồm:

  • width
  • height
  • bits
  • pixel_count
  • bounds

onnxruntime.crop_masks_by_boxes(masks, boxes)​

Cắt các bảng mask đã ngưỡng bằng [N, 4] boxes.

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

Thay đổi kích thước các bảng mask đến kích thước mục tiêu.

  • Chỉ hỗ trợ opts.interpolation = "nearest" hiện tại

onnxruntime.mask_to_polygon(mask[, opts])​

Chuyển đổi một mask nhị phân thành một danh sách điểm đa giác.

  • opts.epsilon / opts.approx_epsilon có thể được sử dụng để đơn giản hóa đa giác

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

Dựng lại các mask prototype, hệ số mask, và các hộp phát hiện về kích thước hình ảnh mục tiêu.

  • project_masks() là một biệt danh
  • Giá trị trả về là một danh sách bảng mask Lua, không phải tensor

Hàm trợ giúp điểm mốc và hình học​

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

Ghi chú:

  • reshape_keypoints() chuyển đổi giữa [N, K*D] và [N, K, D]
  • scale_points() giả định một bố cục điểm tổng quát mặc định; scale_keypoints() giả định một bố cục điểm quan trọng mặc định
  • Các bảng chuyển đổi khớp với các trường dữ liệu tiền xử lý hình ảnh như scale_x, scale_y, pad_left, và pad_top

onnxruntime.tracker([opts])​

Tạo một đối tượng theo dõi có thể sử dụng lại với:

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

Các trường cấu hình phổ biến:

  • iou_threshold
  • max_age
  • min_hits

onnxruntime.ctc_greedy_decode(logits[, opts])​

Trả về một bảng như:

  • indices

  • text

  • confidence

  • Đầu vào có thể có hình dạng [T, C] hoặc [N, T, C]

  • Hỗ trợ blank_index, merge_repeated, apply_softmax, return_probabilities, và charset

  • 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

  • Đầu vào batched trả về một mảng các kết quả giải mã per-batch

onnxruntime.sample_logits(logits[, opts])​

Hỗ trợ các tùy chọn lấy mẫu sau:

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

Đối với logits 1D, nó trả về một chỉ số scalar. Đối với logits batched, nó trả về một tensor int64. Chỉ số là dựa trên 1.

Ví dụ​

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