Kompilera och cachelagera ONNX-modeller i Windows ML

Kompilering är det steg som omvandlar din ONNX-modell till den maskinvaruspecifika binärfil som en körningsprovider (EP) faktiskt kör. På NPU:er och GPU:er kan det ta allt från några sekunder till flera minuter för stora modeller – och om appen inte cachelagr resultatet betalar användarna den kostnaden varje gång appen startar.

Den här sidan förklarar vad kompilering innebär, när du ska förkompilera och hur du validerar en cachelagrad kompilerad modell innan du återanvänder den.

Förutsättningar

API:erna för kompilerad modellkompatibilitet kräver Windows ML 2.3 eller senare. I uppströmsversionen av ONNX Runtime finns GetModelCompatibilityForEpDevices() i version 1.23 och GetCompatibilityInfoFromModel() i version 1.24.

Två typer av kompilering

"Kompilering" kan betyda två olika saker. Om du separerar dem blir resten av den här sidan enklare att resonera kring:

  • Grafoptimering – Fusion, konstant vikning och layoutarbete som ONNX Runtime utför när sessionen skapas. Det är billigt, EP-agnostiskt och körs varje gång du skapar en session.
  • EP-kompilering – Konvertering av ONNX-grafen till en EP:s eget format, följt av kompilering ned till en maskinvaruspecifik binär fil. Maskinvaru-EPs (QNN, OpenVINO, VitisAI, NvTensorRtRtx, MIGraphX) gör detta, och det är det dyra steget. På NPU:er kan det ta tiotals sekunder till minuter för större modeller.

Windows ML undviker återbetalande EP-kompilering med hjälp av ONNX Runtimes EPContext-mekanism. Den första kompileringen serialiserar en maskinvaruklar binärfil till en *_ctx.onnx modell (eller en sidovagn .bin); senare sessioner läser in den fördefinierade binära filen och hoppar över konverteringen helt.

Varför förkompileras?

Windows ML rekommenderar varmt förkompilering när du använder exekveringsprovidrar. Att förkompilera omvandlar en kallstart på flera sekunder – ibland flera minuter lång – till en engångskostnad, och ger din app:

  • Snabb kallstart – efterföljande uppskjutningar hoppar över grafkonvertering och maskinvarukompilering.
  • Förutsägbart beteende – plattformen stöder kontroll av om en kompilerad modell är optimal för de enheter som appen väljer innan du skapar en slutsatsdragningssession.
  • Lägre processor- och batterianvändning – du slutar kompilera om samma graf vid varje start.

Utan förkompilering kör din app ep-konvertering och kompilering på nytt vid varje skapande av sessioner, och användarna känner fördröjningen varje gång.

När du ska förkompilera

Kompilera i förväg när din app riktar in sig på en maskinvaru-EP. Det finns två alternativ för tidsinställningar:

Strategy Bäst för Trade-offs
Förhandskompilering (AOT) — kompilera vid bygg- eller installationstillfället och leverera den kompilerade artefakten. Kontrollerade maskinvaru- och drivrutinsflottor eller installationsprogram per enhet. Kräver korskompileringsverktyg för mål som byggdatorn inte kan köra. Validera artefakten på målenheten och tillhandahåll en reservlösning vid omkompilering.
Kompilera vid förstakörningen (rekommenderas för bred distribution) – sök efter en kompilerad artefakt, kompilera den om den saknas och cachelagrar och återanvänder den. Lagra appar och allmän konsumentdistribution över olika maskinvarubaser. Användarna betalar kompileringskostnaden en gång vid första starten.

Genomgången av Windows ML demonstrerar de grundläggande mekanismerna för kompilering vid första körningen genom att kontrollera om en kompilerad artefakt finns. Det är inte ett fullständigt exempel på cachehantering. Innan du återanvänder en befintlig kompilerad modell i en app ska du tillämpa kompatibilitetskontrollen som beskrivs i den här artikeln. Kompilerings-API:et i kontext finns i Kompilera modeller.

Verifiera en kompilerad modell innan den återanvänds

En kompilerad modell kan vara beroende av den EP- och enhetskonfiguration som producerade den. EP avgör om en cachelagrad modell förblir kompatibel och optimal för en uppsättning enheter.

Under kompilering kan en EP generera en null-avslutad UTF-8-kompatibilitetssträng som ONNX Runtime skriver till den kompilerade modellens metadataegenskaper. Strängens format och innehåll definieras av EP:n. Din app ska inte parsa eller tolka den.

Din app skickar strängen och EP-målenheterna till GetModelCompatibilityForEpDevices(). ONNX Runtime anropar EP-fabrikens valideringsimplementering och returnerar status OrtCompiledModelCompatibility . För källkontrakten, se GetModelCompatibilityForEpDevices() och ValidateCompiledModelCompatibilityInfo() i ONNX Runtime-lagringsplatsen.

Scenarier för kompatibilitetskontroll

Du kan använda samma validerings-API i två scenarier:

  • Verifiera en modell som redan finns på enheten. Anropa GetCompatibilityInfoFromModel() för att extrahera strängen från en kompilerad modellfil. Om modellen redan finns i minnet anropar du GetCompatibilityInfoFromModelBytes(). Skicka sedan strängen till GetModelCompatibilityForEpDevices().
  • Verifiera innan du laddar ned en kompilerad modell. Publicera den opaka strängen som lättviktsmetadata tillsammans med den kompilerade modellen. Appen kan hämta strängen först, verifiera den med GetModelCompatibilityForEpDevices()och ladda ned den potentiellt stora modellen endast när den returnerade statusen uppfyller din cache- eller distributionsprincip.

Håll metadata för fjärrkompatibilitet kopplade till den exakta kompilerade artefakten som skapade den. Om artefakten ändras uppdaterar du den associerade kompatibilitetssträngen.

I båda scenariona:

  1. Anropa GetEpDevices() för att räkna upp tillgängliga EP-enheter och tillämpa sedan samma EP- eller enhetsprincip som du använder för att konfigurera slutsatsdragningssessionen.
  2. Hämta kompatibilitetssträngen från den lokala modellen eller från metadata som är associerade med en fjärrmodell.
  3. Skicka strängen och den matchande enhetsgruppen till GetModelCompatibilityForEpDevices().
  4. Tillämpa din cache- eller nedladdningsprincip på den returnerade statusen. Windows ML-exempel använder en konservativ princip och accepterar endast den kompilerade modellen för EP_SUPPORTED_OPTIMAL.

GetCompatibilityInfoFromModel() parsar hela ONNX ModelProto från disken. Använd fjärrmetadatamönstret när du behöver fatta ett kompatibilitetsbeslut innan du laddar ned själva modellen.

API:erna returnerar ett OrtCompiledModelCompatibility värde:

Status Meaning Rekommenderad åtgärd
EP_SUPPORTED_OPTIMAL Den kompilerade modellen stöds och är optimal för EP-enheterna. Återanvänd den kompilerade modellen.
EP_SUPPORTED_PREFER_RECOMPILATION Den kompilerade modellen stöds, men EP rekommenderar omkompilering för bättre prestanda. Modellen kan köras, men en cacheprincip med enbart optimalt läge kompilerar om den.
EP_UNSUPPORTED Den kompilerade modellen stöds inte av de aktuella EP-enheterna. Läs inte in den kompilerade modellen. Kompilera om eller använd den ursprungliga modellen.
EP_NOT_APPLICABLE EP:n angav inte någon kompatibilitetsbestämning för de angivna enheterna. Detta är också standard när EP:n inte implementerar kompatibilitetsverifiering. Behandla inte den här statusen som bevis för att cacheminnet är kompatibelt. Använd den ursprungliga modellen om inte din app har en annan valideringsprincip.

Under en cacheprincip som endast är optimal behandlar du saknade kompatibilitetsmetadata för den föredragna EP:n som en cachemiss. Om kompatibilitetsutvärderingen returnerar ett fel använder du den ursprungliga modellen för den körningen och höjer inte upp en nyligen kompilerad artefakt eftersom appen inte kan verifiera den.

Händelser som kan kräva en ny cachepost är:

  • En ny EP har installerats.
  • GPU- eller NPU-drivrutinen uppdateras.
  • Användarens maskinvaruändringar.
  • ONNX-källmodellen ändras.
  • Din app ändrar inställningarna för ONNX Runtime, EP eller kompilering som används för att skapa artefakten.

API:erna för kompatibilitet verifierar en befintlig kompilerad artefakt mot EP-enheter. de avgör inte om artefakten har skapats från den aktuella källmodellen. Inkludera en källmodellversion eller hash i cachenyckeln och ogiltigförklara cacheminnet när kompileringsindata ändras.

Om din app är distribuerad över en mängd olika enheter lagrar du kompilerade artefakter på en lokal cacheplats så att varje enhet producerar och återanvänder sin egen binärfil.

Grundläggande kompatibilitetskontroll

Följande hjälpfunktioner kontrollerar en kompilerad modell för en EP. Innan du anropar en helper tillämpar du samma EP- eller enhetsprincip som du använder för att konfigurera inferenssessionen. Enhetssamlingen får inte vara tom och måste innehålla enheter från samma EP.

static bool IsCompiledModelOptimal(
    OrtEnv ortEnv,
    string compiledModelPath,
    string epName,
    IReadOnlyList<OrtEpDevice> epDevices)
{
    string compatibilityInfo =
        ortEnv.GetCompatibilityInfoFromModel(compiledModelPath, epName);

    return !string.IsNullOrWhiteSpace(compatibilityInfo) &&
        ortEnv.GetModelCompatibilityForEpDevices(
            epDevices,
            compatibilityInfo) ==
        OrtCompiledModelCompatibility.EP_SUPPORTED_OPTIMAL;
}

Använd kontrollen innan sessionen skapas:

  • Om resultatet uppfyller appens kompatibilitetsprincip använder du den kompilerade modellen.
  • Annars kan du använda eller kompilera om den ursprungliga modellen.

De Windows ML-exemplen använder en konservativ princip och accepterar endast EP_SUPPORTED_OPTIMAL. Din app avgör hur du lagrar, uppdaterar och ersätter kompilerade modeller.

Kompilera modeller

Innan du använder en ONNX-modell i en slutsatsdragningssession måste den ofta kompileras till en optimerad representation som kan köras effektivt på enhetens underliggande maskinvara.

Från och med ONNX Runtime 1.22 finns det nya API:er som bättre kapslar in kompileringsstegen. Mer information finns i dokumentationen för ONNX Runtime-kompilering (se OrtCompileApi struct).

// Prepare compilation options
OrtModelCompilationOptions compileOptions = new(sessionOptions);
compileOptions.SetInputModelPath(modelPath);
compileOptions.SetOutputModelPath(compiledModelPath);

// Compile the model
compileOptions.CompileModel();

Anmärkning

Kompilering kan ta flera minuter att slutföra. Så att alla användargränssnitt förblir dynamiska kan du överväga att göra detta som en bakgrundsåtgärd i ditt program eller varna användaren om att en modell håller på att förberedas.

Se även