Dışa aktarıcıları genişletme

torch.export modeli bir grafa izler, sonraki aşamalar bu grafi dönüştürür ve son aşama onu hedef çalışma zamanı için düşürür veya yazar. Çoğu model dokunulmadan geçer. Arka uyunun (backend) işleyemediği bir PyTorch deseni olduğunda, dışa aktarıcı (exporter) modeli düzenlemek yerine o aşamada küçük bir geçici çözüm uygular.

Bir çözüm yolu eklemek için bir fonksiyon yazın ve onu bir dekoratör ile kaydedin. Her çözüm yolu, onu temiz bir şekilde ifade edebilen en düşük aşamaya ait olmalıdır.

Yamalar ve düzeltmeler

Bir geçici çözüm, bir yama (patch) veya bir düzeltmedir. İkisi, geri alınabilir olup olmadıklarına göre farklılık gösterir.

Her ikisi de exporters/utils.py içindeki bir kayıt defterinde bulunur ve exportör, kendi backend'i için kayıtlı olan her şeyi doğru aşamada yükler.

Sorun tek bir backend'in lowering hatasıysa bir yama kullanın: eksik bir ONNX çevirisi, ORT doğrulama tuhaflığı veya ölü bir op üreten bir FX decomposition. Workaround exporter'da kalır ve modelleme kodu temiz kalır.

Desen blokları, veriye bağlı döngüler, Cache dışında durumlu önbellekler veya elle yazılmış bölünmüş döngü dikkati gibi birden çok arka uçta dışa aktarıldığında, modeli düzeltin. Modelde bir kez yapılan düzeltme, tüm dışa aktarıcılara yardımcı olur.

Yama ekle

Bir model yönteminin torch.export tarafından izlenemeyecek bir işlem yaptığını varsayalım. NLLB-MoE'nin NllbMoeTop2Router._cast_classifier yöntemi, sınıflandırıcı ağırlıklarını başka bir dtype'a dönüştürür ve bu işlem izlenemezdir. Dışa aktarma süresince bu yöntemi bir no-op ile değiştirin.

Orijinal yöntemi alıp onun yerini alacak olanı döndüren bir fabrika yazın, ardından fabrikayı yöntemin noktalı yoluna karşı kaydedin:

from transformers.exporters.utils import register_patch

@register_patch("dynamo", "transformers.models.nllb_moe.modeling_nllb_moe.NllbMoeTop2Router._cast_classifier")
def _patch_classifier_cast(_original):
    # Replace the untraceable dtype cast with a no-op during export.
    return lambda self, *args, **kwargs: None

Dışa aktarıcı, izleme işleminden önce yöntemi değiştirir ve sonrasında geri yükler, bu nedenle yama yalnızca dışa aktarmayı etkiler. Birkaç varyasyon:

• Farklı çağrı noktaları arasında bir fabrikayı paylaşmak için ek yollar geçin, örneğin @register_patch("dynamo", path_a, path_b).
• torch operatörünü yamalamak için yolunu ona yönlendirin, örneğin @register_patch("onnx", "torch.where"). Fabrika, gerçek operatörü argüman olarak alır, bu nedenle yer değiştirme ona çağrı yapabilir.
• Grafin izleme sonrası yeniden yazılması gerektiğinde yama yerine düzeltme yazın. Mekanizma aynıdır: eşleşen kayıt defterinde dekore edilmiş bir fonksiyon.

Aşama referansı

Her dışa aktarıcının kaynak kodu, aşamalarını # ── Stage N: … ── yorum bloklarıyla etiketler; böylece dosya ile bu referans uyumlu hale gelir. Her bir aşamanın hangi işlemleri ve sınıfları ele aldığını görmek için oraya bakın.

DynamoExporter

Temel dışa aktarıcı, DynamoExporter.export içinde sırasıyla bir yama aşaması ve dört yardımcı çalıştırır (bkz. exporter_dynamo.py).

1. Forward-imzası yaması: model.forward öğesine düz bir argüman imzası verir, böylece torch.export girdileri tek bir **kwargs demetine paketlemez. Bu iç bir bileşendir ve bir genişletme noktası değildir.
2. Model yamaları: izleme sırasında izlenemeyen model yöntemlerini dışa aktarım için güvenli eşdeğerleriyle değiştirir. @register_patch("dynamo", ...) ile genişletin.
3. Pytree kaydı: torch.export'un düzleştirebilmesi ve yeniden oluşturabilmesi için her bir Cache ve ModelOutput'i kaydedin (genellikle otomatik olarak gerçekleşir). Öznitelik gezintisinin ulaşamadığı bir tür için _flatten_to_context / _unflatten_from_context içine bir dal ekleyin.
4. Dinamik şekiller: dynamic=True olduğunda her tensöre ve önbelleğe alınan yaprağa Dim.AUTO atayın. DynamoConfig.dynamic_shapes ile geçersiz kılın.
5. Durum temizliği: torch.export tarafından sahte tensörler olarak bırakılan, bir modelin forward içinde ayarladığı tensör özniteliklerini sıfırlayın. _STATEFUL_CACHE_ATTRS içine öznitelik adını ekleyerek genişletin.

