Begrepp för Windows ML Runtime API

WINDOWS ML Runtime API är ett inbyggt lokalt ramverk för AI-inferens som skapats specifikt för Windows. Med Windows ML Runtime API har du explicit kontroll över modellinläsning, maskinvaruplacering, tensorägarskap, pipelinesammansättning, kompilering och diagnostik.

Vi rekommenderar att du använder Runtime-API:et för bästa modellinferensprestanda på Windows, men om din app behöver köras på andra plattformar eller om du redan har fungerande plattformsoberoende ONNX Runtime-kod kan du också använda ONNX Runtime via Windows ML.

Hur objekten passar ihop

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

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

Varje metod returnerar HRESULT, och varje gränssnittspekare följer normal COM-referensräkning. Valfria funktioner identifieras med QueryInterface. En otillgänglig funktion returnerar E_NOINTERFACE.

Runtime

Skapa IWinMLRuntime med WinMLCreateRuntime. Använd den för att läsa in modellartefakter, skapa körningsmål och skapa pipelineverktyg.

Model och schema

IWinMLModel är en oföränderlig, opak modellartefakt. LoadModelFromFile accepterar alla absoluta eller relativa filsökvägar som appen kan läsa. modellens placering avgörs av hur appen paketeras.

Inläsning verifierar att artefakten känns igen och kan läsas strukturellt. Målkompatibiliteten fastställs senare när pipelineverktygets Build metod lyckas.

Återspegla en modells deklarerade ordningsschema via IWinMLModelSchema. Vissa ONNX-artefakter exponerar även namn via den valfria IWinMLOrtModelSchema, men körningsidentiteten förblir positionell.

Former och operatorer

Ett deklarerat modellschema kan innehålla fria dimensioner som representeras av UINT64_MAX. En konkret IWinMLTensor har alltid fastställda dimensioner. ORT-baserade pipelines kan binda och köra konkreta värden för en fri dimension.

Fasta eller uttryckligen avgränsade shaper förblir det optimerade designcentret eftersom de låter Build validera kompatibilitet, allokera stabila resurser och avgöra om replay eller enhetsresident iteration är tillåten. De ger också den bredaste kompatibiliteten mellan bakändar för körning. Det här är en optimerings- och portabilitetsskillnad, inte ett generellt avvisande av modeller vars deklarerade ONNX-schema innehåller fria dimensioner.

Standard ONNX-operatorer förbättrar också portabiliteten för bakänden. En lyckad modellinläsning garanterar inte att varje mål kan köra varje operator; Build är kompatibilitetskontrollen.

Backends

Modellfilen väljer backend. Appen använder samma Runtime-objekt oavsett vilket: modell, körningsmål, pipelinebyggare, steg, bindningar och Run.

Serverdelarna skiljer sig åt i vad ett steg kan uttrycka:

En pipeline kan blanda backender. Till exempel kan ett Whisper-steg i ONNX Runtime mata en GGUF-språkmodell i llama.cpp.

Körningsmål

IWinMLExecutionTarget är en oföränderlig placement token som begär en maskinvaruklass och eventuellt en specifik adapter. Varje serverdel löser det när Build körs:

IWinMLRuntime::CreateExecutionTarget(kind, preference) väljer en adapter för den begärda klassen utan att du behöver räkna upp enheter själv och preference rangordnar adaptrar när det finns fler än en, till exempel en integrerad och en diskret GPU:

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

Explicit adapterval kräver att en kompatibel ONNX Runtime-provider exponerar maskinvaruidentiteten via ORT. Om ingen providerenhet matchar misslyckas Build i stället för att tyst välja ett annat kort eller en annan processor.

CreateExecutionTargetFromD3D12 Behåller anroparens enhet och valfria kö på målet, men ORT-körningen använder endast adapteridentiteten för EP-val. ORT-providern äger sina körningsresurser och anroparens kommandokö används inte för ORT-inlämning.

Ett D3D12-mål exponerar fortfarande IWinMLD3D12ExecutionTarget till QueryInterface. Återanvändning av ett explicit mål mellan faser uttrycker affinitet till samma adapter. Distinkta mål gör överföringsgränser explicita.

Kör en GGUF-modell

1. Läs in filen med LoadModelFromFile. Tillägget .gguf väljs för llama.cpp. För en shardad modell, behåll varje shard i en mapp och läs in den första sharden.
2. Lägg till ett modellsteg med en CPU, GPU eller nullptrmål. Om du vill ange kontextlängden frågar du IWinMLStatefulStageOptions från stage-miljön och anropar SetSequenceCapacityHint.
3. Ringa Build. Bind sedan promptens token-ID till indata 0, begär utdata 0 och anropa Run. Varje senare körning tar nästa token; serverdelen behåller KV-cachen mellan körningar.
4. Anropa ResetExecutionState före en oberoende sekvens.

// 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- och konversationsformateringen kommer från GGUF-filen, så en GGUF-modell behöver inte separata tokenizer-filer. Om du vill hoppa över tokenloopen använder du Text Generation API, som fungerar med GGUF- och ONNX-modeller.

Distribuera llama.cpp-backend

