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.

Güncellendi: 9 Eylül 20265 dk
Paylaş:XLinkedIn

Ö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:

gemini_stream.py
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

İlgili Teknik Rehberler

Bu mimariyle bağlantılı diğer üretim odaklı rehber ve vaka analizlerini inceleyin: