跳至主要內容

CoreML 通用推理器物件方法

coreml_model_request_object 是 coreml.new_model_request(...) / coreml.session(...) 返回的推理物件。
它負責把準備好的輸入特徵送進模型，並返回按輸出名組織的結果。

這個物件的職責很單一：

  • 提交推理
  • 讀取異步結果
  • 查詢模型輸入輸出簽名
  • 查詢目前 request 的運行設定

它不負責文字分詞、圖片預處理或業務後處理，這些應由 Lua 層自行組織。

這些方法在 20260319 以後版本方可使用

推理方法​

:predict(inputs[, opts])​

返回結果, 錯誤資訊 = 通用推理器物件:predict(輸入映射表)

或

是否已提交, 錯誤資訊 = 通用推理器物件:predict(輸入映射表, {
    async = 是否異步,
    multi_array_output = "table" 或 "MLMultiArray",
    uses_cpu_only = 是否本次只使用 CPU,
})

執行一次單樣本模型推理。

  • inputs 必須是按輸入名組織的表
  • 同步模式下直接返回結果表
  • 異步模式下只返回 true，稍後再用 :is_done() 和 :results() 取結果
  • multi_array_output 用於控制模型輸出里的 MLMultiArray 是保留為原生張量，還是轉成 Lua 表
  • uses_cpu_only 只影響本次推理，不會修改物件預設設定

:run(inputs[, opts])​

run() 是 predict() 的別名，行為完全一致。

:predict_batch(batch_inputs[, opts])​

批量結果, 錯誤資訊 = 通用推理器物件:predict_batch({
    { input_ids = ids1 },
    { input_ids = ids2 },
}, {
    async = false,
    multi_array_output = "MLMultiArray",
})

執行 batch 推理。需要 iOS 12+。

  • batch_inputs 必須是陣列，陣列里的每一項都是一個“按輸入名組織的輸入表”
  • 同步模式下返回 batch 結果陣列；每個元素仍按單樣本輸出規則組織
  • 異步模式下返回 true，稍後通過 :results() 取回
  • opts 字段與 predict() 相同

:run_batch(batch_inputs[, opts])​

run_batch() 是 predict_batch() 的別名，行為完全一致。

:results([opts])​

返回結果, 錯誤資訊 = 通用推理器物件:results()

或

返回結果, 錯誤資訊 = 通用推理器物件:results({
    multi_array_output = "table" 或 "MLMultiArray",
})

讀取最近一次異步推理的結果。

  • 如果最近一次異步呼叫來自 predict()，這裡返回單樣本結果表
  • 如果最近一次異步呼叫來自 predict_batch()，這裡返回 batch 結果陣列
  • multi_array_output 預設沿用最近一次推理呼叫的設定
  • 如果異步任務還沒結束，返回 nil, "not yet"
  • 如果目前沒有可讀取的成功結果，返回 nil, "unknown"

:is_done()​

是否完成 = 通用推理器物件:is_done()

檢查最近一次異步推理是否已經完成。只有在 predict(..., { async = true }) 或 predict_batch(..., { async = true }) 之後才有意義。

運行設定與元資訊​

:metadata()​

元資訊 = 通用推理器物件:metadata()

返回模型自帶的 metadata。適合偵錯、通用封裝或做模型資訊展示。

:uses_cpu_only()​

是否預設只用 CPU = 通用推理器物件:uses_cpu_only()

返回這個 request 建立時儲存的預設 CPUOnly 設定。

:compute_units()​

計算單元設定 = 通用推理器物件:compute_units()

返回這個 request 目前記錄的 compute_units 字串。

  • 在 iOS 12+ 上，這裡返回建立時記錄下來的小寫字串
  • 常見回傳值包括 "all"、"cpu_only"、"cpu"、"cpu_and_gpu"、"gpu"、"cpu_and_neural_engine"、"ane"、"neural_engine"
  • 如果建立時傳了 uses_cpu_only = true，這裡會返回 "cpu_only"
  • 在 iOS 11 上返回 nil

輸入輸出簽名方法​

:input_count() / :output_count()​

返回輸入 / 輸出特徵數量。

:input_features() / :output_features()​

返回按名稱索引的特徵描述表。

目前實際返回字段比較精簡：

  • type
  • optional
  • 當特徵類型是 multi_array 時，額外帶 shape 和 data_type

:input_info(name_or_index) / :output_info(name_or_index)​

按輸入 / 輸出名或 1-based 序號讀取單個特徵的資訊。

  • 返回字段與 input_features() / output_features() 基本一致
  • 會額外帶 name
  • 序號訪問使用與 input_names() / output_names() 相同的排序規則

:input_names() / :output_names()​

返回穩定有序的輸入 / 輸出名清單。

  • 名稱會按字典序排序
  • output_names() 的順序與同步推理返回結果里的數字索引順序一致

:class_labels()​

返回模型聲明的類別標籤。需要 iOS 14+。

生命週期與類型判斷​

:close()​

銷毀底層 request 狀態。關閉後不應再繼續呼叫其它方法。

:is_model_request() / :is_session()​

物件級類型判斷介面，二者是同義別名。

說明​

  • predict() / run() 的返回結果始終是一個表
  • 結果同時支援數字索引和輸出名索引
  • predict_batch() / run_batch() 返回的是 batch 結果陣列；陣列里的每項仍是“數字索引 + 輸出名索引”雙訪問方式
  • 對新的通用推理器來說，MLMultiArray 預設保留為原生張量物件，更適合繼續做後處理
  • 如果只是想看資料內容，或要兼容舊式腳本，可以顯式傳 multi_array_output = "table"

結果訪問範例：

out[1]
out.text_features
batch_out[1].text_features

範例​

local req = assert(coreml.new_model_request(XXT_HOME_PATH.."/models/demo.mlmodelc"))

local out = assert(req:predict({
    input_ids = ids,
}, {
    multi_array_output = "MLMultiArray",
}))

print(out[1])
print(out.text_features)
print(req:output_names())