Gemini 3.8 Flash API Eğitimi: Düşünme Seviyeleri, PDF Çıkarımı ve Python’da Fonksiyon Çağırma

Gemini 3.8 Flash Nedir?

Gemini 3.8 Flash, 2 Eylül 2026’dan beri genel erişimde olan Google’ın iş gücü modelidir; model kimliği gemini-3.8-flash. 3.7 Flash’tan 3 hafta sonra geldi ve Google bunu uzun ufuklu kodlama, ajansal iş akışları ve finans ve hukuk gibi uzmanlaşmış alanlarda çok adımlı akıl yürütme için konumlandırıyor.

API çağrıları için önemli olan teknik özellikler 3.7’den değişmedi: 

• 1M belirteçlik bağlam penceresi
• 64k maksimum çıktı belirteci
• metin çıktıyla çok modlu girdi (metin, görseller, video, ses, PDF’ler)
• 31 Aralık 2026’ya kadar 1M giriş belirteci için $0,75 ve 1M çıkış belirteci için $3,75 olan aynı tanıtım fiyatı (1 Ocak 2027’den itibaren $1,50 ve $7,50)

Değişen şey yüzey değil, davranıştır: Google, 3.8’in karmaşık görevlerde daha fazla çalıştığını, ek akıl yürütme adımları attığını ve araçları yinelemeli olarak çağırdığını söylüyor; bu da daha yüksek çaba seviyelerinde belirteç kullanımını artırabilir. Derinlikten çok verimliliğin önemli olduğu iş yükleri için 3.7 Flash tam destek almaya devam eder.

Kıyaslamalar ve ayrıntılı fiyatlandırma için Gemini 3.8 Flash rehberimize göz atın veya platform genel görünümü için Google Gemini nedir? rehberini okuyun.

Gemini 3.8 Flash vs. 3.8 Flash Cyber

Çıkışta 2 varyant var ve yalnızca 1’inin yazabileceğiniz bir model kimliği var. 

• Gemini 3.8 Flash genel modeldir; bugün Google AI Studio ve Gemini API’de mevcuttur. 
• Gemini 3.8 Flash Cyber, güvenlik açıklarını keşfetme ve otomatik yamalama için ayarlı bir siber güvenlik varyantıdır.

Cyber varyantı herkese açık API’de yoktur: erişim, Google’ın Fairwind Programı üzerinden sağlanır ve onaylı kamu otoriteleri, kritik altyapı işletmecileri ve yazılım bakımcılarıyla sınırlıdır.

Bu eğitimi takip ediyorsanız model kimliğiniz gemini-3.8-flash. Aşağıda Cyber varyantına ihtiyaç duyulan veya kullanılan hiçbir şey yok.

Interactions API vs. generateContent

Gemini 3.8 Flash’ı çağırmak için google-genai SDK’sında client.interactions.create() kullanın. Google, Interactions API’yi Haziran 2026’da GA yaptı ve tüm yeni işler için tavsiye ediyor. generateContent hâlâ çalışsa da artık eski sayılır. Sunucu tarafı geçmiş, arka planda yürütme ve gözlemlenebilir yürütme adımları gibi yeni özellikler önce Interactions’a gelir.

Pratikteki en büyük değişim durum yönetimidir. Çok turlu çağrılar artık sunucu tarafı previous_interaction_id kullanır: son etkileşim kimliğini gönderirsiniz, sunucu durumu geri yükler. Sohbet geçmişinin tamamını istemcinizden elle eklemeniz veya yeniden göndermeniz gerekmez. Model turlarını önden doldurmaktan da kaçının; bu eski bir generateContent desenidir ve Gemini 3.x’te bozulur.

Herkesi yakalayan bir nokta var ve PDF bölümünde geri geliyor: previous_interaction_id yalnızca konuşma geçmişini geri yükler, başka bir şeyi değil. tools, system_instruction, generation_config ve response_format etkileşim kapsamındadır; bu yüzden onlara ihtiyaç duyan her turda yeniden geçirilmeleri gerekir.

thinking_level örnekleme ayarlarının yerini alır

Eski Gemini modellerinde geliştiriciler çıktı rastgeleliğini kontrol etmek için temperature, top_p ve top_k kullanırdı. Gemini 3.x bu örnekleme ayarlarını kaldırır ve onların yerine tek ayar olan thinking_level gelir.

