Pojęcia dotyczące interfejsu API środowiska uruchomieniowego Windows ML

Important

Interfejs API środowiska uruchomieniowego Windows ML jest obecnie eksperymentalny i nie jest obsługiwany do użycia w środowiskach produkcyjnych. Aplikacje testujące ten interfejs API nie powinny być publikowane w Microsoft Store.

Interfejs API Windows ML Runtime to natywna lokalna struktura inferencji AI utworzona specjalnie dla systemu Windows. Za pomocą interfejsu API Windows ML Runtime masz jawną kontrolę nad ładowaniem modelu, przypisaniem do sprzętu, własnością tensorów, kompozycją potoku, kompilacją i diagnostyką.

Zalecamy użycie Runtime API w celu uzyskania najlepszej wydajności inferencji modelu w systemie Windows, ale jeśli aplikacja musi działać na innych platformach lub jeśli masz już działający międzyplatformowy kod ONNX Runtime, możesz również użyć ONNX Runtime za pośrednictwem Windows ML.

Jak obiekty pasują do siebie

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

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

Każda metoda zwraca wartość HRESULT, a każdy wskaźnik interfejsu jest zgodny z normalnym zliczeniem odwołań COM. Opcjonalne możliwości są wykrywane za pomocą QueryInterface; niedostępna możliwość zwraca E_NOINTERFACE.

Runtime

Utwórz IWinMLRuntime za pomocą WinMLCreateRuntime. Służy do ładowania artefaktów modelu, tworzenia celów wykonania i tworzenia konstruktorów potoku.

Modele i schematy

IWinMLModel jest niezmiennym, niejawnym artefaktem modelu. LoadModelFromFile akceptuje dowolną bezwzględną lub względną ścieżkę pliku, którą aplikacja może odczytać; lokalizacja modelu to decyzja o pakowaniu aplikacji.

Ładowanie potwierdza, że artefakt jest rozpoznawany i czytelny strukturalnie. Zgodność docelowa zostanie zastosowana później, gdy metoda konstruktora potoku Build zakończy się pomyślnie.

Odzwierciedlić zadeklarowany schemat porządkowy modelu za pomocą elementu IWinMLModelSchema. Niektóre artefakty ONNX uwidaczniają również nazwy za pośrednictwem opcjonalnego IWinMLOrtModelSchema, ale identyfikacja wykonania nadal opiera się na pozycji.

Kształty i operatory

Zadeklarowany schemat modelu może zawierać wolne wymiary reprezentowane przez UINT64_MAXelement . Beton IWinMLTensor zawsze ma określone wymiary. Potoki przetwarzania oparte na ORT mogą wiązać i uruchamiać konkretne wartości dla dynamicznego wymiaru.

Stałe lub jawnie ograniczone kształty pozostają optymalnym punktem odniesienia projektu, ponieważ umożliwiają Build weryfikowanie zgodności, przydzielanie stabilnych zasobów i określanie, czy odtwarzanie lub iteracja utrzymywana na urządzeniu jest legalna. Zapewniają one również najszerszą zgodność w różnych backendach wykonawczych. Jest to rozróżnienie dotyczące optymalizacji i przenośności, a nie ogólne odrzucenie modeli, których zadeklarowany schemat ONNX zawiera wolne wymiary.

Standardowe operatory ONNX również zwiększają przenośność backendu. Pomyślne załadowanie modelu nie gwarantuje, że każdy element docelowy platformy może wykonać każdy operator; Build jest sprawdzaniem zgodności.

Backends

Plik modelu wybiera backend. Aplikacja używa tych samych obiektów Runtime w obu przypadkach: model, cel wykonywania, konstruktor potoku, etapy, powiązania i Run.

Plik modelu Backend Przyspieszanie sprzętowe
.onnx, .ort Środowisko uruchomieniowe ONNX Dostawcy wykonywania (EP), które system Windows instaluje i aktualizuje za pośrednictwem katalogu Windows ML EP
.gguf llama.cpp llama.cpp moduły wdrożone w aplikacji: moduł procesora CPU w pakiecie oraz opcjonalny moduł CUDA dla procesorów graficznych NVIDIA. Procesor CPU i CUDA to jedyne backendy llama.cpp walidowane przez Windows ML dla tej wersji.

Backendy różnią się pod względem tego, co może wyrazić faza:

Capability Środowisko uruchomieniowe ONNX llama.cpp
Kształt sceny Dowolny graf ONNX; w jednym potoku można połączyć kilka etapów Jeden etap dekodera na plik GGUF: identyfikatory tokenów w (wejście 0), logity na wyjściu (dane wyjściowe 0)
Stan sekwencji (pamięć podręczna KV) Deklaruj pary tensorów stanu za pomocą IWinMLStatefulStageOptions; środowisko uruchomieniowe zarządza nimi Należące do backendu; nic do deklarowania
Długość kontekstu SetSequenceCapacityHint przed Build, lub deklarowana pojemność modelu SetSequenceCapacityHint przed Build ustawia długość kontekstu llama.cpp
Opcje przypinania dostawcy i etapu ORT Obsługiwane (WinMLRuntimeOrt.h) Nieobsługiwane; Build zwraca HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)
Raport rozmieszczenia po Build IWinMLOrtStageDiagnostics nazywa żądanych i wybranych dostawców IWinMLStage::GetExecutionTarget zgłasza CPU lub GPU

Jeden potok przetwarzania może łączyć różne backendy. Na przykład etap Whisper w środowisku uruchomieniowym ONNX może przekazywać dane do modelu językowego GGUF w llama.cpp.

Cele wykonania

IWinMLExecutionTarget jest niezmiennym tokenem rozmieszczenia, który żąda klasy sprzętu i opcjonalnie konkretnego adaptera. Każdy backend rozwiązuje to, gdy Build jest uruchamiany:

Docelowy etap Środowisko uruchomieniowe ONNX llama.cpp
nullptr przekazano do AddModelStage Automatyczne przydzielanie wybiera zgodny GPU EP, jeśli jest dostępny, z przełączeniem awaryjnym na CPU. Przekazuje do modułu CUDA, gdy jest wdrożony, a model pasuje; w przeciwnym razie działa na procesorze CPU.
CreateCpuExecutionTarget Wybiera zgodny CPU EP, przyjmując dostawcę CPU ORT jako punkt odniesienia. Działa na procesorze CPU.
CreateExecutionTarget z typem GPU, CreateExecutionTargetFromAdapter lub CreateExecutionTargetFromD3D12 Mapuje identyfikator adaptera na zgodne urządzenie GPU EP. Jeśli żadne urządzenie dostawcy nie pasuje, Build zakończy się niepowodzeniem. Wymaga co najmniej częściowego przeniesienia obliczeń do modułu CUDA. Build Zwraca wartość HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) , gdy nie wdrożono modułu CUDA i HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY) gdy model nie pasuje. Moduł wybiera procesor GPU; identyfikator adaptera nie jest używany.
CreateExecutionTarget z typem NPU lub adapterem NPU Mapuje do zgodnego urządzenia NPU EP. Nieobsługiwane; Build zwraca wartość HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).
IWinMLOrtCompatibility::CreateExecutionTarget(provider, kind, hardwareTarget) Przypisuje jeden zarejestrowany punkt końcowy. Po ustawieniu hardwareTarget na nullptr środowisko uruchomieniowe paruje dostawcę z jednym z własnych urządzeń; na komputerze z dwoma procesorami GPU pozwala to uniknąć parowania dostawcy z adapterem, którego nie obsługuje. Nieobsługiwane; Build zwraca wartość HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

IWinMLRuntime::CreateExecutionTarget(kind, preference) wybiera adapter żądanej klasy bez konieczności samodzielnego listowania urządzeń, a preference szereguje adaptery, gdy istnieje więcej niż jeden adapter, na przykład zintegrowany i dyskretny układ GPU:

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

Jawny wybór adaptera wymaga zgodnego dostawcy środowiska uruchomieniowego ONNX w celu uwidocznienia tego identyfikatora sprzętu za pośrednictwem ORT. Jeśli żadne urządzenie dostawcy nie jest zgodne, Build zakończy się niepowodzeniem, zamiast po cichu wybierać inną kartę lub procesor CPU.

CreateExecutionTargetFromD3D12 zachowuje urządzenie obiektu wywołującego i opcjonalną kolejkę w obiekcie docelowym, ale wykonywanie ORT używa tylko tożsamości adaptera do wyboru EP. Dostawca ORT jest właścicielem zasobów wykonawczych, a kolejka poleceń wywołującego nie jest używana do przekazywania zadań do ORT.

Obiekt docelowy D3D12 nadal udostępnia IWinMLD3D12ExecutionTarget do QueryInterface. Ponowne użycie jednego jawnego obiektu docelowego na różnych etapach wyraża powinowactwo do tego samego adaptera; odrębne obiekty docelowe sprawiają, że granice transferu są jawne.

Uruchom model GGUF

  1. Załaduj plik za pomocą polecenia LoadModelFromFile. Rozszerzenie .gguf wybiera silnik llama.cpp. W przypadku modelu podzielonego na fragmenty zachowaj każdy fragment w jednym folderze i załaduj pierwszy fragment.
  2. Dodaj jeden etap modelu z procesorem CPU, procesorem GPU lub celem nullptr. Aby ustawić długość kontekstu, wykonaj zapytanie IWinMLStatefulStageOptions z etapu i wywołaj metodę SetSequenceCapacityHint.
  3. Zadzwoń do Build. Następnie powiąż identyfikatory tokenów monitu z danymi wejściowymi 0, zażądaj danych wyjściowych 0 i wywołaj metodę Run. Każde późniejsze uruchomienie przyjmuje następny token; backend przechowuje pamięć podręczną KV między przebiegami.
  4. Wywołaj ResetExecutionState przed niezależną sekwencją.
// 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 i formatowanie konwersacji pochodzą z pliku GGUF, więc model GGUF nie potrzebuje oddzielnych plików tokenizatora. Aby pominąć pętlę tokenu, użyj interfejsu API generowania tekstu, który współpracuje z modelami GGUF i ONNX.

Wdróż backend llama.cpp

Zaplecze llama.cpp jest lokalne dla aplikacji. Gdy projekt włączy tę opcję, pakiet NuGet Windows ML kopiuje adapter llama.cpp środowiska uruchomieniowego, rdzeń llama.cpp i moduł CPU obok aplikacji. Akceleracja GPU wymaga opcjonalnego modułu CUDA utworzonego dla tej samej wersji llama.cpp co pakiet i umieszczonego obok aplikacji.

Aby zapoznać się z przewodnikiem obu kroków, zobacz przykłady modeli GGUF i przykłady llama.cpp.

Procesy i etapy

Zbuduj potok za pomocą jednorazowego zrzutu IWinMLPipelineBuilder:

  1. Dodaj etapy modelu lub procesora z ich miejscami docelowymi wykonywania.
  2. Połącz porty etapu według indeksu porządkowego.
  3. Uruchom Build raz, aby zablokować graf, ustalić rozmieszczenie i zweryfikować zgodność.

W przypadku dwóch etapów modelu dodaj oba etapy, połącz indeks wyjścia pierwszego etapu z indeksem wejścia drugiego etapu i zbuduj model tylko raz. Aplikacja dostarcza modele i wiąże wszelkie zewnętrzne dane wejściowe. Nie wymaga interfejsu API środowiska uruchomieniowego specyficznego dla modelu: osadzanie, dekoder, przetwarzanie wstępne obrazów i inne architektury aplikacji używają tych samych prymitywów etapów i prymitywów tensorowych.

Każdy IWinMLStage ma pozycyjne powiązania wejściowe i udostępnia swoje bieżące tensory wyjściowe. Przypisania wejścia są zachowywane między kolejnymi uruchomieniami. Wywołaj BindOutput przed wykonaniem, gdy aplikacja dostarcza pamięć wyjściową.

Opcjonalne możliwości etapu obejmują określony element docelowy, zmaterializowany schemat, zasady rezydencji danych wyjściowych i kontrolę stanu sekwencji. Użyj QueryInterface, aby przetestować każdą funkcję.

Wykonanie potoku

IWinMLPipeline::Run wykonuje przygotowany potok synchronicznie. Wywołaj ResetExecutionState między niezależnymi sekwencjami w celu wyczyszczenia stanu zarządzanego przez środowisko uruchomieniowe.

Opcjonalne interfejsy wykonywania zapewniają przesyłanie do osi czasu urządzenia i powtórne odtwarzanie iteracyjne o stałej liczbie iteracji, gdy utworzony graf i wybrane zaplecze je obsługują. Ścieżka podstawowa Run pozostaje typowym punktem odniesienia.

tensory i blokady

IWinMLTensor reprezentuje dane typizowane, wielowymiarowe. Utwórz tensory z fabryki pobranej z celu wykonania, aby rozmieszczenie tensorów było zgodne z rozmieszczeniem celu.

Metody tworzące obejmują nieprzetworzone bajty, dane obrazu, dane audio, identyfikatory tokenów i komponowalne procesory tensorów. Opcjonalne interfejsy tensorów udostępniają mutację, powiązania buforu D3D12 i synchronizację.

Wywołaj IWinMLTensor::Lock przed uzyskaniem dostępu do bajtów tensorowych na procesorze CPU. Zwrócone IWinMLTensorDataLock ustanawia okno dostępu dla CPU, wykonuje wymagane mapowanie lub synchronizację i zarządza okresem istnienia wskaźnika zwróconego przez GetData.

Kompilowanie i wagi zewnętrzne

Kompilacja z wyprzedzeniem jest opcjonalną funkcją obiektu docelowego wykonywania uwidacznianą za pośrednictwem elementu IWinMLModelCompiler. Skompilowane artefakty są przeładowywane za pomocą normalnych metod ładowania modelu. Aplikacje mogą dostarczać zewnętrzne wagi za pośrednictwem elementu IWinMLResourceMapReader.

Obciążenia związane z tekstem

Zadania tekstowe używają tego samego środowiska uruchomieniowego, tego samego elementu docelowego, tego samego potoku, tego samego etapu i tych samych prymitywów tensorowych. Aplikacja może bezpośrednio obsługiwać metadane pakietu modelu, próbkowanie, strategię zatrzymywania i akumulację wygenerowanych tokenów lub użyć interfejsu API generowania tekstu, aby koordynować te operacje za pośrednictwem zgodnego potoku środowiska uruchomieniowego.

IWinMLTokenizer Zapewnia operacje kodowania i dekodowania niskiego poziomu. Obiekt IWinMLTokenizerDecoder obsługuje niezależny kursor dekodowania przyrostowego dla jednej sekwencji. Interfejs API generowania tekstu dodaje sesje generowania tekstu, opcje, aktualizacje przesyłania strumieniowego, anulowanie, przyczyny zakończenia i ukończone wyniki bez zmiany własności bazowych obiektów środowiska uruchomieniowego.

Zgodność środowiska uruchomieniowego ONNX

Opcjonalne interfejsy w WinMLRuntimeOrt.h oferują udogodnienia ONNX:

  • IWinMLOrtCompatibility wybiera już zarejestrowanego dostawcę Execution Provider środowiska uruchomieniowego ONNX.
  • IWinMLOrtModelSchema odzwierciedla nazwy wejściowe i wyjściowe.
  • IWinMLOrtNamedBindings wiąże etap wspierany przez ORT według nazwy.
  • IWinMLOrtStageDiagnostics zgłasza żądanych i wybranych dostawców po Build.

Te interfejsy ustalają nazwy i zasady dostawcy podczas instalacji. Wykonanie nadal korzysta z tego samego kontraktu pozycyjnego potoku.

Wykonaj zapytanie IWinMLOrtCompatibility ze środowiska uruchomieniowego, aby przypiąć etap modelu ONNX do już zarejestrowanego dostawcy wykonania, zamiast zezwalać Build na automatyczne wybranie jednego:

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

Przekazywanie nullptr elementu hardwareTarget umożliwia środowisku uruchomieniowemu sparowanie dostawcy z jednym z jego własnych urządzeń tej klasy sprzętu; przekaż istniejący IWinMLExecutionTarget, aby przypiąć dostawcę do tego konkretnego adaptera. Ten element docelowy nie jest obsługiwany dla .gguf etapów; Build zwraca wartość HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

Informacje dodatkowe

  • Ostatnia aktualizacja o