Gemini API’de araç çağırma ve yapılandırılmış çıktı: Mimarlık için rehber

Bu rehberde ne öğreneceksiniz?

Gemini API’de araç çağırmanın ve yapılandırılmış çıktı almanın ne işe yaradığını, iki yaklaşımın hangi işlerde tercih edilebileceğini ve mimarlık odaklı bir örneğin nasıl tasarlanacağını göreceksiniz. Rehberin odağında; proje notlarından mekân bilgilerini derlemek ve modelin bir harici işlev için gerekli parametreleri üretmesini sağlamak var.

Bu iki özellik aynı şey değildir. İşlev çağırmada model, tanımlı işlevlerden birinin çağrılması gerekip gerekmediğini değerlendirir ve gerekli parametreleri döndürür. Yapılandırılmış çıktıda ise yanıtın, önceden belirlenen bir şemaya uygun biçimde üretilmesi istenir. İlki araçlarla etkileşime, ikincisi düzenli veri almaya yöneliktir; gerektiğinde aynı iş akışının farklı aşamalarında kullanılabilir.

Gereksinimler

Google’ın Gemini API belgelerinde Python ve JavaScript SDK örneklerinin yanı sıra Java, Go ve REST örnekleri de yer alıyor. Python örneği google paketinden genai istemcisini, JavaScript örneği ise @google/genai paketini kullanıyor. REST örneğinde API anahtarı GEMINI_API_KEY değişkeniyle aktarılıyor. Kaynaklar kurulum adımlarını, ücretleri veya hesap koşullarını açıklamadığından bu konularda bir varsayım yapılmamalı; uygulama öncesinde güncel API erişim ve fiyatlandırma bilgileri ayrıca kontrol edilmeli.

Örneklerde kullanılan model adı gemini-3.8-flash. Model seçimi uygulama gereksinimine göre yapılmalı; burada verilen örnek, kaynak belgelerdeki model adını izliyor. Kodla ilerleyecek ekiplerin kullandıkları dilin ilgili SDK’sı ve Gemini API erişimi hazır olmalı. Bu rehber, belirli bir IDE ya da mimarlık yazılımı eklentisi gerektirmiyor.

İşlev çağırma örneği için uygulamanın çağrılabilir bir servis veya işlevi bulunmalı. Örneğin bu, bir projedeki mekân kayıtlarını döndüren kurum içi bir servis olabilir. Model işlev tanımını ve parametreleri üretir; servis çağrısını yapma, dönen sonucu işleme ve gerekiyorsa kullanıcıya sunma sorumluluğu uygulamanın akışında kalır.

Adım adım: İşlev çağırma

1. İşlevi tanımlayın. İşlevin adını, açıklamasını ve parametre şemasını belirleyin. Aşağıdaki örnek, projeye ait mekân verisini almak için uygulamanın sağlayabileceği bir işlev tanımını gösteriyor. project_id bir metin parametresi olarak belirtiliyor; gerçek servisin beklentileriyle eşleşecek şekilde tanımlanmalı.

from google import genai

get_room_data_function = {
    "type": "function",
    "name": "get_room_data",
    "description": "Returns room data for a project.",
    "parameters": {
        "type": "object",
        "properties": {
            "project_id": {"type": "string"}
        },
        "required": ["project_id"]
    }
}

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Mimari projedeki mekân verilerini getir.",
    tools=[{"type": "function", **get_room_data_function}]
)

for step in interaction.steps:
    if step.type == "function_call":
        print(step.name)
        print(step.arguments)

Bu örnek, modelin işlev çağrısı adımındaki işlev adını ve argümanlarını okumayı gösterir. Burada uygulamanın veri servisine bağlanan kod yer almıyor: işlev tanımı tek başına mekân verisini getirmez. Uygulama, dönen çağrıyı kendi servisinde karşılamalı; parametreleri doğrulamalı ve işlem sonucunu kendi akışında ele almalıdır.

1. İşlev kapsamını dar tutun. Bir işlevin ne yaptığı ve hangi parametreleri istediği açık olmalı. Mimari iş akışında mekân listesini okumak ile bir proje kaydını değiştirmek farklı işlemlerdir; bu tür görevleri ayrı tanımlamak, uygulamanın hangi eylemi yürütmesi gerektiğini belirginleştirir. Gerçek sistemlerde yazma veya dış dünyada sonuç doğurma ihtimali bulunan işlemler için uygulama tarafındaki doğrulama ve onay adımlarını da tasarlayın.

2. Çağrı adımını uygulama tarafında yönetin. Resmî örnekler, etkileşimin adımları arasında function_call türündeki adımları bulup işlev adını ve argümanları okumayı gösteriyor. Sonraki aşama, ilgili uygulama işlevini çalıştırmak ve sonucu işlemek olmalı. Modelin işlev çağrısı üretmesi, harici servisin başarılı olduğu anlamına gelmez; hata yönetimi ve sonuç kontrolü servis entegrasyonunun parçasıdır.

