Windows ML Çalışma Zamanı API'si kavramları

Important

Windows ML Çalışma Zamanı API'si şu anda deneyseldir ve üretim ortamlarında kullanılmak üzere desteklenmemektedir. Bu API'yi deneyen uygulamalar Microsoft Store'da yayımlanmamalıdır.

Windows ML Çalışma Zamanı API'si, Windows için özel olarak oluşturulmuş yerel bir yapay zeka çıkarım altyapısıdır. Windows ML Çalışma Zamanı API'siyle model yükleme, donanım yerleştirme, tensor sahipliği, işlem hattı oluşturma, derleme ve tanılama üzerinde açık denetime sahip olursunuz.

Windows'ta en iyi model çıkarım performansı için Runtime API'sini kullanmanızı öneririz, ancak uygulamanızın başka platformlarda çalışması gerekiyorsa veya platformlar arası ONNX Runtime kodunuz zaten çalışıyorsa, Windows ML aracılığıyla ONNX Runtime'ı da kullanabilirsiniz.

Nesneler birbirine nasıl uyar

IWinMLRuntime
  |-- loads --> IWinMLModel
  |-- creates -> IWinMLExecutionTarget
  `-- creates -> IWinMLPipelineBuilder
                   |-- adds/connects -> IWinMLStage
                   `-- Build() ------> IWinMLPipeline

IWinMLExecutionTarget -- creates --> IWinMLTensor
IWinMLStage ----------- binds -----> IWinMLTensor
IWinMLPipeline -------- Run() -----> stage outputs

Her yöntem döndürür HRESULTve her arabirim işaretçisi normal COM başvuru sayımını izler. İsteğe bağlı yetenekler QueryInterface ile bulunur; kullanılamayan bir yetenek E_NOINTERFACE döndürür.

Runtime

IWinMLRuntime ile WinMLCreateRuntime oluşturun. Model artefaktlarını yüklemek, yürütme hedefleri oluşturmak ve işlem hattı oluşturucuları oluşturmak için bunu kullanın.

Modeller ve şemalar

IWinMLModel sabit, opak bir model artefaktıdır. LoadModelFromFile uygulamanızın okuyabileceği herhangi bir mutlak veya göreli dosya yolunu kabul eder; model konumu, uygulamanızın paketleme kararıdır.

Yükleme, yapıtın tanındığını ve yapısal olarak okunabilir olduğunu doğrular. Hedef uyumluluk daha sonra işlem hattı oluşturucusunun Build yöntemi başarılı olduğunda kesinleştirilir.

Bir modelin bildirilen sıralı şemasını IWinMLModelSchema aracılığıyla yansıtır. Bazı ONNX yapıtları da adları isteğe bağlı IWinMLOrtModelSchema üzerinden gösterir, ancak yürütme kimliği konumsal kalır.

Şekiller ve operatörler

Bildirilmiş bir model şeması, UINT64_MAX ile gösterilen serbest boyutlar içerebilir. Bir beton IWinMLTensor her zaman çözülmüş boyutlara sahiptir. ORT destekli işlem hatları, serbest boyut için somut değerlerle bağlanıp çalıştırılabilir.

Sabit veya açıkça sınırlandırılmış şekiller, Build’ın uyumluluğu doğrulamasına, kararlı kaynaklar ayırmasına ve yeniden yürütmenin veya cihazda yerleşik yinelemenin yasal olup olmadığını belirlemesine olanak tanıdığı için optimize edilmiş tasarım odağı olmaya devam eder. Ayrıca yürütme arka uçları arasında en geniş uyumluluğu sağlar. Bu bir iyileştirme ve taşınabilirlik ayrımıdır, bildirilen ONNX şeması serbest boyutlar içeren modellerin toptan reddi değildir.

Standart ONNX operatörleri aynı şekilde arka uç taşınabilirliğini geliştirir. Başarılı bir model yüklemesi, her hedefin her işleci yürütebileceğini garanti etmez; Build uyumluluk denetimini ifade eder.

Arka uç sistemler

Model dosyası arka ucu seçer. Uygulamanız her iki şekilde de aynı Runtime nesnelerini kullanır: model, yürütme hedefi, işlem hattı oluşturucusu, aşamalar, bağlamalar ve Run.

