Använda gRPC-tilläggsprotokollet


Med Azure Video Analyzer kan du förbättra dess pipelinebearbetningsfunktioner via en pipelinetilläggsnod. GRPC-tilläggsprocessorn möjliggör utökningsscenarier med ett mycket effektivt, strukturerat, gRPC-baserat protokoll.

I den här artikeln får du lära dig hur du använder gRPC-tilläggsprotokollet för att skicka meddelanden mellan Video Analyzer-modulen och din gRPC-server som bearbetar dessa meddelanden och returnerar resultat. gRPC är ett modernt RPC-ramverk med öppen källkod med höga prestanda som körs i alla miljöer och stöder kommunikation mellan plattformar och mellan språk. Transporttjänsten gRPC använder HTTP/2 dubbelriktad strömning mellan:

  • gRPC-klienten (Video Analyzer-modulen) och
  • gRPC-servern (ditt anpassade tillägg).

En gRPC-session är en enskild anslutning från gRPC-klienten till gRPC-servern via TCP/TLS-porten. I en enda session: Klienten skickar en beskrivning av medieströmmen följt av bildrutor till servern som ett protobuf-meddelande över gRPC-strömsessionen. Servern verifierar dataströmsbeskrivningen, analyserar videoramen och returnerar härledningsresultat som ett protobuf-meddelande.

Vi rekommenderar starkt att svar returneras med giltiga JSON-dokument som följer det fördefinierade schemat som definierats enligt objektmodellen för inferensmetadataschemat. Detta säkerställer bättre samverkan med andra komponenter och scenarier som inspelning och uppspelning av video med härledningsmetadata.

Azure Video Analyzer module

Implementera gRPC-protokoll

Skapa en gRPC-anslutning

Anpassat tillägg måste implementera följande gRPC-tjänst:

service MediaGraphExtension
    {
        rpc ProcessMediaStream(stream MediaStreamMessage) returns (stream MediaStreamMessage);
    }

När den anropas öppnas en dubbelriktad dataström där meddelanden flödar mellan gRPC-tillägget och Video Analyzer-livepipelinen. Det första meddelandet som skickas i den här strömmen av varje part innehåller en MediaStreamDescriptor, som definierar vilken information som ska skickas i följande MediaSamples.

Tillägget kan till exempel skicka meddelandet (uttryckt här i JSON) för att ange att det kommer att skicka rgb24-kodade bildrutor med 416 x 416 inbäddade bildrutor som är inbäddade i gRPC-meddelandena till det anpassade tillägget.

 {
    "sequence_number": 1,
    "ack_sequence_number": 0,
    "media_stream_descriptor": 
    {
        "graph_identifier": 
        {
            "media_services_arm_id": "/subscriptions/{subscriptionID}/resourceGroups/{resource-group-name}/providers/microsoft.media/videoanalyzers/{video-analyzer-account-name}",
            "graph_instance_name": "{live-pipeline-name}",
            "graph_node_name": "{grpc-extension-node-name}"
        },
        "media_descriptor": 
        {
            "timescale": 90000,
            "video_frame_sample_format": 
            {
                "encoding": "RAW",
                "pixel_format": "RGB24",
                "dimensions": 
                {
                    "width": 416,
                    "height": 416
                },
                "stride_bytes": 1248
            }
        }
    }
}

Det anpassade tillägget skulle som svar skicka följande meddelande för att indikera att det endast returnerar slutsatsledning.

{
    "sequence_number": 1,
    "ack_sequence_number": 1,
    "media_stream_descriptor": 
    {
        "extension_identifier": "customExtensionName"    
    }
}

Nu när båda sidor har utväxlade mediebeskrivningar börjar Video Analyzer överföra bildrutor till gRPC-servern.

Anteckning

GRPC-servern kan implementeras med val av programmeringsspråk.

Sekvensnummer

Både gRPC-tilläggsnoden och det anpassade tillägget har en separat uppsättning sekvensnummer som tilldelas till sina meddelanden. Dessa sekvensnummer bör monotont öka med början från 1. ack_sequence_number kan ignoreras om inget meddelande bekräftas, vilket kan inträffa när det första meddelandet skickas.

En begäran måste bekräftas när motsvarande meddelande har bearbetats fullständigt. Vid en delad minnesöverföring anger den här bekräftelsen att avsändaren kan frigöra det delade minnet och att mottagaren inte kommer åt det längre. Avsändaren måste innehålla allt delat minne tills det har bekräftats.

Läsa inbäddat innehåll

Inbäddat innehåll kan läsas direkt från MediaSample-meddelandet via content_bytes-fältet. Data kodas enligt MediaDescriptor.

Läsa innehåll från delat minne

Vid överföring av innehåll via delat minne inkluderar avsändaren SharedMemoryBufferTransferProperties i MediaStreamDescriptor när de först upprättar en session. Detta kan se ut så här (uttryckt i JSON):

{
  "handle_name": "inference_client_share_memory_2146989006636459346"
  "length_bytes": 20971520
}

