Dışa Aktarıcılar

Hedef çalışma zamanından bağımsız olarak herhangi bir PreTrainedModel nesnesini ONNX, ExecuTorch veya bağımsız bir PyTorch programına dışa aktarın.

exporter = DynamoExporter()  # or OnnxExporter, ExecutorchExporter
config = DynamoConfig(dynamic=True)
exported = exporter.export(model, inputs, config=config)

Dışa aktarıcılar, bir aşağı akış kütüphanesi yerine Transformers içinde yer aldığı için mimari değişiklikler, yeni dikkat kalıpları ve özel önbellek türleri, modelleme koduna eklendikleri anda dışa aktarma sırasında desteklenir.

Dışa aktarıcılar deneyseldir. Bu modüldeki yamaların çoğu, belirli üst akış hatalarının (Torch, ONNX Script, ONNX Runtime, ExecuTorch) etrafından dolaşmak için çalışır ve düzeltme üst akışa eklendiği anda kaldırılacaktır. API kararlılaşana kadar, yamaları test paketinde kullanılan sürümlere bağlı olarak ele alın. Üretim araçlarında bu sürümleri sabitleyin ve üst akış değişiklikleri geldikçe yeni yamaların ortaya çıkmasını, eski yamaların ise kaybolmasını bekleyin.

Dışa Aktarıcı	Program (`.program`)	Kaydedilen	Çalışma zamanı
`DynamoExporter`	`ExportedProgram`	`model.pt2`	Herhangi bir PyTorch çalışma zamanı, AOT derleme
`OnnxExporter`	`onnx_ir.Model`	`model.onnx`	Herhangi bir ONNX çalışma zamanı (ORT, TensorRT, OpenVINO)
`ExecutorchExporter`	`ExecutorchProgramManager`	`model.pte`	Mobil ve kenar cihazları (ExecuTorch)
`OpenVINOExporter`	`openvino.Model`	`openvino_model.xml` + `.bin`	OpenVINO çalışma zamanı (Intel CPU/GPU/NPU)

Her dışa aktarma, components haritasının adları ExportedComponent nesnelerine eşlediği bir ExportedModel döndürür. Bir bileşen, arka planın programını (.program) ve izleme sırasında kaydedilen ExportMetadata bilgisini (girdi ve çıktı adları, hassasiyet, izlenen girdi şekilleri, dışa aktarma yapılandırması) içerir. ~HfExporter.export tek bir "model" bileşeni oluşturur, bu nedenle programı doğrudan exported.program şeklindedir. ~ExportedModel.save_pretrained her bileşen için bir dosya, her bileşenin dosyasını ve metadata'sını içeren bir export.json manifesti ve model yapılandırmasını yazar.

~ExportedModel.from_pretrained, from_pretrained() ile aynı indirme kwargs’larını kullanarak, yerel bir dizinden veya Hub deposundan geri yükler. Model ağırlıklarının yanında tutulan bir dışa aktarma için subfolder parametresini iletin; yalnızca dışa aktarmaya ait dosyalar indirilir. Dynamo, ONNX ve OpenVINO programları, dışa aktarmanın döndürdüğü türde yüklenir. Yüklenen bir ONNX grafiği, ağırlıklarını okunana kadar model.onnx.data içinde tutar. ExecutorchProgramManager dosyadan yeniden oluşturulamadığı için, ExecuTorch .pte dosyası bir executorch.runtime.Program olarak yüklenir.

from transformers.exporters import ExportedModel

exported.program  # the backend's program
exported.save_pretrained("exported-model")  # model.<suffix>, export.json, config.json
loaded = ExportedModel.from_pretrained("exported-model")

Bir dizin, export.json ve config.json dosyalarının sabit isimlere sahip olması nedeniyle tek bir dışa aktarmayı barındırır. Farklı formatlardaki dışa aktarmaları kendi alt dizinlerinde (onnx/, openvino/) tutun ve subfolder="onnx" parametresiyle yükleyin.

AutoHfExporter bir yapılandırmadan doğru dışa aktarıcıyı seçer ve AutoExportConfig bir sözlükten doğru yapılandırma sınıfını seçer. İkisi de Transformers'taki aynı otomatik-sınıf desenini izler; bu, arka uç çağrı noktasında sabit kodlanmak yerine çalışma zamanında seçildiğinde faydalıdır.

from transformers.exporters import AutoExportConfig, AutoHfExporter