Model dosyası	Backend	Donanım hızlandırma
.onnx, .ort	ONNX Çalışma Zamanı	Windows'un Windows ML EP kataloğu aracılığıyla yüklediği ve güncel tuttuğu yürütme sağlayıcıları (EP'ler)
.gguf	llama.cpp	Uygulamanızla dağıtılan llama.cpp modülleri: paketteki bir CPU modülü ve NVIDIA GPU'ları için isteğe bağlı cuda modülü. CPU ve CUDA, Windows ML'nin bu sürüm için doğruladığı tek llama.cpp arka uçlarıdır.

Arka uçlar, bir aşamanın neleri ifade edebileceği açısından farklılık gösterir:

Yeteneği	ONNX Çalışma Zamanı	llama.cpp
Sahne şekli	Herhangi bir ONNX grafiği; bir işlem hattında birkaç aşama bağlanabilir	GGUF dosyası başına bir kod çözücü aşaması: içindeki belirteç kimlikleri (giriş 0), logitler çıkışta (çıkış 0)
Sekans durumu (KV önbelleği)	Durum tensor çiftlerini IWinMLStatefulStageOptions ile bildirin; bunları Çalışma Zamanı yönetir	Arka uç tarafından yönetilir; bildirilecek hiçbir şey yok
Bağlam uzunluğu	SetSequenceCapacityHint, Build öncesinde veya modelin beyan edilen kapasitesi	Build öncesindeki SetSequenceCapacityHint, llama.cpp bağlam uzunluğunu ayarlar
Sağlayıcı sabitleme ve ORT aşama seçenekleri	Desteklenen (WinMLRuntimeOrt.h)	Desteklenmez; Build, HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) döndürür
Build sonrası yerleştirme raporu	IWinMLOrtStageDiagnostics istenen ve seçilen sağlayıcıları adlandırır	IWinMLStage::GetExecutionTarget CPU veya GPU'yu raporlar

Bir işlem hattı birden fazla arka ucu birlikte kullanabilir. Örneğin, ONNX Runtime üzerinde çalışan bir Whisper aşaması, llama.cpp'deki bir GGUF dil modelini besleyebilir.

Çalıştırma hedefleri

IWinMLExecutionTarget, bir donanım sınıfı ve isteğe bağlı olarak belirli bir bağdaştırıcı isteyen değiştirilemez bir yerleştirme belirtecidir. Her arka uç, Build çalıştığında bunu çözümler:

Hedef aşama	ONNX Çalışma Zamanı	llama.cpp
AddModelStage öğesine geçirilen nullptr	Otomatik yerleştirme, kullanılabilir olduğunda uyumlu bir GPU EP seçer ve CPU'ya geri döner.	Bir CUDA modülü dağıtılmışsa ve model uygunsa CUDA modülüne aktarılır; aksi takdirde CPU üzerinde çalışır.
CreateCpuExecutionTarget	ORT'nin CPU sağlayıcısını temel alarak uyumlu bir CPU EP seçer.	CPU üzerinde çalışır.
CreateExecutionTarget GPU türüyle, CreateExecutionTargetFromAdapterveya CreateExecutionTargetFromD3D12	Bağdaştırıcı kimliğini uyumlu bir GPU EP cihazıyla eşler. Hiçbir sağlayıcı cihaz eşleşmezse, Build başarısız olur.	CUDA modülüne en az kısmi aktarım gereklidir. Build, hiçbir CUDA modülü dağıtılmadığında HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY) ve model sığmadığında HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) döndürür. Modül GPU'yu seçer; bağdaştırıcı kimliği kullanılmaz.
CreateExecutionTarget NPU türünde veya NPU bağdaştırıcısıyla	Uyumlu bir NPU EP cihazına eşlenir.	Desteklenmez; BuildHRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) döndürür.
IWinMLOrtCompatibility::CreateExecutionTarget(provider, kind, hardwareTarget)	Kayıtlı bir EP'i iğneler. hardwareTarget nullptr olarak ayarlandığında, Çalışma Zamanı sağlayıcıyı kendi cihazlarından biriyle eşleştirir; iki GPU'ya sahip bir bilgisayarda bu, sağlayıcının sağlayıcıyı desteklemeyen bir bağdaştırıcıyla eşleştirilmesini önler.	Desteklenmez; Build, HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) döndürür.

