jevlaya
Deutsch
Dokumentation

Konvertierungshinweise

Diese Seite beschreibt den gewöhnlichen Core ML-Export. Der separat neu geschriebene ANE-Graph und die optionale Gewichts-Palettierung sind in ANE_ENGINEERING.md dokumentiert.

Der Export lädt originale Laya-Checkpoints in FP32-PyTorch-Module, prüft strikt alle State-Dict-Schlüssel, traciert eine reine Inferenz-Implementierung und speichert ein Core ML ML Program. Die veröffentlichten Checkpoint-Dateien selbst enthalten überwiegend FP16-Tensoren; FP32 beschreibt hier die Export-/Referenzberechnung, nicht Quellgewichte höherer Präzision. Es wird kein Training, kein Pruning und keine Gewichtsquantisierung durchgeführt. FP16 ist eine Wahl der Konvertierungspräzision; FP32 kann für Diagnosen gewählt werden.

Die Laufzeit verwendet den Tokenizer, das Prompt-Layout, die Optionsmarker, das Fragetyp-Embedding, den Decision Head, den Action Head und die Kalibrierungstemperaturen des Checkpoints. Choice, score, noul, strukturierte Kriterien, Token-Abrechnung und null generierte Tokens folgen der Upstream-API. Der Encoder ist bidirektional: Jede Frage durchläuft weiterhin ihre eigene Encoder-Sequenz. Es gibt keinen Hidden-State-Cache über einen gemeinsamen Zustand.

Validierte Konvertierungsoptionen

  • coremltools==9.0, torch==2.7.0, numpy==2.1.3, Python 3.12.
  • TorchScript-Tracing mit Graph-Prüfung, Evaluationsmodus, originale Gewichte in FP32-Module geladen.
  • ML Program, Deployment-Ziel macOS 15 / iOS 18. Die tatsächliche Ausführung wurde auf einem M3 Max mit macOS 27.2 getestet; die Ausführung auf iPhone/iPad und älteren macOS-Versionen wurde nicht getestet.
  • Die Standard-Sequenzlängen werden aus 16, 32, 64, 96, 128, 192, 256, 384, 512, 768, 1024 gewählt, begrenzt durch das Kontextlimit des Checkpoints. Die Laufzeit füllt auf die kleinste verfügbare Länge auf und maskiert diese hinzugefügten Tokens.
  • Die Standard-Batchgröße ist eins, mit 32 Marker-Slots. Mehr Fragen laufen in Blöcken. --batch-size und --max-options erzeugen unterschiedliche exportierte Signaturen.
  • Für eine bekannte Workload sind feste Shapes verfügbar. Eingaben, die die Länge oder Optionskapazität eines Exports überschreiten, lösen einen Fehler aus; sie werden nicht still abgeschnitten, um in einen kleineren Export zu passen. Die Kontext-Trunkierung des ursprünglichen Checkpoints bleibt erhalten.

Apple dokumentiert die TorchScript-Konvertierung und aufgezählte Eingabe-Shapes. Mehrere aufgezählte Eingaben benötigen dieselbe Anzahl an Shapes, nach Index zugeordnet; dieser Export paart Eingabe-IDs und Attention-Masken entsprechend.

Fehler, die für die Reproduzierbarkeit erhalten bleiben

Dies sind Beobachtungen auf dieser Maschine und diesem OS, keine Aussagen über jede Core ML-Version.

  1. PyTorchs boolescher Operator __or__ wurde nicht konvertiert. Explizite torch.logical_or / torch.logical_and bewahren dieselbe Maskensemantik.
  2. NumPy 2.5 lehnte eine veraltete Array-zu-Skalar-Konvertierung innerhalb von coremltools 9.0 ab. Die unterstützte Projektabhängigkeit ist auf unter NumPy 2.2 fixiert. PyTorch wurde auf die getestete Version 2.7.0 des Konverters statt auf 2.7.1 fixiert.
  3. RangeDim mit erzwungenem CPU_AND_GPU erzeugte große numerische Fehler und unterschiedliche Ergebnisse bei wiederholten identischen Eingaben. Der ursprüngliche SDPA-Export stimmte nur bei 47/63 Referenzantworten überein, und explizite matmul/softmax-Attention stimmte bei 20/63 überein. FP32 löste den beobachteten GPU-Fehler bei kurzen Eingaben nicht. CPU / automatische Auswahl lieferten korrekte Ausgaben für den SDPA-Graphen.
  4. Aufgezählte Längen stellten GPU-Treue und Wiederholbarkeit wieder her. Ein separater winziger Regressionstest deckte dann einen MPSGraph-Compiler-SIGTRAP auf, als eine konstante boolesche Local-Attention-Matrix geslict wurde. Die Diagnose benannte ElementsAttr::getValues<bool> / FoldStridedSliceOp.
  5. Die endgültige Implementierung slict ganzzahlige Positionen und konstruiert die boolesche lokale Maske danach. Das beseitigt die Compiler-Falle. Es heilt jedoch nicht den allgemeinen RangeDim-GPU-Fehler: Das nachfolgende Experiment stimmte weiterhin nur bei 49/63 überein und war nicht wiederholbar. Aufgezählte Längen bleiben der Standard.