export_config_dict = {"export_format": "onnx", "dynamic": True}
config = AutoExportConfig.from_dict(export_config_dict)
exporter = AutoHfExporter.from_config(config)

exported = exporter.export(model, inputs, config=config)

Kurulum

Dışa aktarmayı planladığınız arka uç için bağımlılıkları yükleyin.

Aşağıdaki sürümler, dışa aktarıcı test takımının sabitlendiği sürümlerdir. Daha yeni veya eski sürümler genellikle çalışır, ancak dışa aktarıcı yamaları belirli bir API yüzeyine yönelik olduğundan, üretim araçları için bu sürümleri sabitleyin ve HfExporter'ın sapma algıladığında bir uyarı kaydettiğini bekleyin.

Dynamo

ONNX

ExecuTorch XNNPACK

ExecuTorch MLX

OpenVINO

Bir model dışa aktarın

Tüm dışa aktarıcılar aynı arayüzü paylaşır. Bir yapılandırma ile dışa aktarıcı oluşturun ve export() çağrısını yapın.

Dışa aktarıcı sınıfını değiştirerek çalışma zamanları arasında geçiş yapın.

Dynamo

ONNX

ExecuTorch

OpenVINO

Dışa aktarma çalıştırın

ExportedModel, backend’inin çalışma zamanında (torch.export modülü, ONNX Runtime, OpenVINO veya ExecuTorch çalışma zamanı) bir dışa aktarma çalıştırır ve geldiği model gibi çağrılır: aynı kwargs, aynı ModelOutput sınıfı. Hesaplama backend’de çalışır ve bu, genellikle eager PyTorch’ten daha hızlıdır (CPU’da OpenVINO, CUDA’da ONNX Runtime) ve kuantize dışa aktarmalar da aynı şekilde çalışır. Dışa aktarma sırasında izlenmeyen girdiler düşürülür, bu nedenle bir işleyicinin (processor) tüm çıktısı geçirilebilir.

Yeni bir dışa aktarma, ilk çağrıda (backend'in varsayılan cihazında veya ~ExportedModel.to'nun seçtiği cihazda) çalıştırılır ve ExportedModel.from_pretrained, kaydedilmiş bir dışa aktarmayı yerel bir dizinden veya Hub'dan yükleyerek çalışmaya hazır hale getirir.

from transformers.exporters import ExportedModel

outputs = exported(**inputs)

exported.save_pretrained("qwen3-onnx")
model = ExportedModel.from_pretrained("qwen3-onnx", device="cuda")
logits = model(**inputs).logits

device, çalışacağı yeri seçer: bir ONNX Runtime sağlayıcısı ("cpu", "cuda"), bir OpenVINO cihazı ("cpu", Intel GPU için "xpu" veya varsayılan olarak AUTO) veya bir torch.export modülünün taşındığı yer. Bir ExecuTorch programı, indirildiği yerde çalışır. Birden fazla bileşene sahip dışa aktarmalar (üretim) henüz çalışmıyor.

Dinamik şekiller

dynamic=True parametresinin geçirilmesi, dışa aktarılan grafiğin çalışma zamanında yeniden izleme yapmadan herhangi bir boyutta girdileri kabul etmesi için her tensör boyutunu dinamik olarak işaretler.

Hangi boyutların dinamik olacağına dair ince taneli kontrol için, bunun yerine doğrudan torch.export.export'a iletilen açık dynamic_shapes parametresini geçirin.

Dynamo

ONNX

ExecuTorch

OpenVINO

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from transformers.exporters import DynamoExporter, DynamoConfig

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")
inputs = tokenizer(["Hello, world!", "Hi"], padding=True, return_tensors="pt")

batch = torch.export.Dim("batch", min=1, max=32)
seq = torch.export.Dim("seq", min=1, max=2048)

exporter = DynamoExporter()
config = DynamoConfig(
    dynamic_shapes={"input_ids": {0: batch, 1: seq}, "attention_mask": {0: batch, 1: seq}},
    # Emit data-dependent shape guards as runtime asserts instead of failing the export when a
    # guard wouldn't hold across the explicit symbolic range. Most LLMs need this under fine-grained
    # ``Dim(min=, max=)`` bounds. Not needed with ``dynamic=True`` / ``Dim.AUTO``, where torch.export
    # infers shape relations instead of verifying them against user-stated bounds.
    prefer_deferred_runtime_asserts_over_guards=True,
)
exported = exporter.export(model, inputs, config=config)

Üretken modeller