IWinMLRuntime::CreateExecutionTarget(kind, preference) cihazları kendiniz listelemenizi gerektirmeden istenen sınıfın bir bağdaştırıcısını seçer ve preference birden fazla bağdaştırıcı olduğunda (örneğin tümleşik ve ayrı bir GPU) bağdaştırıcılara öncelik verir:

ComPtr<IWinMLExecutionTarget> target;
THROW_IF_FAILED(runtime->CreateExecutionTarget(
    WINML_EXECUTION_TARGET_KIND_GPU,
    WINML_EXECUTION_TARGET_PREFERENCE_PERFORMANCE,
    target.GetAddressOf()));

Açık bağdaştırıcı seçimi, ORT aracılığıyla bu donanım kimliğini görünür kılması için uyumlu bir ONNX Çalışma Zamanı sağlayıcısı gerektirir. Hiçbir sağlayıcı cihazı eşleşmiyorsa, Build başka bir bağdaştırıcıyı veya CPU'yi sessizce seçmek yerine başarısız olur.

CreateExecutionTargetFromD3D12 çağıranın cihazını ve isteğe bağlı kuyruğu hedefte tutar, ancak ORT yürütmesi yalnızca EP seçimi için bağdaştırıcı kimliğini kullanır. ORT sağlayıcısı yürütme kaynaklarının sahibidir ve çağıranın komut kuyruğu ORT gönderimi için kullanılmaz.

Bir D3D12 hedefi hâlâ QueryInterface ile IWinMLD3D12ExecutionTarget arasını kullanıma sunar. Aşamalar arasında tek bir açık hedefin yeniden kullanılması aynı bağdaştırıcı yakınlığını ifade eder; ayrı hedefler aktarım sınırlarını açık hale getirir.

GGUF modelini çalıştırın

1. LoadModelFromFile ile dosyayı yükleyin. .gguf uzantısı llama.cpp seçer. Parçalı model için her parçayı bir klasörde tutun ve ilk parçayı yükleyin.
2. CPU, GPU veya nullptr hedef ile bir model aşaması ekleyin. Bağlam uzunluğunu ayarlamak için aşamadan IWinMLStatefulStageOptions sorgulayın ve SetSequenceCapacityHint çağırın.
3. Build'ı arayın. Ardından istemin belirteç kimliklerini giriş 0'a bağlayın, çıkış 0'ı isteyin ve Run çağrısını yapın. Sonraki her çalıştırma bir sonraki belirteci alır; arka uç, çalıştırmalar arasında KV önbelleğini tutar.
4. ResetExecutionState bağımsız bir diziden önce çağırın.

// Create the runtime and an execution target (CPU here; GPU also available).
ComPtr<IWinMLRuntime> runtime;
THROW_IF_FAILED(WinMLCreateRuntime(IID_PPV_ARGS(runtime.GetAddressOf())));
ComPtr<IWinMLExecutionTarget> target;
THROW_IF_FAILED(runtime->CreateCpuExecutionTarget(target.GetAddressOf()));

ComPtr<IWinMLModel> model;
THROW_IF_FAILED(runtime->LoadModelFromFile(
    L"C:\\models\\qwen2.5-0.5b-instruct.gguf", nullptr, model.GetAddressOf()));

ComPtr<IWinMLPipelineBuilder> builder;
THROW_IF_FAILED(runtime->CreatePipelineBuilder(builder.GetAddressOf()));

ComPtr<IWinMLStage> stage;
THROW_IF_FAILED(builder->AddModelStage(
    model.Get(), target.Get(), L"decoder", stage.GetAddressOf()));
THROW_IF_FAILED(stage->RequestOutput(0));

// Set the llama.cpp context length before Build.
ComPtr<IWinMLStatefulStageOptions> stateOptions;
THROW_IF_FAILED(stage->QueryInterface(IID_PPV_ARGS(stateOptions.GetAddressOf())));
THROW_IF_FAILED(stateOptions->SetSequenceCapacityHint(4096));

ComPtr<IWinMLPipeline> pipeline;
THROW_IF_FAILED(builder->Build(pipeline.GetAddressOf()));

// Bind token IDs to input 0 and run one token at a time; the backend keeps
// the KV cache between runs.
THROW_IF_FAILED(stage->BindInput(0, tokenIdsTensor.Get()));
THROW_IF_FAILED(pipeline->Run());

ComPtr<IWinMLTensor> logits;
THROW_IF_FAILED(stage->GetOutput(0, logits.GetAddressOf()));

// Start an independent sequence on the same pipeline.
THROW_IF_FAILED(pipeline->ResetExecutionState());

Tokenizer ve konuşma biçimlendirmesi GGUF dosyasından geldiğinden, bir GGUF modelinin ayrı tokenizer dosyalarına ihtiyacı yoktur. Belirteç döngüsünü atlamak için GGUF ve ONNX modelleriyle çalışan Text Generation API'sini kullanın.

llama.cpp arka ucunu dağıtın

llama.cpp arka ucu uygulamaya özeldir. Bir proje etkinleştirildiğinde, Windows ML NuGet paketi Çalışma Zamanı'nın llama.cpp bağdaştırıcısını, llama.cpp çekirdeğini ve CPU modülünü uygulamanızın yanına kopyalar. GPU hızlandırma, paketle aynı llama.cpp revizyonu için oluşturulmuş ve uygulamanızın yanına yerleştirilmiş isteğe bağlı CUDA modülüne ihtiyaç duyar.

Her iki adımın nasıl yapılacağını görmek için GGUF modeli örnekleri ve llama.cpp örnekleri bölümüne bakın.

İş hatları ve aşamalar

Tek seferlik IWinMLPipelineBuilderile bir işlem hattı oluşturun:

1. Yürütme hedefleriyle model veya işlemci aşamaları ekleyin.
2. aşama portlarını ordinal indekse göre bağlayın.
3. Build öğesini grafiği dondurmak, yerleştirmeyi çözmek ve uyumluluğu doğrulamak için bir kez çağırın.

İki model aşaması için her iki aşamayı da ekleyin, ilk aşamanın çıkış ordinalini ikinci aşamanın giriş ordinaline bağlayın ve bir kez derleyin. Uygulamanız modelleri sağlar ve herhangi bir dış girdiyi bağlar. Modele özgü bir Çalışma Zamanı API'sine gerek yoktur: gömme, kod çözücü, görüntü ön işleme ve diğer uygulama mimarileri aynı aşamayı ve tensor ilkel işleçlerini kullanır.

Her IWinMLStage biri konumsal giriş bağlamalarına sahiptir ve geçerli çıkış tensörlerini kullanıma sunar. Giriş bağlamaları çalıştırmalar arasında kalıcı olur. Uygulamanız çıkış depolama alanı sağladığında, yürütmeden önce BindOutput öğesini çağırın.

İsteğe bağlı aşama özellikleri çözümlenen hedefi, materyalize şemayı, çıktı ikamet politikasını ve sıra durumu denetimini içerir. Her bir özelliği test etmek için kullanın QueryInterface .

Pipeline çalıştırma

IWinMLPipeline::Run hazırlanan ardışık düzeni eşzamanlı olarak yürütür. Çalışma zamanı tarafından yönetilen durumu temizlemek için bağımsız diziler arasında ResetExecutionState öğesini çağırın.

İsteğe bağlı yürütme arabirimleri, oluşturulan grafik ve seçilen arka uç bunları desteklediğinde cihaz zaman çizelgesi gönderimi ve sabit sayıda yinelenen yeniden yürütme sağlar. Temel Run yol ortak temel olarak kalır.

Tensörler ve kilitler

IWinMLTensor, tiplenmiş, çok boyutlu verileri temsil eder. Tensor yerleşiminin hedef yerleştirmeyi takip edebilmesi için yürütme hedefinden sorgulanan bir fabrikadan tensor oluşturun.

Fabrikalar ham baytları, görüntü verilerini, ses verilerini, belirteç kimliklerini ve birleştirilebilir tensör işlemcilerini destekler. İsteğe bağlı tensor arabirimleri mutasyonu, D3D12 arabellek bağlamalarını ve eşitlemeyi sunar.

