Přehled 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.

Important

Rozhraní API modulu Windows ML Runtime je aktuálně dostupné v jazyce C++ a Python; Jazyk C# se v současné době nepodporuje. Dejte nám vědět, jestli vás zajímají tato rozhraní API z jazyka C# publikováním problému v úložišti Windows ML GitHub.

Rozhraní API modulu Windows ML Runtime je nativní místní framework C/C++ pro AI inferenci vytvořený speciálně pro Windows. Pomocí rozhraní API modulu runtime Windows ML můžete načíst model, zvolit cíl spuštění procesoru, GPU nebo NPU (včetně konkrétního adaptéru DXCore nebo zařízení D3D12), svázat tensory s tímto cílem, sestavit fáze modelu a procesoru do kanálu, zkompilovat kanál a spustit ho a vytvořit výstupní tensory.

Volitelná rozhraní API pro generování textu a rozpoznávání řeči skládají tyto stejné objekty Runtime do pracovních postupů vyšší úrovně nad modelem, který poskytuje vaše aplikace: Viz Téma Generování textu pomocí vlastního jazykového modelu pomocí Windows ML a rozpoznávání řeči s vlastním modelem Whisper pomocí Windows ML.

Runtime API vs ONNX Runtime

Pokud vaše aplikace cílí jenom na Windows (a vy jste ochotni používat rozhraní API, která jsou aktuálně experimentální), použijte Runtime API. Poskytuje explicitní kontrolu nad výběrem hardwaru (včetně konkrétního adaptéru DXCore nebo zařízení D3D12), rezidencí tensorů, umístěním vícefázové pipeline a kompilací.

Jinak platí, že pokud vaše aplikace potřebuje běžet na jiných platformách nebo už má funkční kód relace ONNX Runtime, použijte místo toho rozhraní API ONNX Runtime, která jsou součástí Windows ML.

Základní objektový model

Concept Primární rozhraní API Description
Runtime IWinMLRuntime Rozhraní vrácené WinMLCreateRuntime; načte soubory modelu, vytvoří cíle spuštění a vytvoří objekty pro sestavení pipeline.
Model IWinMLModel Neměnný, neprůhledný artefakt modelu načtený ze souboru nebo vyrovnávací paměti Reflektujte deklarované schéma prostřednictvím IWinMLModelSchema.
Cíl spuštění IWinMLExecutionTarget Token umístění CPU, GPU nebo NPU sloužící k sestavení fází a vytváření tensorů.
Tvůrce pipeline IWinMLPipelineBuilder Přidá fáze modelu a procesoru, připojí je a sestaví připravenou pipeline.
Kanál IWinMLPipeline Připravený, okamžitě spustitelný graf, který provádí operace nad navázanými tensory a vytváří výstupní tensory.
Stage IWinMLStage Krok v pipeline, který vlastní poziční vstupní a výstupní vazby a svůj určený cíl spuštění.
Tenzor IWinMLTensor Typovaná multidimenzionální data svázaná se vstupy a výstupy fáze.
Generování textu / rozpoznávání řeči Windows rozhraní API pro generování textu a rozpoznávání řeči ML Pracovní tok vyšší úrovně složený z objektů runtime vlastněných volajícím s typovanými sessionami, datovými proudy a výsledky.

Volba back-endu a cíle spuštění

LoadModelFromFile vybere back-end z přípony souboru artefaktu modelu. Vaše aplikace používá stejné objekty runtime – model, cíl spuštění, tvůrce pipeline, fáze, vazby a Run – bez ohledu na to, který back-end soubor načte.

Soubor modelu Backend Hardwarová akcelerace
.onnx, .ort ONNX Runtime Zprostředkovatelé provádění (EPs), které systém Windows instaluje a udržuje aktuální prostřednictvím katalogu Windows ML EP
.gguf llama.cpp Lokální modul CPU pro aplikaci a volitelný modul CUDA pro GPU NVIDIA, který nasadíte společně s aplikací. CPU a CUDA jsou jedinými llama.cpp back-endy, které Windows ML ověřuje pro tuto verzi.

Cíl spuštění představuje třídu hardwaru – cpu, GPU nebo NPU – vytvořenou pomocí IWinMLRuntime. Znovu použijte cíl k vytváření stupňů a tensorů: opakované použití jednoho cíle vyjadřuje afinitu ke stejnému cíli, zatímco použití jedinečných cílů znamená explicitní hranice přenosu mezi cíli. Když se spustí metoda Build nástroje pro sestavení kanálu, modul runtime umístí každou fázi do back-endu spuštění pro svůj cíl a potvrdí kompatibilitu cíle a back-endu.

Pro hardwarovou třídu, aniž byste sami vytvářeli výčet zařízení, volejte CreateExecutionTarget s WINML_EXECUTION_TARGET_KIND a WINML_EXECUTION_TARGET_PREFERENCE, který řadí kandidáty této třídy, například integrovaný oproti diskrétnímu GPU. Zacházejte s ERROR_NOT_FOUND a ERROR_NOT_SUPPORTED stejně a použijte jinou třídu jako záložní:

ComPtr<IWinMLExecutionTarget> target;
HRESULT hr = runtime->CreateExecutionTarget(
    WINML_EXECUTION_TARGET_KIND_NPU,
    WINML_EXECUTION_TARGET_PREFERENCE_EFFICIENCY,
    target.GetAddressOf());
if (hr == HRESULT_FROM_WIN32(ERROR_NOT_FOUND) ||
    hr == HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED))
{
    THROW_IF_FAILED(runtime->CreateExecutionTarget(
        WINML_EXECUTION_TARGET_KIND_GPU,
        WINML_EXECUTION_TARGET_PREFERENCE_PERFORMANCE,
        target.GetAddressOf()));
}
else
{
    THROW_IF_FAILED(hr);
}

CreateCpuExecutionTarget odpovídá požadavku na druh procesoru. CreateExecutionTargetFromAdapter a CreateExecutionTargetFromD3D12 vážou cíl na konkrétní adaptér DXCore nebo zařízení D3D12 místo toho, aby modul runtime jeden z nich vybral. U modelů ONNX, které závisí na nainstalovaném execution provideru (EP), umožňuje volitelné rozhraní kompatibility ONNX Runtime pevně nastavit poskytovatele, kterého jste už zaregistrovali. Každý back-end tyto cíle zpracovává jinak – například back-end llama.cpp používaný modely .gguf vyžaduje alespoň částečný offload na GPU, aby bylo možné respektovat cíl GPU, a nepodporuje cíle NPU ani připnutí poskytovatele. Úplnou matici cílových rozlišení pro každý backend a návod ke spuštění modelu GGUF najdete v Koncepty rozhraní Windows ML Runtime API.

Další kroky

  • Poslední aktualizace v