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

Mô-đun mảng đa chiều ML

MLMultiArray là loại tensor phổ biến nhất trong CoreML.
Trang này tổng hợp các API coreml liên quan đến MLMultiArray, bao gồm:

  • tạo tensor
  • chuyển đổi dữ liệu Lua / ảnh / OpenCV thành tensor
  • chuyển đổi giữa MLMultiArray và tensor ORT
  • các phép toán, phép rút gọn, sắp xếp và nối thường dùng
  • các tiện ích hậu xử lý cho phát hiện / OBB / mặt nạ / điểm mốc / trình theo dõi

Nếu muốn tạo trình bao Lua cho bộ phân loại, mô hình embedding, mô hình văn bản, mô hình phát hiện hoặc mô hình CoreML đa dụng khác, đây là trang nền tảng chính.

Mô-đun này khả dụng trong các phiên bản phát hành sau 20260319

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

coreml.new_multi_array(opts) / coreml.tensor(opts)​

array, err = coreml.new_multi_array({
    shape = shape,
    data_type = data_type,
})

Tạo một đối tượng mảng đa chiều CoreML rỗng để sau đó dùng làm đầu vào mô hình hoặc tensor trung gian.

  • shape là hình dạng đích, ví dụ {1, 3, 224, 224}
  • data_type có thể là "int32", "float32", "float16" hoặc "double"; "float64" được chấp nhận làm bí danh của "double"
  • coreml.tensor(opts) là một bí danh tương đương

coreml.multi_array_from_table(data, opts) / coreml.tensor_from_table(data, opts)​

array, err = coreml.multi_array_from_table(data, {
    shape = shape,
    data_type = data_type,
})

Chuyển đổi rõ ràng dữ liệu bảng Lua thành MLMultiArray.

  • shape phải khớp với tổng số phần tử
  • data_type tuân theo cùng quy tắc như new_multi_array()
  • coreml.tensor_from_table(...) là một bí danh tương đương

coreml.tensor_from_image(image[, opts])​

array, meta = coreml.tensor_from_image(image, opts)

Chuyển một đối tượng ảnh thành tensor sẵn sàng cho CoreML bằng các tùy chọn tiền xử lý được chỉ định rõ.

Các tùy chọn thường dùng:

  • width / height
  • layout: chỉ hỗ trợ "nchw" và "nhwc"
  • channel_order: "rgb", "bgr", "gray", "grey" hoặc "grayscale"
  • data_type
  • scale
  • mean
  • std
  • resize_mode: "stretch", "letterbox", "center_crop"
  • letterbox_mode: hỗ trợ "center" và "top_left"; "topleft" được xem là "top_left"
  • pad_color
  • interpolation: "bilinear", "nearest"
  • alpha_mode: "ignore", "white", "black", "premultiply"
  • crop = {x, y, width, height}

Lưu ý:

  • Hàm này chỉ chuyển ảnh thành tensor theo cấu hình được chỉ định rõ; không âm thầm gắn với quy tắc tiền xử lý của một mô hình cụ thể
  • Khi thành công, giá trị trả về thứ hai là bảng siêu dữ liệu tiền xử lý; khi thất bại, trả về nil, err
  • Các trường siêu dữ liệu thường gặp gồm: src_width, src_height, crop_x, crop_y, crop_width, crop_height, dst_width, dst_height, resized_width, resized_height, scale_x, scale_y, ratio, pad_left, pad_top, pad_right, pad_bottom, resize_mode, offset_x, offset_y, and letterbox_mode

coreml.tensor_from_images(images[, opts])​

batch_array, batch_meta = coreml.tensor_from_images({img1, img2}, {
    width = 640,
    height = 640,
    layout = "nchw",
})

Chuyển một lô ảnh thành một MLMultiArray.

  • Kích thước ảnh nguồn có thể khác nhau
  • Có thể tạo lô miễn là mỗi ảnh cho ra cùng hình dạng đầu ra và data_type
  • Giá trị trả về thứ hai là một mảng siêu dữ liệu theo đúng thứ tự đầu vào

coreml.image_from_tensor(tensor[, opts])​

image, err = coreml.image_from_tensor(tensor, opts)

