API & Backend
FastAPI ve Gemini 3.7 API ile Gerçek Zamanlı Streaming ve Function Calling
Python FastAPI backend kullanarak Google Gemini API ile Server-Sent Events (SSE) tabanlı gerçek zamanlı yapay zekâ streaming ve araç çağırma (function calling) mimarisi.
Özet & Doğrudan Çözüm (TL;DR)
FastAPI ile Google Gemini 3.7 API entegrasyonunda Server-Sent Events (SSE) kullanılarak, modelin ürettiği ilk token'lar milisaniyeler (<250ms) içinde istemciye ulaştırılır. Asenkron jeneratörler (async generator), HTTP/2 streaming ve Pydantic v2 veri modelleri birleştirilerek hem yüksek eşzamanlılık hem de kesintisiz kullanıcı deneyimi sağlanır.
Önemli Çıkarımlar:
- TTFT (Time to First Token) Optimizasyonu: Streaming sayesinde tüm cevabı beklemek yerine kullanıcı ilk kelimeleri 200-300ms içinde okur.
- FastAPI StreamingResponse ve SSE Protokolü: text/event-stream başlığı ile istemci tarafında EventSource veya fetch stream tüketimi.
- Function Calling ve Structured Tool Streaming: Gemini'nin araç çağırma yeteneğini streaming esnasında yakalama ve yürütme.
- Nginx Buffering ve Timeout Yönetimi: X-Accel-Buffering başlığı ile proxy sunucularda paket gecikmelerini sıfırlama.
1. Neden Streaming? LLM Uygulamalarında Gecikme Anatomisi
Büyük dil modellerinde yanıt uzunluğu arttıkça toplam üretim süresi 5 ila 15 saniyeye kadar çıkabilir. Eğer istemciye tüm yanıt tamamlandıktan sonra tek bir JSON bloğu dönülürse, kullanıcı beyaz ekrana bakmak zorunda kalır ve uygulamanın çöktüğünü düşünebilir.
Server-Sent Events (SSE) protokolü ve FastAPI asenkron jeneratörleri, üretilen her token parçasını (chunk) anında istemciye ileterek İlk Tokena Ulaşma Süresini (TTFT) 250ms seviyesine indirir.
2. FastAPI ve Google GenAI ile Uçtan Uca Asenkron Streaming
Aşağıdaki üretim düzeyindeki implementasyon, Google GenAI SDK'sının asenkron akışını FastAPI `StreamingResponse` üzerinden istemciye dağıtır:
import json
from typing import AsyncGenerator
from fastapi import FastAPI, HTTPException
from fastapi.responses import StreamingResponse
from google import genai
from google.genai import types
app = FastAPI(title="Gemini Streaming API")
ai_client = genai.Client()
async def generate_gemini_stream(prompt: str) -> AsyncGenerator[str, None]:
try:
response = ai_client.models.generate_content_stream(
model="gemini-3.7-flash",
contents=prompt,
config=types.GenerateContentConfig(
temperature=0.3,
max_output_tokens=2048,
)
)
for chunk in response:
if chunk.text:
# SSE standart veri biçimi: data: <payload>\n\n
payload = json.dumps({"text": chunk.text})
yield f"data: {payload}\n\n"
except Exception as exc:
err_payload = json.dumps({"error": str(exc)})
yield f"data: {err_payload}\n\n"
@app.get("/api/chat/stream")
async def chat_stream_endpoint(q: str):
if not q.strip():
raise HTTPException(status_code=400, detail="Sorgu boş olamaz.")
headers = {
"Content-Type": "text/event-stream",
"Cache-Control": "no-cache",
"Connection": "keep-alive",
"X-Accel-Buffering": "no", # Nginx önbelleğe almasını kapatır
}
return StreamingResponse(generate_gemini_stream(q), headers=headers)3. Function Calling (Araç Çağırma) ile Akışı Birleştirme
Kullanıcı hava durumu, borsa verisi veya veritabanı sorgusu sorduğunda model bir araç çağırma (tool call) talebinde bulunur.
Streaming hattı, modelden gelen yanıtın normal metin mi yoksa fonksiyon çağırma isteği mi olduğunu `chunk.function_calls` üzerinden kontrol eder. Fonksiyon çağrısı geldiğinde backend işlemi yürütür ve sonucu modele tekrar akıtarak kesintisiz yanıt üretir.
4. Nginx, Cloudflare ve Timeout Tuzakları
Üretim ortamında FastAPI'nin önüne Nginx veya Cloudflare girdiğinde, aradaki proxy sunucular token'ları paketleyip biriktirmek isteyebilir. Bu durum akışın kesintili gelmesine yol açar.
Bunu önlemek için yanıta mutlaka `X-Accel-Buffering: no` başlığı eklenmeli ve proxy timeout süresi (proxy_read_timeout) en az 120 saniyeye ayarlanmalıdır.
Sıkça Sorulan Sorular
FastAPI WebSocket mi yoksa SSE (Server-Sent Events) mi tercih edilmeli?
Yalnızca sunucudan istemciye tek yönlü veri akışı gerektiren sohbet ve LLM çıktılarında SSE çok daha hafif, HTTP tabanlı ve firewall dostudur. Çift yönlü mikrofon/kamera akışlarında ise WebSocket gereklidir.
Streaming sırasında token maliyeti artar mı?
Hayır. Google Gemini API'de token fiyatlandırması üretilen toplam girdi ve çıktı token'ları üzerinden hesaplanır; streaming veya tekil yanıt olması fiyatı değiştirmez.
Doğrulanmış Kaynaklar ve Dokümantasyon
- Google GenAI Python SDK DocumentationResmi Doküman
- FastAPI Streaming Endpoints Official GuideResmi Doküman
- MDN Server-Sent Events SpecificationResmi Doküman
İlgili Teknik Rehberler
Bu mimariyle bağlantılı diğer üretim odaklı rehber ve vaka analizlerini inceleyin:
LLM Yapılandırılmış Çıktılar: Pydantic v2, JSON Schema ve Instructor ile Sıfır Hatalı Veri Çıkarma
LLM çıktılarının kırılmasını önlemek için Pydantic v2, Instructor ve yerel JSON Schema modları ile %100 tip güvenli veri çıkarma rehberi.
FastAPI Async Mimarisi: Asyncio Event Loop ve Yüksek Eşzamanlılık (Concurrency)
FastAPI'de async def ve def fonksiyonlarının nasıl çalıştığını, threadpool tuzaklarını ve saniyede on binlerce isteği bloklanmadan yönetme tekniklerini öğrenin.
FastAPI Dependency Injection (DI) ile Temiz ve Test Edilebilir Mimari Kurulumu
FastAPI'nin Depends mekanizmasını kullanarak veritabanı oturumlarını, kimlik doğrulama katmanlarını ve servis bağımlılıklarını izole etme rehberi.