跳到主要内容

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