Zum Hauptinhalt springen

Methoden des allgemeinen CoreML-Inferenz-Requests

coreml_model_request_object ist das von coreml.new_model_request(...) / coreml.session(...) zurückgegebene Inferenzobjekt.
Es übergibt vorbereitete Eingabefeatures an das Modell und gibt Ergebnisse zurück, die nach Ausgabenamen organisiert sind.

Die Aufgaben dieses Objekts sind klar abgegrenzt:

  • Inferenz übermitteln
  • Asynchrone Ergebnisse lesen
  • Ein-/Ausgabesignatur des Modells abfragen
  • Laufzeitkonfiguration des aktuellen Requests abfragen

Text-Tokenisierung, Bildvorverarbeitung und fachliche Nachverarbeitung gehören nicht dazu und müssen in der Lua-Schicht organisiert werden.

Diese Methoden sind in Versionen nach 20260319 verfügbar

Inferenzmethoden​

:predict(inputs[, opts])​

result, err = request:predict(inputs)

oder

submitted, err = request:predict(inputs, {
    async = is_async,
    multi_array_output = "table" or "MLMultiArray",
    uses_cpu_only = nur_CPU_verwenden,
})

Führt eine Einzelbeispiel-Inferenz aus.

  • inputs muss eine nach Eingabenamen organisierte Tabelle sein.
  • Im synchronen Modus wird die Ergebnistabelle direkt zurückgegeben.
  • Im asynchronen Modus wird nur true zurückgegeben; das Ergebnis wird später mit :is_done() und :results() gelesen.
  • multi_array_output legt fest, ob ein MLMultiArray in der Modellausgabe als nativer Tensor erhalten bleibt oder in eine Lua-Tabelle umgewandelt wird.
  • uses_cpu_only wirkt nur auf diese Inferenz und ändert die Standardkonfiguration des Objekts nicht.

:run(inputs[, opts])​

run() ist ein Alias für predict() und verhält sich identisch.

:predict_batch(batch_inputs[, opts])​

batch_result, err = request:predict_batch({
    { input_ids = ids1 },
    { input_ids = ids2 },
}, {
    async = false,
    multi_array_output = "MLMultiArray",
})

Führt eine Batch-Inferenz aus. Erfordert iOS 12+.

  • batch_inputs muss ein Array sein; jedes Element ist eine „nach Eingabenamen organisierte Eingabetabelle“.
  • Im synchronen Modus wird ein Batch-Ergebnisarray zurückgegeben; jedes Element folgt weiterhin der Einzelbeispiel-Ausgaberegel.
  • Im asynchronen Modus wird true zurückgegeben; das Ergebnis kann später mit :results() abgerufen werden.
  • Die Felder von opts entsprechen denen von predict().

:run_batch(batch_inputs[, opts])​

run_batch() ist ein Alias für predict_batch() und verhält sich identisch.

:results([opts])​

result, err = request:results()

oder

result, err = request:results({
    multi_array_output = "table" or "MLMultiArray",
})

Liest das Ergebnis der letzten asynchronen Inferenz.

  • Wenn der letzte asynchrone Aufruf von predict() stammt, wird hier eine Einzelbeispiel-Ergebnistabelle zurückgegeben.
  • Wenn der letzte asynchrone Aufruf von predict_batch() stammt, wird ein Batch-Ergebnisarray zurückgegeben.
  • multi_array_output übernimmt standardmäßig die Einstellung des letzten Inferenzaufrufs.
  • Wenn die asynchrone Aufgabe noch nicht beendet ist, wird nil, "not yet" zurückgegeben.
  • Wenn derzeit kein erfolgreiches Ergebnis gelesen werden kann, wird nil, "unknown" zurückgegeben.

:is_done()​

is_done = request:is_done()

Prüft, ob die letzte asynchrone Inferenz abgeschlossen ist. Dies ist nur nach predict(..., { async = true }) oder predict_batch(..., { async = true }) sinnvoll.

Laufzeitkonfiguration und Metadaten​

:metadata()​

metadata = request:metadata()

Gibt die vom Modell bereitgestellten Metadaten zurück. Geeignet für Debugging, allgemeine Wrapper oder die Anzeige von Modellinformationen.

:uses_cpu_only()​

nur_CPU_verwenden = request:uses_cpu_only()

Gibt die beim Erstellen dieses Requests gespeicherte CPUOnly-Standardkonfiguration zurück.

:compute_units()​

compute_units = request:compute_units()

Gibt die aktuell für diesen Request gespeicherte compute_units-Zeichenkette zurück.

  • Unter iOS 12+ wird hier die beim Erstellen gespeicherte Zeichenkette in Kleinbuchstaben zurückgegeben.
  • Häufige Rückgabewerte sind "all", "cpu_only", "cpu", "cpu_and_gpu", "gpu", "cpu_and_neural_engine", "ane" und "neural_engine".
  • Wenn beim Erstellen uses_cpu_only = true übergeben wurde, wird hier "cpu_only" zurückgegeben.
  • Unter iOS 11 wird nil zurückgegeben.

Methoden für Ein-/Ausgabesignaturen​

:input_count() / :output_count()​

Gibt die Anzahl der Eingabe-/Ausgabefeatures zurück.

:input_features() / :output_features()​

Gibt eine nach Namen indizierte Tabelle mit Featurebeschreibungen zurück.

Die tatsächlich zurückgegebenen Felder sind derzeit kompakt:

  • type
  • optional
  • Bei einem Featuretyp multi_array werden zusätzlich shape und data_type mitgegeben.

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

Liest die Informationen eines einzelnen Features nach Ein-/Ausgabenamen oder 1-basiertem Index.

  • Die Felder entsprechen im Wesentlichen input_features() / output_features().
  • Zusätzlich wird name aufgenommen.
  • Der Indexzugriff verwendet dieselbe Sortierreihenfolge wie input_names() / output_names().

:input_names() / :output_names()​

Gibt stabile, geordnete Listen der Ein-/Ausgabenamen zurück.

  • Die Namen werden lexikografisch sortiert.
  • Die Reihenfolge von output_names() entspricht der numerischen Indexreihenfolge in synchron zurückgegebenen Ergebnissen.

:class_labels()​

Gibt die vom Modell deklarierten Klassenlabels zurück. Erfordert iOS 14+.

Lebenszyklus und Typprüfung​

:close()​

Zerstört den Status des zugrunde liegenden Requests. Nach dem Schließen sollten keine weiteren Methoden aufgerufen werden.

:is_model_request() / :is_session()​

Objektbezogene Typprüfungen; beide sind gleichbedeutende Aliase.

Hinweise​

  • Das Ergebnis von predict() / run() ist immer eine Tabelle.
  • Das Ergebnis unterstützt sowohl numerische Indizes als auch Indizes nach Ausgabenamen.
  • predict_batch() / run_batch() geben ein Batch-Ergebnisarray zurück; jedes Element kann weiterhin sowohl numerisch als auch nach Ausgabenamen indiziert werden.
  • Bei einem neuen allgemeinen Inferenz-Request bleibt MLMultiArray standardmäßig ein natives Tensorobjekt und eignet sich damit besser für weitere Nachverarbeitung.
  • Wenn nur der Dateninhalt angezeigt oder ein älteres Skript kompatibel gehalten werden soll, kann explizit multi_array_output = "table" übergeben werden.

Beispiele für den Ergebniszugriff:

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

Beispiel​

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