Google Cloud Vision su gRPC in Delphi

5 giugno 2026 · Componenti

Google Cloud Vision analizza le immagini e ti dice cosa contengono: restituisce etichette descrittive, legge testo stampato e manoscritto (OCR), rileva volti, riconosce luoghi noti e loghi famosi e altro ancora. sgcWebSockets Enterprise include un client gRPC Vision tipizzato che poggia sopra TsgcGRPCClient, così puoi inviare un'immagine e leggere di ritorno le sue annotazioni da Delphi e C++Builder senza alcun runtime esterno o protobuf scritto a mano.

Come funziona

Cloud Vision espone un servizio gRPC ImageAnnotator. Una richiesta è un batch di una o più immagini, ciascuna accoppiata con la lista delle feature che vuoi rilevare, e la risposta è un batch corrispondente di annotazioni. L'intero scambio è costituito da messaggi Protocol Buffers incapsulati su HTTP/2.

sgcWebSockets include già uno stack HTTP/2 completo, quindi il trasporto è un TsgcHTTP2Client puntato a vision.googleapis.com:443 su TLS. TsgcGRPCClient poggia sopra di esso e fa l'incapsulamento gRPC, gli header, i timeout e l'analisi dei trailer. Le classi di messaggi Vision in sgcGRPC_Google_Vision sono helper protobuf tipizzati: compili l'oggetto richiesta, chiami ToBytes per serializzarlo, lo invii con il client generico e ricarichi i byte della risposta in un oggetto risposta tipizzato con LoadFromBytes.

L'autenticazione è il flusso standard con account di servizio Google. Un JWT autofirmato viene scambiato con un token bearer e inviato come metadata gRPC su ogni chiamata. Poiché il JWT è vincolato all'audience, il token è puntato all'endpoint Vision in modo che vision.googleapis.com lo accetti.

Configurare i client

Crea il trasporto HTTP/2, collega ad esso il client gRPC e indica al canale di usare il content type protobuf binario. Vision parla application/grpc+proto.

uses
  sgcHTTP2_Client, sgcGRPC_Types, sgcGRPC_Client,
  sgcGRPC_Google_Vision;

var
  HTTP2: TsgcHTTP2Client;
  GRPC: TsgcGRPCClient;
begin
  HTTP2 := TsgcHTTP2Client.Create(nil);
  HTTP2.Host := 'vision.googleapis.com';
  HTTP2.Port := 443;
  HTTP2.TLS  := True;

  GRPC := TsgcGRPCClient.Create(nil);
  GRPC.Client := HTTP2;
  GRPC.ChannelOptions.ContentType := grpcProto;
  GRPC.ChannelOptions.Compression := grpcNoCompression;
end;

Autenticazione

Il token bearer proviene dalle tue credenziali dell'account di servizio. Configura le opzioni JWT con i valori dalla chiave JSON scaricata, punta l'audience all'endpoint Vision e aggiungi il token risultante a DefaultMetadata in modo che viaggi su ogni chiamata gRPC.

// configure the service-account JWT (values from the JSON key file)
CloudClient.GoogleCloudOptions.Authentication := gcaJWT;
CloudClient.GoogleCloudOptions.JWT.ClientEmail  := ClientEmail;
CloudClient.GoogleCloudOptions.JWT.PrivateKeyId := PrivateKeyId;
CloudClient.GoogleCloudOptions.JWT.PrivateKey.Text := PrivateKey;
CloudClient.GoogleCloudOptions.JWT.ProjectId := ProjectId;
// the self-signed JWT is audience-bound to the Vision endpoint
CloudClient.GoogleCloudOptions.JWT.API_Endpoint :=
  'https://vision.googleapis.com/';

// once the token is acquired, send it as gRPC metadata
GRPC.DefaultMetadata.Clear;
GRPC.DefaultMetadata.Add('authorization', 'Bearer ' + Token);

Annotare un'immagine

Per analizzare un'immagine costruisci un TsgcGRPCVisionBatchAnnotateImagesRequest, aggiungi una richiesta immagine, puntala all'immagine (qui un URI di Google Cloud Storage, ma puoi anche inviare byte grezzi) e aggiungi una o più feature. Ogni feature ha un FeatureType e un MaxResults opzionale. Serializza con ToBytes e chiama il metodo BatchAnnotateImages del servizio ImageAnnotator.

