Concetti dell'API di Windows ML Runtime

Importante

L'API Windows ML Runtime è attualmente sperimentale e non è supportata per l'uso in ambienti di produzione. Le app che provano questa API non devono essere pubblicate nel Microsoft Store.

L'API runtime di Windows ML è un framework nativo di inferenza IA locale sviluppato specificamente per Windows. Con l'API Windows ML Runtime, è possibile controllare esplicitamente il caricamento del modello, il posizionamento hardware, la proprietà dei tensori, la composizione della pipeline, la compilazione e la diagnostica.

È consigliabile usare l'API di runtime per ottenere prestazioni di inferenza del modello ottimali in Windows, ma se l'app deve essere eseguita in altre piattaforme o se si ha già codice ONNX Runtime multipiattaforma, è anche possibile usare ONNX Runtime tramite Windows ML.

Come gli oggetti si combinano tra loro

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

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

Ogni metodo restituisce HRESULTe ogni puntatore di interfaccia segue il normale conteggio dei riferimenti COM. Le funzionalità facoltative vengono individuate con QueryInterface. Una funzionalità non disponibile restituisce E_NOINTERFACE.

Runtime

Creare IWinMLRuntime con WinMLCreateRuntime. Usalo per caricare gli artefatti del modello, creare target di esecuzione e creare generatori di pipeline.

Modelli e schemi

IWinMLModel è un artefatto di modello opaco non modificabile. LoadModelFromFile accetta qualsiasi percorso di file assoluto o relativo che l'app può leggere; la posizione del modello è la decisione sulla creazione di pacchetti dell'app.

Il caricamento conferma che l'artefatto sia riconosciuto e leggibile strutturalmente. Il commit della compatibilità del target viene eseguito in un secondo momento, quando il metodo del generatore di Build pipeline ha esito positivo.

Rispecchia lo schema ordinale dichiarato di un modello tramite IWinMLModelSchema. Alcuni artefatti ONNX espongono anche nomi tramite l'elemento facoltativo IWinMLOrtModelSchema, ma l'identità di esecuzione rimane posizionale.

Forme e operatori

Uno schema del modello dichiarato può contenere dimensioni libere, rappresentate da UINT64_MAX. Un elemento concreto IWinMLTensor ha sempre dimensioni risolte. Le pipeline supportate da ORT possono vincolare ed eseguire valori concreti per una dimensione non vincolata.

Le forme fisse o delimitate esplicitamente rimangono il centro di progettazione ottimizzato perché consentono a Build di convalidare la compatibilità, allocare risorse stabili e determinare se la riproduzione o l'iterazione residente nel dispositivo è legale. Offrono anche la compatibilità più ampia tra back-end di esecuzione. Si tratta di una distinzione di ottimizzazione e portabilità, non un rifiuto generale dei modelli il cui schema ONNX dichiarato contiene dimensioni libere.

Gli operatori ONNX standard migliorano allo stesso modo la portabilità del backend. Un caricamento corretto del modello non garantisce che ogni target possa eseguire ogni operatore; Build esegue il controllo di compatibilità.

Backends

Il file del modello determina il backend. L'app usa gli stessi oggetti runtime in entrambi i modi: modello, destinazione di esecuzione, generatore di pipeline, fasi, associazioni e Run.

File del modello Backend Accelerazione hardware
.onnx, .ort Runtime ONNX Provider di esecuzione (EPs) che Windows installa e mantiene aggiornati tramite il catalogo EP di Windows ML
.gguf llama.cpp llama.cpp moduli distribuiti con l'app: un modulo CPU nel pacchetto e un modulo CUDA facoltativo per GPU NVIDIA. CPU e CUDA sono gli unici back-end llama.cpp Windows ML convalidati per questa versione.

I back-end differiscono in base a ciò che una fase può esprimere:

Capability Runtime ONNX llama.cpp
Forma del palco Qualsiasi grafo ONNX; diverse fasi possono essere connesse in una pipeline Una fase del decodificatore per ogni file GGUF: ID token in (input 0), logits out (output 0)
Stato sequenza (cache KV) Dichiarare coppie di tensore di stato con IWinMLStatefulStageOptions; il runtime le gestisce Di proprietà del back-end; niente da dichiarare
Lunghezza del contenuto SetSequenceCapacityHint prima di Build, o della capacità dichiarata del modello SetSequenceCapacityHint prima di Build imposta la lunghezza del contesto di llama.cpp
Opzioni di blocco del provider e fase ORT Supportato (WinMLRuntimeOrt.h) Non supportato; Build restituisce HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)
Report di posizionamento dopo Build IWinMLOrtStageDiagnostics indica i provider richiesti e selezionati IWinMLStage::GetExecutionTarget segnala CPU o GPU

Una pipeline può utilizzare più backend. Ad esempio, una fase Whisper in ONNX Runtime può passare l'output a un modello linguistico GGUF in llama.cpp.

Obiettivi di esecuzione

IWinMLExecutionTarget è un placement token non modificabile che richiede una classe hardware e, facoltativamente, una scheda specifica. Ogni back-end lo risolve quando Build viene eseguito:

Destinazione della fase Runtime ONNX llama.cpp
nullptr fornito a AddModelStage Il posizionamento automatico seleziona un EP GPU compatibile quando disponibile, con il fallback della CPU. Esegue l'offload al modulo CUDA quando ne è implementato uno e il modello rientra; in caso contrario viene eseguito sulla CPU.
CreateCpuExecutionTarget Seleziona un EP CPU compatibile, con il provider di CPU ORT come baseline. Viene eseguito sulla CPU.
CreateExecutionTarget con il tipo di GPU, CreateExecutionTargetFromAdapter, o CreateExecutionTargetFromD3D12 Esegue il mapping dell'identità dell'adattatore a un dispositivo EP GPU compatibile. Se nessun dispositivo provider corrisponde, Build ha esito negativo. Richiede almeno un offload parziale nel modulo CUDA. Build restituisce HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) quando non viene distribuito alcun modulo CUDA e HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY) quando il modello non entra. Il modulo sceglie la GPU; l'identità dell'adattatore non viene usata.
CreateExecutionTarget con il tipo di NPU o un adattatore NPU Esegue il mapping a un dispositivo EP NPU compatibile. Non è supportato; Build restituisce HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).
IWinMLOrtCompatibility::CreateExecutionTarget(provider, kind, hardwareTarget) Fissa un EP registrato. Con hardwareTarget impostato su nullptr, il runtime associa il provider a uno dei propri dispositivi. In un PC con due GPU, in questo modo si evita l'associazione del provider a un adattatore che non supporta. Non supportato; Build restituisce HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

IWinMLRuntime::CreateExecutionTarget(kind, preference) sceglie un adattatore della classe richiesta senza che sia necessario enumerare manualmente i dispositivi e preference classifica gli adattatori quando sono presenti più schede, ad esempio una GPU integrata e discreta:

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

La selezione esplicita dell'adattatore richiede un provider di runtime ONNX compatibile per esporre l'identità hardware tramite ORT. Se nessun dispositivo provider corrisponde, Build non riesce anziché selezionare automaticamente un'altra scheda o CPU.

CreateExecutionTargetFromD3D12 mantiene il dispositivo del chiamante e la coda facoltativa nella destinazione, ma l'esecuzione ORT usa solo l'identità dell'adattatore per la selezione EP. Il provider ORT possiede le risorse di esecuzione e la coda dei comandi del chiamante non viene usata per l'invio ORT.

Una destinazione D3D12 espone IWinMLD3D12ExecutionTarget ancora tramite QueryInterface. Il riutilizzo di una destinazione esplicita in più fasi esprime l'affinità del medesimo adattatore; destinazioni distinte rendono espliciti i limiti di trasferimento.

Eseguire un modello GGUF

  1. Caricare il file con LoadModelFromFile. L'estensione .gguf seleziona llama.cpp. Per un modello suddiviso in shard, mantenere ogni shard in una cartella e caricare il primo shard.
  2. Aggiungere una fase del modello con una CPU, una GPU o un target. Per impostare la lunghezza del contesto, eseguire una query IWinMLStatefulStageOptions dallo stage e chiamare SetSequenceCapacityHint.
  3. Chiamare Build. Associare quindi gli ID token del prompt all'input 0, richiedere l'output 0 e chiamare Run. Ogni esecuzione successiva elabora il token successivo; il back-end mantiene la cache KV tra le esecuzioni.
  4. Chiama ResetExecutionState prima di una sequenza indipendente.
// 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());

Il tokenizer e la formattazione della conversazione provengono dal file GGUF, quindi un modello GGUF non richiede file di tokenizer separati. Per ignorare il ciclo di token, usare Text Generation API, che funziona con i modelli GGUF e ONNX.

Distribuisci il backend di llama.cpp

Il back-end llama.cpp è locale dell'app. Quando un progetto attiva esplicitamente, il pacchetto NuGet Windows ML copia l'adattatore llama.cpp del runtime, il core llama.cpp e il modulo CPU accanto all'app. L'accelerazione GPU richiede il modulo CUDA facoltativo, compilato per la stessa revisione di llama.cpp del pacchetto e posizionato accanto alla tua app.

Per una procedura dettagliata di entrambi i passaggi, vedere gli esempi di modelli GGUF e gli esempi di llama.cpp.

Pipeline e fasi

