メインコンテンツまでスキップ

ONNX Runtime モジュール (onnxruntime)

このモジュールは 20260402 以降のバージョンでのみ使用できます
iOS 13 以降のシステムにのみ対応しています

onnxruntime モジュールは、デバイス上で ONNX モデルを直接読み込んで実行します。テキスト、Embedding、分類、検出、および各種の汎用テンソル推論に適しています。

モジュールの読み込み​

local ort = require("onnxruntime")

これはオンデマンドで読み込まれるモジュールであり、coreml のような組み込みグローバルモジュールではありません。

require("onnxruntime") の実行に成功すると、組み込みの coreml モジュールに二つのブリッジインターフェースも追加されます。

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

どちらの変換もネイティブ層で直接コピーされ、Lua テーブルを経由しません。

モジュールレベル関数​

ランタイムと基本情報​

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

説明：

  • providers() は、現在の ORT ランタイムで実際に利用できる Execution Provider の一覧を返します
  • configure() はグローバルなランタイムのデフォルト値を設定するために使用します。セッションを作成する前に必ず呼び出してください

テンソル、画像、および数値処理の補助関数​

  • 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: メソッドと同等であり、テンソルを最初の引数として渡す点だけが異なります
  • where() ではスカラー / ブール値 / テンソルを混在させることができ、ブロードキャスト規則に従って結果を生成します
  • 画像の前処理、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() は、形状が [5]、[1, 5]、または [N, 5] の回転ボックステンソルを受け取ります。五つの個別のスカラー引数を受け取るものではありません
  • create_decoder() はデコーダーオブジェクトを返し、:decode()、:task()、:schema() を使用できます
  • tracker() はトラッカーオブジェクトを返し、:update()、:reset()、:state()、:close() を使用できます
  • records_from_boxes()、obb_records_from_rows()、points_to_records() は、テンソルの結果を Lua 側で扱いやすいレコードテーブルに整理します
  • proto_masks() と project_masks() は現在同じ実装を使用しており、後者は単なる別名です
  • mask_iou() は、二つのマスクの IoU を直接計算します。第三の引数 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 に対応しています
  • sample_logits() は 1D 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)

optional、sequence、map、sparse tensor など、純粋なテンソルではない入出力の処理に適しています。

現在の動作は次のようにまとめられます。

  • onnxruntime.value(x) x がすでに ORT tensor / value / sequence / map / sparse tensor である場合は、そのまま返されます。x が Lua テーブルである場合は sequence として処理され、それ以外の場合はスカラーがテンソルにラップされます
  • 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)

セッションオブジェクトは、モデルの読み込み、入出力情報の参照、推論の実行、および 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 の一覧を返しますが、現在セッションオプションでネイティブに処理され、サポートされる Provider 文字列は次のとおりです。

  • "cpu"
  • "coreml"

説明：

  • provider / providers は CPUExecutionProvider、CoreMLExecutionProvider などの別名も受け付け、内部で "cpu"、"coreml" に正規化されます
  • Provider を明示的に指定していない場合、または Provider の一覧が空の場合、セッションの作成時に 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"))