Gemini API ile mimari görselleri JSON çıktısına dönüştürme rehberi

Bu rehberde ne öğreneceksiniz?

Bir mimari görselden mekân, nesne veya görünür özelliklerle ilgili düzenli notlar çıkarmak; ardından bu notları JSON biçiminde almak mümkün. Bu rehberde Gemini API’ye metin ve görseli birlikte göndermeyi, istemi açık yazmayı ve yanıt yapısını şemayla tarif etmeyi adım adım ele alıyoruz. Örnekler iç mekân görseli üzerinden hazırlanmıştır; görselde bulunmayan ölçü veya malzemeyi tahmin ettirmemek için istemlerde belirsizliği belirtmeye de yer veriyoruz.

Google’ın Gemini API belgelerinde görsel anlama; görsel açıklama, sınıflandırma ve görsel soru-cevap gibi kullanım alanlarıyla anlatılıyor. Görsel girdisi URL, satır içi veri veya Files API üzerinden aktarılabiliyor. Bu örnekte model adı olarak belgelerdeki örneklerde yer alan gemini-3.8-flash kullanılıyor.

Gereksinimler

• Gemini API ile çalışabilecek bir istemci veya REST isteği. Belgeler Python ve JavaScript örneklerinin yanında Java ve Go örnekleri de sunuyor.

Örnek olarak, bir iç mekân görselindeki görünür nesneleri ve konum tariflerini düzenli bir dizi olarak almak istediğimizi düşünelim. Aşağıdaki şema, bu amaçla kullanılabilecek basit bir yapıyı gösterir. Alanları gerçek iş akışına göre değiştirmek mümkündür; önemli olan, istemde beklenen çıktıyla şemadaki alanların birbiriyle örtüşmesidir.

{
  "type": "object",
  "properties": {
    "gozlemler": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "unsur": { "type": "string" },
          "konum": { "type": "string" },
          "gorunur_ozellik": { "type": "string" }
        },
        "required": ["unsur", "konum", "gorunur_ozellik"]
      }
    }
  },
  "required": ["gozlemler"]
}

Uygulama adımları

1. Görseli ve hedefi belirleyin

Analiz edilecek görselin hangi soruya yanıt vermesi gerektiğini önce netleştirin. Örneğin amaç, bir perspektifte görünen mobilyaları listelemek olabilir; başka bir kullanımda görünür yüzey özellikleri tarif edilebilir. Görselde yer almayan ölçü, yapı sistemi veya ürün bilgilerini isteme dahil etmeyin. Bu tür bilgiler görüntüden kesin olarak çıkarılamıyorsa modelin bunu açıkça söylemesini isteyin.

2. İstemi açık ve sınırları belli yazın

Google’ın istem tasarımı rehberi, görev ve kısıtların açıkça belirtilmesini; istenen yanıt biçiminin de tarif edilmesini öneriyor. Aşağıdaki örnek, iç mekân görseli için bu yaklaşımı uygular:

Görseli bir iç mekân sunum paftasını inceler gibi değerlendir. Yalnızca görüntüde açıkça seçilebilen unsurları listele. Her unsur için kısa bir konum tarifi ve görülebilir özelliğini yaz. Ölçü, marka veya malzeme türünü görüntüden kesin biçimde belirleyemiyorsan tahmin etme; bunu belirt. Yanıtı, tanımladığım JSON şemasındaki alanlara uygun biçimde ver.

İstem, görevi ve kapsamı belirler; şema ise yanıtın hangi alanlarda döneceğini tanımlar. Sadece “görseli analiz et” demek, hangi ayrıntıların önemli olduğunu modele bırakır. Gerekli alanları ve tahmin edilmemesi gereken bilgileri baştan yazmak, çıktıyı proje notlarında kullanmayı kolaylaştırır. Yine de sonuç, görselin içeriğine dair doğrulanmış bir ölçüm veya teknik inceleme yerine geçmez.

3. Görseli API isteğine ekleyin

Küçük bir görseli base64 kodlayıp data alanıyla gönderebilirsiniz. Belgelerde bu yöntem için metin istemiyle birlikte görsel verisi ve MIME türü kullanılıyor. Satır içi görsel verisi, istem metni ve sistem talimatlarıyla beraber toplam istek boyutunu 20 MB ile sınırlar. Bu sınır aşılabilecekse dosyayı Files API’ye yükleyip dönen URI’yi isteğe eklemek gerekir.

Files API, büyük dosyalar veya aynı görseli birden fazla istekte kullanma durumları için belgelerde öneriliyor. İstek içinde metin girdisiyle görsel girdisini birlikte iletin; görselin MIME türünü de uygun biçimde belirtin. Belgelerde örneklenen görsel türlerinden biri image/jpeg.

4. JSON yanıt biçimini yapılandırın

