Gemini API ile mimari metinlerden şemalı JSON çıktısı üretme

Bu rehberde ne öğreneceksiniz?

Bir proje brief’i, malzeme notu veya mekân açıklaması çoğu zaman serbest metin olarak gelir. Bu metinlerden oda adı, malzeme ve kullanım amacı gibi alanları düzenli biçimde çıkarmak gerektiğinde, yanıtın yalnızca doğal dilde verilmesi sonraki işlemleri zorlaştırabilir. Gemini API’nin yapılandırılmış çıktı özelliği, model yanıtının önceden tanımlanmış bir JSON Schema’ya uymasını istemeye yarar.

Bu uygulamada üç noktayı birlikte ele alacağız: beklenen alanları belirlemek, görevi ve kısıtları açık bir istemle anlatmak, ardından uygun şemayı API isteğine eklemek. Örnekler mimari iş akışlarına göre yazıldı; aşağıdaki istemler kaynaklarda aynen yer almıyor, belgelenen yöntemlere göre hazırlanmış özgün örneklerdir.

Gereksinimler ve kapsam

Google’ın belgeleri, yapılandırılmış çıktılar için REST API’de JSON Schema desteğinden söz ediyor. Google GenAI SDK’larında ise şema tanımlama seçenekleri olarak Python tarafında Pydantic, JavaScript tarafında Zod gösteriliyor. Kaynakta Java, Go ve başka örnekler de bulunuyor; bu rehberde kod yerine aktarımı kolay bir JSON Schema taslağı kullanıyoruz.

Belge örneklerinde JavaScript için Zod’un kurulması gerektiği not ediliyor; ancak SDK sürümü, hesap koşulları veya ücret bilgisi bu kaynaklarda verilmemiş. Bu nedenle proje başlamadan önce kullanılacak SDK’nın ve modelin güncel gereksinimlerini ilgili Gemini API belgelerinden kontrol edin. Belgelerin üst kısmında Gemini 4 Argon’un kullanılabilir olduğu yazarken, örnek kodda gemini-3.8-flash model adı geçiyor. Örnek model adını otomatik olarak güncel veya her kullanım için uygun kabul etmeyin.

1. Çıkarılacak alanları belirleyin

Şema hazırlamadan önce metinden hangi verilerin alınacağını ve her birinin hangi türde olacağını kararlaştırın. Örneğin aşağıdaki taslak, bir iç mekân brief’inden mekân adı, belirtilen malzeme ve işlev açıklaması çıkarmayı hedefliyor. object, properties, string ve required gibi temel JSON Schema yapıları, kaynakta gösterilen örneklerle uyumludur.

{
  "type": "object",
  "properties": {
    "mekan_adi": { "type": "string" },
    "malzeme": { "type": "string" },
    "islev": { "type": "string" }
  },
  "required": ["mekan_adi", "malzeme", "islev"]
}

Burada üç alan da zorunlu tutuluyor. Kaynak metin bir alanı belirtmiyorsa ne yapılacağını istemde ayrıca açıklayın; örneğin alanın boş bırakılmasını veya “belirtilmemiş” yazılmasını isteyebilirsiniz. Bu tercih, proje verisinin nasıl işleneceğine bağlıdır; şemayı kurarken bu kararı baştan vermek, ekip içinde tutarlı sonuç almayı kolaylaştırır.

2. Görevi ve girdiyi açıkça yazın

İyi bir istem; yapılacak işi, üzerinde çalışılacak metni ve yanıtın biçimini anlaşılır biçimde tarif eder. Google’ın istem tasarımı rehberi, açık ve belirli yönergeler kullanmayı; gerekiyorsa kısıtları ve biçim beklentisini belirtmeyi öneriyor. Aşağıdaki örneği kendi brief alanlarınıza göre düzenleyebilirsiniz.

Aşağıdaki iç mekân proje brief’inden mekân adını, açıkça belirtilen malzemeyi ve mekânın işlevini çıkar. Yalnızca verilen metindeki bilgilere dayan. Bir bilgi metinde yoksa bunu “belirtilmemiş” olarak yaz. Yanıtı, sağlanan JSON şemasındaki alanlarla uyumlu bir JSON nesnesi olarak üret.

Brief: Zemin katta yer alan okuma alanında meşe kaplama yüzeyler ve ortak çalışma masaları bulunuyor.

Bu istem, metni girdi olarak verir; çıkarım görevini tanımlar ve bilinmeyen alanlar için davranış belirtir. Yapılandırılmış çıktı özelliği de beklenen yanıtın şemaya uymasını sağlar. İstem ile şema aynı alanları tarif etmelidir: Şemada olmayan yeni anahtarlar istemde talep edilmemeli, istenen alanlar da şemadan çıkarılmamalıdır.

3. Kısıtları proje ihtiyacına göre daraltın

Mimari dokümanlarda yorum ile kaynak bilgiyi birbirinden ayırmak önemlidir. Bir malzeme listesi çıkarıyorsanız, metinde bulunmayan ürün veya teknik özelliklerin eklenmemesini açıkça isteyin. Örneğin aşağıdaki istem, bir mahal açıklamasından yalnızca yazılı malzemeleri toplamaya odaklanır.

Bu mahal açıklamasında adı geçen kaplama ve yüzey malzemelerini çıkar. Yeni malzeme önerme, eş anlamlı veya marka tahmini ekleme. Sonucu yalnızca malzeme adlarından oluşan bir liste olarak ver.

Açıklama: Giriş holünde terrazzo döşeme ve boyalı alçı duvar yüzeyi kullanılacaktır.

