Aller au contenu principal

Méthodes de l’objet inféreur CoreML générique

coreml_model_request_object est l’objet d’inférence renvoyé par coreml.new_model_request(...) / coreml.session(...).
Il transmet au modèle les features d’entrée préparées et renvoie les résultats organisés par nom de sortie.

Les responsabilités de cet objet sont limitées :

  • soumettre une inférence
  • lire un résultat asynchrone
  • consulter la signature des entrées et sorties du modèle
  • consulter la configuration d’exécution de la requête actuelle

Il ne prend pas en charge la tokenisation de texte, le prétraitement d’images ni le post-traitement métier ; ces opérations doivent être organisées dans Lua.

Ces méthodes sont disponibles à partir des versions postérieures au 20260319

Méthodes d’inférence​

:predict(inputs[, opts])​

resultat, message_erreur = objet_inference_generique:predict(table_mapping_entrees)

ou

soumis, message_erreur = objet_inference_generique:predict(table_mapping_entrees, {
    async = asynchrone,
    multi_array_output = "table" ou "MLMultiArray",
    uses_cpu_only = uniquement CPU pour cette inférence,
})

Effectue une inférence sur un échantillon.

  • inputs doit être une table organisée par nom d’entrée
  • En mode synchrone, renvoie directement une table de résultats
  • En mode asynchrone, renvoie uniquement true, puis :is_done() et :results() permettent de lire le résultat
  • multi_array_output indique si les MLMultiArray des sorties doivent rester des tenseurs natifs ou être convertis en tables Lua
  • uses_cpu_only ne concerne que cette inférence et ne modifie pas la configuration par défaut de l’objet

:run(inputs[, opts])​

run() est un alias de predict() et son comportement est identique.

:predict_batch(batch_inputs[, opts])​

resultats_batch, message_erreur = objet_inference_generique:predict_batch({
    { input_ids = ids1 },
    { input_ids = ids2 },
}, {
    async = false,
    multi_array_output = "MLMultiArray",
})

Effectue une inférence par lots. Nécessite iOS 12+.

  • batch_inputs doit être un tableau dont chaque élément est une table d’entrée organisée par nom
  • En mode synchrone, renvoie un tableau de résultats par lots ; chaque élément suit encore les règles de sortie d’un échantillon
  • En mode asynchrone, renvoie true, puis le tableau est récupéré avec :results()
  • Les champs de opts sont les mêmes que pour predict()

:run_batch(batch_inputs[, opts])​

run_batch() est un alias de predict_batch() et son comportement est identique.

:results([opts])​

resultat, message_erreur = objet_inference_generique:results()

ou

resultat, message_erreur = objet_inference_generique:results({
    multi_array_output = "table" ou "MLMultiArray",
})

Lit le résultat de la dernière inférence asynchrone.

  • Si le dernier appel asynchrone provenait de predict(), renvoie la table de résultats d’un échantillon
  • S’il provenait de predict_batch(), renvoie le tableau de résultats par lots
  • multi_array_output reprend par défaut la configuration du dernier appel d’inférence
  • Si la tâche asynchrone n’est pas terminée, renvoie nil, "not yet"
  • S’il n’existe aucun résultat réussi lisible, renvoie nil, "unknown"

:is_done()​

est_termine = objet_inference_generique:is_done()

Vérifie si la dernière inférence asynchrone est terminée. Cette méthode n’a de sens qu’après predict(..., { async = true }) ou predict_batch(..., { async = true }).

Configuration d’exécution et métadonnées​

:metadata()​

metadonnees = objet_inference_generique:metadata()

Renvoie les metadata intégrées au modèle, utiles pour le débogage, les encapsulations génériques ou l’affichage d’informations sur le modèle.

:uses_cpu_only()​

CPU_par_defaut = objet_inference_generique:uses_cpu_only()

Renvoie la configuration CPUOnly par défaut enregistrée lors de la création de cette requête.

:compute_units()​

configuration_unites_calcul = objet_inference_generique:compute_units()

Renvoie la chaîne compute_units actuellement enregistrée par la requête.

  • Sous iOS 12+, renvoie la chaîne en minuscules enregistrée lors de la création
  • Les valeurs courantes comprennent "all", "cpu_only", "cpu", "cpu_and_gpu", "gpu", "cpu_and_neural_engine", "ane" et "neural_engine"
  • Si uses_cpu_only = true a été fourni à la création, renvoie "cpu_only"
  • Sous iOS 11, renvoie nil

Méthodes de signature des entrées et sorties​

:input_count() / :output_count()​

Renvoie le nombre de features d’entrée / de sortie.

:input_features() / :output_features()​

Renvoie une table de descriptions des features indexée par nom.

Les champs effectivement renvoyés sont actuellement limités :

  • type
  • optional
  • lorsque le type de feature est multi_array, les champs shape et data_type sont également présents

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

Lit les informations d’une feature selon son nom d’entrée / sortie ou son numéro 1-based.

  • Les champs renvoyés sont globalement les mêmes que ceux de input_features() / output_features()
  • Le champ name est ajouté
  • L’accès par numéro suit le même ordre que input_names() / output_names()

:input_names() / :output_names()​

Renvoie la liste stable et ordonnée des noms d’entrée / de sortie.

  • Les noms sont triés dans l’ordre lexicographique
  • L’ordre de output_names() est le même que celui des indices numériques dans les résultats d’une inférence synchrone

:class_labels()​

Renvoie les étiquettes de classes déclarées par le modèle. Nécessite iOS 14+.

Cycle de vie et détermination du type​

:close()​

Détruit l’état de la requête sous-jacente. Après la fermeture, aucune autre méthode ne doit être appelée.

:is_model_request() / :is_session()​

Interfaces de détermination du type de l’objet ; ce sont deux alias synonymes.

Description​

  • Le résultat de predict() / run() est toujours une table
  • Le résultat peut être consulté par index numérique ou par nom de sortie
  • predict_batch() / run_batch() renvoient un tableau de résultats par lots ; chaque élément peut encore être consulté par index numérique et par nom de sortie
  • Pour un nouvel inféreur générique, MLMultiArray reste par défaut un objet tenseur natif, ce qui convient mieux au post-traitement
  • Pour examiner le contenu ou assurer la compatibilité avec d’anciens scripts, transmettez explicitement multi_array_output = "table"

Exemple d’accès aux résultats :

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

Exemple​

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