koncepty rozhraní API modulu Windows ML Runtime

Important

Rozhraní API modulu Windows ML Runtime je v současné době experimentální a není podporováno pro použití v produkčních prostředích. Aplikace, které toto rozhraní API zkouší, by se neměly publikovat do Microsoft Store.

Rozhraní API pro Windows ML Runtime je nativní místní architektura AI inference vytvořená speciálně pro Windows. S rozhraním API modulu runtime Windows ML máte explicitní kontrolu nad načítáním modelu, umístěním na hardware, vlastnictvím tensoru, sestavením pipeline, kompilací a diagnostikou.

Doporučujeme použít rozhraní API modulu runtime pro nejlepší výkon inference modelu na Windows, ale pokud vaše aplikace potřebuje běžet na jiných platformách nebo pokud už máte funkční kód modulu runtime ONNX pro různé platformy, můžete také použít modul runtime ONNX prostřednictvím Windows ML.

Jak do sebe objekty zapadají

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

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

Každá metoda vrátí HRESULT a každý ukazatel rozhraní se řídí běžným počítáním referencí v modelu COM. Volitelné funkce jsou zjištěny pomocí QueryInterface; nedostupná funkce vrátí E_NOINTERFACE.

Runtime

Vytvořit IWinMLRuntime pomocí WinMLCreateRuntime. Slouží k načtení artefaktů modelu, vytváření cílů spouštění a vytváření nástrojů pro sestavení kanálů.

Modely a schéma

IWinMLModel je neměnný neprůhledný artefakt modelu. LoadModelFromFile přijímá jakoukoli absolutní nebo relativní cestu k souboru, který může vaše aplikace číst; umístění modelu je rozhodnutí o balení vaší aplikace.

Načítání ověřuje, že artefakt je rozpoznán a strukturálně čitelný. Cílová kompatibilita se zafixuje později, až metoda tvůrce kanálu Build úspěšně proběhne.

Reflektujte deklarované pořadové schéma modelu prostřednictvím IWinMLModelSchema. Některé artefakty ONNX také zpřístupňují názvy prostřednictvím volitelné IWinMLOrtModelSchema, ale identita provádění zůstává poziční.

Tvary a operátory

Deklarované schéma modelu může obsahovat volné dimenze reprezentované UINT64_MAX. Konkrétní IWinMLTensor má vždy vyřešené rozměry. Pipeliney založené na ORT můžou přiřadit a spouštět konkrétní hodnoty pro nepevnou dimenzi.

Pevné nebo explicitně omezené tvary zůstávají optimalizovaným centrem návrhu, protože umožňují Build ověřit kompatibilitu, přidělit stabilní prostředky a určit, jestli je opakování nebo iterace rezidentní v zařízení legální. Poskytují také nejširší kompatibilitu napříč spouštěcími backendy. Jedná se o rozlišení z hlediska optimalizace a přenositelnosti, nikoli plošné zamítnutí modelů, jejichž deklarované schéma ONNX obsahuje volné dimenze.

Standardní operátory ONNX také zlepšují přenositelnost back-endu. Úspěšné načtení modelu nezaručuje, že každý cíl může spustit každý operátor; Build slouží ke kontrole kompatibility.

Backends

Soubor modelu určuje backend. Vaše aplikace používá stejné objekty runtime v obou případech: model, cíl spuštění, tvůrce pipeline, fáze, vazby a Run.

Soubor modelu	Backend	Hardwarová akcelerace
.onnx, .ort	ONNX Runtime	Poskytovatelé spouštění (EP), které systém Windows instaluje a udržuje aktuální prostřednictvím katalogu Windows ML EP
.gguf	llama.cpp	llama.cpp moduly nasazené ve vaší aplikaci: modul CPU v balíčku a volitelný modul CUDA pro GPU NVIDIA. CPU a CUDA jsou jedinými back-endy llama.cpp, které Windows ML pro tuto verzi ověřuje.

Back-endy se liší v tom, co může fáze vyjádřit:

Schopnosti	ONNX Runtime	llama.cpp
Tvar scény	Jakýkoli graf ONNX; v jedné pipeline je možné připojit několik fází.	Jedna fáze dekodéru na soubor GGUF: ID tokenů (vstup 0), logity na výstupu (výstup 0)
Stav sekvence (mezipaměť KV)	Deklarujte páry tensoru stavu s IWinMLStatefulStageOptions; modul runtime je spravuje	Spravováno backendem; není co deklarovat
Délka kontextu	SetSequenceCapacityHint před Build nebo deklarovanou kapacitou modelu	SetSequenceCapacityHint před Build nastaví délku kontextu llama.cpp.
Možnosti připnutí poskytovatele a fáze ORT	Podporováno (WinMLRuntimeOrt.h)	Nepodporováno; Build vrátí hodnotu HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)
Sestava o umístění za Build	IWinMLOrtStageDiagnostics uvádí požadované a vybrané poskytovatele	IWinMLStage::GetExecutionTarget hlášení CPU nebo GPU

Jedna pipeline může kombinovat back-endy. Například fáze Whisper v modulu runtime ONNX může předávat vstup jazykovému modelu GGUF na llama.cpp.

Cíle spuštění

IWinMLExecutionTarget je neměnný token umístění, který požaduje hardwarovou třídu a volitelně konkrétní adaptér. Každý back-end ho vyřeší, když se Build spustí:

Cíl etapy	ONNX Runtime	llama.cpp
nullptr předáno AddModelStage	Automatické umístění vybere kompatibilní EP GPU, pokud je k dispozici, se záložním použitím CPU.	Přesměruje zpracování do modulu CUDA, pokud je nasazen a model se do něj vejde; v opačném případě běží na procesoru.
CreateCpuExecutionTarget	Vybere kompatibilní CPU EP, přičemž výchozí hodnotou je CPU provider ORT.	Běží na procesoru.
CreateExecutionTarget s typem GPU, CreateExecutionTargetFromAdapter nebo CreateExecutionTargetFromD3D12	Namapuje identitu adaptéru na kompatibilní zařízení GPU EP. Pokud se žádné zařízení poskytovatele neshoduje, Build selže.	Vyžaduje alespoň částečné přenesení zpracování do modulu CUDA. Build vrátí HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) , když není nasazen žádný modul CUDA a HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY) pokud se model nevejde. Modul zvolí GPU; identita adaptéru se nepoužívá.
CreateExecutionTarget s typem NPU nebo adaptérem NPU	Mapuje se na kompatibilní zařízení NPU EP.	Nepodporováno; Build vrátí HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).
IWinMLOrtCompatibility::CreateExecutionTarget(provider, kind, hardwareTarget)	Připne jedno registrované EP. Když je nullptr nastaveno na hardwareTarget, modul runtime spáruje poskytovatele s jedním ze svých vlastních zařízení; na počítači se dvěma GPU se tím zabrání spárování poskytovatele s adaptérem, který nepodporuje.	Nepodporováno; Build vrací HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

IWinMLRuntime::CreateExecutionTarget(kind, preference) zvolí adaptér požadované třídy, aniž byste museli sami procházet zařízení, a preference seřadí adaptéry v případě, že existuje více než jeden, například integrovaný a diskrétní GPU:

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

Explicitní výběr adaptéru vyžaduje, aby kompatibilní provider modulu runtime ONNX zpřístupnil identitu hardwaru prostřednictvím ORT. Pokud se žádné zařízení provideru neshoduje, Build selže místo tichého výběru jiného adaptéru nebo procesoru.

CreateExecutionTargetFromD3D12 zachovává zařízení volajícího a volitelnou frontu na cílovém zařízení, ale provádění ORT používá pouze identitu adaptéru pro výběr EP. Poskytovatel ORT vlastní své prostředky pro provádění a fronta příkazů volajícího se nepoužívá k odeslání ORT.

Cíl D3D12 stále zveřejňuje IWinMLD3D12ExecutionTarget až QueryInterface. Opakované používání jednoho explicitního cíle napříč fázemi vyjadřuje afinitu ke stejnému adaptéru; odlišné cíle jasně vymezují hranice přenosu.

Spusťte model GGUF

1. Načtěte soubor pomocí LoadModelFromFile. Rozšíření .gguf vybírá llama.cpp. U shardovaného modelu ponechte každý shard v jedné složce a načtěte první shard.
2. Přidejte jednu fázi modelu s využitím procesoru, GPU nebo nullptr cílového zařízení. Pokud chcete nastavit délku kontextu, získejte IWinMLStatefulStageOptions ze stage a zavolejte SetSequenceCapacityHint.
3. Zavolejte Build. Pak přiřaďte ID tokenů výzvy ke vstupu 0, vyžádejte výstup 0 a zavolejte Run. Každé pozdější spuštění převezme další token; back-end udržuje mezipaměť KV mezi spuštěními.
4. Zavolejte ResetExecutionState před nezávislou sekvencí.

// 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());

Tokenizátor a formátování konverzace pocházejí ze souboru GGUF, takže model GGUF nepotřebuje samostatné soubory tokenizátoru. Pokud chcete smyčku tokenu přeskočit, použijte rozhraní API pro generování textu, které funguje s modely GGUF a ONNX.

Nasaďte back-end llama.cpp

Backend llama.cpp je lokální pro aplikaci. Když se projekt přihlásí k používání, balíček NuGet Windows ML zkopíruje adaptér llama.cpp modulu Runtime, jádro llama.cpp a modul procesoru vedle vaší aplikace. Akcelerace GPU potřebuje volitelný modul CUDA vytvořený pro stejnou revizi llama.cpp jako balíček a umístěný vedle vaší aplikace.

Návod k oběma krokům najdete v ukázkách modelu GGUF a ukázkách llama.cpp.

Pipeline a fáze

Vytvořte kanál jednorázovým postupem IWinMLPipelineBuilder:

1. Přidejte fáze modelu nebo procesoru s cílovými umístěními spuštění.
2. Připojte porty etapy podle pořadového indexu.
3. Voláním Build jednou zablokujte graf, určete umístění a ověřte kompatibilitu.

Pro dvě fáze modelu přidejte obě fáze, propojte výstupní ordinál první fáze se vstupním ordinálem druhé fáze a jednou sestavte. Vaše aplikace dodává modely a propojí všechna externí vstupní data. Nepotřebuje Runtime API specifické pro model: embedding, dekodér, předběžné zpracování obrázků a další architektury aplikací používají stejné fáze a primitiva tenzorů.

Každý IWinMLStage vlastní poziční vstupní vazby a zpřístupňuje své aktuální výstupní tensory. Vstupní vazby se zachovají napříč běhy. Zavolejte BindOutput před provedením, když vaše aplikace poskytuje výstupní úložiště.

Volitelné schopnosti fáze zahrnují přeložený cíl, materializované schéma, zásady rezidence výstupu a řízení stavu sekvence. Slouží QueryInterface k otestování jednotlivých možností.

Spuštění pipeline

IWinMLPipeline::Run spustí připravený pipeline synchronně. Zavolejte ResetExecutionState mezi nezávislými sekvencemi za účelem vymazání stavu spravovaného modulem runtime.

Volitelná prováděcí rozhraní poskytují odesílání do časové osy zařízení a iterativní opakování s pevným počtem, pokud je podporují vytvořený graf a vybraný back-end. Základní Run cesta zůstává běžným základem.

Tenzory a zámky

IWinMLTensor představuje typovaná vícerozměrná data. Vytvořte tensory z factory získané z cíle spuštění, takže umístění tensoru se řídí umístěním cíle.

Factory metody pokrývají nezpracované bajty, obrazová data, zvuková data, ID tokenů a kompozovatelné procesory tensoru. Volitelná rozhraní tensoru zpřístupňují mutace, vazby vyrovnávací paměti D3D12 a synchronizaci.

Před přístupem k bajtům tensoru na procesoru volejte IWinMLTensor::Lock . Vrácené IWinMLTensorDataLock vytvoří okno přístupu CPU, provede požadované mapování nebo synchronizaci a vlastní životnost ukazatele vráceného GetData.

Kompilace a externí vážení

Kompilace před spuštěním je volitelná schopnost cíle spuštění, která je zpřístupněna prostřednictvím IWinMLModelCompiler. Kompilované artefakty se znovu načítají prostřednictvím normálních metod načítání modelu. Aplikace mohou poskytovat externě definované váhy prostřednictvím IWinMLResourceMapReader.

Textová zatížení

Textové zátěže používají stejný modul runtime, cíl, pipeline, fázi a primitiva tensoru. Vaše aplikace může přímo zajišťovat metadata balíčku modelu, vzorkování, zásady ukončení a akumulaci vygenerovaných tokenů nebo pomocí rozhraní API pro generování textu koordinovat tyto operace v rámci pipeline kompatibilního runtime.

IWinMLTokenizer poskytuje operace kódování a dekódování nízké úrovně. IWinMLTokenizerDecoder udržuje nezávislý kurzor přírůstkového dekódování pro jednu sekvenci. Rozhraní API pro generování textu přidává relace generování textu, možnosti, aktualizace streamování, zrušení, důvody dokončení a dokončené výsledky beze změny vlastnictví podkladových objektů runtime.

Kompatibilita modulu runtime ONNX

Volitelná rozhraní v WinMLRuntimeOrt.h poskytují usnadnění pro ONNX:

• IWinMLOrtCompatibility vybere již zaregistrovaného poskytovatele spuštění modulu runtime ONNX.
• IWinMLOrtModelSchema zobrazuje názvy vstupu a výstupu.
• IWinMLOrtNamedBindings naváže fázi založenou na ORT podle názvu.
• IWinMLOrtStageDiagnostics hlásí požadované a vybrané poskytovatele po Build.

Tato rozhraní během instalace určí názvy a zásady zprostředkovatele. Provádění nadále používá stejné rozhraní poziční pipeline.

Dotazujte se pomocí IWinMLOrtCompatibility z modulu runtime pro připnutí fáze modelu ONNX ke zprostředkovateli spuštění, který jste už zaregistrovali, místo toho, aby poskytovatele automaticky vybral modul runtime Build:

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()));

Předáním nullptr pro hardwareTarget umožníte modulu Runtime spárovat zprostředkovatele s jedním z jeho vlastních zařízení této hardwarové třídy; místo toho předejte existující IWinMLExecutionTarget, aby se zprostředkovatel připnul k tomuto konkrétnímu adaptéru. Tento cíl není podporován ve fázích .gguf; Build vrátí HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

Viz také

• Nastavení projektu C++ pro rozhraní API modulu Windows ML Runtime
• Generování textu pomocí vlastního jazykového modelu pomocí Windows ML
• Rozpoznávejte řeč pomocí vlastního modelu Whisper pomocí Windows ML
• Spuštění modelu pomocí rozhraní API Windows ML Runtime