Den llama.cpp backenden är applokal. När ett projekt väljer att aktiveras kopierar Windows ML NuGet-paketet Runtimes llama.cpp-adapter, llama.cpp core och CPU-modulen bredvid din app. GPU-acceleration behöver den valfria CUDA-modulen som har skapats för samma llama.cpp revision som paketet och placerats bredvid din app.

För en genomgång av båda stegen, se GGUF-modellexemplen och llama.cpp-exemplen.

Pipelines och steg

Skapa en pipeline med one-shot IWinMLPipelineBuilder:

1. Lägg till modell- eller processorfaser med sina körningsmålgrupper.
2. Anslut scenportar efter ordningstalsindex.
3. Anropa Build en gång för att frysa grafen, fastställa placeringen och validera kompatibiliteten.

För två modellsteg lägger du till båda stegen, ansluter det första stegets utdataordning till det andra stegets indataordning och skapar en gång. Din app tillhandahåller modellerna och kopplar externa indata. Det kräver inget modellspecifikt Runtime API: embedding, dekodering, bildförbehandling och andra programarkitekturer använder samma steg- och tensorprimitiver.

Varje IWinMLStage har positionella indatabindningar och tillhandahåller sina aktuella utdatatensorer. Indatabindningar bevaras mellan körningar. Anropa BindOutput före en körning när appen tillhandahåller utdatalagring.

Valfria stegfunktioner inkluderar resolved target, materialiserat schema, utdataplaceringsprincip och sekvenstillståndskontroll. Använd QueryInterface för att testa för varje funktionalitet.

Pipelinekörning

IWinMLPipeline::Run utför den förberedda processkedjan synkront. Anropa ResetExecutionState mellan oberoende sekvenser för att rensa körningshanterat tillstånd.

Valfria körningsgränssnitt ger inlämning till enhetens tidslinje och iterativ uppspelning med fast antal när den byggda grafen och den valda backend stöder dem. Den grundläggande Run sökvägen är fortfarande den gemensamma utgångspunkten.

tensorer och lås

IWinMLTensor representerar typade, flerdimensionella data. Skapa tensorer från en fabrik som hämtas från körningsmålet så att tensorplacering följer målplaceringen.

Fabriker omfattar råa byte, bilddata, ljuddata, token-ID:er och komponerbara tensorprocessorer. Valfria tensor-gränssnitt exponerar mutation, D3D12-buffertbindningar och synkronisering.

Anropa IWinMLTensor::Lock innan du kommer åt tensor-byte på processorn. Den returnerade IWinMLTensorDataLock upprättar cpu-åtkomstfönstret, utför nödvändig mappning eller synkronisering och äger livslängden för pekaren som returneras av GetData.

Kompilering och externa vikter

Kompilering i förväg är en valfri funktion för ett körningsmål som exponeras via IWinMLModelCompiler. Kompilerade artefakter läses in igen via de normala modellinläsningsmetoderna. Appar kan tillhandahålla externaliserade vikter via IWinMLResourceMapReader.

Textarbetsbelastning

Textarbetslaster använder samma körnings-, mål-, pipeline-, fas- och tensor-primitiver. Din app kan hantera metadata för modellpaket, sampling, stoppolicy och ackumulering av genererade token direkt, eller använda Text Generation API för att samordna dessa åtgärder över en kompatibel Runtime-pipeline.

IWinMLTokenizer tillhandahåller åtgärder på låg nivå för kodning och avkodning. En IWinMLTokenizerDecoder upprätthåller en oberoende inkrementell avkodningsmarkör för en sekvens. Text Generation API lägger till textgenereringssessioner, alternativ, strömmande uppdateringar, annullering, avslutsorsaker och slutförda resultat utan att ändra ägarskapet för de underliggande Runtime-objekten.

ONNX Runtime-kompatibilitet

De valfria gränssnitten i WinMLRuntimeOrt.h ger ONNX-bekvämligheter:

• IWinMLOrtCompatibility väljer en redan registrerad ONNX Runtime-körningsprovider.
• IWinMLOrtModelSchema återspeglar indata- och utdatanamn.
• IWinMLOrtNamedBindings binder ett ORT-backat steg efter namn.
• IWinMLOrtStageDiagnostics rapporter som begärts och valda leverantörer efter Build.

Dessa gränssnitt löser namn och providerpolicy under installationen. Körningen fortsätter att använda samma positionella pipelinekontrakt.

Fråga körtiden via IWinMLOrtCompatibility för att fästa ett ONNX-modellsteg till en execution provider som du redan har registrerat, i stället för att låta Build välja en automatiskt:

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

Genom att skicka nullptr för hardwareTarget kan Runtime para ihop providern med en av sina egna enheter i den maskinvaruklassen. Skicka en befintlig IWinMLExecutionTarget för att fästa providern på den specifika adaptern i stället. Den här målplattformen stöds inte för .gguf faser; Build returnerar HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

Se även

• Konfigurera ett C++-projekt för Windows ML Runtime API
• Generera text med din egen språkmodell med hjälp av Windows ML
• Känn igen tal med din egen Whisper-modell med hjälp av Windows ML
• Kör en modell med Windows ML Runtime API