3 değer kabul eder:

• low: en az akıl yürütme belirteci, en hızlı ve en ucuz. Çıkarım, sınıflandırma ve kendiniz kontrol edeceğiniz her şey için uygundur.

• medium: varsayılan ve Google’ın kod ve ajan işleri için önerisi.

• high: en geniş akıl yürütme bütçesi; zor çok adımlı mantık ve araç ağırlıklı görevler için.

minimal göndermeyin. Gemini Flash 3.7’den beri geçersizdir ve 400 doğrulama hatası döndürür. 

3.7’den devreden bir başka kural: frequency_penalty, presence_penalty ve candidate_count artık etkin bir API hatası fırlatır; bunları da eski konfigürasyonlardan kaldırın.

Gemini 3.8 Flash API Nasıl Kurulur?

Ortamınızı kurmak yaklaşık 2 dakika sürer. Google AI Studio’dan bir API anahtarına ve güncel google-genai Python kütüphanesine ihtiyacınız var.

Google AI Studio’dan API anahtarı alın

Tarayıcınızda Google AI Studio’yu açın ve Google hesabınızla oturum açın. Create API Key’e tıklayın, bir Google Cloud projesi seçin veya oluşturun ve gizli anahtar dizgenizi kopyalayın. 

Terminalinizi açın ve anahtarı bir ortam değişkeni olarak kaydedin: export GEMINI_API_KEY=<your-key>.

Anahtarı asla bir URL’de ?key= sorgu parametresi olarak göndermeyin; sorgu dizeleri sunucu günlüklerine, tarayıcı geçmişine ve ara belleklerine düşer. Koda geçmeden önce modeli bir oyun alanında keşfetmek isterseniz, Google AI Studio Eğitimi Chat, Build ve Stream modlarını kapsar; bu yazı API üzerinde kalır.

Üretim sistemlerinde kimlik doğrulama hikâyesi değişir: Vertex AI (şimdi Gemini Enterprise Agent Platform’un parçası) ham bir API anahtarı yerine OAuth, IAM rolleri ve bölgesel uç noktalar sunar. Bu eğitimde her şey, öğrenmek için en hızlı yol olduğu için AI Studio anahtarlarını kullanır; ancak gerçek kullanıcı verisine dokunmadan önce Vertex geçişini planlayın.

google-genai’yi kurun ve bir istemci oluşturun

Birçok eğitim hâlâ google-generativeai yüklemeyi söyler. Bu eski SDK’dır ve Interactions API’si yoktur. google-genai (2.3.0 veya üstü) kurun:

pip install -U google-genai

Kurulumdan sonra, Python’un kütüphaneyi yüklediğini ve istemcinizi hatasız başlattığını doğrulayın:

from google import genai # reads GEMINI_API_KEY from the environment
client = genai.Client() 
print("Client initialized successfully.")

İlk Interactions API çağrınızı yapın

Interactions API’ye her istek bir Interaction kaynağı oluşturur; bu kaynak tüm turu kaydeder: girdinizi, modelin düşüncelerini, varsa araç çağrılarını ve nihai çıktıyı. SDK, son metni output_text kolaylık özelliğiyle sunar; bu yüzden adımları elden tek tek gezmeniz nadiren gerekir.

from google import genai
client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=(
        "Write a pandas one-liner that adds a 7-day rolling average "
        "revenue column per store_id to a DataFrame with columns "
        "date, store_id, revenue. Reply with only the code, no explanation."
    ),
    generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)
usage = interaction.usage
print(
    f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
    f"thinking={usage.total_thought_tokens} | total={usage.total_tokens}"
)

Makinemde model, zincirlenmiş bir pandas tek satırlık komutla yanıt verdi ve şu kullanım satırını üretti:

Bu sayılar, 3.7’ye kıyasla ilk gerçek farkı gizler. Aynı görevi daha uzun bir istemle ve çıktı kısıtlaması olmadan tekrar çalıştırdım; 3.8, 870 çıktı belirtecine karşı 1.436 düşünme belirteci harcadı. Kısıtlamayla 1.515’e karşı 42 harcadı. Akıl yürütme bütçesi neredeyse oynamadı; bu, aynı 2 istemin düşünmeyi 838’den 1.530’a savurduğu 3.7’nin tersidir.

