Kör ONNX-slutsatsdragning i DATAflödesdiagram för WebAssembly (WASM) (förhandsversion)

Den här artikeln visar hur du bäddar in och kör små ONNX-modeller (Open Neural Network Exchange) i dina WebAssembly-moduler för att utföra in-band-slutsatsdragning som en del av Dataflödesdiagram för Azure IoT Operations. Använd den här metoden för berikning och klassificering med låg latens direkt på strömmande data utan att anropa externa förutsägelsetjänster.

ONNX är ett öppet modellformat. I den här förhandsversionen körs slutsatsdragning endast på CPU via WEBAssembly System Interface (WASI) neurala nätverks-API (wasi-nn).

Varför använda ONNX-interferens i band

Med dataflödesdiagram för Azure IoT Operations kan du bädda in små ONNX-modellinferenser direkt i pipelinen i stället för att anropa en extern förutsägelsetjänst. Den här metoden erbjuder flera praktiska fördelar:

• Låg svarstid: Utför berikning eller klassificering i realtid i samma operatorsökväg där data tas emot. Varje meddelande medför endast lokal CPU-slutsatsdragning, vilket undviker nätverksresor.
• Kompakt fotavtryck: Inrikta sig på kompakta modeller som MobileNet-klassmodeller. Den här funktionen gäller inte för stora transformatormodeller, GPU/TPU-acceleration eller frekventa distributioner av A/B-modeller.
• Optimerad för specifika användningsfall:
  • I linje med flödesbearbetning från flera källor där funktioner redan är sammanställda i grafen
  • I linje med semantik för händelsetid använder slutsatsdragning samma tidsstämplar som andra operatorer
  • Hålls tillräckligt liten för att bädda in med modulen utan att överskrida praktiska begränsningar för WASM-storlek och minne
• Enkla uppdateringar: Skicka en ny modul med WASM och inbäddad modell och uppdatera sedan diagramdefinitionsreferensen. Du behöver inte ha ett separat modellregister eller en extern slutpunktsändring.
• Maskinvarubegränsningar: I den här förhandsversionen körs ONNX-serverdelen på CPU via WebAssembly System Interface (WASI) wasi-nn. Inga GPU/TPU-mål; endast ONNX-operatorer som stöds körs.
• Vågrät skalning: Slutsatsdragningen skalas när dataflödesdiagrammet skalar. När körtiden lägger till fler arbetare för genomströmning, läser varje arbetare in den inbäddade modellen och deltar i belastningsbalansering.

När du ska använda ONNX-inferens inom bandet

Använd in-band-slutsatsdragning när du har följande krav:

• Låg latens behöver berika eller klassificera meddelanden direkt vid intagstidpunkt.
• Små och effektiva modeller som MobileNet-klass vision eller liknande kompakta modeller
• Slutsatsdragning som måste anpassas till bearbetning av händelsetid och samma tidsstämplar som andra operatorer
• Enkla uppdateringar genom att skicka en ny modulversion med en uppdaterad modell

Undvik in-band-slutsatsdragning när du har följande krav:

• Stora transformatormodeller, GPU/TPU-acceleration eller avancerade A/B-distributioner
• Modeller som kräver flera tensor-indata, cachelagring av nyckelvärden eller ONNX-operatorer som inte stöds

Förutsättningar

Kontrollera att du har följande innan du börjar:

• En Azure IoT Operations-distribution med funktioner för dataflödesdiagram.
• Åtkomst till ett containerregister som Azure Container Registry.
• Utvecklingsmiljö som har konfigurerats för utveckling av WebAssembly-moduler.

Detaljerade installationsinstruktioner finns i Utveckla WebAssembly-moduler.

Arkitekturmönster

Det vanliga mönstret för ONNX-slutsatsdragning i dataflödesdiagram omfattar:

1. Förbearbeta data: Transformera rådata så att de matchar modellens förväntade format. För bildmodeller omfattar den här processen vanligtvis:
   • Avkodning av bildbyte.
   • Ändra storlek till en måldimension (till exempel 224×224).
   • Konverterar färgutrymmet (till exempel RGB till BGR).
   • Normalisera pixelvärden till det förväntade intervallet (0–1 eller -1 till 1).
   • Ordna data i rätt tensorlayout: NCHW (batch, kanaler, höjd, bredd) eller NHWC (batch, höjd, bredd, kanaler).
2. Kör inferens: Konvertera förbearbetade data till tensorer med hjälp av wasi-nn-gränssnittet, läs in din inbäddade ONNX-modell med CPU-bakänden, ange indata-tensorer i körningskontexten, anropa modellens framåtpass och hämta utdata-tensorer som innehåller råa förutsägelser.
3. Efterbearbetningsutdata: Omvandla råmodellutdata till meningsfulla resultat. Vanliga åtgärder:
   • Använd softmax för att skapa klassificeringsannolikheter.
   • Välj top-K-förutsägelser.
   • Använd ett förtroendetröskelvärde för att filtrera resultat med låg konfidens.
   • Mappa förutsägelseindex till mänskligt läsbara etiketter.
   • Formatera resultat för nedströmsförbrukning.

