aoti-debug
Offizieller PyTorch-Leitfaden zum systematischen Debuggen von AOTInductor-Fehlern.
- Skill Road
- aoti-debug
Kategorien
aoti-debug ist ein offizieller Skill aus dem PyTorch-Quellrepository für die Untersuchung von Fehlern und Abstürzen in AOTInductor, kurz AOTI. Er richtet sich an Entwicklerinnen und Entwickler, die mit Ahead-of-Time kompilierten PyTorch-Modellen arbeiten und bei aot_compile, aot_load, aoti_compile_and_package oder aoti_load_package unerwartete Laufzeitfehler sehen. Laut Anbieter deckt die Anleitung unter anderem Segmentation Faults, Gerätefehler, Probleme beim Laden von Konstanten, falsche Ausgaben, CUDA-Fehler und Triton-Assertions ab. Der Katalogeintrag beschreibt deshalb einen fokussierten Diagnoseleitfaden für Claude Code im PyTorch-Quellbaum und kein eigenständiges Laufzeitpaket, keinen Compiler und keine automatische Reparatur.
Zweck und Einordnung
Die wichtigste erste Prüfung ist laut Anbieter unabhängig vom konkreten Fehlerbild die Übereinstimmung von Kompiliergerät, Ladegerät, Eingabegeräten und Eingabeformen. Ein auf CUDA erzeugtes AOTI-Artefakt darf nicht einfach auf CPU geladen werden, während ein CPU-Artefakt auf CPU bleiben muss. Unterschiedliche Geräteindizes können je nach aktuellem API-Pfad möglich sein, ein Wechsel des Gerätetyps ist jedoch nicht vorgesehen. Ebenso müssen Eingaben die beim Kompilieren erwarteten Formen, Datentypen und Strides einhalten oder durch ausdrücklich modellierte dynamische Formbedingungen abgedeckt sein. Diese Reihenfolge verhindert, dass ein offensichtlicher Vertragsbruch vorschnell als tiefer Compilerfehler analysiert wird.
Diagnose von Laufzeitfehlern
Bei Eingabefehlern empfiehlt die Primärquelle die Laufzeitprüfung über AOTI_RUNTIME_CHECK_INPUTS. Sie kann Abweichungen bei Gerätetyp, Datentyp, Größe und Stride verständlicher melden. Bei CUDA Illegal Memory Access schlägt der Anbieter zunächst zusätzliche Prüfungen wie TORCHINDUCTOR_NAN_ASSERTS vor und empfiehlt anschließend Maßnahmen, die asynchrone oder nichtdeterministische Fehler besser eingrenzen. CUDA_LAUNCH_BLOCKING kann die Kernel-Ausführung synchronisieren. PYTORCH_NO_CUDA_MEMORY_CACHING kann die Wirkung des Caching Allocators aus dem Fehlerbild herausnehmen. Diese Einstellungen gehören in eine kontrollierte Entwicklungsumgebung und müssen mit dem konkreten PyTorch-Stand, dem Backend und der vorhandenen Hardware abgeglichen werden.
Kernel und Zwischenwerte
Für die Lokalisierung eines problematischen Kernels verweist der Skill auf den AOTInductor Intermediate Value Debugger. AOT_INDUCTOR_DEBUG_INTERMEDIATE_VALUE_PRINTER kann erzeugte Kernel schrittweise sichtbar machen. Mit einem passenden Filter lassen sich bestimmte Kernel und ihre Eingaben untersuchen. Zusätzlich können TORCH_LOGS mit Inductor- und Output-Code-Informationen sowie TORCH_SHOW_CPP_STACKTRACES weitere Kontextdaten liefern. Laut Anbieter sind dynamische Formen und eigene C++-Operatoren häufige Ausgangspunkte für Fehler; bei eigenen Operatoren kann insbesondere die Meta-Funktion für SymInt-Anforderungen geprüft werden. Diese Hinweise sind Diagnosewege, keine Garantie, dass eine einzelne Umgebungsvariable die Ursache behebt.
Triton und dynamische Formen
Ein mitgelieferter Unterleitfaden behandelt Triton-Assertions mit dem Muster index out of bounds. Dafür wird das AOTI-Paket beziehungsweise das extrahierte Archiv mit seiner Wrapper-Datei benötigt. Die Untersuchung verbindet die fehlgeschlagene Assertion mit dem generierten Kernel, dem dynamischen Größenparameter, dem zugehörigen Modelleingang und den Quellknoten. Leere Tensoren, fehlende untere Schranken und nicht getestete Randfälle sind typische Hypothesen. Der Leitfaden empfiehlt, leere und minimale Formen bereits beim Export zu berücksichtigen oder den Modellpfad für leere Eingaben ausdrücklich abzusichern. Änderungen müssen anschließend mit relevanten PyTorch-Tests und fachlicher Prüfung bestätigt werden.
API-Stand und Grenzen
Die Primärquelle unterscheidet veraltete APIs wie torch._export.aot_compile und torch._export.aot_load von den aktuellen Funktionen torch._inductor.aoti_compile_and_package und torch._inductor.aoti_load_package. Der neue Paketpfad speichert laut Anbieter Gerätemetadaten und wählt dadurch den passenden Gerätetyp beim Laden; ein Wechsel des Gerätetyps bleibt ausgeschlossen. Der Skill ersetzt keine Release- oder Backend-Prüfung und garantiert weder numerische Gleichheit noch identische Laufzeit. Er setzt einen kontrollierten Arbeitsbaum, reproduzierbare Eingaben, Kenntnisse über PyTorch-Compilation und eine Prüfung generierter Artefakte voraus. Secrets, private Modelle und sensible Eingabedaten gehören nicht in Logs oder Beispielmaterial.
Quelle, Sicherheit und Kompatibilität
Die Primärquelle ist https://github.com/pytorch/pytorch/tree/main/.claude/skills/aoti-debug. Ergänzend beschreibt die offizielle PyTorch-Dokumentation unter https://docs.pytorch.org/docs/main/user_guide/torch_compiler/torch.compiler_aot_inductor.html den AOTInductor-Kontext für exportierte Modelle. PyTorch veröffentlicht seinen Quellbaum unter BSD-3-Clause. Diese Beschreibung wurde am 9. September 2026 geprüft. GitHub-Sterne werden nicht gespeichert, weil das Skill-Modell kein github_stars-Feld besitzt. Die Kompatibilität mit Claude Code folgt aus der Veröffentlichung unter .claude/skills; technische Ergebnisse hängen vom PyTorch-Commit, Betriebssystem, Backend und Gerät ab. Laut Anbieter sollte jede Diagnose mit minimalen, reproduzierbaren Eingaben erfolgen und Änderungen sollten vor dem Übernehmen geprüft werden.
Installationsanleitung
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.
Schritt 1: 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.
Schritt 2: 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.
- Anbieter
- PyTorch
- Lizenz
- BSD-3-Clause
- Zuletzt geprüft
- 09.09.2026
Repository und Dokumentation
Kategorien
Kompatibel mit
Passende Ratgeber
Anleitungen und Hintergrund, die zu diesem Eintrag passen.