Integrasi partner dan library

Panduan ini menguraikan strategi arsitektur untuk membangun library, platform, dan gateway di atas Gemini API. Dokumen ini menjelaskan pertimbangan teknis antara penggunaan SDK GenAI resmi, Direct API (REST/gRPC), dan lapisan kompatibilitas OpenAI.

Gunakan panduan ini jika Anda membuat alat untuk developer lain, seperti framework open source, gateway perusahaan, atau agregator SaaS, dan perlu mengoptimalkan kebersihan dependensi, ukuran paket, atau paritas fitur.

Apa itu integrasi partner?

Partner adalah siapa saja yang membangun integrasi antara Gemini API dan developer pengguna akhir. Kami mengategorikan partner ke dalam empat arketipe. Mengidentifikasi mana yang paling cocok dengan Anda akan membantu Anda memilih jalur integrasi yang tepat.

Framework ekosistem

• Siapa Anda: Pengelola framework open source (misalnya, LangChain, LlamaIndex, Spring AI) atau klien khusus bahasa.
• Sasaran Anda: Kompatibilitas luas. Anda ingin library Anda berfungsi di lingkungan apa pun yang dipilih pengguna tanpa memaksakan konflik.

Platform runtime dan edge

• Siapa Anda: Platform SaaS, Gateway AI, atau penyedia infrastruktur cloud (misalnya, Vercel, Cloudflare, Zapier) tempat eksekusi kode terjadi di lingkungan terbatas.
• Sasaran Anda: Performa. Anda memerlukan latensi rendah, ukuran paket minimal, dan cold start yang cepat.

Agregator

• Siapa Anda: Platform, proxy, atau "Taman Model" internal yang menormalisasi akses di berbagai penyedia LLM (misalnya, OpenAI, Anthropic, Google) ke dalam satu antarmuka.
• Sasaran Anda: Portabilitas dan keseragaman.

Gateway perusahaan

• Siapa Anda: Tim Engineering Platform internal di perusahaan besar yang membangun "Jalur Ideal" untuk ratusan developer internal.
• Sasaran Anda: Standardisasi, tata kelola, dan autentikasi terpadu.

Perbandingan sekilas

Praktik terbaik global: Semua partner harus mengirimkan header x-goog-api-clientterlepas dari jalur yang dipilih.

Integrasi Google GenAI SDK

Untuk framework, penerapan Google GenAI SDK sering kali merupakan jalur yang paling sederhana, mengingat jumlah baris kode yang paling sedikit dalam bahasa yang didukung.

Untuk tim platform internal, hasil utama Anda sering kali berupa "jalur emas" yang memungkinkan engineer produk bergerak cepat sekaligus mematuhi kebijakan keamanan.

Manfaat:

• Antarmuka terpadu untuk migrasi Vertex AI: Developer internal sering kali membuat prototipe menggunakan Kunci API (Gemini API) dan men-deploy ke Vertex AI (IAM) untuk kepatuhan produksi. SDK mengabstraksi perbedaan autentikasi ini. Demikian pula untuk framework, Anda dapat menerapkan satu jalur kode dan mendukung dua set pengguna.
• Helper sisi klien: SDK menyertakan utilitas idiomatik yang mengurangi boilerplate untuk tugas yang rumit.
  • Contoh: Mendukung objek gambar PIL secara langsung dalam perintah, panggilan fungsi otomatis, dan jenis yang komprehensif.
• Akses fitur pada hari peluncuran: Fitur API baru tersedia pada waktu peluncuran melalui SDK.
• Dukungan pembuatan kode yang ditingkatkan: Penginstalan SDK lokal mengekspos definisi jenis dan docstring ke asisten coding (misalnya, Kursor, Copilot). Konteks ini meningkatkan akurasi pembuatan kode dibandingkan dengan membuat permintaan REST mentah.

Komprominya:

• Bobot & kompleksitas dependensi: SDK memiliki dependensinya sendiri, yang dapat meningkatkan ukuran bundle dan berpotensi menimbulkan risiko rantai pasokan.
• Pembuatan Versi: Fitur API baru sering kali disematkan ke versi SDK minimum. Anda mungkin perlu mengirimkan update kepada pengguna untuk mengakses fitur atau model baru, yang dalam beberapa kasus mungkin memerlukan perubahan pada dependensi transitif yang memengaruhi pengguna Anda.
• Batasan protokol: SDK hanya mendukung HTTPS untuk API utama dan WebSockets (WSS) untuk Live API. gRPC tidak didukung menggunakan klien SDK tingkat tinggi.
• Dukungan bahasa: SDK mendukung versi bahasa saat ini. Jika Anda perlu mendukung versi EOL (misalnya, Python 3.9), Anda harus mempertahankan fork.

Praktik terbaik:

• Mengunci versi: Sematkan versi SDK di image dasar internal Anda untuk memastikan stabilitas di seluruh tim.

Integrasi API langsung

Jika Anda mendistribusikan library kepada ribuan developer, menjalankan di lingkungan yang terbatas, atau membangun agregator yang memerlukan fitur canggih Gemini, Anda mungkin perlu berintegrasi dengan API secara langsung menggunakan REST atau gRPC.

Manfaat:

• Akses fitur lengkap: Tidak seperti lapisan kompatibilitas OpenAI, penggunaan API secara langsung memungkinkan fitur khusus Gemini, seperti mengupload ke File API, membuat caching konten, dan menggunakan Live API dua arah.
• Dependensi minimal: Dalam lingkungan yang dependensinya sensitif karena ukuran atau biaya audit. Menggunakan API secara langsung melalui library standar seperti fetch atau melalui wrapper seperti httpx memastikan library Anda tetap ringan.
• Agnostik bahasa: Ini adalah satu-satunya jalur untuk bahasa yang tidak tercakup oleh SDK, seperti Rust, PHP, dan Ruby, karena tidak ada batasan bahasa.
• Performa: Direct API memiliki overhead inisialisasi nol, sehingga meminimalkan cold start dalam fungsi serverless.

Komprominya:

• Implementasi Vertex AI manual: Tidak seperti SDK, penggunaan API secara langsung tidak secara otomatis menangani perbedaan autentikasi antara AI Studio (Kunci API) dan Vertex AI (IAM). Anda harus menerapkan handler autentikasi terpisah jika ingin mendukung kedua lingkungan.
• Tidak ada jenis atau helper bawaan: Anda tidak akan mendapatkan penyelesaian kode atau pemeriksaan waktu kompilasi untuk objek permintaan kecuali jika Anda menerapkannya sendiri. Tidak ada "helper" klien (misalnya, konverter fungsi ke skema), jadi Anda harus menulis logika ini secara manual sendiri.

Praktik terbaik

Kami mengekspos spesifikasi yang dapat dibaca mesin yang dapat Anda gunakan untuk membuat definisi jenis untuk library Anda, sehingga Anda tidak perlu menuliskannya secara manual. Download spesifikasi selama proses build, buat jenis, dan kirim kode yang dikompilasi.

• Endpoint: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

Integrasi OpenAI SDK

Jika Anda adalah platform yang memprioritaskan skema terpadu (OpenAI Chat Completions) daripada fitur khusus model, ini adalah cara tercepat Anda.

Manfaat:

• Gesekan rendah: Anda sering kali dapat menambahkan dukungan Gemini dengan mengubah baseURL dan apiKey. Cara ini adalah cara cepat untuk mengintegrasikan penerapan "Bawa Kunci Anda Sendiri", menambahkan dukungan Gemini tanpa menulis kode baru.
• Batasan: Jalur ini hanya direkomendasikan jika Anda dibatasi untuk OpenAI SDK dan tidak memerlukan fitur Gemini lanjutan seperti File API, atau menambahkan dukungan untuk alat seperti Perujukan dengan Penelusuran Google secara manual.

Komprominya:

• Batasan fitur: Lapisan kompatibilitas memberikan batasan pada kemampuan inti Gemini. Alat sisi server yang tersedia berbeda di setiap platform, dan mungkin memerlukan penanganan manual agar dapat berfungsi dengan alat Gemini API.
• Overhead terjemahan: Karena skema OpenAI tidak dipetakan satu per satu ke arsitektur Gemini, mengandalkan lapisan kompatibilitas akan menimbulkan beberapa kompleksitas yang memerlukan pekerjaan penerapan tambahan untuk diselesaikan, seperti memetakan alat "penelusuran" pengguna ke alat platform yang tepat. Jika Anda memerlukan banyak sekali penanganan khusus, mungkin lebih baik menggunakan SDK atau API khusus untuk setiap platform.

Praktik terbaik

Jika memungkinkan, lakukan integrasi langsung dengan Gemini API. Namun, untuk kompatibilitas maksimum, pertimbangkan untuk menggunakan library yang mengetahui berbagai penyedia dan dapat menangani pemetaan alat dan pesan untuk Anda.

Praktik terbaik untuk semua partner: identifikasi klien

Saat melakukan panggilan ke Gemini API sebagai platform atau library, Anda harus mengidentifikasi klien menggunakan header x-goog-api-client.

Dengan begitu, Google dapat mengidentifikasi segmen traffic spesifik Anda, dan jika library Anda menghasilkan pola error tertentu, kami dapat menghubungi Anda untuk membantu men-debug.

Gunakan format company-product/version (misalnya, acme-framework/1.2.0).

Contoh implementasi

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",
    }
)

Langkah berikutnya

• Buka ringkasan library untuk mempelajari SDK GenAI
• Jelajahi referensi API
• Baca panduan kompatibilitas OpenAI