Başka bir deyişle, 3.8 ne kadar düşüneceğine görevi nasıl ifade ettiğinize göre değil, görevin kendisine göre karar veriyor; bu da Google’ın modelin kasıtlı olarak daha fazla düşündüğü ve doğruladığı yönündeki iddiasıyla örtüşüyor. Düşünme, çıktı oranından faturalandırılır; bu nedenle kısıtlı çağrıda faturalanan belirteçlerin yaklaşık %97’si hiç görmediğim akıl yürütmeydi. Bir sonraki bölümün varlığı bu yüzden. 

Yanıtı akışla iletin

Sohbet arayüzleri veya bir kişinin izlediği her şey için, tam yanıtı beklemek birkaç saniye sürerse yavaş hissettirir. client.interactions.create() çağrısına stream=True geçin ve parçalar geldikçe yazdırın:

	from google import genai

	client = genai.Client()

	stream = client.interactions.create(
	   model="gemini-3.8-flash",
	   input="Explain the difference between a JOIN and a correlated subquery in SQL.",
	   generation_config={"thinking_level": "low"},
	   stream=True,
	)

	for event in stream:
	   if event.event_type == "step.delta" and event.delta.type == "text":
	       print(event.delta.text, end="", flush=True)
	print() 

Bunu çalıştırdığımda, model thinking_level: "low" ile uzun ve iyi örgütlenmiş bir yanıt verdi: kavramsal bir karşılaştırma, özet bir tablo ve her müşterinin en son siparişini bulmak için 2 SQL örneği; biri türetilmiş tablo JOIN’i, diğeri SELECT listesinde ilişkili alt sorgu ile. İlk sözcükler neredeyse anında geldi; amaç tam da bu.

Son print() bir sebepten var. Onsuz, son parça satır ortasında biter ve akış, metnin bittiği yerde tam durduğu için, zsh isteminizden önce serseri bir % işareti gösterir. Ayrıca, delta’lar yalnızca metin taşırsa parça başına belirteç sayılarını günlüğe alır; bunları parçaları toplayarak değil, son tamamlama olayından okuyun.

thinking_level Maliyet ve Kaliteyi Nasıl Değiştirir?

thinking_level, Gemini 3.8 Flash’ın yanıtı yazmadan önce ne kadar akıl yürüttüğünü belirler. Akıl yürütme belirteçleri 1M başına $3,75’lik çıktı oranından faturalandırılır; bu nedenle seçtiğiniz seviye doğrudan maliyet ve gecikmeyi kontrol eder ve Google, 3.8’in bunu bilerek öne çıkardığını söylüyor: karmaşık görevlerde ekstra adımlar atar ve 3.7’ye kıyasla daha yüksek çaba seviyelerinde daha fazla belirteç harcayabilir.

Aynı istemi low, medium ve high’ta çalıştırın

Test, tüm 3 seviyede aynı istemle gönderilen bir ödeme-yeniden deneme fonksiyonundaki yarış durumu (race condition). Eşzamanlılık hataları üstünkörü okumayı cezalandırır; dolayısıyla seviyeler farklıysa en çok burada ortaya çıkar. Bu yazıdan yalnızca 1 kod bloğu çalıştıracaksanız, bu olsun; çünkü sayılar, her türlü anlatıdan daha iyi konuşur.

import time

from google import genai

client = genai.Client()

BUGGY_CODE = '''
import threading

payment_attempts = {}

def retry_payment(order_id, charge_fn, max_retries=3):
    """Retry a failed payment up to max_retries times."""
    if order_id not in payment_attempts:
        payment_attempts[order_id] = 0

    while payment_attempts[order_id] < max_retries:
        success = charge_fn(order_id)
        if success:
            del payment_attempts[order_id]
            return True
        payment_attempts[order_id] += 1
    return False
'''

PROMPT = (
    "Two worker threads can call retry_payment() with the same order_id "
    "at the same time. Identify the concurrency bug that can double-charge "
    "a customer, and rewrite the function to fix it.\n\n" + BUGGY_CODE
)

