Перейти к основному содержимому

Методы объекта универсального инференсера 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",
})

Выполняет пакетный инференс. Требуется iOS 12+.

  • batch_inputs должен быть массивом, каждый элемент которого является таблицей входов, организованной по именам
  • В синхронном режиме возвращает массив пакетных результатов; каждый элемент организован по правилам одиночного результата
  • В асинхронном режиме возвращает 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(), возвращается массив пакетных результатов
  • multi_array_output по умолчанию наследует настройку последнего вызова инференса
  • Если асинхронная задача ещё не завершена, возвращается nil, "not yet"
  • Если сейчас нет доступного успешного результата, возвращается nil, "unknown"

:is_done()​

завершено = объект_универсального_инференсера:is_done()

Проверяет завершение последнего асинхронного инференса. Имеет смысл только после predict(..., { async = true }) или predict_batch(..., { async = true }).

Конфигурация выполнения и метаданные​

: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.

  • Возвращаемые поля в основном совпадают с 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() возвращают массив пакетных результатов; каждый элемент также поддерживает доступ по числовому индексу и имени выхода
  • Для новых универсальных инференсеров 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())