PyTorch AOTI-Debugging einrichten

Was ist aoti-debug und wofür wird es gebraucht

aoti-debug ist eine Claude-Code-Skill aus dem offiziellen PyTorch-Repository auf GitHub und liegt dort unter dem Pfad .claude/skills/aoti-debug/SKILL.md im Hauptprojekt pytorch/pytorch. Die Skill richtet sich an Entwicklerinnen und Entwickler, die mit AOTInductor arbeiten, kurz AOTI. AOTInductor ist laut Anbieter die Ahead-of-Time-Kompilierungskomponente von PyTorch 2, mit der trainierte Modelle vorab in eine ausführbare Form übersetzt werden, statt sie bei jedem Programmstart erneut zu kompilieren. Das beschleunigt den Start von Inferenz-Workloads erheblich, bringt aber eine eigene Klasse von Fehlern mit sich, die sich von klassischen Python-Tracebacks unterscheiden: Segfaults, stille Abstürze beim Laden von Konstanten oder verwirrende Meldungen über nicht übereinstimmende Geräte. Genau hier setzt die Skill an. Sie fungiert als strukturierter Debugging-Leitfaden, den Claude Code automatisch heranzieht, sobald im Gespräch Begriffe wie aot_compile, aot_load, aoti_compile_and_package oder aoti_load_package auftauchen oder ein Nutzer einen AOTI-Absturz beschreibt. Für Teams, die PyTorch-Modelle produktiv über AOTI ausliefern, verkürzt eine solche Skill die Zeit bis zur Ursachenfindung spürbar, weil sie das Wissen erfahrener PyTorch-Maintainer in eine wiederholbare Checkliste gießt, statt dass jede Entwicklerin das Problem von Grund auf neu untersuchen muss.

Voraussetzungen

Um die Skill sinnvoll zu nutzen, braucht es eine lokale PyTorch-Installation mit aktivierter AOTInductor-Funktionalität sowie idealerweise Zugriff auf eine GPU, da viele der beschriebenen Fehlerbilder wie Illegal-Memory-Access-Fehler oder Device-Mismatch-Probleme CUDA-spezifisch sind. Die Skill selbst ist Teil des PyTorch-Repositorys und wird über den Claude-Code-Skill-Mechanismus geladen, etwa per npx skills add pytorch/pytorch mit dem Parameter für die gewünschte Skill oder durch manuelles Kopieren der SKILL.md in das lokale .claude/skills-Verzeichnis eines Projekts. Nutzerinnen sollten zudem wissen, auf welchem Gerätetyp ihr Modell kompiliert wurde, denn diese Information ist für praktisch jeden Debugging-Schritt notwendig. Grundkenntnisse in der PyTorch-Kompilierungspipeline, etwa was Guards, Kernels oder Torch-Inductor-Codegen bedeuten, erleichtern das Verständnis der vorgeschlagenen Maßnahmen, sind aber keine harte Voraussetzung, weil die Skill die Begriffe im Kontext erklärt.

Einrichtung Schritt für Schritt

Zunächst wird die Skill-Datei in das Skill-Verzeichnis des jeweiligen Projekts oder Nutzerprofils gelegt, wonach Claude Code sie automatisch erkennt, sobald eine passende Anfrage gestellt wird. Der erste inhaltliche Schritt der Skill selbst besteht darin, die Fehlermeldung zu prüfen und anhand von Mustern zu routen: Erkennt die Skill eine Meldung der Form Assertion index out of bounds, verweist sie auf einen spezialisierten Unterleitfaden für Triton-Indexfehler. Bei allen anderen Fehlerarten folgt die Skill einer festen Reihenfolge, die laut Anbieter immer zuerst prüft, ob das Kompilierungsgerät mit dem Ladegerät übereinstimmt, ob die Eingabegeräte zum Modellgerät passen und ob die Eingabeformen mit den beim Kompilieren verwendeten Formen übereinstimmen. Diese drei Punkte sind deshalb so zentral, weil AOTInductor laut Dokumentation keine geräteübergreifende Ladefunktion unterstützt: Ein auf der GPU kompiliertes Modell lässt sich nicht auf der CPU laden und umgekehrt, während nur der Geräteindex innerhalb desselben Gerätetyps variieren darf. Wer diese Grundregel kennt, kann die meisten Segfaults und Laufzeitfehler bereits im ersten Debugging-Schritt eingrenzen, bevor überhaupt tiefer in Kernel-Logs geschaut werden muss.

Sicherheit und Best Practices

Da es sich um eine reine Debugging-Hilfe handelt, die keine Produktionsdaten verändert, sind die Sicherheitsrisiken überschaubar, dennoch lohnt ein bewusster Umgang mit den vorgeschlagenen Umgebungsvariablen. Flags wie AOTI_RUNTIME_CHECK_INPUTS oder TORCHINDUCTOR_NAN_ASSERTS aktivieren laut Anbieter zusätzliche Laufzeitprüfungen, die die Ausführung verlangsamen, weshalb sie nur temporär während der Fehlersuche und nicht dauerhaft in Produktionsumgebungen gesetzt werden sollten. Auch CUDA_LAUNCH_BLOCKING erzwingt synchrone statt asynchroner Kernel-Ausführung und sollte nach abgeschlossener Diagnose wieder deaktiviert werden, um keine unnötigen Leistungseinbußen zu verursachen. Wichtig ist außerdem, dass die Skill explizit zwischen einer veralteten und einer aktuellen API unterscheidet: torch._export.aot_compile und aot_load gelten als deprecated, während aoti_compile_and_package und aoti_load_package die empfohlene, aktuelle Schnittstelle darstellen, die Gerätemetadaten automatisch im Paket mitspeichert. Projekte, die noch die alte API verwenden, sollten die Migration mittelfristig einplanen, weil zukünftige PyTorch-Versionen die alten Funktionen absehbar entfernen könnten.

Praxisbeispiel und Grenzen

Ein typisches Szenario: Eine Entwicklerin kompiliert ein Modell auf einer CUDA-GPU, lädt es aber versehentlich in einem CPU-only-Container, was zu einer kryptischen Fehlermeldung über einen nicht registrierten Speicherzeiger führt. Die Skill würde in diesem Fall sofort auf die Geräte-Übereinstimmungsregel verweisen und die Lösung liefern, statt dass stundenlang in Kernel-Traces gesucht werden muss. Bei nichtdeterministischen CUDA-Illegal-Memory-Access-Fehlern schlägt die Skill ein mehrstufiges Vorgehen vor: zunächst Sanity-Checks über Compile-Time-Flags, dann das deterministische Reproduzieren mittels PYTORCH_NO_CUDA_MEMORY_CACHING und CUDA_LAUNCH_BLOCKING, schließlich die genaue Kernel-Identifikation über den sogenannten Intermediate Value Debugger. Die Grenzen der Skill liegen dort, wo Fehler außerhalb des AOTI-Stacks entstehen, etwa in eigenem C++-Code für benutzerdefinierte Operatoren mit dynamischen Formen; hier verweist die Skill lediglich darauf, dass die Meta-Funktion möglicherweise symbolische Ganzzahlen korrekt behandeln muss, liefert aber keine automatisierte Lösung. Wer intensiv mit AOTInductor arbeitet, sollte die Skill daher als strukturierten Ausgangspunkt verstehen, der viele Standardfälle abdeckt, komplexere Custom-Op-Probleme aber weiterhin eigenständige Tiefenanalyse erfordern.