跳至主要內容

建立一個通用 CoreML 推理器 (coreml.new_model_request)

coreml.new_model_request 用於載入一個已經編譯好的 CoreML 模型，並建立一個不依賴 Vision 的通用推理器。
它適合文字模型、張量輸入模型、多輸入多輸出模型、Embedding 模型以及任何“輸入不是一張普通圖片”的模型。

如果模型本身是圖片識別流程，且希望直接傳 image 物件做視覺推理，應優先使用 new_vision_request。
如果需要自己準備輸入特徵，或模型輸入包含 MLMultiArray、文字 token、多個命名輸入，應使用該介面。

另外，coreml.session(...) 是這個函式的別名。

聲明​

通用推理器物件, 錯誤資訊 = coreml.new_model_request(編譯好的模型路徑)

或

通用推理器物件, 錯誤資訊 = coreml.new_model_request({
    compiled_model_path = 編譯好的模型路徑,
    uses_cpu_only = 是否只使用 CPU,
    compute_units = 計算單元設定,
})

參數​

  • compiled_model_path 文字型，已經編譯完成的 .mlmodelc 模型目錄路徑。

  • uses_cpu_only 布林型，可選參數，是否預設只使用 CPU 推理，預設 false。

  • compute_units 文字型，可選參數，iOS 12+ 生效。支援以下值：

    • "all"
    • "cpu_only" 或 "cpu"
    • "cpu_and_gpu" 或 "gpu"
    • "cpu_and_neural_engine"、"ane" 或 "neural_engine"（iOS 16+）

    當 uses_cpu_only = true 時，會優先強制使用 CPUOnly 設定。

回傳值​

  • 通用推理器物件
    通用推理器物件，建立失敗返回 nil。

  • 錯誤資訊
    文字型，建立成功返回 nil，失敗時返回錯誤資訊。

說明​

該函式在 20260319 以後版本方可使用

  • 基礎能力支援 iOS 11+
  • compute_units 相關設定依賴 iOS 12+
  • 如果模型聲明的是 image feature，且你想把 image_object 直接作為輸入傳給這個通用 request，則需要 iOS 13+
  • 傳入輸入參數時，需使用“輸入名映射表”的形式，例如 { input_ids = ids }
  • 輸入值支援數字、字串、布林值、字典、MLMultiArray，以及模型聲明為圖片特徵時的 image 物件
  • 這個物件只負責模型推理，不負責圖片預處理或文字分詞；這些步驟需要在 Lua 層自行準備
  • 同一個推理器物件可以重復呼叫 predict() / run()，適合快取起來反復使用，而不是每次推理都重新建立
  • 如果老裝置或某些模型在預設後端上不穩定，可以在建立時設定 uses_cpu_only = true

類型判斷​

聲明​

是否通用推理器 = coreml.is_model_request(需要判斷的值)

或

是否通用推理器 = coreml.is_session(需要判斷的值)

參數​

  • 需要判斷的值
    值，需要判斷是否為 CoreML 通用推理器物件的值。

回傳值​

  • 是否通用推理器
    布林型，是返回 true，否則返回 false。

說明​

  • coreml.is_session() 與 coreml.is_model_request() 是同義介面
  • 適合在通用 Lua 封裝里做類型保護或參數校驗
  • 如果你已經明確持有的是 new_model_request(...) / session(...) 回傳值，通常不需要額外呼叫它

範例​

local compiled_model_path = XXT_HOME_PATH.."/models/demo_text.mlmodelc"

local req, err = coreml.new_model_request({
    compiled_model_path = compiled_model_path,
    uses_cpu_only = false,
    compute_units = "all",
})
if not req then
    error(err)
end

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

print(req:input_names())
print(req:output_names())
print(out[1])