I IoT-exemplen för Rust WASM-operatorn hittar du två exempel som följer det här mönstret:

• Exempel på datatransformering: avkodar och ändrar storlek på bilder till RGB24 224×224.
• Exempel på bild-/videobearbetning av ögonblicksbilder: bäddar in en MobileNet v2 ONNX-modell, kör CPU-slutsatsdragning och beräknar softmax.

Konfigurera grafdefinition

Om du vill aktivera ONNX-slutsatsdragning i dataflödesdiagrammet måste du konfigurera både grafstrukturen och modulparametrarna. Grafdefinitionen anger pipelineflödet, medan modulkonfigurationer tillåter körningsanpassning av förbearbetnings- och slutsatsdragningsbeteende.

Aktivera stöd för WASI-NN

Om du vill aktivera stöd för WebAssembly Neural Network-gränssnittet lägger du till funktionen i grafdefinitionen wasi-nn :

moduleRequirements:
  apiVersion: "0.2.0"
  hostlibVersion: "0.2.0"
  features:
    - name: "wasi-nn"

Definiera åtgärder och dataflöde

Konfigurera de åtgärder som utgör din slutsatsdragningspipeline. Det här exemplet visar ett typiskt arbetsflöde för bildklassificering:

operations:
  - operationType: "source"
    name: "camera-input"
  - operationType: "map"
    name: "module-format/map"
    module: "format:1.0.0"
  - operationType: "map"
    name: "module-snapshot/map"
    module: "snapshot:1.0.0"
  - operationType: "sink"
    name: "results-output"

connections:
  - from: { name: "camera-input" }
    to: { name: "module-format/map" }
  - from: { name: "module-format/map" }
    to: { name: "module-snapshot/map" }
  - from: { name: "module-snapshot/map" }
    to: { name: "results-output" }

Den här konfigurationen skapar en pipeline där:

• camera-input tar emot rå bilddata från en källa
• module-format/map förbearbetar bilder (avkoda, ändra storlek, formatera konvertering)
• module-snapshot/map kör ONNX-slutsatsdragning och efterbearbetning
• results-output genererar klassificeringsresultat till en mottagare

Konfigurera modulparametrar

Definiera körningsparametrar för att anpassa modulbeteendet utan att omkompilera. Dessa parametrar skickas till DINA WASM-moduler vid initieringen:

moduleConfigurations:
  - name: module-format/map
    parameters:
      width:
        name: width
        description: "Target width for image resize (default: 224)"
        required: false
      height:
        name: height
        description: "Target height for image resize (default: 224)"
        required: false
      pixelFormat:
        name: pixel_format
        description: "Output pixel format (rgb24, bgr24, grayscale)"
        required: false

  - name: module-snapshot/map
    parameters:
      executionTarget:
        name: execution_target
        description: "Inference execution target (cpu, auto)"
        required: false
      labelMap:
        name: label_map
        description: "Label mapping strategy (embedded, imagenet, custom)"
        required: false
      scoreThreshold:
        name: score_threshold
        description: "Minimum confidence score to include in results (0.0-1.0)"
        required: false
      topK:
        name: top_k
        description: "Maximum number of predictions to return (default: 5)"
        required: false

Operatören init kan läsa dessa värden via modulkonfigurationsgränssnittet. Mer information finns i Modulkonfigurationsparametrar.

Paketera modellen

Genom att bädda in ONNX-modeller direkt i DIN WASM-komponent säkerställs atomisk distribution och versionskonsekvens. Den här metoden förenklar distributionen och tar bort körningsberoenden för externa modellfiler eller register.

Riktlinjer för modellförberedelse

Innan du bäddar in din modell kontrollerar du att den uppfyller kraven för WASM-distribution:

• Håll modeller under 50 MB för praktiska WASM-inläsningstider och minnesbegränsningar.
• Kontrollera att din modell accepterar en enda tensor-indata i ett gemensamt format (float32 eller uint8).
• Kontrollera att SERVERDELEN FÖR WASM ONNX-körning stöder varje operatör som din modell använder.
• Använd VERKTYG för ONNX-optimering för att minska modellstorleken och förbättra slutsatsdragningshastigheten.

Arbetsflöde för inbäddning

Följ dessa steg för att bädda in din modell och associerade resurser:

1. Ordna modelltillgångar: Placera .onnx modellfilen och valfri labels.txt i källträdet. Använd en dedikerad katalogstruktur, till exempel src/fixture/models/ och src/fixture/labels/ för en tydlig organisation.
2. Bädda in vid kompileringstid: Använd språkspecifika mekanismer för att inkludera modellbyte i binärfilen. I Rust använder du include_bytes! för binära data och include_str! för textfiler.
3. Initiera WASI-NN graf: I operatorns init funktion skapar du en wasi-nn graf från de inbäddade bytea och anger ONNX-kodnings- och CPU-körningsmålet.
4. Implementera slutsatsdragningsloop: För varje inkommande meddelande, förbearbeta indata för att matcha modellkrav, ange indata tensorer, köra slutsatsdragning, hämta utdata och tillämpa efterbearbetning.
5. Hantera fel korrekt: Implementera korrekt felhantering för modellinläsningsfel, operatorer som inte stöds och körningsinferensfel.

Ett fullständigt implementeringsmönster finns i exemplet "ögonblicksbild".

Rekommenderad projektstruktur

Organisera ditt WASM-modulprojekt med tydlig uppdelning av problem:

src/
├── lib.rs                 # Main module implementation
├── model/
│   ├── mod.rs            # Model management module
│   └── inference.rs      # Inference logic
└── fixture/
    ├── models/
    │   ├── mobilenet.onnx      # Primary model
    │   └── mobilenet_opt.onnx  # Optimized variant
    └── labels/
        ├── imagenet.txt        # ImageNet class labels
        └── custom.txt          # Custom label mappings

Exempelfilreferenser

Använd följande fillayout från exemplet "snapshot" som referens:

• Etikettkatalog – Innehåller olika mappningsfiler för etiketter
• Modellkatalog – Innehåller ONNX-modellfiler och metadata

Minimalt inbäddningsexempel

I det följande exemplet visas minimal inbäddning i Rust. Sökvägarna är relativa till källfilen som innehåller makrot:

// src/lib.rs (example)
// Embed ONNX model and label map into the component
static MODEL: &[u8] = include_bytes!("fixture/models/mobilenet.onnx");
static LABEL_MAP: &[u8] = include_bytes!("fixture/labels/synset.txt");

fn init_model() -> Result<(), anyhow::Error> {
  // Create wasi-nn graph from embedded ONNX bytes using the CPU backend
  // Pseudocode – refer to the snapshot sample for the full implementation
  // use wasi_nn::{graph::{load, GraphEncoding, ExecutionTarget}, Graph};
  // let graph = load(&[MODEL.to_vec()], GraphEncoding::Onnx, ExecutionTarget::Cpu)?;
  // let exec_ctx = Graph::init_execution_context(&graph)?;
  Ok(())
}

Prestanda optimering

Om du vill undvika att återskapa ONNX-grafen och körningskontexten för varje meddelande initierar du det en gång och återanvänder det. Det offentliga exemplet använder en statisk LazyLock:

use std::sync::LazyLock;
use wasi_nn::{graph::{load, Graph, GraphEncoding, ExecutionTarget}, GraphExecutionContext};

static mut CONTEXT: LazyLock<GraphExecutionContext> = LazyLock::new(|| {
  let graph = load(&[MODEL.to_vec()], GraphEncoding::Onnx, ExecutionTarget::Cpu).unwrap();
  Graph::init_execution_context(&graph).unwrap()
});

fn run_inference(/* input tensors, etc. */) {
  unsafe {
    // (*CONTEXT).set_input(...)?; (*CONTEXT).compute()?; (*CONTEXT).get_output(...)?;
  }
}

Distribuera dina moduler

Återanvänd de strömlinjeformade exempelbyggarna eller bygget lokalt:

• Information om hur du använder den strömlinjeformade Docker-byggaren finns i Rust Docker Builder-exempel
• En allmän WebAssembly-distribution och registersteg finns i Använda WebAssembly med dataflödesdiagram

Följ den här distributionsprocessen:

1. Skapa din WASM-modul i produktionsläge och generera en <module-name>-<version>.wasm-fil.
2. Ladda upp modulen och eventuellt en grafdefinition till registret med hjälp av OCI Registry som lagringsplats (ORAS).
3. Skapa eller återanvända en registerslutpunkt i Azure IoT Operations.
4. Skapa en dataflödesdiagramresurs som refererar till din diagramdefinitionsartefakt.

Exempel: MobileNet-bildklassificering

De offentliga IoT-exemplen innehåller två exempel som är kopplade till ett diagram för bildklassificering: exemplet "format" innehåller bilddekodning och storleksändringsfunktioner, och exemplet "snapshot" innehåller ONNX-slutsatsdragning och softmax-bearbetning.

Om du vill distribuera det här exemplet hämtar du artefakterna från det offentliga registret, push-överför dem till registret och distribuerar ett dataflödesdiagram enligt exempel 2: Distribuera ett komplext diagram. Det komplexa diagrammet använder dessa moduler för att bearbeta ögonblicksbilder av bilder och generera klassificeringsresultat.

Begränsningar

Den här förhandsversionen har följande begränsningar:

• ENDAST ONNX. Dataflödesdiagram stöder inte andra format som TFLite.
• Endast CPU. Ingen GPU/TPU-acceleration.
• Små modeller rekommenderas. Stora modeller och minnesintensiv slutsatsdragning stöds inte.
• Modeller med enkla tensorindata stöds. Modeller med flera indata, cachelagring av nyckelvärden och avancerade sekvenser eller generativa scenarier stöds inte.
• Kontrollera att ONNX-serverdelen i WASM-körningen stöder modellens operatorer. Om en operator inte stöds misslyckas slutsatsdragningen vid belastnings- eller körningstidpunkten.

Relaterat innehåll

• Utveckla WebAssembly-moduler
• Konfigurera WebAssembly-grafdefinitioner
• Använda WebAssembly med dataflödesdiagram