for level in ["low", "medium", "high"]:
    start = time.perf_counter()
    interaction = client.interactions.create(
        model="gemini-3.8-flash",
        input=PROMPT,
        generation_config={"thinking_level": level},
    )
    elapsed = time.perf_counter() - start
    usage = interaction.usage
    print(f"\n=== thinking_level: {level} | {elapsed:.1f}s ===")
    print(interaction.output_text)
    print(
        f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
        f"thinking={usage.total_thought_tokens}"
    )

Bağlam için, zafiyet payment_attempts[order_id] üzerinde atomik olmayan kontrol-sonra-eylem desenidir. Eşzamanlılık altında 2 iş parçacığı da while koşulundan geçebilir ve sayaç artmadan önce her ikisi de charge_fn() çağırabilir. Düzeltmek, okuma-kontrol-yükle-arttır akışını sipariş başına kilitle sarmak veya ağ geçidinde idempotency anahtarı kullanmak anlamına gelir.

Sonuçların karşılaştırılması

Kendi çalıştırmalarımın sonuçları:

Üç seviye de çift tahsilatı buldu ve üçü de ilişkili olmayan siparişlerin paralel çalışması için sipariş başına kilitleme önerdi. 3.7 ile karşılaştırırsanız manşet bu ikinci kısım: orada low her şeyi ağ çağrısı boyunca tutulan tek bir global kilide sardı; sipariş başına kilitler yalnızca medium seviyesinde ortaya çıktı. 3.8’de low bu daha iyi tasarımı 0 düşünme belirteciyle, 7,8 saniyede ve üçte bir sentten daha düşük maliyetle yazdı.

Peki seviyeler şimdi ne kazandırıyor? Denetim derinliği. Bu kodda 4 ayrı hata modu var (çift tahsilat, eşzamanlı silmede KeyError, başarı yolunda durum silindikten sonra yeniden tahsilat ve atomik olmayan sayaç artışları) ve high bunların dördünü de adlandıran tek seviyeydi; low yeniden tahsilat durumunu kaçırdı, medium ise sayacı.

high ayrıca düzeltmesinin hata yolu anlambilimini açıkça belirten tek seviyeydi: denemeler tükendiğinde, sonraki çağıranlar tekrar tahsil etmek yerine False döner.

Düşünme sütunu, Google’ın “3.8 daha çok çalışıyor” iddiasının terminalde belirmesidir. Aynı isteme karşı 3.7’de medium 2.343 düşünme belirtecinden 3.158’e; high 2.217’den 4.512’ye çıktı, kabaca iki katına; ek belirteçler farklı bir hüküm yerine daha eksiksiz bir analiz satın aldı. Bu çalıştırmada gecikme de buna paralel arttı (7,8 sn, 16,6 sn, 25,5 sn), ancak bu modellerde tek çalıştırma süreleri dalgalanır; saniyeler yerine belirteç sayılarını karşılaştırın.

Bir varsayılan seçin ve ne zaman yükselteceğinizi belirleyin

Akıl yürütme seviyeleri için başparmak kuralım:

• 3.8’de low, Google’ın medium varsayımının önerdiğinden daha büyük bir rol hak etti: 0 düşünme belirteciyle doğru ve iyi tasarlanmış bir düzeltme üretti; bu yüzden önem kazanmadan önce bir insanın okuyacağı her şey için oradan başlayın (triyaj, taslaklar, özetler, gözden geçireceğiniz kod). 

• Çıktının okunmadan sevk edildiği yerlerde medium’ı kullanın; çünkü ekstra akıl yürütme, hata modlarının daha eksiksiz analizini getirdi ve okunmayan bir ardışık düzen, listelemediğiniz hata modunun ateşlendiği yerdir.

• high seviyesini, hata yolunun bizzat ürün olduğu çıktılar için ayırın; örneğin ödeme akışları, geçişler veya bir değerlendiricinin satır satır denetleyeceği her şey. Benim çalıştırmamda, 4 hatanın tamamını yakalayan ve denemeler tükendiğinde ne olduğunu belgeleyen tek seviyeydi.

1M çıktı belirteci için $3,75’e karşı 31 Aralık 2026 sonrası $7,50’de maliyet farkı düşünüldüğünde, low’a kıyasla high için 6,6 kat maliyet takası çok farklı görünür; bu yüzden küresel değil, istek başına yükseltin.