OnnxExporter

OnnxExporter, torch.onnx.export etrafına beş aşama ekler (bkz. exporter_onnx.py). Yamaların tam listesi için dosyada grep yapın:

grep -nE "^def (_patch_|_fix_|_aten_)" src/transformers/exporters/exporter_onnx.py

1. Torch yamaları: ONNX dışa aktarıcısının olduğu gibi çeviremediği torch işlemlerini değiştirir. @register_patch("onnx", ...) ile genişletilir.
2. ONNX yamaları: run_decompositions çalıştırıldıktan sonra düğüm düzeltmelerini yeniden çalıştırın, böylece yeni tanıtılan şekil koruma düğümleri düşürme (lowering) işleminden önce onarılır. Aynı @register_patch("onnx", ...) kayıt defterini kullanır.
3. FX düğümü düzeltmeleri: ONNX dışa aktarıcısının indirgeyemediği grafik düğümlerini, örneğin alias işlemleri, yerinde görünümler ve ölü assert'ler, yeniden yazar. @register_fx_node_fix("onnx") ile genişletin.
4. ONNX çevirileri: varsayılanı eksik veya hatalı olan bir aten op'si için özel bir lowering sağlayın (örneğin aten.index_put veya aten._grouped_mm). _ONNX_TRANSLATION_TABLE'e bir _aten_* fonksiyonu ekleyin.
5. ONNX IR düzeltmeleri: ONNX Runtime hatalarını aşmak için tamamlanan ONNX programını yeniden yazın (örneğin TopK(sorted=True) değerini zorlayın). _IR_FIXES içine bir _fix_ir_* fonksiyonu ekleyin.

ExecutorchExporter

ExecutorchExporter, to_edge_transform_and_lower ve to_executorch etrafında beş aşama ekler; bunlar backend hazırlığıyla başlar (bkz. exporter_executorch.py).

1. Backend hazırlığı: modeli hedef cihaz ve dtype'e taşıyıp bölücü (partitioner) seçin (prepare_for_xnnpack, prepare_for_cuda). _BACKEND_PREPARE içinde prepare_for_<name> kaydını ekleyerek bir backend ekleyin.
2. Torch yamaları: torch işlemlerini, split_copy, chunk ve topk(k>dim) gibi ExecuTorch arka uçlarının kabul edemediği işlemleri değiştirir. @register_patch("executorch", ...) ile genişletin.
3. ExecuTorch yamaları: geçerli dinamik şekilli grafiklerde çöken ExecuTorch iç bileşenlerini değiştirir. Aynı @register_patch("executorch", ...) kayıt defterini kullanır.
4. FX program düzeltmeleri: düzeltmenin tüm program bağlamına ihtiyaç duyduğu durumlarda, örneğin aralık kısıtlarını genişletme veya eksik yer tutucu meta verilerini doldurma gibi, dışa aktarılan programı onarır. @register_fx_program_fix("executorch") ile genişletin.
5. FX düğümü düzeltmeleri: Python sembolik işlemlerini executorch_prim.*’ye eşleme veya pow’ı mul zinciri olarak yeniden yazma gibi bireysel düğümleri yeniden yazın. @register_fx_node_fix("executorch") ile genişletin.

Bilinen üst akış (upstream) geçici çözümleri

Bazı model sınıfları, onnxscript grafik optimizasyoncusunda doğrulanmış hatalara takılıyor (SplitToSequence üzerinde sabit katlama çökmesi, FPN başlatıcılarının düşmesi). ONNX_DISABLE_OPTIMIZE, bu modeller için onnxscript optimizasyonunu devre dışı bırakır. Her kayıt, model adının yanında ilgili upstream sorununu belirtir. Upstream hataların çözülmesiyle listenin küçülmesi beklenir; bu nedenle yeni bir kayıt, keyfi olarak optimizasyonu devre dışı bırakmak yerine belirli bir upstream hataya atıfta bulunmalıdır.

EXPORT_SKIPS, modelin olduğu haliyle temelde dışa aktarılamaz olduğu durumlarda (vektörleştirilemeyen veriye bağımlı kontrol akışı veya forward argümanları olarak ele alınan modüller) bir avuç model sınıfını dışa aktarma taramasından tamamen hariç tutar. Her giriş, model tarafında gerekli değişikliği adlandıran bir gerekçe taşır. Bu listenin de büyümesi değil, küçülmesi beklenir.