Die Laufzeit lehnt RangeDim + cpu_gpu ab, sofern es nicht ausdrücklich für ein Diagnoseexperiment erlaubt ist. Um diese fehlgeschlagene Konfiguration zu reproduzieren:

laya-coreml convert laya-multilingual models/range-experiment --shape-mode range
python -m benchmarks.validate models/range-experiment \
  --name laya-multilingual --compute-units cpu_gpu --allow-unvalidated-gpu \
  --repeats 10 --output artifacts/range-experiment.json

Der Test wird voraussichtlich in der gemessenen Umgebung fehlschlagen. Rohe fehlgeschlagene und erfolgreiche Berichte bleiben in benchmarks/results/ erhalten; Berichte mit "passed": false dürfen nicht als validierte Konfigurationen zitiert werden.

Gerätebelege

CPU_AND_NE bedeutet, dass CPU und Neural Engine erlaubt sind, nicht dass jeder Operator auf der Neural Engine läuft. Der Benchmark zeichnet die bevorzugten/unterstützten Geräte und geschätzten Kosten des Core ML Compute Plans auf. Das ist ein antizipierter Plan, kein Instruments-Laufzeit-Hardware-Trace, keine Leistungsmessung und kein Beweis ausschließlicher Ausführung auf der Neural Engine.

Hub-Snapshots laden

Der Release-Smoke-Test fand ein separates Paketierungsproblem: Das Laden einer Weight-Datei als symbolischer Link aus dem gemeinsamen Hugging Face-Cache veranlasste den nativen Compiler von Core ML, eine fehlende model.mlmodelc/weights/weight.bin zu melden. Alle sechs äquivalenten lokalen Bundles ließen sich erfolgreich laden. Die Laufzeit kopiert symlink-gestützte Pakete nun in einen inhaltsadressierten Cache aus regulären Dateien, bevor sie MLModel konstruiert. Hashes werden vor und nach dem Kopieren sowie bei der Wiederverwendung geprüft; ein veränderter oder beschädigter Cache löst einen Fehler aus. Lokale Bundles aus regulären Dateien nehmen diesen Kopierpfad nicht. Siehe USAGE.md für den Cache-Speicherort und die Überschreibung.

Reproduzierbarkeit

Jeder Export enthält coreml_config.json: SHA256 der ursprünglichen Gewichte, Quellrevision, Shapes, Präzision, Attention-Implementierung, Tool-Versionen, Konvertierungszeit und Hashes jeder Paket-/Tokenizer-/Konfigurationsdatei. Exporte weigern sich, vorhandene Verzeichnisse zu überschreiben. Ein fehlgeschlagener Export entfernt nur sein neu erstelltes Ausgabeverzeichnis.

Die committete Golden Reference wurde aus der unveränderten Upstream-Laya-Revision 573e5b62696ba441230cd6be71d593331b5d23af mit FP32 PyTorch MPS erzeugt. Sie enthält vollständige Eingabe-Token-IDs und ungerundete Logits. Die Validierung vergleicht diese Tokens exakt und prüft ausgewählte Antworten, kalibrierte Wahrscheinlichkeiten, Action-Wahrscheinlichkeiten, Token-Abrechnung und wiederholte öffentliche Ergebnisse.

Um die Golden Reference in einer upstream-kompatiblen Umgebung neu zu erzeugen:

git clone https://github.com/NandhaKishorM/laya .upstream
git -C .upstream checkout 6a5819129eb220570792e417e49723d697efd76f
python -m benchmarks.reference --upstream .upstream --model-root /path/to/original/checkpoints

Die genauen Referenzabhängigkeiten sind im erzeugten JSON festgehalten. Sie sind getrennt von der fixierten Exportumgebung; Transformers ist keine Laufzeit- oder Exportabhängigkeit von laya-coreml.