var
  oRequest: TsgcGRPCVisionBatchAnnotateImagesRequest;
  oImgReq: TsgcGRPCVisionAnnotateImageRequest;
  oFeature: TsgcGRPCVisionFeature;
  oResponse: TsgcGRPCResponse;
begin
  oRequest := TsgcGRPCVisionBatchAnnotateImagesRequest.Create;
  try
    oImgReq := oRequest.AddRequest;
    oImgReq.Image.Source.GcsImageUri :=
      'gs://cloud-samples-data/vision/demo-image.jpg';

    oFeature := oImgReq.AddFeature;
    oFeature.FeatureType := 4;   // LABEL_DETECTION
    oFeature.MaxResults := 10;

    oResponse := GRPC.Call('google.cloud.vision.v1.ImageAnnotator',
      'BatchAnnotateImages', oRequest.ToBytes);
  finally
    oRequest.Free;
  end;
end;

I valori di FeatureType seguono l'enum dell'API Vision: 1 FACE_DETECTION, 2 LANDMARK_DETECTION, 3 LOGO_DETECTION, 4 LABEL_DETECTION, 5 TEXT_DETECTION, 6 DOCUMENT_TEXT_DETECTION e gli altri. Per eseguire più rilevamenti sulla stessa immagine in un unico viaggio di andata e ritorno, aggiungi più di una feature.

Leggere le annotazioni

I byte della risposta si caricano direttamente in una risposta batch tipizzata. Ogni immagine nel batch porta liste separate per le annotazioni di etichette, luoghi noti, loghi e testo. Ogni voce è un TsgcGRPCVisionEntityAnnotation con una Description e, per le etichette, un punteggio di confidenza Score.

var
  oResponse: TsgcGRPCVisionBatchAnnotateImagesResponse;
  oImgResp: TsgcGRPCVisionAnnotateImageResponse;
  i, j: Integer;
begin
  oResponse := TsgcGRPCVisionBatchAnnotateImagesResponse.Create;
  try
    oResponse.LoadFromBytes(aData);
    for i := 0 to oResponse.ResponseCount - 1 do
    begin
      oImgResp := oResponse.Response(i);

      for j := 0 to oImgResp.LabelAnnotationCount - 1 do
        Memo1.Lines.Add('Label: ' + oImgResp.LabelAnnotation(j).Description +
          ' (score: ' + FloatToStr(oImgResp.LabelAnnotation(j).Score) + ')');

      for j := 0 to oImgResp.TextAnnotationCount - 1 do
        Memo1.Lines.Add('Text: ' + oImgResp.TextAnnotation(j).Description);

      for j := 0 to oImgResp.LandmarkAnnotationCount - 1 do
        Memo1.Lines.Add('Landmark: ' + oImgResp.LandmarkAnnotation(j).Description);
    end;
  finally
    oResponse.Free;
  end;
end;

Immagini da storage o da byte

La sorgente dell'immagine è flessibile. Imposta Image.Source.GcsImageUri per un oggetto in Google Cloud Storage, oppure Image.Source.ImageUri per un URL HTTP(S) pubblico. Per annotare un file locale, leggilo in un TBytes e assegnalo invece a Image.Content, così l'immagine viaggia inline nella richiesta. Le stesse classi di richiesta e risposta gestiscono ogni sorgente.

Sincrono o asincrono

L'esempio sopra usa il Call bloccante, che restituisce un TsgcGRPCResponse con lo StatusCode, i byte grezzi di Data e i trailer. Per mantenere reattiva l'interfaccia, usa CallAsync e gestisci la risposta nell'evento OnGRPCResponse, dove analizzi aResponse.Data esattamente nello stesso modo. Uno stato non-OK emerge tramite OnGRPCError e un guasto di trasporto tramite OnGRPCException.

Disponibilità

Il client gRPC Vision tipizzato fa parte dell'edizione Enterprise di sgcWebSockets e gira su Windows, macOS, Linux, iOS e Android. Un esempio pronto all'uso è in Demos\21.GRPC\13.Vision e il riferimento completo è sulla pagina prodotto gRPC Client.

Domande o feedback? Contattaci. Riceverai una risposta dalle persone che hanno scritto il codice.