Creare una pipeline con il one-shot IWinMLPipelineBuilder:

  1. Aggiungere fasi del modello o del processore con le relative destinazioni di esecuzione.
  2. Connettere le porte dello stage per indice ordinale.
  3. Chiamare Build una volta per congelare il grafico, risolvere il posizionamento e convalidare la compatibilità.

Per due fasi del modello, aggiungere entrambe le fasi, connettere l'ordinale di output della prima fase all'ordinale di input della seconda fase e eseguire la compilazione una sola volta. L'app fornisce i modelli e associa eventuali input esterni. Non è necessaria un'API runtime specifica del modello: embedding, decodificatore, pre-elaborazione delle immagini e altre architetture dell'applicazione usano le stesse primitive di fase e tensor.

Ciascun IWinMLStage possiede associazioni di input posizionali ed espone i relativi tensori di output correnti. Le associazioni di input vengono mantenute tra le esecuzioni. Chiama BindOutput prima dell'esecuzione quando l'app fornisce l'archiviazione di output.

Le funzionalità opzionali dello stage includono la destinazione risolta, lo schema materializzato, i criteri di residenza dell'output e il controllo dello stato della sequenza. Usare QueryInterface per testare ogni funzionalità.

Esecuzione della pipeline

IWinMLPipeline::Run esegue la pipeline preparata in modo sincrono. Chiamare ResetExecutionState tra sequenze indipendenti per cancellare lo stato gestito dal runtime.

Le interfacce di esecuzione facoltative forniscono l'invio della sequenza temporale del dispositivo e la riproduzione iterativa con conteggio fisso quando il grafo costruito e il back-end selezionato li supportano. Il percorso di base Run rimane la linea di base comune.

Tensori e blocchi

IWinMLTensor rappresenta dati tipizzati e multidimensionali. Creare tensori da una factory interrogata dalla destinazione di esecuzione in modo che il posizionamento dei tensori segua il posizionamento della destinazione.

Le factory coprono byte non elaborati, dati di immagine, dati audio, ID token e processori tensor componibili. Le interfacce tensor facoltative espongono mutazioni, associazioni di buffer D3D12 e sincronizzazione.

Chiamare IWinMLTensor::Lock prima di accedere ai byte del tensore nella CPU. L'oggetto restituito IWinMLTensorDataLock stabilisce la finestra di accesso alla CPU, esegue il mapping o la sincronizzazione richiesta e gestisce il ciclo di vita del puntatore restituito da GetData.

Raccolta e pesi esterni

La compilazione anticipata è una funzionalità facoltativa di una destinazione di esecuzione, esposta tramite IWinMLModelCompiler. Gli artefatti compilati vengono ricaricati tramite i normali metodi di caricamento del modello. Le app possono fornire pesi esternalizzati tramite IWinMLResourceMapReader.

Carichi di lavoro testuali

I workload di testo usano lo stesso runtime, target, pipeline, stage e primitive del tensore. L'app può gestire direttamente i metadati del pacchetto di modelli, il campionamento, i criteri di arresto e l'accumulo di token generati, oppure usare l'API Generazione testo per coordinare tali operazioni su una pipeline di runtime compatibile.

IWinMLTokenizer fornisce operazioni di codifica e decodifica di basso livello. Un IWinMLTokenizerDecoder oggetto mantiene un cursore indipendente di decodifica incrementale per una sequenza. L'API Generazione di testo aggiunge sessioni di generazione di testo, opzioni, aggiornamenti in streaming, annullamento, motivi di fine e risultati completati senza modificare la proprietà degli oggetti Runtime sottostanti.

Compatibilità del runtime ONNX

Le interfacce facoltative in WinMLRuntimeOrt.h forniscono praticità ONNX:

  • IWinMLOrtCompatibility seleziona un provider di esecuzione ONNX Runtime già registrato.
  • IWinMLOrtModelSchema riflette i nomi di input e output.
  • IWinMLOrtNamedBindings associa una fase supportata da ORT per nome.
  • IWinMLOrtStageDiagnostics report richiesti e fornitori selezionati dopo Build.

Queste interfacce risolvono i nomi e i criteri del provider durante l'installazione. L'esecuzione continua a usare lo stesso contratto di pipeline posizionale.

Eseguire una query IWinMLOrtCompatibility dal runtime per vincolare una fase del modello ONNX a un provider di esecuzione già registrato, anziché consentire Build di sceglierne uno automaticamente:

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

Il passaggio nullptr per hardwareTarget consente al runtime di associare il provider a uno dei propri dispositivi di tale classe hardware. Passare invece un oggetto esistente IWinMLExecutionTarget per vincolare il provider a quello specifico adattatore. Questa destinazione non è supportata per .gguf le fasi; Build restituisce HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

Vedere anche

  • Ultimo aggiornamento: