Panoramica dell'API di Ml Runtime di Windows

Importante

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

Importante

L'API di runtime Windows ML è attualmente disponibile in C++ e Python; C# non è attualmente supportato. Segnalare se si è interessati a usare queste API da C# aprendo un issue nel repo GitHub di Windows ML.

L'API runtime di Windows ML è un framework locale di inferenza di intelligenza artificiale C/C++ nativo progettato specificamente per Windows. Con l'API di runtime di ML Windows è possibile caricare un modello, scegliere una destinazione di esecuzione cpu, GPU o NPU (incluso un adattatore DXCore specifico o un dispositivo D3D12), associare tensori a tale destinazione, comporre le fasi del modello e del processore in una pipeline, compilare la pipeline ed eseguirla per produrre tensori di output.

Le API facoltative di generazione del testo e di riconoscimento vocale compongono questi stessi oggetti runtime in flussi di lavoro di livello superiore su un modello fornito dall'app: vedere Generare testo con il proprio modello linguistico usando Windows ML e Riconoscere il parlato con il proprio modello Whisper usando Windows ML.

API di runtime vs ONNX Runtime

Se l'app è destinata solo a Windows (e si è disposti a usare le API attualmente sperimentali), usare l'API di runtime. Fornisce un controllo esplicito sulla selezione hardware (incluso un adattatore DXCore specifico o un dispositivo D3D12), sulla residenza dei tensori, sul posizionamento della pipeline a più fasi e sulla compilazione.

In caso contrario, se l'app deve essere eseguita in altre piattaforme o ha già codice di sessione ONNX Runtime multipiattaforma, usare invece le API di ONNX Runtime incluse in Windows ML.

Modello a oggetti di base

Concetto API principale Description
Runtime IWinMLRuntime Interfaccia restituita da WinMLCreateRuntime; carica i file di modello, crea destinazioni di esecuzione e crea builder di pipeline.
Model IWinMLModel Artefatto del modello opaco non modificabile caricato da un file o da un buffer. Riflette lo schema dichiarato tramite IWinMLModelSchema.
Destinazione di esecuzione IWinMLExecutionTarget Token di posizionamento CPU, GPU o NPU usato per creare fasi e creare tensori.
Builder di pipeline IWinMLPipelineBuilder Aggiunge fasi del modello e del processore, le connette e crea una pipeline preparata.
Pipeline IWinMLPipeline Grafo preparato, immediatamente eseguibile che esegue tensori associati e produce tensori di output.
Stage IWinMLStage Passaggio della pipeline che possiede le associazioni di input e output posizionali e la relativa destinazione di esecuzione risolta.
Tensore IWinMLTensor Dati multidimensionali tipizzati associati a input e output di fase.
Generazione di testo/riconoscimento vocale API di Windows ML per la generazione del testo e il riconoscimento vocale Flusso di lavoro di livello superiore composto su oggetti Runtime di proprietà del chiamante, con sessioni, flussi e risultati tipizzati.

Scegli un back-end e una destinazione di esecuzione

LoadModelFromFile seleziona il back-end dall'estensione del file dell'artefatto del modello. L'app usa gli stessi oggetti runtime, ovvero modello, destinazione di esecuzione, generatore di pipeline, fasi, associazioni e Run , indipendentemente dal back-end che carica il file.

File del modello Backend Accelerazione hardware
.onnx, .ort Runtime ONNX Provider di esecuzione (EP) che Windows installa e mantiene aggiornati attraverso il catalogo EP di Windows ML
.gguf llama.cpp Un modulo CPU locale dell'app, oltre a un modulo CUDA facoltativo per GPU NVIDIA da distribuire insieme all'app. CPU e CUDA sono gli unici back-end llama.cpp Windows ML convalidati per questa versione.

Una destinazione di esecuzione rappresenta una classe hardware ( CPU, GPU o NPU ) creata con IWinMLRuntime. Riutilizzare un target per creare stage e creare tensori: il riutilizzo di un target esprime l'affinità con lo stesso target, mentre l'uso di target distinti rende espliciti i limiti di trasferimento tra target. Quando viene eseguito il metodo del generatore di Build pipeline, il runtime inserisce ogni fase nel back-end di esecuzione per la destinazione e garantisce la compatibilità tra destinazione e back-end.

Per una classe hardware senza enumerare manualmente i dispositivi, chiamare CreateExecutionTarget con un WINML_EXECUTION_TARGET_KIND e un oggetto WINML_EXECUTION_TARGET_PREFERENCE che classifica i candidati di tale classe, ad esempio una GPU integrata rispetto a una GPU discreta. Trattare ERROR_NOT_FOUND e ERROR_NOT_SUPPORTED allo stesso modo ed eseguire il fallback a un'altra classe:

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 equivale a richiedere il tipo di CPU. CreateExecutionTargetFromAdapter e CreateExecutionTargetFromD3D12 associano un target a un adattatore DXCore specifico o a un dispositivo D3D12 invece di consentire al runtime di sceglierne uno. Per i modelli ONNX che dipendono da un provider di esecuzione installato (EP), una superficie di compatibilità ONNX Runtime facoltativa consente di vincolare un provider già registrato. Ogni back-end risolve queste destinazioni in modo diverso, ad esempio il back-end llama.cpp usato dai .gguf modelli richiede almeno un offload GPU parziale per rispettare una destinazione GPU e non supporta le destinazioni NPU o il vincolo del provider. Per la matrice completa della risoluzione di destinazione per back-end e per una procedura dettagliata sull'esecuzione di un modello GGUF, vedere Concetti dell'API di Windows ML Runtime.

Passaggi successivi

  • Ultimo aggiornamento: