Intégrations de partenaires et de bibliothèques

Ce guide présente les stratégies architecturales permettant de créer des bibliothèques, des plates-formes et des passerelles sur l'API Gemini. Il détaille les compromis techniques entre l'utilisation des SDK officiels d'IA générative, de l'API Direct (REST/gRPC) et de la couche de compatibilité OpenAI.

Utilisez ce guide si vous créez des outils pour d'autres développeurs, tels que des frameworks Open Source, des passerelles d'entreprise ou des agrégateurs SaaS, et que vous devez optimiser l'hygiène des dépendances, la taille du bundle ou la parité des fonctionnalités.

Qu'est-ce que l'intégration de partenaires ?

Un partenaire est toute personne qui crée une intégration entre l'API Gemini et les développeurs d'utilisateurs finaux. Nous classons les partenaires en quatre archétypes. Identifier celui qui vous correspond le mieux vous aidera à choisir la bonne voie d'intégration.

Framework d'écosystème

• Votre profil : vous êtes responsable d'un framework Open Source (par exemple, LangChain, LlamaIndex, Spring AI) ou des clients spécifiques à un langage.
• Votre objectif : une compatibilité étendue. Vous souhaitez que votre bibliothèque fonctionne dans n'importe quel environnement choisi par votre utilisateur sans forcer les conflits.

Plate-forme d'exécution et de périphérie

• Vous êtes une plate-forme SaaS, une passerelle d'IA ou un fournisseur d'infrastructure cloud (par exemple, Vercel, Cloudflare, Zapier) où l'exécution du code a lieu dans des environnements restreints.
• Votre objectif : les performances. Vous avez besoin d'une faible latence, d'une taille de bundle minimale et de démarrages à froid rapides.

Agrégateur

• Qui êtes-vous ? Plates-formes, proxys ou "Model Gardens" internes qui normalisent l'accès à de nombreux fournisseurs de LLM différents (par exemple, OpenAI, Anthropic, Google) dans une seule interface.
• Votre objectif : portabilité et uniformité.

Passerelle Enterprise

• Votre profil : vous faites partie d'une équipe d'ingénierie des plates-formes internes dans une grande entreprise et vous créez des "voies optimales" pour des centaines de développeurs internes.
• Votre objectif : standardisation, gouvernance et authentification unifiée.

Comparaison en un coup d'œil

Bonne pratique à l'échelle mondiale : tous les partenaires doivent envoyer l'en-tête x-goog-api-client, quel que soit le chemin choisi.

Intégration du SDK Google GenAI

Pour les frameworks, l'implémentation du SDK Google GenAI est souvent la méthode la plus simple, car elle nécessite le moins de lignes de code dans les langages compatibles.

Pour les équipes de plate-forme internes, votre principal livrable est souvent un "chemin d'or" qui permet aux ingénieurs produit d'avancer rapidement tout en respectant les règles de sécurité.

Avantages :

• Interface unifiée pour la migration Vertex AI : les développeurs internes créent souvent des prototypes à l'aide de clés API (API Gemini) et les déploient sur Vertex AI (IAM) pour la conformité en production. Le SDK fait abstraction de ces différences d'authentification. De même, pour les frameworks, vous pouvez implémenter un chemin de code et prendre en charge deux ensembles d'utilisateurs.
• Assistance côté client : le SDK inclut des utilitaires idiomatiques qui réduisent le code passe-partout pour les tâches complexes.
  • Exemples : prise en charge des objets image PIL directement dans les requêtes, appel de fonction automatique et types complets.
• Accès aux fonctionnalités dès le premier jour : les nouvelles fonctionnalités de l'API sont disponibles au moment du lancement via les SDK.
• Prise en charge améliorée de la génération de code : l'installation locale du SDK expose les définitions de type et les docstrings aux assistants de codage (par exemple, Cursor ou Copilot, par exemple). Ce contexte améliore la précision de la génération de code par rapport à la génération de requêtes REST brutes.

Le compromis :

• Poids et complexité des dépendances : les SDK ont leurs propres dépendances, ce qui peut augmenter la taille du bundle et potentiellement le risque lié à la chaîne d'approvisionnement.
• Gestion des versions : les nouvelles fonctionnalités de l'API sont souvent associées à des versions minimales du SDK. Vous devrez peut-être envoyer des mises à jour aux utilisateurs pour qu'ils puissent accéder aux nouvelles fonctionnalités ou aux nouveaux modèles. Dans certains cas, cela peut nécessiter des modifications des dépendances transitives qui affectent vos utilisateurs.
• Limites de protocole : les SDK ne sont compatibles qu'avec HTTPS pour l'API principale et WebSockets (WSS) pour l'API Live. gRPC n'est pas compatible avec les clients SDK de haut niveau.
• Langues acceptées : les SDK sont compatibles avec les versions linguistiques actuelles. Si vous devez prendre en charge les versions en fin de vie (par exemple, Python 3.9), vous devrez gérer un fork.

Bonne pratique :

• Verrouillez les versions : épinglez la version du SDK dans vos images de base internes pour assurer la stabilité entre les équipes.

Intégration directe à l'aide de l'API

Si vous distribuez une bibliothèque à des milliers de développeurs, que vous l'exécutez dans un environnement contraint ou que vous créez un agrégateur qui nécessite les fonctionnalités de pointe de Gemini, vous devrez peut-être l'intégrer directement à l'API à l'aide de REST ou de gRPC.

Avantages :

• Accès complet aux fonctionnalités : contrairement à la couche de compatibilité OpenAI, l'utilisation directe de l'API permet d'accéder à des fonctionnalités spécifiques à Gemini, telles que l'importation dans l'API File, la création de mise en cache de contenu et l'utilisation de l'API Live bidirectionnelle.
• Dépendances minimales : dans un environnement où les dépendances sont sensibles en raison de leur taille ou des coûts d'audit. L'utilisation de l'API directement via une bibliothèque standard comme fetch ou via un wrapper comme httpx garantit que votre bibliothèque reste légère.
• Indépendant du langage : il s'agit de la seule option pour les langages non couverts par les SDK, tels que Rust, PHP et Ruby, car il n'y a aucune restriction de langage.
• Performances : l'API Direct n'a aucun coût d'initialisation, ce qui minimise les démarrages à froid dans les fonctions sans serveur.

Le compromis :

• Implémentation manuelle de Vertex AI : contrairement au SDK, l'utilisation directe de l'API ne gère pas automatiquement les différences d'authentification entre AI Studio (clé API) et Vertex AI (IAM). Vous devez implémenter des gestionnaires d'authentification distincts si vous souhaitez prendre en charge les deux environnements.
• Pas de types ni d'assistants natifs : vous n'obtenez pas de complétion de code ni de vérifications au moment de la compilation pour les objets de requête, sauf si vous les implémentez vous-même. Il n'existe pas d'assistants clients (par exemple, des convertisseurs de fonction en schéma). Vous devez donc écrire cette logique manuellement.

Bonne pratique

Nous exposons une spécification lisible par machine que vous pouvez utiliser pour générer des définitions de type pour votre bibliothèque, ce qui vous évite de les écrire à la main. Téléchargez la spécification lors du processus de compilation, générez les types et distribuez le code compilé.

• Point de terminaison : https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

Intégration du SDK OpenAI

Si vous êtes une plate-forme qui privilégie un schéma unifié (OpenAI Chat Completions) aux fonctionnalités spécifiques aux modèles, il s'agit de la méthode la plus rapide.

Avantages :

• Faible friction : vous pouvez souvent ajouter la prise en charge de Gemini en modifiant baseURL et apiKey. Il s'agit d'un moyen rapide d'intégrer les implémentations "Bring Your Own Key" (Apportez votre propre clé), en ajoutant la prise en charge de Gemini sans écrire de nouveau code.
• Contraintes : Ce chemin n'est recommandé que si vous êtes limité au SDK OpenAI et que vous n'avez pas besoin de fonctionnalités Gemini avancées comme l'API File, ou d'ajouter manuellement la prise en charge d'outils comme l'ancrage avec la recherche Google.

Le compromis :

• Limites des fonctionnalités : la couche de compatibilité impose des limites aux fonctionnalités Gemini de base. Les outils côté serveur disponibles diffèrent selon les plates-formes et peuvent nécessiter une gestion manuelle pour fonctionner avec les outils de l'API Gemini.
• Surcharge de traduction : comme le schéma OpenAI ne correspond pas exactement à l'architecture de Gemini, le recours à la couche de compatibilité introduit certaines complexités qui nécessitent un travail d'implémentation supplémentaire pour être résolues, comme le mappage d'un outil de "recherche" utilisateur à l'outil de plate-forme approprié. Si vous avez besoin d'un grand nombre de cas particuliers, il peut être plus intéressant d'utiliser un SDK ou une API dédiés pour chaque plate-forme.

Bonne pratique

Si possible, intégrez directement l'API Gemini. Toutefois, pour une compatibilité maximale, envisagez d'utiliser une bibliothèque qui connaît les différents fournisseurs et qui peut gérer le mappage des outils et des messages pour vous.

Bonne pratique pour tous les partenaires : identification des clients

Lorsque vous appelez l'API Gemini en tant que plate-forme ou bibliothèque, vous devez identifier votre client à l'aide de l'en-tête x-goog-api-client.

Cela permet à Google d'identifier vos segments de trafic spécifiques. Si votre bibliothèque produit un modèle d'erreur spécifique, nous pouvons vous contacter pour vous aider à le déboguer.

Utilisez le format company-product/version (par exemple, acme-framework/1.2.0).

Exemples d'intégration

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

Étapes suivantes

• Consultez la présentation de la bibliothèque pour en savoir plus sur les SDK GenAI.
• Parcourir la documentation de référence sur l'API
• Consultez le guide de compatibilité OpenAI.