Delphi'de gRPC Üzerinden Google Cloud Vision

5 Haziran 2026 · Bileşenler

Google Cloud Vision, görüntüleri analiz eder ve içlerinde ne olduğunu söyler: açıklayıcı etiketler döndürür, basılı ve el yazısı metni okur (OCR), yüzleri algılar, ünlü önemli yerleri ve logoları tanır ve daha fazlasını yapar. sgcWebSockets Enterprise, TsgcGRPCClient üzerine oturan türlü bir Vision gRPC istemcisi içerir, böylece bir görüntü gönderip ek açıklamalarını (annotations) Delphi ve C++Builder'dan harici bir çalışma zamanı veya elle yazılmış protobuf'lar olmadan geri okuyabilirsiniz.

Nasıl çalışır

Cloud Vision, bir ImageAnnotator gRPC hizmeti sunar. Bir istek, her biri algılanmasını istediğiniz özelliklerin listesiyle eşleştirilmiş bir veya daha fazla görüntüden oluşan bir gruptur ve yanıt, eşleşen bir ek açıklama grubudur. Tüm alışveriş, HTTP/2 üzerinde çerçevelenmiş Protocol Buffers mesajlarıdır.

sgcWebSockets zaten eksiksiz bir HTTP/2 yığını içerir, bu nedenle taşıma, TLS üzerinden vision.googleapis.com:443 adresine yönlendirilmiş bir TsgcHTTP2Client'tır. TsgcGRPCClient onun üzerine oturur ve gRPC çerçevelemesini, üst bilgilerini, zaman aşımlarını ve trailer ayrıştırmasını yapar. sgcGRPC_Google_Vision içindeki Vision mesaj sınıfları türlü protobuf yardımcılarıdır: istek nesnesini doldurursunuz, onu serileştirmek için ToBytes metodunu çağırırsınız, genel istemciyle gönderirsiniz ve yanıt baytlarını LoadFromBytes ile türlü bir yanıt nesnesine geri yüklersiniz.

Kimlik doğrulama, standart Google hizmet hesabı akışıdır. Kendinden imzalı bir JWT, bir bearer belirteciyle takas edilir ve her çağrıda gRPC meta verisi olarak gönderilir. JWT hedef kitleye bağlı (audience-bound) olduğundan, belirteç Vision uç noktasına hedeflenir, böylece vision.googleapis.com onu kabul eder.

İstemcilerin kurulması

HTTP/2 taşımasını oluşturun, gRPC istemcisini ona ekleyin ve kanala ikili protobuf içerik türünü kullanmasını söyleyin. Vision, application/grpc+proto konuşur.

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;

Kimlik Doğrulama

Bearer belirteci, hizmet hesabı kimlik bilgilerinizden gelir. JWT seçeneklerini indirilen JSON anahtarından alınan değerlerle yapılandırın, hedef kitleyi Vision uç noktasına yönlendirin ve ortaya çıkan belirteci DefaultMetadata'ya ekleyin, böylece her gRPC çağrısında taşınır.

// 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);

Bir görüntüye ek açıklama ekleme

Bir görüntüyü analiz etmek için bir TsgcGRPCVisionBatchAnnotateImagesRequest oluşturursunuz, bir görüntü isteği eklersiniz, onu görüntüye yönlendirirsiniz (burada bir Google Cloud Storage URI'si, ancak ham bayt da gönderebilirsiniz) ve bir veya daha fazla özellik eklersiniz. Her özelliğin bir FeatureType'ı ve isteğe bağlı bir MaxResults'u vardır. ToBytes ile serileştirin ve ImageAnnotator hizmetinin BatchAnnotateImages metodunu çağırın.

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;

FeatureType değerleri Vision API numaralandırmasını izler: 1 FACE_DETECTION, 2 LANDMARK_DETECTION, 3 LOGO_DETECTION, 4 LABEL_DETECTION, 5 TEXT_DETECTION, 6 DOCUMENT_TEXT_DETECTION ve gerisi. Aynı görüntü üzerinde tek bir gidiş dönüşte birkaç algılama çalıştırmak için birden fazla özellik ekleyin.

Ek açıklamaları okuma

Yanıt baytları doğrudan türlü bir grup yanıtına yüklenir. Gruptaki her görüntü; etiket, önemli yer, logo ve metin ek açıklamaları için ayrı listeler taşır. Her giriş, bir Description ve etiketler için bir güven Score'una sahip bir TsgcGRPCVisionEntityAnnotation'dır.

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;

Depolamadan veya baytlardan görüntüler

Görüntü kaynağı esnektir. Google Cloud Storage'daki bir nesne için Image.Source.GcsImageUri'yi veya genel bir HTTP(S) URL'si için Image.Source.ImageUri'yi ayarlayın. Yerel bir dosyaya ek açıklama eklemek için, onu bir TBytes içine okuyup bunun yerine Image.Content'e atayın, böylece resim istek içinde satır içi olarak taşınır. Aynı istek ve yanıt sınıfları her kaynağı işler.

Senkron veya asenkron

Yukarıdaki örnek, StatusCode, ham Data baytları ve trailer'larla birlikte bir TsgcGRPCResponse döndüren bloklayan Call metodunu kullanır. Kullanıcı arayüzünü duyarlı tutmak için CallAsync kullanın ve yanıtı, aResponse.Data'yı tam olarak aynı şekilde ayrıştırdığınız OnGRPCResponse olayında işleyin. OK olmayan bir durum OnGRPCError aracılığıyla, bir taşıma hatası ise OnGRPCException aracılığıyla ortaya çıkar.

Kullanılabilirlik

Türlü Vision gRPC istemcisi, sgcWebSockets Enterprise sürümünün bir parçasıdır ve Windows, macOS, Linux, iOS ve Android üzerinde çalışır. Çalıştırılmaya hazır bir örnek Demos\21.GRPC\13.Vision içinde yer alır ve tam referans gRPC Client ürün sayfasında bulunur.

Sorularınız veya geri bildirimleriniz mi var? Bize ulaşın. Kodu yazan kişilerden bir yanıt alacaksınız.