Otonom regresif üretimde, modelin forward fonksiyonu, prefill adımı (tam istem, KV önbelleği yok) ile decode adımı (tek token, dolu KV önbelleği) arasında farklı şekillere sahiptir. Dışa aktarıcılar, her iki aşamayı ayırıp her birini dışa aktaran ~HfExporter.export_for_generation yöntemini sunar.

Çok modlu üretken modellerde, prefill ayrıca bir görüntü veya ses kodlayıcıya, dil modeline ve lm_head bileşenine ayrılır. Kodlayıcı ve dil modelinin keşfi, get_encoder() (modality="image" veya "audio") ve get_decoder() erişimcilerini kullandığından, bu bileşenleri kullanan herhangi bir yeni mimari hazır olarak çalışır.

Bir projeksiyon bileşeni yalnızca model, bir öznitelik adı altında (multi_modal_projector, connector, embed_vision, embed_audio) bir projeksiyon açığa çıkardığında görünür. Aşağıdaki Qwen2-VL, projeksiyonunu görme kulesine (vision tower) dahil eder, bu nedenle bileşen sözlüğünde ayrı bir multi_modal_projector anahtarı yoktur. Yeni mimariler, listeyi büyütmek yerine projeksiyon özniteliklerini bu adlardan biriyle hizalamalıdır.

Dynamo

ONNX

ExecuTorch

OpenVINO

from transformers import AutoModelForImageTextToText, AutoProcessor
from transformers.exporters import DynamoExporter, DynamoConfig

model = AutoModelForImageTextToText.from_pretrained("Qwen/Qwen2-VL-2B-Instruct")
processor = AutoProcessor.from_pretrained("Qwen/Qwen2-VL-2B-Instruct")
messages = [{"role": "user", "content": [{"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"}, {"type": "text", "text": "Describe this image."}]}]
text = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
inputs = processor(text=text, images=messages[0]["content"][0]["url"], return_tensors="pt").to(model.device)

exporter = DynamoExporter()
config = DynamoConfig(dynamic=True)
exported = exporter.export_for_generation(model, inputs, config=config)
# exported: ExportedModel with "image_encoder", "language_model", "lm_head" and "decode",
# each an ExportedComponent whose `.program` is an ExportedProgram

Dışa aktarılan bileşenler bağımsız grafiklerdir, çalışmaya hazır bir çıkarım hattı değildir. Çağıran taraf, her kodlayıcıyı çalıştırmaktan, gömme projeksiyonlarını uygulamaktan ve üretim döngüsünü koordine etmekten sorumludur.

export_for_generation nasıl çalışır

decompose_for_generation() model.generate(**inputs, max_new_tokens=2) komutunu bir kez çalıştırır ve gerçek prefill ile decode kwargs'larını yakalamak için model.forward fonksiyonuna hook ekler (model çok modluysa, her encoder/projector/language model alt modülüne eklenen hook'lar aracılığıyla alt modül bazlı kwargs'ları da yakalar). Bu sayede, model bazlı yapıştırıcı kodlara (glue code) gerek kalmadan, yalnızca decoder'lı, SSM, encoder-decoder ve çok modlu modeller dahil olmak üzere herhangi bir mimari için çalışır. export_for_generation bunun üzerine kurulu tek satırlık bir işlemdir.

Capture, modeli inputs üzerinde aceleci (eager) olarak çalıştırır; bu nedenle kısa bir istem, tek bir küçük görsel veya birkaç ses çerçevesi gibi küçük ama temsilci değerler geçirin. Dışa aktarılan program bu boyutlara bağlı değildir (dinamik şekiller yine de akar), ancak daha küçük capture girdileri decompose_for_generation işlemini daha ucuz hale getirir ve sembolik şekil çıkarımını yönetilebilir tutar.

decompose_for_generation fonksiyonunu doğrudan çağırarak, ayrıştırma ve dışa aktarma işlemleri arasında müdahale edebilirsiniz; örneğin doğrulama için bir eager forward çalıştırabilir, bir alt modülün girdilerini değiştirebilir veya bir aşamayı atlayabilirsiniz.

from transformers.exporters.utils import decompose_for_generation

components = decompose_for_generation(model, inputs)
# {"image_encoder": (submodel, fwd_kwargs), "language_model": (...), ..., "decode": (...)}

exported = {}
for name, (submodel, subinputs) in components.items():
    eager_outputs = submodel(**subinputs)  # sanity-check the eager forward before exporting
    exported[name] = exporter.export(submodel, subinputs, config=config)

Çoklu jeton çözme