Bilinmeye değer bir kaçış kapısı, Google’ın 3.7 Flash’ın verimlilik öncelikli iş yükleri için tam destekli kaldığını belirtmesidir. 3.8’in ek titizliği görevinizin ihtiyaç duyduğundan fazla maliyet yaratıyorsa, o iş yükü için gemini-3.7-flash üzerinde kalmak desteklenen bir tercihtir, hile değil.

PDF’ten Yapılandırılmış Veri Nasıl Çıkarılır?

Gemini 3.8 Flash, PDF’leri doğrudan girdi olarak okur; böylece bir fatura veya rapor gönderebilir ve hakkında sorular sorabilirsiniz. Fatura numarası, tarihler, 4 satır öğesi ve toplam içeren tek sayfalık bir tedarikçi faturası kullandım.

PDF’i isteme ekleyin

Yerel bir fatura PDF’sini Files API ile yükleyelim. Files API, dosya depolama ve önbelleklemesini Google altyapısında yönetir:

	from google import genai
	client = genai.Client()
	print("Uploading invoice...")
	doc = client.files.upload(file="invoice_aug_2026.pdf")
	print(f"File uploaded: {doc.uri}\n")

	interaction = client.interactions.create(
	   model="gemini-3.8-flash",
	   input=[
	       {
	           "type": "text",
	           "text": "Extract the invoice number, total amount due, and due date.",
	       },
	       {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
	   ],
	)
	print(interaction.output_text)

Benim faturamdan çıkan çıktı:

Üç değer de doğru. Yükleme bir kez yapılır ve dosya sonraki istekler için kullanılabilir kalır; bu, aynı belge hakkında 1’den fazla soru sorduğunuz anda önem kazanır. Yanıt markdown madde imleri olarak gelir; bu, okumak için iyi, bir boru hattına beslemek için iyi değildir.

Yanıt şemasıyla JSON’u zorlayın

Düzyazı yerine JSON almak için response_format içinde bir şema geçin. Interactions API’de bu üst düzey bir parametredir; daha eski eğitimlerde göreceğiniz generationConfig içindeki responseMimeType ayarı, eski generateContent uç noktasına aittir.

import json

from google import genai
from pydantic import BaseModel

client = genai.Client()


class Invoice(BaseModel):
    invoice_number: str
    total_due_usd: float
    due_date: str  # ISO 8601


doc = client.files.upload(file="invoice_aug_2026.pdf")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "text",
            "text": "Extract the invoice number, total amount due in USD, and due date.",
        },
        {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Invoice.model_json_schema(),
    },
)

invoice = json.loads(interaction.output_text)
print(invoice)

Aldığım çıktı şu şekildeydi: 

Pydantic sınıfınız gerekli alanları ve veri türlerini tanımlar; model_json_schema() ise Gemini API’nin gerektirdiği JSON şemasını üretir. İşlendikten sonra json.loads() modelin çıktısını standart bir Python sözlüğüne dönüştürür. Bu noktadan sonra, yapılandırılmış veri bir DataFrame satırına dönüştürülebilir, bir veritabanına işlenebilir veya bir Google Sayfası’na eklenebilir.

previous_interaction_id ile takip sorusu sorun

Aynı belge hakkında ikinci bir soru için, ilk etkileşimin id değerini previous_interaction_id olarak geçin. Sunucu, PDF ve ilk değiş tokuşa zaten sahiptir; bu nedenle ikisini de tekrar göndermezsiniz:

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input="List each line item on the invoice with its amount.",
)

print(follow_up.output_text)

Sırasıyla tüm 4 öğeyi, tekrarlanan compute satırı da dâhil olmak üzere, tekrar hakkında yorum yapmadan döndürdü. Sorulan soruya göre bu doğru davranıştır; anormallikleri işaretlemesini istiyorsanız, bunu isteyin. 

Bilginize, 3.7 burada aynı şekilde davrandı; dolayısıyla 3.8’in ek titizliği, talep etmediğiniz denetimleri gönüllü olarak üstlenmesine değil, kendi akıl yürütmesine uygulanır.

Bu çağrı hakkında bilinmesi gereken 2 şey: 

• response_format taşınmadı; çünkü etkileşim kapsamındadır; bu tur düzyazı döndürdü. 

• Ve etkileşimler varsayılan olarak (ücretli katmanda 55 gün, ücretsiz katmanda 1 gün) saklanır (store=True); store=False bir çağrıyı durumsuz yapar, ancak o zaman onun üzerinden bir previous_interaction_id zincirleyemezsiniz.

