Gemini API ile mimari iş akışı: Python’da ilk metin isteği

Bu eğitimde ne öğreneceksiniz?

Bu rehber, Gemini API ile ilk metin isteğini Python üzerinden göndermek isteyen mimarlık, iç mimarlık ve görselleştirme ekipleri için hazırlandı. Google’ın Interactions API arayüzünü kullanarak bir istem oluşturmayı, gelen metin yanıtını okumayı ve yanıtı akış biçiminde almayı göstereceğiz. Örnekler, küçük bir konut salonu için öneri istemek ve bir kafe konsept toplantısına hazırlanmak gibi tasarım sürecinde karşılaşılabilecek metin görevlerine odaklanıyor.

Bu eğitimdeki kod örnekleri metin yanıtı almak üzere düzenlendi. Gemini API’nin kapsamı bununla sınırlı değil: Google’ın başlangıç kılavuzu metin üretiminin yanı sıra çok modlu anlama, görsel üretimi, yapılandırılmış çıktı ve araç kullanımını da API ile ele alınabilecek başlıklar arasında sayıyor. Ancak burada gösterilen metin çıktıları çizim, render veya teknik doğrulama yerine geçmez; proje kararları ekip tarafından kontrol edilmelidir.

Gereksinimler: hesap, anahtar ve yazılım

Başlamak için Google AI Studio üzerinden bir API anahtarı alın. Google’ın kılavuzuna göre yeni kullanıcılar için AI Studio otomatik olarak bir proje ve anahtar oluşturabiliyor; mevcut kullanıcılar ise API anahtarları sayfasından yeni bir anahtar-proje eşleşmesi oluşturabiliyor. Google Cloud’dan içe aktarılan ek projelerin ücretsiz katmanı kullanabilmesi için proje doğrulaması gerekebileceği de belirtiliyor.

Bu eğitimde Python SDK’sı kullanılacak. Kaynakta verilen kurulum komutu google-genai paketini yükler veya günceller. Kılavuz belirli bir Python sürüm gereksinimi vermediğinden burada ek bir sürüm koşulu tanımlanmıyor. API anahtarını doğrudan kaynak koduna yazmak yerine ortam değişkeni olarak tanımlayın:

export GEMINI_API_KEY="YOUR_API_KEY"

YOUR_API_KEY alanını kendi anahtarınızla değiştirin. Bu komut anahtarı, komutun çalıştırıldığı ortamda GEMINI_API_KEY adıyla tanımlar. Anahtarı herkese açık kod depolarına veya ekip dışına açık dosyalara eklememek, erişimi kontrol altında tutmak açısından önemlidir.

Ücretli katmana geçmek isteyenlerin Cloud Billing kurması, ödeme yöntemi eklemesi ve en az 5 dolar ya da karşılığı tutarda ücretli kredi için ön ödeme yapması gerekiyor. Google, ücretli katmanın hız sınırlarını artırdığını belirtiyor. API kullanımını Google AI Studio’daki kullanım ekranından izlemek mümkün.

Adım adım ilk isteği gönderin

1. SDK’yı yükleyin. Python ortamınızda aşağıdaki komutu çalıştırın:

pip install -U google-genai

Komut, google-genai paketini pip aracılığıyla yükler veya mevcut kurulumu günceller. Birden fazla Python ortamı kullanılıyorsa komutun, kodun çalıştırılacağı ortamda uygulanmasına dikkat edin.

1. İlk metin isteğini hazırlayın. Bir Python dosyasına aşağıdaki örneği ekleyin. İstem, küçük bir konut salonu için yazılı öneriler istiyor:

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Küçük bir konut salonu için gün ışığını ve dolaşımı gözeten üç tasarım önerisi yaz. Her öneride tasarım kararını ve gerekçesini belirt."
)
print(interaction.output_text)

İstek gemini-3.8-flash modeline Interactions API üzerinden gönderilir; örnekte sonuç interaction.output_text ile ekrana yazdırılır. İstem metnini, gerçek iş akışında ihtiyaç duyulan metin görevine göre düzenleyebilirsiniz. Örneğin bir sunum için konsept açıklaması, malzeme seçeneklerini karşılaştıran bir taslak veya müşteri toplantısı için soru listesi talep edilebilir. Beklenen yanıtın kapsamını ve biçimini açıkça tarif etmek, gelen metni değerlendirmeyi kolaylaştırır.

1. İstemi proje bağlamına göre daraltın. Genel bir komut yerine mekân türünü ve istenen çıktıyı belirtin. Aşağıdaki örnek, bir iç mekân tasarım toplantısına hazırlık için oluşturulmuş özgün bir istemdir:

Bir kafe iç mekânı için konsept geliştirme toplantısına hazırlanıyorum. Tasarım ekibinin tartışması için üç farklı atmosfer yönü öner. Her yönü kısa bir başlık, mekânsal yaklaşım ve müşteriye sorulacak iki net soruyla açıkla. Proje verisi verilmediğinde varsayım üretme; eksik bilgileri ayrıca belirt.

Bu istem, görsel veya teknik çıktı değil, toplantıda değerlendirilecek yazılı bir taslak ister. Bilinmeyenleri ayrıca belirtmesini talep etmek, yanıtın proje verileriyle karıştırılmasını önlemeye yardımcı olabilir; yine de oluşturulan metin ekip tarafından incelenmelidir.

1. Yanıtı akış olarak alın. Uygulamanın yanıtı oluşturulurken parçalar halinde işlemesi gerekiyorsa istekte stream=True kullanılabilir. Aşağıdaki örnek, API’den dönen olayları dolaşarak ekrana yazdırır:

from google import genai

client = genai.Client()
stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Bir mimari konsept sunumu için kısa bir açılış metni yaz.",
    stream=True
)
for event in stream:
    print(event)

Akış kullanımında yanıt tek bir metin olarak alınmak yerine olaylar halinde gelir. Google’ın kılavuzu, step.delta olaylarının yanıt oluşturulurken metin parçalarını taşıyabildiğini açıklıyor. Bu örnekte her olay doğrudan yazdırılıyor; bir uygulama geliştirirken olayların kullanıcıya nasıl sunulacağı ayrıca ele alınmalıdır.

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

Bu örnekler; konsept açıklaması hazırlama, toplantı gündemini destekleyecek sorular üretme, tasarım seçeneklerini yazılı biçimde karşılaştırma ve sunum metni taslağı oluşturma gibi metin ağırlıklı işler için başlangıç noktası olabilir. Bir ekip, tekrar eden ve kapsamı net olan tek bir görevi seçerek çıktının ne kadar düzenleme gerektirdiğini değerlendirebilir. Bu yaklaşım API’nin görsel üretim ya da proje doğrulama kapasitesi hakkında sonuç çıkarmaz; yalnızca burada gösterilen metin isteklerinin iş akışına uygunluğunu sınar.

İş istasyonu açısından bu örnekler yerel render performansını ölçmüyor. Kaynakta bu kullanım için belirli bir GPU gereksinimi veya donanım önerisi verilmediğinden, örneklerden hareketle cihaz yükseltme kararı çıkarmamak gerekir. Hesap tarafında API anahtarının yönetimi, kullanımın izlenmesi ve gerekiyorsa ücretli katmanın maliyetinin değerlendirilmesi önem taşıyor. Ücretli kullanıma geçiş Cloud Billing ve ön ödeme gerektiriyor; ekiplerin kullanım sorumluluğunu ve bütçe takibini önceden belirlemesi yararlı olur.

Sık yapılan hatalar ve sonraki adımlar

• Anahtar tanımlı değil: GEMINI_API_KEY değişkeninin tanımlandığı ortamdan Python dosyasını çalıştırın.

• Paket farklı bir ortama kuruldu: google-genai paketinin kodu çalıştıran Python ortamında bulunduğunu kontrol edin.

• İstem fazla genel: Mekân türünü, istenen metnin amacını ve yanıt biçimini belirtin.

• Yanıtı onaylanmış proje bilgisi saymak: Metni tasarım kararı veya teknik doğrulama olarak kabul etmeyin; ekip değerlendirmesinden geçirin.

• Ücretli kullanımı plansız başlatmak: Cloud Billing ve ön ödeme koşullarını, ücretli kullanıma geçmeden önce inceleyin.

İlk isteğiniz çalıştıktan sonra hemen kapsamlı bir otomasyon kurmak yerine ekipte sık tekrarlanan, sınırları belirli bir metin görevini seçin. İstemi küçük adımlarla iyileştirip sonuçların kullanılabilirliğini, gereken düzeltme miktarını ve API kullanımını takip edin. Google’ın kılavuzu, uygulama geliştirmek için SDK’ları; bir betik veya komut satırı işinin doğrudan API çağırması içinse Gemini API CLI seçeneğini de açıklıyor. Bu eğitimde kod örnekleri Python SDK’sı ve Interactions API ile sınırlı tutuldu.

Kaynak ve lisans

Bu eğitim, Google’ın Gemini API için yayımladığı “Getting started” kılavuzundan (K1) yararlanılarak Türkçeye uyarlanmıştır. Kaynak CC BY 4.0 lisansıyla yayımlanmıştır. Mimarlık ve iç mekân odaklı örnek istemler bu eğitim için özgün olarak hazırlanmıştır.