Integrazioni con partner e biblioteche

Questa guida illustra le strategie architetturali per la creazione di librerie, piattaforme e gateway basati sull'API Gemini. Descrive in dettaglio i compromessi tecnici tra l'utilizzo degli SDK GenAI ufficiali, dell'API Direct (REST/gRPC) e del livello di compatibilità OpenAI.

Utilizza questa guida se stai creando strumenti per altri sviluppatori, come framework open source, gateway aziendali o aggregatori SaaS, e devi ottimizzare l'igiene delle dipendenze, le dimensioni dei bundle o la parità delle funzionalità.

Che cos'è l'integrazione dei partner?

Un partner è chiunque crei un'integrazione tra l'API Gemini e gli sviluppatori utenti finali. Classifichiamo i partner in quattro archetipi. Identificare a quale corrispondi più da vicino ti aiuterà a scegliere il percorso di integrazione giusto.

Framework dell'ecosistema

• Chi sei: manutentore di un framework open source (ad es. LangChain, LlamaIndex, Spring AI) o client specifici per la lingua.
• Il tuo obiettivo: ampia compatibilità. Vuoi che la tua libreria funzioni in qualsiasi ambiente scelto dall'utente senza forzare conflitti.

Runtime e piattaforma edge

• Chi sei: piattaforme SaaS, gateway AI o fornitori di infrastrutture cloud (ad es. Vercel, Cloudflare, Zapier) in cui l'esecuzione del codice avviene in ambienti con limitazioni.
• Il tuo obiettivo: rendimento. Hai bisogno di bassa latenza, dimensioni minime del bundle e avvii a freddo rapidi.

Aggregatore

• Chi sei: piattaforme, proxy o "Model Gardens" interni che normalizzano l'accesso a molti fornitori di LLM diversi (ad es. OpenAI, Anthropic, Google) in un'unica interfaccia.
• Il tuo obiettivo: portabilità e uniformità.

Gateway aziendale

• Chi sei:team di ingegneria delle piattaforme interne di grandi aziende che creano "percorsi aurei" per centinaia di sviluppatori interni.
• Il tuo obiettivo: standardizzazione, governance e autenticazione unificata.

Confronto riepilogativo

Best practice globale: tutti i partner devono inviare l'x-goog-api-client intestazione indipendentemente dal percorso scelto.

Integrazione dell'SDK Google GenAI

Per i framework, l'implementazione dell'SDK Google GenAI è spesso il percorso più semplice, dato il minor numero di righe di codice nei linguaggi supportati.

Per i team della piattaforma interni, il risultato principale è spesso un "percorso ottimale" che consente agli ingegneri di prodotto di muoversi rapidamente rispettando le norme di sicurezza.

Vantaggi:

• Interfaccia unificata per la migrazione di Vertex AI: gli sviluppatori interni spesso creano prototipi utilizzando le chiavi API (API Gemini) ed eseguono il deployment su Vertex AI (IAM) per la conformità alla produzione. L'SDK astrae queste differenze di autenticazione. Allo stesso modo, per i framework puoi implementare un percorso del codice e supportare due set di utenti.
• Helper lato client: l'SDK include utilità idiomatiche che riducono il boilerplate per attività complesse.
  • Esempi: supporto degli oggetti immagine PIL direttamente nei prompt, chiamata automatica delle funzioni e tipi completi.
• Accesso alle funzionalità il giorno del lancio:le nuove funzionalità dell'API sono disponibili al momento del lancio tramite gli SDK.
• Supporto migliorato per la generazione di codice:l'installazione dell'SDK locale espone le definizioni dei tipi e le docstring agli assistenti alla programmazione (ad es. Cursor, Copilot). Questo contesto migliora l'accuratezza della generazione di codice rispetto alla generazione di richieste REST non elaborate.

Il compromesso:

• Peso e complessità delle dipendenze: gli SDK hanno le proprie dipendenze, che possono aumentare le dimensioni del bundle e potenzialmente il rischio della supply chain.
• Controllo delle versioni:le nuove funzionalità dell'API sono spesso associate a versioni minime dell'SDK. Potresti dover inviare aggiornamenti agli utenti per accedere a nuove funzionalità o modelli, che in alcuni casi potrebbero richiedere modifiche alle dipendenze transitive che interessano i tuoi utenti.
• Limiti del protocollo:gli SDK supportano solo HTTPS per l'API principale e WebSocket (WSS) per l'API Live. gRPC non è supportato utilizzando i client SDK di alto livello.
• Supporto delle lingue:gli SDK supportano le versioni delle lingue attuali. Se devi supportare versioni EOL (ad es. Python 3.9), dovresti mantenere un fork.

Best practice:

• Blocca versioni:blocca la versione dell'SDK nelle tue immagini di base interne per garantire la stabilità tra i team.

Integrazione API diretta

Se distribuisci una libreria a migliaia di sviluppatori, la esegui in un ambiente vincolato o crei un aggregatore che richiede le funzionalità all'avanguardia di Gemini, potresti dover eseguire l'integrazione con l'API direttamente utilizzando REST o gRPC.

Vantaggi:

• Accesso completo alle funzionalità:a differenza del livello di compatibilità OpenAI, l'utilizzo diretto dell'API consente di utilizzare funzionalità specifiche di Gemini, come il caricamento nell'API File, la creazione della memorizzazione nella cache dei contenuti e l'utilizzo dell'API Live bidirezionale.
• Dipendenze minime: in un ambiente in cui le dipendenze sono sensibili a causa delle dimensioni o dei costi di controllo. L'utilizzo dell'API direttamente tramite una libreria standard come fetch o tramite un wrapper come httpx garantisce che la libreria rimanga leggera.
• Indipendente dalla lingua:questo è l'unico percorso per le lingue non coperte dagli SDK, come Rust, PHP e Ruby, in quanto non esistono restrizioni linguistiche.
• Prestazioni: l'API Direct non ha sovraccarico di inizializzazione, riducendo al minimo gli avvii a freddo nelle funzioni serverless.

Il compromesso:

• Implementazione manuale di Vertex AI: a differenza dell'SDK, l'utilizzo diretto dell'API non gestisce automaticamente le differenze di autenticazione tra AI Studio (chiave API) e Vertex AI (IAM). Devi implementare gestori di autenticazione separati se vuoi supportare entrambi gli ambienti.
• Nessun tipo o helper nativo:non ricevi completamenti del codice o controlli in fase di compilazione per gli oggetti richiesta, a meno che non li implementi tu stesso. Non sono presenti "helper" client (ad es. convertitori da funzione a schema), quindi devi scrivere manualmente questa logica.

Best practice

Esporremo una specifica leggibile dalla macchina che potrai utilizzare per generare definizioni di tipo per la tua libreria, evitando di scriverle a mano. Scarica la specifica durante la procedura di compilazione, genera i tipi e invia il codice compilato.

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

Integrazione dell'SDK OpenAI

Se sei una piattaforma che dà la priorità a uno schema unificato (OpenAI Chat Completions) rispetto alle funzionalità specifiche del modello, questo è il percorso più veloce.

Vantaggi:

• Basso attrito:spesso puoi aggiungere il supporto di Gemini modificando baseURL e apiKey. Questo è un modo rapido per integrare le implementazioni "Bring Your Own Key", aggiungendo il supporto di Gemini senza scrivere nuovo codice.
• Vincoli: questo percorso è consigliato solo se sei limitato all'SDK OpenAI e non hai bisogno di funzionalità avanzate di Gemini come l'API File o l'aggiunta manuale del supporto per strumenti come Grounding con la Ricerca Google.

Il compromesso:

• Limitazioni delle funzionalità:il livello di compatibilità fornisce limitazioni alle funzionalità principali di Gemini. Gli strumenti lato server disponibili variano a seconda delle piattaforme e potrebbero richiedere la gestione manuale per funzionare con gli strumenti dell'API Gemini.
• Overhead di traduzione:poiché lo schema OpenAI non corrisponde 1:1 all'architettura di Gemini, l'utilizzo del livello di compatibilità introduce alcune complessità che richiedono un lavoro di implementazione aggiuntivo per risolvere il problema, ad esempio la mappatura di uno strumento di "ricerca" dell'utente allo strumento della piattaforma giusto. Se hai bisogno di una quantità significativa di gestione di casi speciali, potrebbe essere più utile utilizzare un SDK o un'API dedicati per ogni piattaforma.

Best practice

Se possibile, esegui l'integrazione direttamente con l'API Gemini. Tuttavia, per la massima compatibilità, ti consigliamo di utilizzare una libreria che riconosca i diversi provider e possa gestire la mappatura di strumenti e messaggi.

Best practice per tutti i partner: identificazione del cliente

Quando effettui chiamate all'API Gemini come piattaforma o libreria, devi identificare il tuo client utilizzando l'intestazione x-goog-api-client.

Ciò consente a Google di identificare i tuoi segmenti di traffico specifici e, se la tua libreria produce un pattern di errore specifico, possiamo contattarti per aiutarti a eseguire il debug.

Utilizza il formato company-product/version (ad es. acme-framework/1.2.0).

Esempi di implementazione

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

Passaggi successivi

• Visita la panoramica della libreria per scoprire di più sugli SDK GenAI
• Sfoglia il riferimento API
• Leggi la guida alla compatibilità di OpenAI