Gemini 3.8 Flash’a Fonksiyon Çağırmayı Nasıl Eklersiniz?

Gemini 3.8 Flash’ta fonksiyon çağırma tek döngüdür: model bir araç ister, kodunuz onu çalıştırır, sonucu geri gönderirsiniz ve model nihai yanıtı yazar. Bu bölüm, o döngüyü elle kurar.

Google’ın barındırılan çok araçlı ajanlarıyla döngüyü sizin için çalıştırmasını istiyorsanız, Gemini API’de “Managed Agents” eğitimimizi okuyun. Ve uzun vadede ajanlara gidiyorsanız, Building AI Agents with Google ADK dersi aynı temel öğelerle tam bir müşteri destek asistanı kurar.

Bir araç tanımlayın ve etkileşim döngüsünü yürütün

Araç lookup_exchange_rate(currency, date)’tir; küçük bir bellek içi sözlükle desteklenir; böylece örnek harici bir API olmadan çalışır. Bildirim bir JSON şemasıdır. Model fonksiyonu asla çalıştırmaz; kodunuzdan şunları yapmasını isteyen bir function_call adımı döndürür:

import json

from google import genai

client = genai.Client()

# Local "data source" standing in for a real FX API
RATES = {
    ("USD", "2026-08-03"): 87.42,
    ("USD", "2026-08-10"): 87.15,
    ("EUR", "2026-08-03"): 95.08,
}


def lookup_exchange_rate(currency: str, date: str) -> dict:
    rate = RATES.get((currency.upper(), date))
    if rate is None:
        return {"error": f"No rate for {currency} on {date}"}
    return {"currency": currency.upper(), "date": date, "inr_rate": rate}


rate_tool = {
    "type": "function",
    "name": "lookup_exchange_rate",
    "description": "Look up the INR exchange rate for a currency on a date (YYYY-MM-DD).",
    "parameters": {
        "type": "object",
        "properties": {
            "currency": {"type": "string", "description": "ISO code, e.g. USD"},
            "date": {"type": "string", "description": "YYYY-MM-DD"},
        },
        "required": ["currency", "date"],
    },
}

# Turn 1: the model decides to call the tool
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What was the USD to INR exchange rate on 2026-08-03?",
    tools=[rate_tool],
)

fc_step = next(s for s in interaction.steps if s.type == "function_call")
print(f"Model requested: {fc_step.name}({fc_step.arguments})")

# Your code executes the function locally
result = lookup_exchange_rate(**fc_step.arguments)

# Turn 2: send the result back; tools must be re-specified (interaction-scoped)
final = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": fc_step.name,
            "call_id": fc_step.id,
            "result": [{"type": "text", "text": json.dumps(result)}],
        }
    ],
    tools=[rate_tool],
)

print(final.output_text)

Çıktı: 

Burada 3 şey oldu:  

1. 1. tur, bir ad, yapılandırılmış argümanlar ve bir id içeren bir function_call adımı döndürdü.

2. Python kodunuz aramayı yerelde çalıştırdı.

3. 2. tur, bu çağrıyı referans alan bir function_result bloğu gönderdi. 

tools parametresi, PDF bölümünde response_format’in yeniden geçirilmesi gerektiğiyle aynı nedenle 2. turda tekrar geçirilir: previous_interaction_id geçmişi taşır, yapılandırmayı değil.

Gemini 3.x’te fonksiyon çağırma hataları

Bir araç döngüsü bozulursa, neredeyse her zaman 2 şeyden biridir. 

İlk olarak, her sonuç çağrısına geri eşlenmelidir. Interactions API’de bu, function_result bloğundaki call_id ve name’dir; eski generateContent API’sinde ise FunctionResponse, önceki FunctionCall’un id ve name’iyle eşleşmelidir. Hiçbiri Gemini 3.x’te isteğe bağlı değildir.

İkinci olarak, Malformed_Function_Call hatası genellikle model, araç çağrısından önce yorum yazdığında oluşur. Google’ın 3.8 geliştirici rehberi, araç öncesi metni temizlemeyi, satır içi talimatları \n\n ile biçimlendirmeyi ve çalışma notlarını düz metin yerine özel bir fonksiyon çağrısına sarmayı önerir. Sistem talimatını sıkılaştırın; körü körüne yeniden denemeyin.