Mottagaren öppnar sedan filen /dev/shm/inference_client_share_memory_2146989006636459346. Avsändaren skickar ett MediaSample-meddelande som innehåller en ContentReference som refererar till en specifik plats i den här filen.

{
    "timestamp": 143598615750000,
    "content_reference": 
    {
        "address_offset": 519168,
        "length_bytes": 173056
    }
}

Mottagaren läser sedan data från den här platsen i filen.

För att Video Analyzer-gränsmodulen ska kunna kommunicera över delat minne måste IPC-läget för containern vara korrekt konfigurerat. Detta kan göras på många sätt, men här är några rekommenderade konfigurationer.

  • När du kommunicerar med en gRPC-inferensmotor som körs på värdenheten ska IPC-läget vara inställt på värd.
  • När du kommunicerar med en gRPC-server som körs i en annan IoT Edge-modul ska IPC-läget anges till för Video Analyzer-modulen och för det anpassade tillägget, om är namnet på shareablecontainer:avaedge Video avaedge Analyzer-modulen.

Så här kan det se ut i enhetstvillingen med det första alternativet ovan.

"avaedge": 
{
  "version": "1.0",
  "type": "docker",
  "status": "running",
  "restartPolicy": "always",
  "settings": 
  {
    "image": "mcr.microsoft.com/media/video-analyzer:1",
    "createOptions": 
      "HostConfig": 
      {
        "IpcMode": "shareable"
      }
  }
}

Mer information om IPC-lägen finns i IPC-inställningar (--ipc).

Definitionerna för gRPC-tilläggskontraktet i Video Analyzer

I det här avsnittet definieras det gRPC-kontrakt som definierar dataflödet.

Protokollmeddelanden

Video Analyzer protocol messages

Klientautentisering

Implementerare av anpassade tillägg kan verifiera äktheten för inkommande gRPC-anslutningar för att vara säkra på att de kommer från gRPC-tilläggsnoden. Noden tillhandahåller en post i begärandehuvuden att verifiera mot.

Autentiseringsuppgifter för användarnamn/lösenord kan användas för att åstadkomma detta. När du skapar en gRPC-tilläggsnod anges autentiseringsuppgifterna på följande sätt:

{
  "@type": " #Microsoft.VideoAnalyzer.GrpcExtension ",
  "name": "{moduleIdentifier}",
  "endpoint": 
  {
    "@type": " #Microsoft.VideoAnalyzer.UnsecuredEndpoint ",
    "url": "tcp://customExtension:8081",
    "credentials": 
    {
      "@type": "#Microsoft. VideoAnalyzer.UsernamePasswordCredentials",
      "username": "username",
      "password": "password"
    }
  }
  // Other fields omitted
}

När gRPC-begäran skickas tas följande huvud med i begärandemetadata, imiterar HTTP Basic-autentisering.

x-ms-authentication: Basic (Base64 Encoded username:password)

Konfigurera inferensservern för varje live-pipeline via gRPC-tillägg

När du konfigurerar inferensservern behöver du inte exponera en nod för varje AI-modell som är paketerad på inferensservern. För en live-pipeline kan du i stället använda egenskapen för extensionConfigurationextensionConfiguration och definiera hur AI-modellen ska väljas. Under körningen skickar Video Analyzer den här strängen till inferencing-servern som kan använda den för att anropa den önskade AI-modellen. Det extensionConfiguration property här är en valfri egenskap som är specifik för din implementering av gRPC-servern. Egenskapen kan användas på följande sätt:

{
  "@type": "#Microsoft.VideoAnalyzer.GrpcExtension",
  "name": "{moduleIdentifier}",
  "endpoint": 
  {
    "@type": "#Microsoft.VideoAnalyzer.UnsecuredEndpoint",
    "url": "${grpcExtensionAddress}",
    "credentials": 
    {
      "@type": "#Microsoft.VideoAnalyzer.UsernamePasswordCredentials",
      "username": "${grpcExtensionUserName}",
      "password": "${grpcExtensionPassword}"
    }
  },
    // Optional server configuration string. This is server specific 
  "extensionConfiguration": "{Optional extension specific string}",
  "dataTransfer": 
  {
    "mode": "sharedMemory",
    "SharedMemorySizeMiB": "75"
  }
    //Other fields omitted
}

Använda gRPC över TLS

En gRPC-anslutning som används för inferens kan skyddas via TLS. Detta är användbart i situationer där säkerheten i nätverket mellan Video Analyzer och inferensmotorn inte kan garanteras. TLS krypterar allt innehåll som är inbäddat i gRPC-meddelandena, vilket orsakar ytterligare PROCESSORkostnader vid överföring av bildrutor med hög hastighet.

Verifieringsalternativen och stöds inte av gRPC, så servercertifikatet som inferensmotorn presenterar måste innehålla ett eget namn (CN) som exakt matchar IgnoreHostnameIgnoreSignature IP-adressen/värdnamnet i slutpunkts-URL:en för gRPC-tilläggsnoden.

Nästa steg

Lär dig mer om schemat för slutsatsledningsmetadata

edge icon
Du kan också läsa avsnitten under Skapa videoprogram i tjänsten.