Partner- und Bibliotheksintegrationen

In diesem Leitfaden werden Architekturstrategien für das Erstellen von Bibliotheken, Plattformen und Gateways auf der Grundlage der Gemini API beschrieben. Darin werden die technischen Kompromisse zwischen der Verwendung der offiziellen GenAI-SDKs, der Direct API (REST/gRPC) und der OpenAI-Kompatibilitätsebene beschrieben.

Diese Anleitung ist für Sie gedacht, wenn Sie Tools für andere Entwickler erstellen, z. B. Open-Source-Frameworks, Enterprise-Gateways oder SaaS-Aggregatoren, und die Abhängigkeitshygiene, die Bundle-Größe oder die Funktionsparität optimieren müssen.

Was ist die Partnerintegration?

Ein Partner ist jeder, der eine Integration zwischen der Gemini API und Endnutzerentwicklern erstellt. Wir unterteilen Partner in vier Archetypen. Wenn Sie wissen, welcher Typ am besten zu Ihnen passt, können Sie den richtigen Integrationspfad auswählen.

Ecosystem Framework

• Wer Sie sind:Sie sind Maintainer eines Open-Source-Frameworks (z.B. LangChain, LlamaIndex, Spring AI) oder sprachspezifische Clients.
• Ihr Ziel:Umfassende Kompatibilität. Ihre Bibliothek soll in jeder Umgebung funktionieren, die der Nutzer auswählt, ohne Konflikte zu erzwingen.

Laufzeit- und Edge-Plattform

• Wer Sie sind:SaaS-Plattformen, KI-Gateways oder Anbieter von Cloud-Infrastruktur (z.B. Vercel, Cloudflare, Zapier), in denen die Codeausführung in eingeschränkten Umgebungen erfolgt.
• Ihr Ziel:Leistung. Sie benötigen eine niedrige Latenz, eine minimale Bundle-Größe und schnelle Kaltstarts.

Dienstleister

• Wer Sie sind:Plattformen, Proxys oder interne „Model Gardens“, die den Zugriff auf viele verschiedene LLM-Anbieter (z.B. OpenAI, Anthropic, Google) über eine einzige Schnittstelle normalisieren.
• Ihr Ziel:Portabilität und Einheitlichkeit.

Enterprise-Gateway

• Zielgruppe:Interne Platform Engineering-Teams in großen Unternehmen, die „Golden Paths“ für Hunderte von internen Entwicklern erstellen.
• Ihr Ziel:Standardisierung, Governance und einheitliche Authentifizierung.

Vergleich auf einen Blick

Globale Best Practice:Alle Partner müssen den x-goog-api-client-Header senden, unabhängig vom gewählten Pfad.

Google GenAI SDK-Integration

Für Frameworks ist die Implementierung des Google GenAI SDK oft der einfachste Weg, da in unterstützten Sprachen nur wenige Codezeilen erforderlich sind.

Für interne Plattformteams ist das primäre Ergebnis oft ein „Golden Path“, der es Produktentwicklern ermöglicht, schnell zu arbeiten und gleichzeitig Sicherheitsrichtlinien einzuhalten.

Vorteile:

• Einheitliche Schnittstelle für die Vertex AI-Migration:Interne Entwickler erstellen häufig Prototypen mit API-Schlüsseln (Gemini API) und stellen sie zur Einhaltung der Produktionsanforderungen in Vertex AI (IAM) bereit. Das SDK abstrahiert diese Authentifizierungsunterschiede. Bei Frameworks können Sie ebenfalls einen Codepfad implementieren und zwei Nutzergruppen unterstützen.
• Clientseitige Hilfsprogramme:Das SDK enthält idiomatische Hilfsprogramme, die den Boilerplate-Code für komplexe Aufgaben reduzieren.
  • Beispiele:Unterstützung von PIL-Bildobjekten direkt in Prompts, automatischer Funktionsaufruf und umfassende Typen.
• Zugriff auf Funktionen ab dem ersten Tag:Neue API-Funktionen sind ab dem Start über die SDKs verfügbar.
• Verbesserte Unterstützung für die Codeerstellung:Bei der lokalen SDK-Installation werden Typdefinitionen und Docstrings für Coding-Assistenten (z.B. Cursor, Copilot). Dieser Kontext verbessert die Genauigkeit der Codegenerierung im Vergleich zur Generierung von REST-Rohanfragen.

Der Kompromiss:

• Gewichtung und Komplexität von Abhängigkeiten:Die SDKs haben eigene Abhängigkeiten, die die Bundle-Größe und das Risiko in der Lieferkette erhöhen können.
• Versionsverwaltung:Neue API-Funktionen sind oft an Mindest-SDK-Versionen gebunden. Möglicherweise müssen Sie Updates für Nutzer bereitstellen, damit sie auf neue Funktionen oder Modelle zugreifen können. In einigen Fällen sind dazu Änderungen an transitiven Abhängigkeiten erforderlich, die sich auf Ihre Nutzer auswirken.
• Protokollbeschränkungen:Die SDKs unterstützen nur HTTPS für die Haupt-API und WebSockets (WSS) für die Live API. gRPC wird mit den SDK-Clients auf hoher Ebene nicht unterstützt.
• Sprachunterstützung:Die SDKs unterstützen aktuelle Sprachversionen. Wenn Sie EOL-Versionen unterstützen müssen (z.B. Python 3.9) müssten Sie einen Fork verwalten.

Best Practice:

• Versionen sperren:Pinnen Sie die SDK-Version in Ihren internen Basis-Images, um die Stabilität teamübergreifend zu gewährleisten.

Direkte API-Verknüpfung

Wenn Sie eine Bibliothek an Tausende von Entwicklern verteilen, die in einer eingeschränkten Umgebung ausgeführt wird, oder einen Aggregator erstellen, für den die neuesten Funktionen von Gemini erforderlich sind, müssen Sie die API möglicherweise direkt über REST oder gRPC einbinden.

Vorteile:

• Vollständiger Funktionszugriff:Im Gegensatz zur OpenAI-Kompatibilitätsebene können Sie durch die direkte Verwendung der API Gemini-spezifische Funktionen nutzen, z. B. das Hochladen in die File API, das Erstellen von Content-Caching und die bidirektionale Live API.
• Minimale Abhängigkeiten:In einer Umgebung, in der Abhängigkeiten aufgrund von Größe oder Prüfungskosten problematisch sind. Wenn Sie die API direkt über eine Standardbibliothek wie fetch oder über einen Wrapper wie httpx verwenden, bleibt Ihre Bibliothek schlank.
• Sprachunabhängig:Dies ist der einzige Pfad für Sprachen, die nicht von den SDKs abgedeckt werden, z. B. Rust, PHP und Ruby, da es keine Spracheinschränkungen gibt.
• Leistung:Die Direct API hat keinen Initialisierungsaufwand, wodurch Kaltstarts in serverlosen Funktionen minimiert werden.

Der Kompromiss:

• Manuelle Vertex AI-Implementierung:Im Gegensatz zum SDK werden bei der direkten Verwendung der API die Authentifizierungsunterschiede zwischen AI Studio (API-Schlüssel) und Vertex AI (IAM) nicht automatisch berücksichtigt. Wenn Sie beide Umgebungen unterstützen möchten, müssen Sie separate Auth-Handler implementieren.
• Keine nativen Typen oder Helfer: Sie erhalten keine Codevervollständigungen oder Prüfungen zur Kompilierzeit für Anfrageobjekte, sofern Sie sie nicht selbst implementieren. Es gibt keine Client-„Helfer“ (z. B. Konverter von Funktionen zu Schemas). Sie müssen diese Logik also manuell schreiben.

Best Practice

Wir stellen eine maschinenlesbare Spezifikation zur Verfügung, mit der Sie Typdefinitionen für Ihre Bibliothek generieren können. So müssen Sie sie nicht manuell schreiben. Laden Sie die Spezifikation während des Build-Prozesses herunter, generieren Sie die Typen und stellen Sie den kompilierten Code bereit.

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

OpenAI SDK-Integration

Wenn Sie eine Plattform sind, die ein einheitliches Schema (OpenAI Chat Completions) gegenüber modellspezifischen Funktionen priorisiert, ist dies der schnellste Weg.

Vorteile:

• Geringer Aufwand:Oft reicht es, die baseURL und apiKey zu ändern, um Gemini-Unterstützung hinzuzufügen. So lassen sich „Bring Your Own Key“-Implementierungen schnell integrieren und Gemini-Unterstützung hinzufügen, ohne neuen Code schreiben zu müssen.
• Einschränkungen:Dieser Pfad wird nur empfohlen, wenn Sie auf das OpenAI SDK beschränkt sind und keine erweiterten Gemini-Funktionen wie die File API benötigen oder Unterstützung für Tools wie „Fundierung mit der Google Suche“ manuell hinzufügen müssen.

Der Kompromiss:

• Einschränkungen bei Funktionen:Die Kompatibilitätsebene bietet Einschränkungen für die wichtigsten Gemini-Funktionen. Die verfügbaren serverseitigen Tools unterscheiden sich je nach Plattform und erfordern möglicherweise eine manuelle Verarbeitung, um mit den Gemini API-Tools zu funktionieren.
• Übersetzungsaufwand:Da das OpenAI-Schema nicht 1:1 der Gemini-Architektur entspricht, führt die Verwendung der Kompatibilitätsebene zu einigen Komplexitäten, die zusätzlichen Implementierungsaufwand erfordern, z. B. die Zuordnung eines „Such“-Tools für Nutzer zum richtigen Plattformtool. Wenn Sie eine erhebliche Menge an Sonderbehandlungen benötigen, kann es sich lohnen, für jede Plattform ein eigenes SDK oder eine eigene API zu verwenden.

Best Practice

Integrieren Sie die Gemini API nach Möglichkeit direkt. Für maximale Kompatibilität sollten Sie jedoch eine Bibliothek verwenden, die verschiedene Anbieter kennt und die Tool- und Nachrichtenzuordnung für Sie übernehmen kann.

Best Practice für alle Partner: Kundenidentifikation

Wenn Sie als Plattform oder Bibliothek Aufrufe an die Gemini API senden, müssen Sie Ihren Client mit dem Header x-goog-api-client identifizieren.

So kann Google Ihre spezifischen Traffic-Segmente identifizieren. Wenn in Ihrer Bibliothek ein bestimmtes Fehlermuster auftritt, können wir Sie kontaktieren, um Ihnen bei der Fehlerbehebung zu helfen.

Verwenden Sie das Format company-product/version (z.B. acme-framework/1.2.0).

Implementierungsbeispiele

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

Nächste Schritte

• Übersicht über die Bibliotheken
• API-Referenz
• OpenAI-Kompatibilitätsleitfaden lesen