Pular para o conteúdo principal

Métodos do objeto de request CoreML genérico

coreml_model_request_object é o objeto de inferência retornado por coreml.new_model_request(...) / coreml.session(...).
Ele envia ao modelo as features de entrada preparadas e retorna os resultados organizados por nome de saída.

A responsabilidade deste objeto é bem delimitada:

  • enviar inferências
  • ler resultados assíncronos
  • consultar as assinaturas de entrada e saída do modelo
  • consultar a configuração de execução do request atual

Ele não faz tokenização de texto, pré-processamento de imagens nem pós-processamento da lógica de negócio; essas tarefas devem ser organizadas na camada Lua.

Estes métodos só estão disponíveis em versões posteriores a 20260319

Métodos de inferência​

:predict(inputs[, opts])​

resultado, mensagem_de_erro = objeto_request_genérico:predict(mapa_de_entradas)

ou

foi_enviado, mensagem_de_erro = objeto_request_genérico:predict(mapa_de_entradas, {
    async = assíncrono,
    multi_array_output = "table" ou "MLMultiArray",
    uses_cpu_only = usar_apenas_CPU_nesta_execução,
})

Executa uma inferência de modelo para uma única amostra.

  • inputs deve ser uma tabela organizada por nome de entrada.
  • No modo síncrono, retorna diretamente a tabela de resultados.
  • No modo assíncrono, retorna apenas true; use :is_done() e :results() depois para obter o resultado.
  • multi_array_output controla se um MLMultiArray na saída do modelo será mantido como tensor nativo ou convertido em tabela Lua.
  • uses_cpu_only afeta somente esta inferência e não altera a configuração padrão do objeto.

:run(inputs[, opts])​

run() é um alias de predict() e tem exatamente o mesmo comportamento.

:predict_batch(batch_inputs[, opts])​

resultados_do_batch, mensagem_de_erro = objeto_request_genérico:predict_batch({
    { input_ids = ids1 },
    { input_ids = ids2 },
}, {
    async = false,
    multi_array_output = "MLMultiArray",
})

Executa inferência em batch. Requer iOS 12+.

  • batch_inputs deve ser um array, em que cada item é uma “tabela de entrada organizada por nome de entrada”.
  • No modo síncrono, retorna um array de resultados do batch; cada elemento continua organizado conforme as regras de saída de uma única amostra.
  • No modo assíncrono, retorna true; recupere o resultado depois por meio de :results().
  • Os campos de opts são os mesmos de predict().

:run_batch(batch_inputs[, opts])​

run_batch() é um alias de predict_batch() e tem exatamente o mesmo comportamento.

:results([opts])​

resultado, mensagem_de_erro = objeto_request_genérico:results()

ou

resultado, mensagem_de_erro = objeto_request_genérico:results({
    multi_array_output = "table" ou "MLMultiArray",
})

Lê o resultado da inferência assíncrona mais recente.

  • Se a chamada assíncrona mais recente veio de predict(), retorna uma tabela de resultado de uma única amostra.
  • Se veio de predict_batch(), retorna um array de resultados do batch.
  • Por padrão, multi_array_output reutiliza a configuração da última chamada de inferência.
  • Se a tarefa assíncrona ainda não terminou, retorna nil, "not yet".
  • Se não houver um resultado bem-sucedido disponível para leitura, retorna nil, "unknown".

:is_done()​

está_concluído = objeto_request_genérico:is_done()

Verifica se a última inferência assíncrona foi concluída. Só tem significado depois de predict(..., { async = true }) ou predict_batch(..., { async = true }).

Configuração de execução e metadados​

:metadata()​

metadados = objeto_request_genérico:metadata()

Retorna os metadados incluídos no modelo. É útil para depuração, wrappers genéricos ou exibição de informações do modelo.

:uses_cpu_only()​

usa_apenas_CPU_por_padrão = objeto_request_genérico:uses_cpu_only()

Retorna a configuração padrão CPUOnly armazenada quando este request foi criado.

:compute_units()​

configuração_das_unidades_de_cálculo = objeto_request_genérico:compute_units()

Retorna a string compute_units registrada atualmente para este request.

  • No iOS 12+, retorna a string em minúsculas registrada durante a criação.
  • Os valores retornados comuns incluem "all", "cpu_only", "cpu", "cpu_and_gpu", "gpu", "cpu_and_neural_engine", "ane" e "neural_engine".
  • Se uses_cpu_only = true tiver sido passado na criação, retorna "cpu_only".
  • No iOS 11, retorna nil.

Métodos de assinatura de entrada e saída​

:input_count() / :output_count()​

Retornam a quantidade de features de entrada / saída.

:input_features() / :output_features()​

Retornam uma tabela de descrições de features indexada por nome.

Atualmente, os campos retornados são relativamente enxutos:

  • type
  • optional
  • quando o tipo da feature é multi_array, também inclui shape e data_type

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

Lê as informações de uma única feature pelo nome da entrada / saída ou por seu índice começando em 1.

  • Os campos retornados são basicamente os mesmos de input_features() / output_features().
  • Também inclui name.
  • O acesso por índice usa a mesma regra de ordenação de input_names() / output_names().

:input_names() / :output_names()​

Retornam listas estáveis e ordenadas de nomes de entrada / saída.

  • Os nomes são ordenados em ordem lexicográfica.
  • A ordem de output_names() é a mesma ordem dos índices numéricos nos resultados retornados pela inferência síncrona.

:class_labels()​

Retorna os rótulos de classe declarados pelo modelo. Requer iOS 14+.

Ciclo de vida e verificação de tipo​

:close()​

Destrói o estado subjacente do request. Depois de fechá-lo, não continue chamando outros métodos.

:is_model_request() / :is_session()​

Interfaces de verificação de tipo no nível do objeto; as duas são aliases equivalentes.

Observações​

  • O resultado de predict() / run() é sempre uma tabela.
  • O resultado aceita tanto índice numérico quanto índice pelo nome da saída.
  • predict_batch() / run_batch() retorna um array de resultados do batch; cada item continua permitindo acesso duplo por índice numérico e nome de saída.
  • Para um request genérico novo, MLMultiArray é mantido por padrão como objeto de tensor nativo, o que é mais adequado para continuar o pós-processamento.
  • Se quiser apenas visualizar os dados ou manter compatibilidade com scripts antigos, passe explicitamente multi_array_output = "table".

Exemplos de acesso aos resultados:

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

Exemplo​

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