tlparse / TORCH_TRACE

Создано: 29 июл. 2025 | Последнее обновление: 04 янв. 2026

tlparse / TORCH_TRACE — это пара инструментов, создающих отчёты о компиляции, похожие на этот.

Сбор трассировок достаточно прост. Чтобы собрать трассировку, запустите модель следующим образом:

TORCH_TRACE="/tmp/tracedir" python foo.py
pip install tlparse
tlparse /tmp/tracedir --latest

Флаг --latest обрабатывает последний журнал в каталоге. Можно также обработать определённый файл журнала с помощью tlparse <log_file>.

По умолчанию результаты сохраняются в папку tl_out. Можно также указать папку для результатов с помощью -o my_folder.

Этот подход работает и при запуске распределённой задачи, создавая трассировку для каждого ранга. В браузере откроется HTML-страница, похожая на приведённую выше. Если вы сообщаете об ошибке в сложной задаче, для которой у вас нет отдельного воспроизведения, вы всё равно можете значительно помочь разработчикам PyTorch, выполнив следующие действия:

1. прикрепите журнал трассировки, созданный в /tmp/tracedir, или
2. прикрепите zip-архив со всеми результатами работы tlparse (например, все файлы из tl_out). Не прикрепляйте только файл index.html: он содержит лишь перечень выходных файлов, а не сами результаты.

Результаты работы tlparse предназначены в первую очередь для разработчиков PyTorch, а формат журнала позволяет легко загружать его на GitHub и делиться им. Однако даже если вы не разрабатываете PyTorch, из него можно извлечь полезную информацию. Советуем начать со встроенной справки в отчёте, где объясняется его содержимое. Вот какую информацию можно получить из tlparse:

• Какой код модели был скомпилирован? Это можно увидеть по дереву стека. Это особенно полезно, если вы не знакомы с компилируемой кодовой базой!
• Сколько имеется разрывов графа / отдельных областей компиляции? (Каждая отдельная компиляция выделена цветным блоком, например [0/0]). Кадры, в которых потенциально произошёл разрыв графа, подсвечены светло-зелёным цветом [2/4]. Большое количество кадров должно насторожить: это может указывать на критические разрывы графа или на то, что ваш код плохо подходит для torch.compile.
• Сколько раз выполнялась повторная компиляция определённого кадра? Если кадр перекомпилировался много раз, это будет выглядеть так: [10/0] [10/1] [10/2]. Частые повторные компиляции должны насторожить и заслуживают изучения, даже если они не являются первопричиной проблемы.
• Возникала ли ошибка компиляции? Кадры, при компиляции которых произошла ошибка, выглядят так: [0/1].
• Какие промежуточные результаты компилятора были созданы для заданного кадра? Например, можно посмотреть на сгенерированный граф FX высокого уровня или сгенерированный код Triton.
• Есть ли важная информация для определённого кадра? Её можно найти в compilation_metrics.

Ниже приведены имена некоторых файлов и их описания. В зависимости от вашей программы некоторые из этих файлов могут отсутствовать.

TORCH_LOGS="<option1>,<option2>,..." python foo.py

import logging
torch._logging.set_logs(graph_breaks=True, dynamic=logging.DEBUG)