Varsayılan olarak decode bileşeni tek jeton adımdır — KV önbelleğine karşı bir sorgu jetonu — bu nedenle torch.export, sorgu dizisi eksenini 1'e özelleştirir. Bunun yerine decode bileşenini çoklu jeton olarak yakalamak için multi_token_decode=True parametresini iletin: decompose_for_generation() fonksiyonu, iki ardışık decode adımını (yakalama max_new_tokens=3 ile yapılır) tek bir ileri geçişte birleştirir, böylece bu eksen sembolik olarak kalır. Tek bir grafik, her sorgu uzunluğunu karşılar — tek jeton (sıradan çözümleme), birden fazla jetonun aynı anda işlenmesi (geçmişten devam, örneğin spekülatif jetonların bir bölümünün kabulü) ve önbellek boşken düz bir ön işleme (prefill).

Dynamo

ONNX

ExecuTorch

Sorgu ekseni yalnızca dinamik şekilli bir dışa aktarmada (dynamic=True) sembolik kalır; statik bir dışa aktarma, bu ekseni yakalanan uzunlukta dondurarak sabit çoklu-jetonlu bir grafik oluşturur. Bu, aşağıdaki statik KV önbelleğiyle birleşir — birleştirilmiş çözümleme, her adımın jetonlarını sabit boyutlu önbelleğe yerinde yazar ve önbellek, jetonların nereye yerleştirileceğini içsel olarak yönetir.

Statik KV önbelleği

Bu bölümdeki ExecuTorch örnekleri, kopyasız güncellemeler ve çözümleme döngüsü dahil olmak üzere, yalnızca XNNPACK içindir. MLX dışa aktarıcısı StaticCache öğesini reddeder; MLX ile DynamicCache kullanın.

generate() varsayılan olarak bir DynamicCache büyütür ve dizi uzadıkça yeniden tahsis eder — bu, dışa aktarılmış bir grafik için hareketli bir hedeftir. statik bir önbellek, bir kez tahsis edilen ve her adımda geçerli konuma yerinde yazılan sabit boyutlu bir tampondur. çoklu jeton çözme ile birleştirildiğinde, üretimi tek bir dışa aktarılmış grafiğe indirger: decode grafiği, sabit boyutlu bir önbellek ve değişken sayıda sorgu jetonu alır, böylece tek bir grafik hem istemi (boş önbellek → prefill) hem de üretilen her jetonu (dolu önbellek → decode) karşılar. GenerationConfig içinde cache_implementation="static" (ve bir max_cache_len) ile multi_token_decode=True parametresini ileterek dışa aktarın:

Dynamo

ONNX

ExecuTorch XNNPACK

decode grafiği artık iki sembolik eksene sahip — sorgu uzunluğu (kaç token beslediğiniz) ve önbellek uzunluğu (max_cache_len, yükleme sırasında yeniden boyutlandırılabilir). dynamic=True bu eksenleri (ve diğer tüm eksenleri) Dim.AUTO olarak işaretler, böylece dışa aktarılan grafik, yükleme sırasında herhangi bir istem uzunluğunu ve önbellek boyutunu kabul eder.

Sıfır kopyalı yerinde güncellemeler

Statik önbellek dışarıdan geçirilir ve yerinde değiştirilir, böylece bir tampon, host kopyaları olmadan decode adımları arasında durumu taşır — koşullu çalışma zamanı, kendi arena’sı üzerinden kopyalama yapmak yerine çağıranın tamponlarını bağladığı sürece. Bunun gerektirdiği, geriye kalan tek backend’ye özgü kısımdır:

Dynamo — dışa aktarılan program, önbellek yazımını USER_INPUT_MUTATION olarak modellediğinden, exported.runners["decode"](...) çağrısı, doğrudan ilettiğiniz önbellek tensörlerini günceller. Her adımda aynı tensörleri yeniden kullanın; yapılandırılacak bir şey yoktur.
ONNX Runtime — decode grafiği, önbelleği eşleşen input.<name> / output.<name> çiftleri olarak açığa çıkar. ORT’nin CudaSession.set_buffer_sharing (onnxruntime.transformers.io_binding_helper) yöntemi, her çifti tek bir cihaz tamponuna bağlar; böylece önbellek, host tarafına gidip gelmeden döngü boyunca yerinde okunur ve güncellenir.
ExecuTorch (XNNPACK) — ExecutorchConfig üzerinde bellek planlama tahsislerini kapatın, böylece yerinde yazma işlemi çağıranın kendi tensörüne yazılsın (her bayrağın ne yaptığını görmek için referansa bakın):
```
config = ExecutorchConfig(
    backend="xnnpack",
    dynamic=True,
    alloc_graph_input=False,
    alloc_graph_output=False,
    alloc_mutable_buffers=False,
)
```
Sıfır kopyalı yerinde yazma, çağrıcının çalışma zamanında Method::set_output_data_ptr aracılığıyla çıktı tamponlarını bağlamasını da gerektirir — Python çalışma zamanında yüzeye çıkmaz (executorch.runtime.Method yalnızca execute/set_inputs/get_outputs sunar). Yukarıdaki bayraklar bunu kurar, ancak yerinde yazma sadece C++ için bir yoldur (aşağıdaki ExecuTorch decode döngüsü örneğine bakın). Python'dan, güncellenmiş önbelleği her adımda yöntem çıktılarını okuyarak geri alın.

Decode-loop inference examples

Döngü her arka uçta aynı şekildedir — baştan sona aynı grafiktir. Boş, sabit boyutlu bir önbellekten başlayın, tüm istemi bir kez besleyin (boş önbellek → ön doldurma), ardından her adımda bir token ekleyin (dolu önbellek → çözümleme). Her çağrı input_ids, nedensel bir attention_mask ve position_ids (her adımda yeni token sayısınca ilerletilir) ile önbelleği iletir ve her sorgu konumu için logitler döner. Her tokenın önbellekteki yeri, statik önbellek tarafından içsel olarak izlenir, bu nedenle çağrı boyunca ek bir şey iletmenize gerek yoktur. Önbelleğin nasıl kurulduğu çalışma zamanına göre değişir (Dynamo için StaticCache nesnesi, ONNX Runtime için ham cihaz tamponları, ExecuTorch için C++ tarafında çağıran dizileri), bu yüzden her sekme aşağıda kendi kurulumunu oluşturur. Dynamo ve ONNX Runtime sekmeleri önbelleği yerinde günceller; ExecuTorch’ün yerinde güncelleme yolu C++’tır (yukarıda belirtildiği gibi Python çalışma zamanı bunu yapamaz).

Dynamo

ONNX Runtime

ExecuTorch XNNPACK

torch.export, statik önbellek yazımını USER_INPUT_MUTATION olarak kaydeder; bu nedenle decode çalıştırıcısı, doğrudan ilettiğiniz StaticCache önbelleğini günceller — tek bir önbellek, bağlanacak ya da geri taşınacak hiçbir şey olmadan tüm döngü boyunca durumu taşır. Önbelleğin önceden başlatılması gerekir (torch.export, ayrılan K/V değerlerini girdi tanımına gömdüğü için tembel boş bir önbellek eşleşmez) — ancak kaydedilen program kendi example_inputs değerlerini taşır; bu yüzden o zaten başlatılmış StaticCache şablonunu, boş olarak sıfırlanmış haliyle yeniden kullanın:

import copy
import torch
from transformers.exporters import ExportedModel

exported = ExportedModel.from_pretrained("qwen3-static", device="cuda")
decode = exported.runners["decode"]

# the program carries an initialized StaticCache template — reuse it (reset to empty)
_, example_kwargs = exported.components["decode"].program.example_inputs
past_key_values = copy.deepcopy(example_kwargs["past_key_values"])
past_key_values.reset()

def causal_mask(positions, cache_len):   # [1, 1, len(positions), cache_len]
    return (torch.arange(cache_len, device="cuda")[None, :] <= positions[:, None])[None, None]

# prefill: the whole prompt in one call
positions = torch.arange(prompt_len, device="cuda")
logits = decode(input_ids=prompt_ids, attention_mask=causal_mask(positions, max_cache_len),
                position_ids=positions[None], past_key_values=past_key_values).logits
next_token = logits[:, -1:].argmax(-1)

# decode: query=1 buffers reused in place
input_ids = torch.empty((1, 1), dtype=torch.long, device="cuda")
position_ids = torch.empty((1, 1), dtype=torch.long, device="cuda")
attention_mask = torch.empty((1, 1, 1, max_cache_len), dtype=torch.bool, device="cuda")
slots = torch.arange(max_cache_len, device="cuda")
for position in range(prompt_len, max_cache_len):
    input_ids.copy_(next_token)
    position_ids.fill_(position)
    attention_mask[0, 0, 0].copy_(slots <= position)
    logits = decode(input_ids=input_ids, attention_mask=attention_mask,
                    position_ids=position_ids, past_key_values=past_key_values).logits
    next_token = logits[:, -1:].argmax(-1)

ONNX Runtime grafiği olduğu gibi çalıştırır; yerinde önbellek güncellemesi, ORT io-binding üzerine ince bir sarmalayıcı olan ORT’nin CudaSession (onnxruntime.transformers.io_binding_helper) ile yapılır. set_buffer_sharing, bir önbellek input.<name> ve ona karşılık gelen output.<name> öğesini tek bir cihaz tamponuna bağlar; böylece değiştirilen K/V/sayaçlar doğrudan girdiye geri yazılır. allocate_buffers, kalan (paylaşılmayan) çıktıları — burada yalnızca logits — tahsis eder; infer(feed_dict) ise CUDA tensörlerinizi işaretçi üzerinden bağlar ve çalıştırır. Önbellek tamponları, grafiğin kendi girdi meta verisinden (get_inputs() şekli ve tipi) doğrudan gelir, bu nedenle model yapılandırmasına gerek yoktur — tek sembolik eksen (önbellek uzunluğu) max_cache_len olur:

import torch
import onnxruntime as ort
from onnxruntime.transformers.io_binding_helper import CudaSession, TypeHelper

def causal_mask(positions, cache_len):
    return (torch.arange(cache_len, device="cuda")[None, :] <= positions[:, None])[None, None]

session = ort.InferenceSession("decode.onnx", providers=["CUDAExecutionProvider"])
cuda = CudaSession(session, torch.device("cuda"))

# fresh device cache buffers built from each cache input's own shape/dtype; share each
# input.<name>/output.<name> pair on one buffer so the update lands in place
cache = {}
for i in session.get_inputs():
    if not i.name.startswith("input."):
        continue
    name = i.name[len("input.") :]
    dims = [max_cache_len if isinstance(d, str) and not d.isdigit() else int(d) for d in i.shape]
    cache[name] = torch.zeros(dims, dtype=TypeHelper.ort_type_to_torch_type(i.type), device="cuda")
    cuda.set_buffer_sharing(f"input.{name}", f"output.{name}")
cache_feed = {f"input.{name}": buf for name, buf in cache.items()}

vocab_size = next(o.shape[-1] for o in session.get_outputs() if o.name.endswith("logits"))

# prefill: the whole prompt in one call
positions = torch.arange(prompt_len, device="cuda")
cuda.allocate_buffers({"logits": (1, prompt_len, vocab_size)})
out = cuda.infer({"input_ids": prompt_ids, "attention_mask": causal_mask(positions, max_cache_len),
                  "position_ids": positions[None], **cache_feed})
next_token = out["logits"][:, -1:].argmax(-1)

# decode: query=1 buffers reused in place
cuda.allocate_buffers({"logits": (1, 1, vocab_size)})
input_ids = torch.empty((1, 1), dtype=torch.long, device="cuda")
position_ids = torch.empty((1, 1), dtype=torch.long, device="cuda")
attention_mask = torch.empty((1, 1, 1, max_cache_len), dtype=torch.bool, device="cuda")
slots = torch.arange(max_cache_len, device="cuda")
for position in range(prompt_len, max_cache_len):
    input_ids.copy_(next_token)
    position_ids.fill_(position)
    attention_mask[0, 0, 0].copy_(slots <= position)
    out = cuda.infer({"input_ids": input_ids, "attention_mask": attention_mask,
                      "position_ids": position_ids, **cache_feed})
    next_token = out["logits"][:, -1:].argmax(-1)

ExecuTorch’un cihaz içi çalışma zamanı C++’tır ve yerinde önbellek güncellemesi Method::set_output_data_ptr’ye dayanır — Python çalışma zamanında yüzeye çıkmaz (executorch.runtime.Method yalnızca execute/set_inputs/get_outputs’ü açığa çıkarır), bu nedenle kopyasız çözümleme yalnızca C++ yoluyla yapılır. Değiştirilen her önbellek çıkışını eşleşen önbellek girdi tamponuna bağlayın; yeni K/V/sayaçlar kopyalama yapılmadan çağırıcının StaticCache tamponlarına yerleşir. Diğer sekmelerde olduğu gibi biçimler ve boyutlar artefaktın kendisinden gelir — burada programın method_meta’sı (input_tensor_meta/output_tensor_meta → TensorInfo::nbytes()); C++ tarafında sorgulanacak bir Python çalışma zamanı yoktur:

#include <executorch/extension/data_loader/file_data_loader.h>
#include <executorch/extension/tensor/tensor_ptr.h>
#include <executorch/runtime/executor/method.h>
#include <executorch/runtime/executor/program.h>

using namespace executorch::runtime;
using executorch::extension::FileDataLoader;
using executorch::extension::make_tensor_ptr;

// load the exported decode and its `forward` method (Result error-checks elided for brevity)
auto loader = FileDataLoader::from("decode.pte");
auto program = Program::load(&loader.get());

// method-execution memory: a fixed arena for bookkeeping + one buffer per the method's memory plan
std::array<uint8_t, 4 * 1024 * 1024> arena;
MemoryAllocator method_allocator(arena.size(), arena.data());
auto meta = program->method_meta("forward");
std::vector<std::vector<uint8_t>> planned(meta->num_memory_planned_buffers());
std::vector<Span<uint8_t>> planned_spans;
for (size_t i = 0; i < planned.size(); ++i) {
    planned[i].resize(meta->memory_planned_buffer_size(i).get());
    planned_spans.push_back({planned[i].data(), planned[i].size()});
}
HierarchicalAllocator planned_allocator({planned_spans.data(), planned_spans.size()});
MemoryManager memory_manager(&method_allocator, &planned_allocator);
auto decode = std::move(program->load_method("forward", &memory_manager).get());

// shapes and sizes come from method_meta — no external config. Inputs are [ids, mask, position_ids,
// cache×N]; outputs are [returned cache×N, logits, mutated cache×N].
const size_t num_cache_tensors = meta->num_inputs() - 3;
const size_t logits_out_idx = num_cache_tensors;
std::vector<size_t> cache_nbytes(num_cache_tensors), cache_out_idx(num_cache_tensors);
for (size_t i = 0; i < num_cache_tensors; ++i) {
    cache_nbytes[i] = meta->input_tensor_meta(3 + i)->nbytes();
    cache_out_idx[i] = num_cache_tensors + 1 + i;   // mutated cache = the last N outputs
}
const size_t logits_nbytes = meta->output_tensor_meta(logits_out_idx)->nbytes();

// one set of StaticCache buffers (K/V + per-layer counters) is reused across steps, bound in place each call
auto forward = [&](const TensorPtr& input_ids, const TensorPtr& mask, const TensorPtr& position_ids) {
    decode.set_input(EValue(*input_ids), 0);
    decode.set_input(EValue(*mask), 1);
    decode.set_input(EValue(*position_ids), 2);
    for (int i = 0; i < num_cache_tensors; ++i)
        decode.set_input(EValue(*cache_tensor[i]), 3 + i);
    // bind each mutated-cache output onto that same input tensor's data → the write lands in place, zero copies
    for (int i = 0; i < num_cache_tensors; ++i)
        decode.set_output_data_ptr(cache_tensor[i]->mutable_data_ptr(), cache_nbytes[i], cache_out_idx[i]);
    decode.set_output_data_ptr(logits_data, logits_nbytes, logits_out_idx);
    decode.execute();                 // cache updated in place; logits written to logits_data
    return argmax_last(logits_data);  // greedy pick
};

// prefill the whole prompt, then decode one token per step — the cache carries in place across all calls
int64_t next_token = forward(prompt_ids, prompt_mask, prompt_positions);
for (int64_t position = prompt_len; position < max_cache_len; ++position) {
    next_token = forward(make_tensor_ptr({1, 1}, &next_token, ScalarType::Long),
                         causal_mask(position),  // [1, 1, 1, max_cache_len] bool
                         make_tensor_ptr({1, 1}, &position, ScalarType::Long));
}

ONNX Runtime füzyonları

ONNX Runtime’ın füzyonlu dönüştürücü işlemlerine dönüştürülmeden önce kaydedilmeden önce ort_fusions değerini ayarlayarak bir ONNX dışa aktarmayı yeniden yazın. ONNX Runtime, füzyonlu grafiği düz grafiğe kıyasla çok daha hızlı çalıştırır. Füzyonlar RMS ve katman normlarını, dikkat mekanizmasını (anahtar-değer önbelleği varsa MultiHeadAttention veya GroupQueryAttention), döner gömme işlemlerini, GELU’yu ve bir girdiyi paylaşan projeksiyonları kapsar. Her füzyon, yerini aldığı işlemlerle aynı sonucu verir.

ort_fusions parametresini, grafiğin çalışacağı yürütme sağlayıcısına ayarlayın. Her sağlayıcı, desteklediği füzyonlu işlemleri alır.

config = OnnxConfig(ort_fusions="cpu")
config = OnnxConfig(ort_fusions="cuda")
config = OnnxConfig(ort_fusions="webgpu")
config = OnnxConfig(ort_fusions="dml")

	`"cpu"`	`"cuda"`	`"webgpu"`	`"dml"`
Anahtar-değer önbelleği ile dikkat	`GroupQueryAttention`, dönerli dahil	`GroupQueryAttention`, sorgu ve anahtar normlarıyla; ön doldurma (prefill) şimdilik `MultiHeadAttention` kullanmaya devam ediyor (daaha yavaş)	`GroupQueryAttention`, dönerli olarak kendi `RotaryEmbedding`	`MultiHeadAttention`, dönerli (rotary) bileşenini kendi `RotaryEmbedding`
Diğer dikkat	şimdilik düz işlemler (da	`MultiHeadAttention`	`MultiHeadAttention`	`MultiHeadAttention`
Uzmanlar karışımı	unfused	`MoE`	unfused	unfused
CUDA grafikleri	—	statik dışa aktarımlar yeniden oynatılabilir	—	—

"cuda" grafikli bir MoE, ONNX Runtime'ın MoE bileşeni yalnızca CUDA için mevcut olduğu için CPU'da çalışmaz. "webgpu" grafik, onnxruntime-web ile tarayıcıda veya onnxruntime-webgpu ile yerel olarak çalışır. "dml" grafik, onnxruntime-directml ile Windows'ta çalışır.

Füzyonlu işlemler standart ONNX değildir, bu nedenle TensorRT veya OpenVINO gibi diğer ONNX kullanıcıları bunları okuyamaz. Varsayılan değer ort_fusions=None'dir ve bu, grafiği standart tutar. Modeli birden fazla çalışma zamanında kullanmanız gerekiyorsa, her biri için ayrı ayrı dışa aktarın.

Füzyonlar, ONNX Runtime’ın önerdiği üzere, OnnxRuntimeQuantizer grafiği kuantize etmeden önce çalışır. Model dışa aktarılmadan önce kuantize edilirse atlanır ve optimize=True (varsayılan) gerektirir. "cuda" füzyonları onnxruntime 1.28 veya daha yeni bir sürüm gerektirir.

Kantizasyon

Her dışa aktarma yapılandırması, dışa aktarma sırasında modeli torch.export FX grafiğinde (her arka uç için PT2E veya NNCF) ya da dönüştürülmüş ONNX veya OpenVINO modelinde (ONNX Runtime veya NNCF) kuantize eden bir quantizer alır. Kuantizörler, arka uçları, kalibrasyon ve bunlardan birini nasıl ekleyeceğiniz hakkında bilgi için Dışa aktarmaları kuantize etme bölümüne bakın.

Kısıtlamalar ve geçici çözümler

torch.export, torch.onnx.export ve ExecuTorch, belirli PyTorch kalıpları etrafında pürüzlere sahiptir. Dışa aktarıcılar, dışa aktarma akışında iyi tanımlanmış noktalarda uygulanan küçük bir grup geri alınabilir yama ve FX düzeyinde düzeltme ile bu sorunların etrafından dolaşır. Bunların hiçbiri herkese açık export API'sinden görünmez, ancak bilmeniz gereken en yaygın şeyler şunlardır:

FlashAttention ve FlexAttention hiçbir backend üzerinde dışa aktarılamaz. sdpa tercih edilen ayar olup eager de çalışır (daha yavaş). Model başka bir ayar kullanıyorsa, export çağrılmadan önce bunlardan birini modelde ayarlayın.
grouped_mm, DynamoExporter üzerinden sorunsuz izlenir ve OnnxExporter için otomatik olarak çevrilir. XNNPACK veya MLX ile ExecutorchExporter kullanıldığında, dışa aktarıcı dışa aktarma öncesinde MoE uzmanlarını batched_mm olarak değiştirir.
Sliding-window katmanları (Mistral, Gemma 3) tam bir anahtar-değer önbelleğiyle dışa aktarılır; kayan maske hâlâ pencereyi uygular.

Sonraki adımlar

Dışa aktarıcıları genişletme bölümündeki yamalar ve düzeltme kayıt defterleri ile yeni bir mimari veya arka uç için dışa aktarma desteği ekleyin.
Bir dışa aktarmayı kuantize edin veya Dışa aktarmaları kuantize etme bölümünde bir kuantizatör ekleyin.

Update on GitHub