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

Kaynak: https://3dsinifi.com/haber/gemini-apide-arac-cagirma-ve-yapilandirilmis-cikti-mimarlik · Kategori: Eğitimler · Yayın: 12 Ekim 2026

> Gemini API, işlev çağırma ile harici araç ve servislere bağlanabiliyor; yapılandırılmış çıktı özelliği ise yanıtları JSON Schema’ya göre düzenliyor. Bu rehber, iki yöntemin mimarlık iş akışlarında nasıl ele alınacağını anlatıyor.

## Kısaca
- İşlev çağırma, modelin bir araca ait işlevi ve parametrelerini belirlemesini sağlar; işlemi uygulama tarafı yürütür.
- Yapılandırılmış çıktı, yanıtların JSON Schema ile tanımlanan biçimde üretilmesini sağlar.
- Resmî örneklerde Python, JavaScript, Java, Go ve REST kullanımları bulunuyor.
- Gemini 3.8 Flash, kaynak sayfadaki örneklerde kullanılan model olarak gösteriliyor.

## 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ı.

```python
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.

2. **İş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.

3. **Ç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ı

4. **İ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.

5. **Ş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.

```python
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.

6. **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.

## Pro ipucu
İşlev çağrısının ürettiği argümanları çalıştırmadan önce uygulama tarafında doğrulayın; özellikle dış sistemlerde değişiklik yapacak işlemleri ayrı ve açıkça tanımlayın.

## 3dsınıfı yorumu
Mimarlık ofisleri için asıl değer, proje notlarını tekrarlanabilir biçimde veriye dönüştürmek veya mevcut bir servisi kontrollü bir API akışına bağlamak olabilir. Ancak işlev çağrısı tek başına BIM ya da CAD yazılımına entegrasyon sağlamıyor; bunu uygulama tarafında geliştirmek gerekiyor.

Türkiye’deki ofis ve öğrenciler denemeye başlamadan önce API erişimi, olası kullanım maliyeti ve proje verilerinin gönderileceği servis konularını netleştirmeli. Gemini API belgeleri bu başlıkların maliyet ve kurumsal veri politikası ayrıntılarını vermiyor. Bu nedenle küçük, doğrulanabilir bir örnekle başlamak ve sonuçları kaynak proje notlarıyla karşılaştırmak daha sağlıklı bir yaklaşım.

## Kaynaklar
- [ai.google.dev (CC BY 4.0)](https://ai.google.dev/gemini-api/docs/function-calling) (özet)
- [ai.google.dev (CC BY 4.0)](https://ai.google.dev/gemini-api/docs/structured-output) (özet)

_Yapay zekâ ile yazıldı, kaynaklarla doğrulandı. © 3dsınıfı_