Chuyển MLMultiArray 2D / 3D / 4D trở lại thành đối tượng ảnh. Hữu ích khi gỡ lỗi đầu vào và đầu ra của mô hình.

Các tùy chọn thường dùng:

  • layout
  • channel_order
  • batch_index: bắt đầu từ 1, mặc định là 1
  • scale
  • mean
  • std
  • clamp
  • value_range: "0_255" hoặc "0_1"

Lưu ý:

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

coreml.image_to_multi_array(image[, opts])​

Đây là tên API cũ. Hiện tại nó chỉ là bí danh tương thích của coreml.tensor_from_image(...). Mã mới nên ưu tiên tensor_from_image().

coreml.tensor_from_cv_mat(mat[, opts]) / coreml.multi_array_from_cv_mat(mat[, opts])​

Chuyển cv.mat thành MLMultiArray.

  • Yêu cầu require("image.cv")
  • Cả hai tên đều là bí danh tương đương

coreml.tensor_from_quad(mat, quad[, opts]) / coreml.multi_array_from_quad(mat, quad[, opts])​

array, err = coreml.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",
    data_type = "float32",
})

Thực hiện cắt phối cảnh từ cv.mat bằng một vùng tứ giác và chuyển trực tiếp kết quả thành MLMultiArray.

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

coreml.tensor_from_quads(mat, quads[, opts]) / coreml.multi_array_from_quads(mat, quads[, opts])​

batch_array, err = coreml.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 phối cảnh cho nhiều tứ giác và tự động đóng gói kết quả thành tensor theo lô.

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

coreml.multi_array_from_ort_tensor(tensor[, data_type])​

array, err = coreml.multi_array_from_ort_tensor(ort_tensor[, "float32"])

Sao chép onnxruntime.tensor vào MLMultiArray bằng cầu nối gốc.

  • Hàm này mặc định không tồn tại; chỉ được thêm vào mô-đun coreml tích hợp sau khi gọi require("onnxruntime")
  • Quá trình chuyển đổi là một bản sao gốc và không đi qua bảng Lua
  • Không thể chuyển tensor string thành MLMultiArray

Kiểm tra kiểu và bí danh​

coreml.is_multi_array(value) / coreml.is_tensor(value)​

is_multi_array = coreml.is_multi_array(value)

Kiểm tra một giá trị có phải là coreml_multi_array_object hay không. is_tensor() là một bí danh tương đương.

Hàm tiện ích cấp mô-đun​

Tiện ích tensor cơ bản​

  • coreml.concat(arrays, axis)
  • coreml.stack(arrays, axis)
  • coreml.gather(array, dim, indices)
  • coreml.take(array, indices[, dim])
  • coreml.gather_rows(array, indices)
  • coreml.clamp(array, min, max)
  • coreml.sigmoid(array)
  • coreml.exp(array)
  • coreml.where(condition, x, y)
  • coreml.matmul(lhs, rhs)

Lưu ý:

  • take() mặc định dùng chiều 1
  • gather_rows() là bí danh tiện dụng của take(array, indices, 1)
  • where() hỗ trợ kết hợp giá trị vô hướng với MLMultiArray và áp dụng quy tắc broadcasting
  • matmul() hiện hỗ trợ các tổ hợp đầu vào hạng 1 / hạng 2

Tiện ích hình học và phát hiện​

  • coreml.nms(boxes, scores[, opts])
  • coreml.box_points(rotated_boxes)
  • coreml.xywh_to_xyxy(boxes)
  • coreml.xyxy_to_xywh(boxes)
  • coreml.rotated_iou(lhs, rhs)
  • coreml.rotated_nms(boxes, scores[, opts])

Lưu ý:

  • nms() yêu cầu boxes có hình dạng [N, 4] và scores có hình dạng [N] hoặc [N, C]
  • rotated_nms() yêu cầu boxes có hình dạng [N, 5]; đối số scores hiện là một mảng số Lua
  • Cả hai đều trả về MLMultiArray chứa các chỉ mục được giữ lại, bắt đầu từ 1