CPU'da tensor baytlarına erişmeden önce çağırın IWinMLTensor::Lock . Döndürülen IWinMLTensorDataLock, CPU erişim penceresini oluşturur, gerekli eşlemeyi veya eşitlemeyi gerçekleştirir ve GetData tarafından döndürülen işaretçinin ömrünü yönetir.

Derleme ve harici ağırlıklar

Önceden derleme, IWinMLModelCompiler aracılığıyla sunulan bir yürütme hedefinin isteğe bağlı bir özelliğidir. Derlenmiş artefaktlar normal model yükleme yöntemleri aracılığıyla yeniden yüklenir. Uygulamalar IWinMLResourceMapReader aracılığıyla dışsallaştırılmış ağırlıklar sağlayabilir.

Metin işleme yükleri

Metin iş yükleri aynı çalışma zamanı, hedef, işlem hattı, aşama ve tensor temel öğelerini kullanır. Uygulamanız doğrudan model paketi meta verilerine, örneklemeye, durdurma ilkesine ve oluşturulan belirteç birikimine sahip olabilir veya uyumlu bir Runtime işlem hattı üzerinden bu işlemleri koordine etmek için Text Generation API'yi kullanabilir.

IWinMLTokenizer alt düzey kodlama ve kod çözme işlemleri sağlar. Bir IWinMLTokenizerDecoder, tek bir sıra için bağımsız bir artımlı kod çözme imleci tutar. Metin Oluşturma API'si, temel çalışma zamanı nesnelerinin sahipliğini değiştirmeden metin oluşturma oturumları, seçenekler, akış güncelleştirmeleri, iptal, bitiş nedenleri ve tamamlanmış sonuçlar ekler.

ONNX Runtime uyumluluğu

WinMLRuntimeOrt.h içindeki isteğe bağlı arabirimler ONNX kolaylıkları sağlar:

• IWinMLOrtCompatibility zaten kayıtlı bir ONNX Runtime yürütme sağlayıcısını seçer.
• IWinMLOrtModelSchema giriş ve çıkış adlarını yansıtır.
• IWinMLOrtNamedBindings ORT destekli bir stage'i ada göre bağlar.
• IWinMLOrtStageDiagnostics istenen raporlar ve Build sonrasında seçilen sağlayıcılar.

Bu arabirimler, kurulum sırasında adları ve sağlayıcı ilkesini çözümler. Yürütme aynı konumsal işlem hattı bağıtını kullanmaya devam eder.

Bir ONNX modeli aşamasını, IWinMLOrtCompatibility birini otomatik olarak seçmesine izin vermek yerine, önceden kaydettiğiniz bir yürütme sağlayıcısına sabitlemek için çalışma zamanından Build sorgu yapın:

ComPtr<IWinMLOrtCompatibility> ortCompatibility;
THROW_IF_FAILED(runtime->QueryInterface(IID_PPV_ARGS(ortCompatibility.GetAddressOf())));

ComPtr<IWinMLExecutionTarget> target;
THROW_IF_FAILED(ortCompatibility->CreateExecutionTarget(
    L"MyRegisteredProvider",
    WINML_EXECUTION_TARGET_KIND_GPU,
    /* hardwareTarget */ nullptr,
    target.GetAddressOf()));

nullptr için hardwareTarget geçirilmesi, Çalışma Zamanı'nın sağlayıcıyı bu donanım sınıfındaki kendi aygıtlarından biriyle eşleştirmesine olanak tanır; bunun yerine sağlayıcıyı o belirli bağdaştırıcıya sabitlemek için mevcut bir IWinMLExecutionTarget geçirin. Bu hedef, .gguf aşamaları için desteklenmez; Build, HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) döndürür.

Ayrıca bkz.

• Windows ML Çalışma Zamanı API'si için C++ projesi ayarlama
• Windows ML kullanarak kendi dil modelinizle metin oluşturma
• Windows ML kullanarak kendi Whisper modelinizle konuşmayı tanıma
• Windows ML Çalışma Zamanı API'siyle model çalıştırma