Omówienie 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.

Important

Interfejs API środowiska uruchomieniowego Windows ML jest obecnie dostępny w języku C++ i Python; Język C# nie jest obecnie obsługiwany. Daj nam znać, jeśli interesuje Cię używanie tych interfejsów API z języka C#, zgłaszając problem w repozytorium GitHub Windows ML!

Interfejs API środowiska uruchomieniowego Windows ML to natywny lokalny framework wnioskowania AI w języku C/C++, utworzony specjalnie dla systemu Windows. Za pomocą interfejsu API środowiska uruchomieniowego Windows ML można załadować model, wybrać cel wykonania CPU, GPU lub NPU (w tym określoną kartę DXCore lub urządzenie D3D12), powiązać tensory z tym celem, połączyć etapy modelu i procesora w potok, skompilować potok i uruchomić go, aby wygenerować tensor danych wyjściowych.

Opcjonalne interfejsy API generowania tekstu i rozpoznawania mowy składają te same obiekty środowiska uruchomieniowego w przepływy pracy wyższego poziomu oparte na modelu dostarczanym przez aplikację: zobacz Generowanie tekstu przy użyciu własnego modelu językowego z użyciem Windows ML i Rozpoznawanie mowy przy użyciu własnego modelu Whisper z użyciem Windows ML.

Runtime API a środowisko uruchomieniowe ONNX Runtime

Jeśli aplikacja jest przeznaczona tylko dla Windows (i chcesz używać obecnie eksperymentalnych interfejsów API), użyj Runtime API. Zapewnia on jawną kontrolę nad wyborem sprzętu (w tym wybór określonego adaptera DXCore lub urządzenia D3D12), miejscem przechowywania tensorów, umieszczaniem potoków wieloetapowych i kompilacją.

W przeciwnym razie, jeśli aplikacja musi działać na innych platformach lub ma już działający międzyplatformowy kod sesji ONNX Runtime, zamiast tego użyj interfejsów API ONNX Runtime zawartych w Windows ML.

Model podstawowych obiektów

Pojęcie Główny interfejs API Description
Runtime IWinMLRuntime Interfejs zwracany przez WinMLCreateRuntime; ładuje pliki modelu, tworzy cele wykonania i tworzy konstruktory potoków.
Model IWinMLModel Niezmienny, nieprzezroczysty artefakt modelu załadowany z pliku lub buforu. Odzwierciedl zadeklarowany schemat za pomocą elementu IWinMLModelSchema.
Cel uruchomienia IWinMLExecutionTarget Token rozmieszczenia CPU, GPU lub NPU używany do tworzenia etapów i tworzenia tensorów.
Konstruktor potoków IWinMLPipelineBuilder Dodaje etapy modelu i procesora, łączy je i tworzy przygotowany potok.
rurociąg IWinMLPipeline Przygotowany, natychmiast uruchamiany graf, który wykonuje powiązane tensory i generuje tensory wyjściowe.
Etapie IWinMLStage Krok w potoku, który ma przypisane pozycyjne powiązania wejścia i wyjścia oraz ustalony cel wykonania.
Tensor IWinMLTensor Typowane dane wielowymiarowe powiązane z danymi wejściowymi i wyjściowymi etapu.
Generowanie tekstu/rozpoznawanie mowy interfejsy API Windows ML do generowania tekstu i rozpoznawania mowy Przepływ pracy wyższego poziomu składa się z obiektów Runtime należących do wywołującego, z typowanymi sesjami, strumieniami i wynikami.

Wybierz backend i cel wykonania

LoadModelFromFile wybiera backend na podstawie rozszerzenia pliku artefaktu modelu. Aplikacja używa tych samych obiektów środowiska uruchomieniowego — modelu, celu wykonywania, konstruktora potoku, etapów, powiązań i Run — niezależnie od tego, które zaplecze ładuje plik.

Plik modelu Backend Przyspieszanie sprzętowe
.onnx, .ort Środowisko uruchomieniowe ONNX Dostawcy wykonania (EPs), które system Windows instaluje i aktualizuje za pośrednictwem katalogu Windows ML EP
.gguf llama.cpp Lokalny dla aplikacji moduł procesora CPU oraz opcjonalny moduł CUDA dla układów GPU NVIDIA, wdrażane razem z aplikacją. Procesor CPU i CUDA to jedyne backendy llama.cpp, które Windows ML waliduje dla tej wersji.

Cel wykonania reprezentuje klasę sprzętu — CPU, GPU lub NPU — utworzoną za pomocą IWinMLRuntime. Użyj ponownie obiektu docelowego, aby utworzyć etapy i utworzyć tensory: ponowne użycie jednego obiektu docelowego wyraża powiązanie z tym samym obiektem docelowym, a użycie odrębnych obiektów docelowych sprawia, że granice transferu między obiektami docelowymi są jawne. Gdy metoda konstruktora potoku Build zostanie uruchomiona, środowisko uruchomieniowe umieszcza każdy etap w backendzie wykonawczym dla swojego celu i potwierdza zgodność celu i backendu.

W przypadku klasy sprzętowej, bez samodzielnego wyliczania urządzeń, wywołaj CreateExecutionTarget z WINML_EXECUTION_TARGET_KIND i WINML_EXECUTION_TARGET_PREFERENCE, która szereguje kandydatów tej klasy, na przykład zintegrowany i dyskretny procesor GPU. Traktuj ERROR_NOT_SUPPORTED i ERROR_NOT_FOUND jednakowo i przejdź awaryjnie do innej klasy:

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 jest odpowiednikiem żądania rodzaju procesora CPU. CreateExecutionTargetFromAdapter i CreateExecutionTargetFromD3D12 wiążą element docelowy z określoną kartą DXCore lub urządzeniem D3D12 zamiast zezwalać środowisku uruchomieniowemu na wybranie jednego z nich. W przypadku modeli ONNX, które zależą od zainstalowanego dostawcy wykonania (EP), opcjonalna warstwa zgodności ONNX Runtime umożliwia przypięcie już zarejestrowanego dostawcy. Każde zaplecze interpretuje te cele inaczej — na przykład zaplecze llama.cpp wykorzystywane przez modele .gguf wymaga co najmniej częściowego odciążenia na GPU, aby uwzględnić cel GPU, i nie obsługuje celów NPU ani przypinania dostawcy. Aby zapoznać się z pełną macierzą docelowych rozdzielczości dla każdego backendu oraz przewodnikiem po uruchamianiu modelu GGUF, zobacz Windows ML Runtime API concepts.

Następne kroki

  • Ostatnia aktualizacja o