Tiện ích giải mã và bản ghi​

  • coreml.create_decoder(schema)
  • coreml.decode_yolo(output[, opts])
  • coreml.decode_yolo_obb(output[, opts])
  • coreml.decode_matrix_candidates(output, schema[, opts])
  • coreml.decode_dense_detection(output, opts)
  • coreml.records_from_boxes(boxes, scores, class_ids[, keep_indices])
  • coreml.obb_records_from_rows(rows, scores, class_ids[, angles[, keep_indices[, opts]]])
  • coreml.points_to_records(points[, opts])

Lưu ý:

  • create_decoder() trả về một đối tượng giải mã hỗ trợ :decode(), :task() và :schema()
  • decode_dense_detection() trả về { boxes, scores, labels }; khi đầu vào được phân lô, hàm trả về một mảng kết quả theo lô
  • decode_dense_detection() yêu cầu opts.strides, và giá trị này phải là một mảng số nguyên dương không rỗng
  • decode_dense_detection() cũng yêu cầu decode_width và decode_height, hiện chỉ hỗ trợ box_encoding = "grid_center_log_wh"
  • records_from_boxes(), obb_records_from_rows() và points_to_records() chuyển đầu ra tensor thành các bảng bản ghi dễ dùng hơn trong Lua

Tiện ích mặt nạ, điểm mốc và theo dõi​

  • coreml.threshold_masks(masks, threshold)
  • coreml.crop_masks_by_boxes(masks, boxes)
  • coreml.resize_masks(masks, width, height[, opts])
  • coreml.mask_iou(lhs_mask, rhs_mask)
  • coreml.mask_to_polygon(mask[, opts])
  • coreml.proto_masks(proto, coeffs, boxes, image_width, image_height[, opts])
  • coreml.project_masks(proto, coeffs, boxes, image_width, image_height[, opts])
  • coreml.db_postprocess(score_map[, opts])
  • coreml.tracker([opts])
  • coreml.reshape_keypoints(points[, keypoint_count[, keypoint_dim|opts]])
  • coreml.scale_boxes(boxes, transform)
  • coreml.clip_boxes(boxes, clip_width, clip_height)
  • coreml.scale_points(points, transform[, opts])
  • coreml.scale_keypoints(points, transform[, opts])
  • coreml.clip_keypoints(points, clip_width, clip_height[, opts])
  • coreml.ctc_greedy_decode(logits[, opts])
  • coreml.sample_logits(logits[, opts])

Lưu ý:

  • project_masks() là bí danh của proto_masks()
  • mask_iou() tính trực tiếp tỷ lệ giao trên hợp giữa hai mặt nạ
  • mask_iou() cũng chấp nhận đối số opts thứ ba với compare_size = true, hoặc width / height được chỉ định rõ làm kích thước so sánh
  • db_postprocess() dành cho hậu xử lý phát hiện văn bản kiểu DB / DBNet; đầ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, trong đó mỗi phần tử chứa score, points và box; meta / image_meta có thể tái sử dụng siêu dữ liệu tiền xử lý do quá trình chuyển ảnh thành tensor trả về
  • tracker() trả về một đối tượng theo dõi hỗ trợ :update(), :reset(), :state() và :close()
  • ctc_greedy_decode() chấp nhận logit [T, C] hoặc [N, T, C]
  • 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 cung cấp charset; confidence chỉ xuất hiện khi bật apply_softmax hoặc return_probabilities; probabilities và probability_confidence chỉ xuất hiện khi bật return_probabilities
  • sample_logits() hỗ trợ argmax, temperature, top_k, top_p, min_p và seed
  • sample_logits() trả về một chỉ mục bắt đầu từ 1 đối với logit 1D; với logit theo lô, hàm trả về một MLMultiArray chỉ mục

Phương thức đối tượng cơ bản​

Truy vấn cơ bản​

  • array:shape()
  • array:data_type()
  • array:count()
  • array:strides()
  • array:to_table()
  • array:to_cv_mat([opts])

Lưu ý:

  • data_type() trả về "int32", "float32", "float16" hoặc "double"
  • to_cv_mat() yêu cầu require("image.cv")

Cầu nối ORT​

  • array:to_ort_tensor([data_type])