Structured outputs özelliğinde yanıt biçimini JSON olarak ayarlayıp şemayı isteğe eklersiniz. Belgelerdeki REST örneğinde bunun için mime_type değeri application/json olarak veriliyor ve şema schema alanına konuyor. Python örneği de Pydantic modelinden JSON Schema üretip yanıtı bu modelle doğruluyor; JavaScript örneği Zod şemasından yararlanıyor.

Mimari iş akışında şemayı gereksiz yere büyütmeyin. Örneğin yalnızca unsur, konum ve görünür özellik gerekiyorsa, iş akışının kullanmadığı ek alanları eklemek bakım ve kontrol yükü yaratabilir. Şemadaki zorunlu alanları da istemde beklediğiniz bilgilerle eşleştirin.

5. Yanıtı kontrol edin ve kullanıma alın

Modelden gelen JSON’u, belirlenen alanların dolu olup olmadığı ve içeriklerin görselle uyuşup uyuşmadığı açısından inceleyin. Structured outputs biçimsel olarak şemaya uygun yanıtlar üretmeyi kolaylaştırır; bu, görsel yorumunun her durumda doğru olduğu anlamına gelmez. Özellikle malzeme, ölçü veya tasarım kararı gibi sonuçları çizim, proje dokümanı ya da uzman incelemesiyle ayrıca doğrulayın.

Birden fazla görsel için aynı şemayı kullanmak, sonuçları karşılaştırmayı kolaylaştırabilir. Her istekte görselin hangi açıdan inceleneceğini açıkça belirtin ve aynı görev için istemi küçük değişikliklerle deneyerek çıkan yanıtları değerlendirin. İstem tasarımı yinelemeli bir süreçtir; ilk denemeyi nihai kabul etmek yerine, hatalı veya gereksiz alanları gözlemleyip açıklamaları netleştirin.

Sık yapılan hatalar

• Görselde görünmeyeni kesin bilgi gibi istemek: Perspektif, çözünürlük veya kadraj bazı ayrıntıları belirsiz bırakabilir. İstemde modelden tahmin yerine belirsizliği bildirmesini isteyin.

• Şema ile istemi farklı kurmak: İstemde istenen alan şemada yoksa ya da şema zorunlu bir alan içerip görev bunu açıklamıyorsa sonuçların kullanımı zorlaşır. İkisini birlikte gözden geçirin.

• Büyük dosyayı satır içi veriyle göndermek: Satır içi görsel verisi için toplam istek boyutu 20 MB sınırı geçerlidir. Büyük dosyalarda Files API yolunu tercih edin.

• JSON biçimini doğruluk garantisi sanmak: Yapılandırılmış yanıt, bilgilerin görselle kesin olarak örtüştüğünü kanıtlamaz. Önemli tasarım ve teknik kararları ayrıca kontrol edin.

• İlk istemi son sürüm kabul etmek: Görev ve kısıtlar ne kadar açık olursa olsun, gerçek örneklerde çıktıyı gözden geçirip istemi iyileştirmek gerekir.

Mimarlık ve archviz iş akışına etkisi

Bu yöntem, görsel arşivindeki iç mekân karelerini açıklamak, sunum görsellerinden düzenli gözlem listeleri oluşturmak veya farklı görselleri ortak alanlarla karşılaştırmak isteyen mimarlık ofisleri, iç mimarlar ve öğrenciler için yararlı olabilir. JSON biçimi, aynı alanların tekrar tekrar kullanılacağı değerlendirme ve sınıflandırma işlerinde veriyi daha düzenli tutar. Ancak sonuçları proje paftasına veya teknik dokümana doğrudan doğrulanmış bilgi olarak aktarmamak gerekir.

Uyumluluk açısından çalışılan istemci ve API isteğinin belgelerdeki görsel girdisi ve structured output biçimlerini desteklemesi gerekir. Görseli satır içi göndermek ile Files API üzerinden kullanmak arasında dosya boyutu ve tekrar kullanımına göre seçim yapılmalıdır. API erişimi ve maliyet koşulları bu rehberin kaynaklarında belirtilmediğinden, gerçek bir ofis iş akışına geçmeden önce güncel erişim ve lisans koşulları ayrıca kontrol edilmelidir.

Sonraki adımlar

Önce birkaç temsilî görsel üzerinde küçük bir şema deneyin. Yanıtlarda sık tekrarlanan ve iş akışında gerçekten kullanılacak alanları belirleyin; belirsiz kalan gözlemleri ayrıca işaretleyin. Ardından istemi, şemayı ve görsel gönderim yöntemini birlikte gözden geçirin. Daha kapsamlı JSON yapıları gerektiğinde Gemini API’nin structured output belgelerindeki SDK örnekleri, görsel girdisi için de Image understanding rehberi incelenebilir.

Kaynak ve lisans

Bu içerik, Google AI for Developers’ın “Structured outputs”, “Image understanding” ve “Prompt design strategies” rehberlerinden yararlanılarak Türkçeye uyarlanmıştır. Üç kaynak da CC BY 4.0 lisansıyla sunulmuştur.