İş ortağı ve kitaplık entegrasyonları

Bu kılavuzda, Gemini API'nin üzerinde kitaplıklar, platformlar ve ağ geçitleri oluşturmaya yönelik mimari stratejiler özetlenmektedir. Resmi üretken yapay zeka SDK'ları, Direct API (REST/gRPC) ve OpenAI uyumluluk katmanının kullanımı arasındaki teknik avantaj ve dezavantajlar ayrıntılı olarak açıklanır.

Diğer geliştiriciler için araçlar (ör. açık kaynaklı çerçeveler, kurumsal ağ geçitleri veya SaaS toplayıcılar) oluşturuyorsanız ve bağımlılık temizliği, paket boyutu ya da özellik eşliği için optimizasyon yapmanız gerekiyorsa bu kılavuzdan yararlanın.

İş ortağı entegrasyonu nedir?

İş ortağı, Gemini API ile son kullanıcı geliştiricileri arasında entegrasyon oluşturan herkesi ifade eder. İş ortaklarını dört arketipte sınıflandırıyoruz. Hangisiyle en çok eşleştiğinizi belirlemek doğru entegrasyon yolunu seçmenize yardımcı olur.

Ekosistem çerçevesi

• Kim olduğunuz: Açık kaynaklı bir çerçeve (ör. LangChain, LlamaIndex, Spring AI) veya dile özgü istemcilerin bakımını yapan kişi.
• Hedefiniz: Geniş kapsamlı uyumluluk. Kitaplığınızın, kullanıcınızın seçtiği herhangi bir ortamda çakışmaya neden olmadan çalışmasını istiyorsunuz.

Çalışma zamanı ve uç platform

• Kim olduğunuz: Kod yürütmenin kısıtlanmış ortamlarda gerçekleştiği SaaS platformları, yapay zeka ağ geçitleri veya bulut altyapısı sağlayıcıları (ör. Vercel, Cloudflare, Zapier).
• Hedefiniz: Performans. Düşük gecikme süresi, minimum paket boyutu ve hızlı soğuk başlatma gerekir.

Toplayıcı

• Kim olduğunuz: Birçok farklı büyük dil modeli sağlayıcısında (ör. OpenAI, Anthropic, Google) erişimi tek bir arayüzde normalleştiren platformlar, proxy'ler veya dahili "Model Bahçeleri".
• Hedefiniz: Taşınabilirlik ve tekdüzelik.

Kurumsal ağ geçidi

• Kimler için: Büyük şirketlerdeki dahili platform mühendisliği ekipleri, yüzlerce dahili geliştirici için "altın yollar" oluşturuyor.
• Hedefiniz: Standartlaştırma, yönetim ve birleştirilmiş kimlik doğrulama.

Bir bakışta karşılaştırma

Küresel en iyi uygulama: Seçilen yoldan bağımsız olarak tüm iş ortakları x-goog-api-client üstbilgisini göndermelidir.

Google GenAI SDK entegrasyonu

Desteklenen dillerde en az kod satırı gerektiğinden, çerçeveler için Google GenAI SDK'sını uygulamak genellikle en basit yoldur.

Dahili platform ekipleri için temel çıktı genellikle ürün mühendislerinin güvenlik politikalarına uyarken hızlı hareket etmesini sağlayan bir "altın yol"dur.

Avantajları:

• Gemini Enterprise Ajan Platformu'na taşıma için birleşik arayüz: Dahili geliştiriciler genellikle API anahtarlarını (Gemini API) kullanarak prototip oluşturur ve üretim uyumluluğu için Gemini Enterprise Ajan Platformu'na (IAM) dağıtım yapar. SDK, bu kimlik doğrulama farklılıklarını soyutlar. Benzer şekilde, çerçeveler için tek bir kod yolu uygulayabilir ve iki kullanıcı grubunu destekleyebilirsiniz.
• İstemci tarafı yardımcıları: SDK, karmaşık görevler için standart kodları azaltan deyimsel yardımcı programlar içerir.
  • Örnekler: Doğrudan istemlerde PIL görüntü nesnelerini destekleme, otomatik işlev çağrısı ve kapsamlı türler.
• İlk günden itibaren özellik erişimi: Yeni API özellikleri, SDK'lar aracılığıyla kullanıma sunulur.
• Geliştirilmiş kod oluşturma desteği: Yerel SDK yüklemesi, tür tanımlarını ve doküman dizelerini kodlama asistanlarına (ör. Cursor, Copilot) sunar. Bu bağlam, ham REST istekleri oluşturmaya kıyasla kod oluşturma doğruluğunu artırır.

Değiş-tokuş:

• Bağımlılık ağırlığı ve karmaşıklığı: SDK'ların kendi bağımlılıkları vardır. Bu bağımlılıklar, paket boyutunu artırabilir ve potansiyel olarak tedarik zinciri riski oluşturabilir.
• Sürüm oluşturma: Yeni API özellikleri genellikle minimum SDK sürümlerine sabitlenir. Yeni özelliklere veya modellere erişmek için kullanıcıları güncellemeye zorlamanız gerekebilir. Bu durumda, kullanıcılarınızı etkileyen geçişli bağımlılıklar değiştirilebilir.
• Protokol sınırları: SDK'lar, ana API için yalnızca HTTPS'yi, Canlı API için ise WebSocket'leri (WSS) destekler. gRPC, üst düzey SDK istemcileri kullanılarak desteklenmez.
• Dil desteği: SDK'lar, mevcut dil sürümlerini destekler. Destek sonu (EOL) sürümlerini (ör. Python 3.9) desteklemeniz gerekiyorsa bir çatallanmayı sürdürmeniz gerekir.

En iyi uygulama:

• Sürümleri kilitleme: Ekipler arasında kararlılığı sağlamak için dahili temel resimlerinizdeki SDK sürümünü sabitleyin.

Doğrudan API entegrasyonu

Binlerce geliştiriciye kitaplık dağıtıyorsanız, kısıtlanmış bir ortamda çalışıyorsanız veya Gemini'ın en yeni özelliklerini gerektiren bir toplayıcı oluşturuyorsanız REST veya gRPC kullanarak doğrudan API ile entegrasyon yapmanız gerekebilir.

Avantajları:

• Tüm özelliklere erişim: OpenAI uyumluluk katmanının aksine, API'yi doğrudan kullanmak Gemini'a özgü özellikleri (ör. File API'ye yükleme, içerik önbelleğe alma oluşturma ve çift yönlü Live API kullanma) etkinleştirir.
• Minimum bağımlılıklar: Bağımlılıkların boyut veya denetim maliyetleri nedeniyle hassas olduğu bir ortamda. API'yi doğrudan fetch gibi standart bir kitaplık veya httpx gibi bir sarmalayıcı aracılığıyla kullanmak kitaplığınızın hafif kalmasını sağlar.
• Dilden bağımsız: Dil kısıtlaması olmadığından bu, SDK'ların kapsamadığı diller (ör. Rust, PHP ve Ruby) için tek yoldur.
• Performans: Direct API'nin başlatma ek yükü yoktur. Bu sayede, sunucusuz işlevlerdeki soğuk başlatmalar en aza indirilir.

Değiş-tokuş:

• Gemini Enterprise Ajan Platformu'nun manuel olarak uygulanması: SDK'dan farklı olarak, API'nin doğrudan kullanılması, AI Studio (API anahtarı) ile Gemini Enterprise Ajan Platformu (IAM) arasındaki kimlik doğrulama farklılıklarını otomatik olarak işlemez. Her iki ortamı da desteklemek istiyorsanız ayrı kimlik doğrulama işleyicileri uygulamanız gerekir.
• Yerel türler veya yardımcılar yok: İstek nesneleri için kod tamamlamaları veya derleme zamanı kontrolleri almazsınız. Bunları kendiniz uygulamanız gerekir. İstemci "yardımcıları" (ör. işlevden şemaya dönüştürücüler) olmadığından bu mantığı kendiniz manuel olarak yazmanız gerekir.

En iyi uygulama

Kitaplığınız için tür tanımları oluşturmak üzere kullanabileceğiniz, makine tarafından okunabilir bir spesifikasyon sunuyoruz. Böylece, bu tanımları manuel olarak yazmak zorunda kalmazsınız. Derleme işleminiz sırasında spesifikasyonu indirin, türleri oluşturun ve derlenmiş kodu gönderin.

• Uç nokta: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

OpenAI SDK entegrasyonu

Modelden bağımsız özellikler yerine birleşik şemaya (OpenAI Chat Completions) öncelik veren bir platformsanız bu, en hızlı rotanızdır.

Avantajları:

• Kolaylık: Genellikle baseURL ve apiKey değiştirerek Gemini desteği ekleyebilirsiniz. Bu, "Kendi Anahtarını Getir" uygulamalarını entegre etmenin ve yeni kod yazmadan Gemini desteği eklemenin hızlı bir yoludur.
• Kısıtlamalar: Bu yol yalnızca OpenAI SDK ile sınırlıysanız ve File API gibi gelişmiş Gemini özelliklerine ya da Google Arama ile Temellendirme gibi araçlar için manuel olarak destek eklemeniz gerekmiyorsa önerilir.

Değiş-tokuş:

• Özellik sınırlamaları: Uyumluluk katmanı, temel Gemini özelliklerini sınırlar. Kullanılabilen sunucu tarafı araçlar platformlar arasında farklılık gösterir ve Gemini API araçlarıyla çalışmak için manuel olarak işlenmesi gerekebilir.
• Çeviri ek yükü: OpenAI şeması, Gemini'ın mimarisiyle bire bir eşlenmediğinden uyumluluk katmanını kullanmak, çözmek için ek uygulama çalışması gerektiren bazı karmaşıklıklara yol açar. Örneğin, kullanıcının "arama" aracını doğru platform aracıyla eşlemek gibi. Özel durumların önemli ölçüde kullanılması gerekiyorsa her platform için özel bir SDK veya API kullanmak daha faydalı olabilir.

En iyi uygulama

Mümkün olduğunda doğrudan Gemini API ile entegrasyon yapın. Ancak maksimum uyumluluk için farklı sağlayıcıların farkında olan ve araç ile mesaj eşlemeyi sizin için yapabilen bir kitaplık kullanmayı düşünebilirsiniz.

Tüm iş ortakları için en iyi uygulama: istemci tanımlama

Platform veya kitaplık olarak Gemini API'ye çağrı yaparken x-goog-api-client üstbilgisini kullanarak istemcinizi tanımlamanız gerekir.

Bu, Google'ın belirli trafik segmentlerinizi tanımlamasına olanak tanır. Kitaplığınız belirli bir hata modeli üretiyorsa hata ayıklama konusunda yardımcı olmak için sizinle iletişime geçebiliriz.

company-product/version biçimini kullanın (ör. acme-framework/1.2.0).

Uygulama örnekleri

from google import genai

client = genai.Client(
    api_key="...",
    http_options={
        "headers": {
            "x-goog-api-client": "acme-framework/1.2.0",
        }
    }
)

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H 'x-goog-api-client: acme-framework/1.2.0' \
    -d '{...}'

from openai import OpenAI

client = OpenAI(
    api_key="...",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
    default_headers={
        "x-goog-api-client": "acme-framework-oai/1.2.0",
    }
)

Sonraki adımlar

• GenAI SDK'ları hakkında bilgi edinmek için kitaplığa genel bakış sayfasını ziyaret edin.
• API referansına göz atın.
• OpenAI uyumluluk kılavuzunu okuyun.