Phương thức này mặc định không tồn tại; chỉ được thêm vào coreml_multi_array_object sau khi gọi require("onnxruntime").

Chuyển đổi kiểu và hình dạng​

  • array:astype(data_type)
  • array:clone()
  • array:reshape(shape)
  • array:transpose(axes)
  • array:slice(dim, start, stop[, step])
  • array:select(dim, index)
  • array:squeeze([dim])
  • array:unsqueeze(dim)
  • array:flatten([start_dim[, end_dim]])

Lưu ý:

  • Theo mặc định, reshape(), transpose(), squeeze(), unsqueeze() và flatten() trả về view và không sao chép dữ liệu bên dưới
  • reshape() / flatten() thất bại trên bố cục không liên tục; hãy gọi clone() trước nếu cần
  • slice() và select() trả về tensor liên tục mới, không phải view
  • Ngữ nghĩa chỉ mục của slice() / select() / gather() / take() vẫn bắt đầu từ 1 để khớp với tài liệu ONNX

Phương thức số học và lập chỉ mục​

  • array:gather(dim, indices)
  • array:take(indices[, dim])
  • array:l2_norm()
  • array:dot(other)
  • array:max([axis])
  • array:min([axis])
  • array:add(other)
  • array:sub(other)
  • array:mul(other)
  • array:div(other)
  • array:clamp(min, max)
  • array:sigmoid()
  • array:exp()
  • array:matmul(other)
  • array:scale(number)

Lưu ý:

  • add/sub/mul/div hỗ trợ giá trị vô hướng và broadcasting giới hạn
  • sigmoid(), exp() và matmul() nâng kết quả thành đầu ra dấu phẩy động

Rút gọn, xếp hạng và lựa chọn​

  • array:sum([axis])
  • array:mean([axis])
  • array:softmax([axis])
  • array:normalize([axis])
  • array:argmax([axis])
  • array:topk(k[, axis])
  • array:sort([axis[, descending]])

Lưu ý:

  • argmax() không có trục trả về chỉ mục tuyến tính bắt đầu từ 1 của giá trị lớn nhất trong toàn bộ mảng
  • argmax(axis) trả về một MLMultiArray chứa các chỉ mục
  • topk() trả về { values = tensor, indices = tensor }
  • sort() trả về một MLMultiArray mới đã sắp xếp; phương thức không trả về bảng chỉ mục riêng

Phương thức đối tượng cho hình học và hậu xử lý​

  • array:clip_boxes(clip_width, clip_height)
  • array:xywh_to_xyxy()
  • array:xyxy_to_xywh()
  • array:reshape_keypoints([keypoint_count[, keypoint_dim|opts]])
  • array:scale_points(transform[, opts])
  • array:clip_keypoints(clip_width, clip_height[, opts])

Các phương thức này dùng chung triển khai bên dưới với các tiện ích cấp mô-đun; chúng chỉ truyền mảng hiện tại làm đối số đầu tiên.

Lưu ý sử dụng​

  • Trong các API CoreML đa dụng mới hơn, MLMultiArray là kiểu dữ liệu hạng nhất mặc định; tránh chuyển đổi sớm sang bảng Lua
  • Phần lớn thao tác hàng loạt nên giữ trên đối tượng tensor; chủ yếu dùng to_table() để gỡ lỗi, xử lý đầu ra nhỏ hoặc tương thích với mã cũ
  • Nên cấu hình rõ bước tiền xử lý ảnh qua các tùy chọn của tensor_from_image(), thay vì nhúng quy tắc tiền xử lý của một mô hình vào quy trình dùng chung
  • Nếu cần một bản sao độc lập hoặc muốn chuyển bố cục không liên tục thành tensor liên tục, hãy gọi rõ clone()

Ví dụ​

local arr = assert(coreml.tensor({
    shape = {2, 3},
    data_type = "float32",
}))

local filled = assert(coreml.tensor_from_table({
    {1, 2, 3},
    {4, 5, 6},
}, {
    shape = {2, 3},
    data_type = "float32",
}))

local merged = assert(coreml.concat({filled, filled}, 1))
print(coreml.is_tensor(merged))
print(merged:shape())