Adım adım: Yapılandırılmış çıktı

1. İhtiyaç duyulan veri alanlarını belirleyin. Örneğin bir proje notundan mekân adı, alan ve gereksinim maddeleri çıkarmak için nesne, dizi, metin ve tam sayı türlerinden oluşan bir şema kurulabilir. Alan türlerini, uygulamanın bu verileri nasıl kullanacağına göre seçin. Kaynakta JSON Schema’nın yanında Python için Pydantic, JavaScript için Zod ile şema tanımlama seçenekleri de açıklanıyor.

2. Şemayı isteğe ekleyin. Aşağıdaki Python örneği, yanıtı JSON olarak isteme ve output_text alanından alma yöntemini gösteriyor. Alan adları mimarlık odaklı bir eğitim örneğidir; proje belgelerinden hangi bilgilerin alınacağı iş gereksinimine göre belirlenmelidir.

from google import genai

client = genai.Client()
room_schema = {
    "type": "object",
    "properties": {
        "rooms": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "room_name": {"type": "string"},
                    "area_m2": {"type": "integer"},
                    "requirements": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["room_name", "area_m2", "requirements"]
            }
        }
    },
    "required": ["rooms"]
}

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Proje notundaki mekânları çıkar: giriş holü 12 m²; doğal ışık gereksinimi var.",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": room_schema
    }
)

print(interaction.output_text)

Şema, yanıtın alanlarını ve beklenen veri türlerini belirler; ancak proje notunda bulunmayan bilgiyi doğrulanmış hâle getirmez. Örneğin alan ölçüsü metinde yoksa, uygulama bu veriyi ayrıca kontrol etmeli veya eksik bilgi durumunu kendi veri modelinde ele almalıdır. Şemanın zorunlu alanlarını da kaynak metinlerde her zaman bulunacak şekilde seçmek önemlidir.

1. Sonucu uygulamada doğrulayın. Yapılandırılmış çıktı, veriyi ayrıştırmayı kolaylaştırmak için tasarlanmıştır; mimari kararların doğruluğunu garanti eden bir denetim değildir. Model çıktısını proje dokümanı, ölçü çizimi veya yetkili kayıtla karşılaştırın. Özellikle alan, kişi, tarih ve teknik gereksinim gibi sonuç doğurabilecek bilgileri onaysız biçimde çizime ya da proje veri tabanına aktarmayın.

Sık yapılan hatalar

İşlev çağrısını, modelin harici sistemi kendiliğinden çalıştırdığı şeklinde yorumlamak temel bir hatadır. Model çağrı adını ve parametrelerini sağlayabilir; uygulama bu çağrıyı uygun servisle eşleştirip çalıştırmalıdır. İşlev adlarını belirsiz bırakmak, açıklamayı genel yazmak ya da gerekli parametreleri şemada tanımlamamak da entegrasyonu zorlaştırır.

Yapılandırılmış çıktı tarafında ise şemaya uymanın, içerikteki her bilginin doğru olduğu anlamına gelmediğini unutmayın. Ayrıca zorunlu alanları, kaynak metinde bulunup bulunmadıklarını düşünmeden belirlemek eksik veya kullanılamayan kayıtlarla sonuçlanabilir. Model çıktısını, iş akışının son ve denetlenmiş verisi olarak değil, kurallı bir veri adımı olarak ele alın.

Mimarlık ve archviz iş akışında sonraki adımlar

Ofisler, proje notlarının belirli alanlara ayrılması veya kurum içi araçlardan veri alınması gereken süreçlerde bu yaklaşımları değerlendirebilir. Öğrenciler için de metinden düzenli veri çıkarmayı ve API entegrasyonunun temel mantığını öğrenmeye yarar. Ancak bu özellikler, kaynaklarda belirli bir BIM, CAD ya da görselleştirme yazılımına doğrudan bağlanan bir eklenti olarak sunulmuyor; uygulamanın böyle bir bağlantıyı ayrıca kurması gerekir.

İlk denemede yalnızca okuma amaçlı, kapsamı dar bir işlev ve kontrol edilebilir bir şema kullanın. Önce birkaç proje notunda alanların nasıl çıkarıldığını inceleyin; ardından sonuçları kaynağıyla karşılaştırın. Ofis içinde paylaşılacak bir araca geçmeden önce API erişimi ve olası kullanım maliyetlerini, proje verilerinin hangi servise gönderileceğini ve mevcut yazılım altyapısıyla uyumluluğu netleştirin. Bu değerlendirmeler, kaynak metinlerde ayrıntılandırılmadığından kuruma ve seçilen uygulamaya göre ayrıca yapılmalıdır.

Kaynak ve lisans

Bu rehber, Google’ın Gemini API için yayımladığı “Function calling with the Gemini API” ve “Structured outputs” belgelerinden Türkçeye uyarlanmıştır. Her iki kaynak da CC BY 4.0 lisanslıdır. Mimarlık odaklı örnekler rehber için yeniden hazırlanmıştır.