Bu örnekte liste biçimi isteniyor; dolayısıyla bunu JSON nesnesi bekleyen önceki şemayla aynı işte doğrudan kullanmayın. Yanıt biçimi ihtiyaca göre değişir: yapılandırılmış çıktı kullanırken şema, istemde tarif edilen sonuçla eşleşmelidir. Tek bir şemayı farklı türde görevlerde tekrar kullanmak yerine, her işin alanlarını ve veri türlerini yeniden değerlendirin.

4. Örnek yanıtla biçimi gösterin

Bir görevde istenen sınıflandırma veya yazım kalıbı doğal dille anlatıldığında yoruma açık kalıyorsa, kısa örnekler eklemek biçimi belirginleştirebilir. Google’ın rehberi, few-shot yaklaşımında modele örnek girdi ve beklenen yanıt biçimi gösterilebileceğini; örneklerin belirgin ve çeşitli olmasının yararlı olduğunu söylüyor.

Aşağıdaki örnekteki alanları kullanarak yeni mahal notunu sınıflandır.

Örnek not: “Mutfak tezgâhı kuvars kompozit, dolap kapakları mat lake.”
Örnek çıktı: {"mekan": "Mutfak", "malzemeler": ["kuvars kompozit", "mat lake"]}

Yeni not: “Çalışma odasında ahşap parke ve sıva üzeri boya bulunuyor.”
Yalnızca aynı alan düzeninde yanıt ver.

Bu örnek, çıktı düzenini gösterir; gerçek API isteğinde kullanılacak şemayı ayrıca tanımlamanız gerekir. Kaynak rehber, az sayıda örnekle başlanabileceğini ve örnek sayısını kullanım durumuna göre denemenin gerekebileceğini belirtiyor. Çok fazla örneğin de modele aşırı uyum davranışı yaratabileceği uyarısı yer alıyor.

Sık yapılan hatalar

En yaygın sorun, gereksinimleri yalnızca isteme yazıp API tarafında şema belirtmemektir. Google, basit JSON biçimlerinin doğal dille istenebileceğini; daha karmaşık JSON Schema ihtiyaçlarında yapılandırılmış çıktı özelliğinin tercih edilmesini öneriyor. İkinci sorun, şemayla istemin farklı alanlar veya farklı yanıt biçimleri istemesidir. Önce alanları ve türleri netleştirin, sonra istemi bu yapıya göre yazın.

Bir başka hata, belirsiz metinlerde modelden kaynakta olmayan ayrıntıları tamamlamasını beklemektir. İstemde hangi bilginin çıkarılacağını, hangisinin dışarıda bırakılacağını ve eksik verinin nasıl gösterileceğini belirtin. Şema biçim tutarlılığına yardımcı olur; proje kaynağının doğruluğunu veya eksiksizliğini kendiliğinden garanti etmez. Üretilen kayıtları özgün brief ile karşılaştırmak, özellikle teslim ve dokümantasyon süreçlerinde önem taşır.

Mimarlık ve görselleştirme iş akışlarında kullanım

Bu yaklaşım, çok sayıda proje notunu aynı alanlara ayırması gereken mimarlık ofisleri, iç mimarlar ve öğrenciler için yararlı olabilir. Mahal açıklamalarından malzeme adlarını, mekân türlerini veya işlev tanımlarını çıkarmak; bu verilerin sonraki bir araca aktarılacağı iş akışlarında düzenli bir başlangıç noktası sağlar. Kaynaklar belirli bir BIM, CAD veya görselleştirme yazılımına entegrasyon tarif etmiyor; bu nedenle bağlantı ve uyumluluk ayrıca değerlendirilmelidir.

Ofisler, önce küçük bir metin kümesi üzerinde alanların işe yarayıp yaramadığını sınamalı; ardından aynı şema ve istemin farklı brief’lerde nasıl sonuç verdiğini kontrol etmelidir. Öğrenciler içinse bu yöntem, serbest metinden veri çıkarmayı ve JSON yapısını anlamayı pratik biçimde bir araya getirir. Donanım, lisans ve API kullanım maliyeti konusunda kaynaklarda bilgi bulunmuyor; üretim sürecine geçmeden önce bunları ilgili hizmet belgelerinden doğrulayın.

Sonraki adımlar

Önce tek bir kullanım seçin: örneğin mahal notundan malzeme çıkarmak. Alanları belirleyip şemayı kurun; ardından açık yönergeli bir istemle deneyin. Sonuçları kaynak metinle karşılaştırın, tekrarlayan hataları gözlemleyin ve yalnızca gerçekten gerekli olduğunda isteme örnek ekleyin. Uygulama tarafında Python kullanılıyorsa Pydantic, JavaScript kullanılıyorsa Zod ile şema tanımlama seçeneklerini değerlendirin. REST API kullanımı da belgelerde destekleniyor.

İş büyüdüğünde şema değişikliklerini ve beklenen alanları ekip içinde belgeleyin. Böylece mimari brief’leri işleyen farklı görevlerde aynı veri yapısının korunup korunmadığı daha kolay takip edilir. Başlangıç için hedef, her şeyi otomatikleştirmek değil; tekrarlanan bir metin işini açık kurallarla ve kontrol edilebilir bir yanıt biçimiyle sınamaktır.

Kaynak ve lisans

Bu rehber, Google’ın “Structured outputs” ve “Prompt design strategies” belgelerinden Türkçeye uyarlanmıştır. Her iki kaynak da CC BY 4.0 lisanslıdır.