Gemini 3.8 Flash’a Geçtiğinizde Ne Bozulur?

Nereden başladığınıza bağlıdır. 

• Gemini 3.7 Flash’tan: hiçbir şey. Model dizesini gemini-3.8-flash olarak değiştirin ve bu yazıdaki her parça, API yüzeyi aynı olduğu için değişmeden çalışır. 

• Gemini 3.6 Flash veya daha eskisinden geliyorsanız, model yapılandırması daha öncekiyle aynı 15 dakikalık denetimi gerektirir.

Geçiş kontrol listesi (3.6 Flash veya daha eskisinden)

Bunları sırayla çalışın. 1’den 3’e kadar olan maddeler anında 400 döndürür; 4 ve 5 ise sessiz kalite sorunlarına yol açar.

1. Model kimliğini gemini-3.8-flash olarak değiştirin.

2. Ölü örnekleme parametrelerini silin: temperature, top_p ve top_k Gemini 3.x’te yok sayılır veya reddedilir; frequency_penalty, presence_penalty ve candidate_count etkin bir API hatası fırlatır. Eski konfigürasyonlardan tüm 6’sını kaldırın.

3. thinking_budget’ı thinking_level ile değiştirin: yalnızca low, medium veya high kullanın. Eski minimal değeri göndermek doğrulama hatası döndürür. Aynı istekte hem thinking_budget hem thinking_level göndermek 400 döndürür.

4. Önden doldurulmuş model turlarını kaldırın: bunları kurduğunuz her sohbetten temizleyin ve son kullanıcı turunun boş olmayan metni olduğundan emin olun. Geçmiş yükleri model turuyla bitemez.

5. Çok turlu akışları standartlaştırın: istemci tarafı geçmiş oynatımı yerine previous_interaction_id’ye güvenin. Araçlarınızı, system_instruction ve generation_config’i önemli oldukları her turda yeniden belirtmelisiniz.

Google, yetkili sürümü Gemini API model dokümanlarında yayımlar; kodlama ajanınız becerileri destekliyorsa otomatik bir yol da dahildir. Yine de bir kez kendiniz okuyun; otomatik bir geçiş, temperature=0.2 ayarınızın ilk etapta neden orada olduğunu söylemez.

Üretimde karşılaşacağınız hatalar

İşte işleyici yazmaya değer 4 durum kodu ve bu API’de her birinin gerçekte ne anlama geldiği:

Burada 2 ek nokta:

• thinking_level: "high" ile uzun araç döngülerini birleştirirken açık istemci zaman aşımları ayarlayın; çünkü askıda kalan istek, başarısız olandan daha kötüdür ve 3.8’in ek titizliği uzun akıl yürütme çalıştırmalarını daha olası kılar, azaltmaz. 

• Ve her istekle interaction.id’yi günlüğe alın; bu, saklanan etkileşimleri daha sonra alma, hata ayıklama veya silme için tutamağınızdır.

Son Düşünceler

Bu yazıdaki her şey 3 kaymaya dayanır. Interactions API çağrı sözleşmesini değiştirdi, thinking_level ayarladığınız tüm örnekleme düğmelerinin yerini aldı ve previous_interaction_id üzerinden sunucu tarafı durum hem PDF takibini hem de araç döngüsünü, geçmişi yeniden oynatma alıştırmaları yerine tek satırlık turlara dönüştürdü. Gemini 3.8 Flash bunların hiçbir yüzeyini değiştirmedi; değiştirdiği, modelin bunun içinde ne kadar çalıştığıdır; bu yüzden bu yazıdaki ölçümler, 3.7’den taşınmak yerine 3.8 üzerinde taze alındı.

Seviye önerilerimi peşinen kabul etmeden önce, karşılaştırma betiğini kendi bekleyen işlerinizden bir göreve yöneltin; ödeme-yeniden deneme yarışında kazanan seviye, SQL üretimi iş yükünüzde kaybedebilir. 

Tekil API çağrıları yeterli gelmemeye başladığında ve üretim AI sistemleri istediğinizde, Developers için Associate AI Engineer yolumuz tüm yolu kapsar; Data Scientists için Associate AI Engineer yolu ise aynı şeyi veri tarafından yapar.