Integraciones de socios y bibliotecas

En esta guía, se describen las estrategias de arquitectura para compilar bibliotecas, plataformas y puertas de enlace sobre la API de Gemini. Se detallan las compensaciones técnicas entre el uso de los SDKs de GenAI oficiales, la API directa (REST/gRPC) y la capa de compatibilidad de OpenAI.

Usa esta guía si compilas herramientas para otros desarrolladores, como frameworks de código abierto, puertas de enlace empresariales o agregadores de SaaS, y necesitas optimizar la higiene de dependencias, el tamaño del paquete o la paridad de funciones.

¿Qué es la integración de socios?

Un socio es cualquier persona que compile una integración entre la API de Gemini y los desarrolladores de usuarios finales. Categorizamos a los socios en cuatro arquetipos. Identificar con cuál te identificas más te ayudará a elegir la ruta de integración correcta.

Framework del ecosistema

• Quién eres: Mantenedor de un framework de código abierto (p.ej., LangChain, LlamaIndex, Spring AI) o clientes específicos del lenguaje.
• Tu objetivo: Amplia compatibilidad. Quieres que tu biblioteca funcione en cualquier entorno que elija el usuario sin forzar conflictos.

Plataforma de tiempo de ejecución y perimetral

• Quién eres: Plataformas de SaaS, puertas de enlace de IA o proveedores de infraestructura de la nube (p.ej., Vercel, Cloudflare, Zapier) en los que la ejecución de código se realiza en entornos restringidos.
• Tu objetivo: Rendimiento. Necesitas una latencia baja, un tamaño de paquete mínimo y arranques en frío rápidos.

Agregador

• Quién eres: Plataformas, proxies o "Model Gardens" internos que normalizan el acceso a muchos proveedores de LLM diferentes (p.ej., OpenAI, Anthropic, Google) en una sola interfaz.
• Tu objetivo: Portabilidad y uniformidad.

Puerta de enlace empresarial

• Quién eres: Equipos internos de ingeniería de plataformas en grandes empresas que compilan "rutas doradas" para cientos de desarrolladores internos.
• Tu objetivo: Estandarización, gobernanza y autenticación unificada.

Comparación rápida

Práctica recomendada global: Todos los socios deben enviar el x-goog-api-client encabezado, independientemente de la ruta elegida.

Integración del SDK de GenAI de Google

Para los frameworks, implementar el SDK de GenAI de Google suele ser la ruta más sencilla, ya que tiene la menor cantidad de líneas de código en los lenguajes compatibles.

Para los equipos internos de la plataforma, tu principal entregable suele ser una "ruta dorada" que permite a los ingenieros de productos avanzar rápido mientras cumplen con las políticas de seguridad.

Beneficios:

• Interfaz unificada para la migración de Gemini Enterprise Agent Platform: Los desarrolladores internos suelen crear prototipos con claves de API (API de Gemini) y realizar la implementación en Gemini Enterprise Agent Platform (IAM) para el cumplimiento de la producción. El SDK abstrae estas diferencias de autenticación. Del mismo modo, para los frameworks, puedes implementar una ruta de código y admitir dos conjuntos de usuarios.
• Auxiliares del cliente: El SDK incluye utilidades idiomáticas que reducen el código estándar para tareas complejas.
  • Ejemplos: Compatibilidad con objetos de imagen PIL directamente en instrucciones, llamadas automáticas a funciones y tipos integrales.
• Acceso a funciones desde el primer día: Las nuevas funciones de la API están disponibles en el momento del lanzamiento a través de los SDKs.
• Compatibilidad mejorada con la generación de código: La instalación local del SDK expone definiciones de tipos y cadenas de documentación a los asistentes de codificación (p.ej., Cursor, Copilot). Este contexto mejora la exactitud de la generación de código en comparación con la generación de solicitudes REST sin procesar.

La compensación:

• Peso y complejidad de la dependencia: Los SDKs tienen sus propias dependencias, lo que puede aumentar el tamaño del paquete y, potencialmente, el riesgo de la cadena de suministro.
• Control de versiones: Las nuevas funciones de la API suelen fijarse en las versiones mínimas del SDK. Es posible que debas enviar actualizaciones a los usuarios para acceder a funciones o modelos nuevos, lo que, en algunos casos, puede requerir cambios en las dependencias transitivas que afectan a tus usuarios.
• Límites de protocolo: Los SDKs solo admiten HTTPS para la API principal y WebSockets (WSS) para la API Live. gRPC no es compatible con los clientes de SDK de alto nivel.
• Compatibilidad con idiomas: Los SDKs admiten versiones de idiomas actuales. Si necesitas admitir versiones EOL (p.ej., Python 3.9), deberás mantener una bifurcación.

Práctica recomendada:

• Bloquea versiones: Fija la versión del SDK en tus imágenes base internas para garantizar la estabilidad en todos los equipos.

Integración directa con la API

Si distribuyes una biblioteca a miles de desarrolladores, ejecutas en un entorno restringido o compilas un agregador que requiere las funciones de vanguardia de Gemini, es posible que debas realizar la integración directamente con la API mediante REST o gRPC.

Beneficios:

• Acceso completo a las funciones: A diferencia de la capa de compatibilidad de OpenAI, el uso directo de la API habilita funciones específicas de Gemini, como la carga en la API de File, la creación de almacenamiento en caché de contenido y el uso de la API Live bidireccional.
• Dependencias mínimas: En un entorno en el que las dependencias son sensibles debido al tamaño o los costos de auditoría. El uso directo de la API a través de una biblioteca estándar como fetch o a través de un wrapper como httpx garantiza que tu biblioteca siga siendo liviana.
• Agnóstico del lenguaje: Esta es la única ruta para los lenguajes no cubiertos por los SDKs, como Rust, PHP y Ruby, ya que no hay restricciones de lenguaje.
• Rendimiento: La API directa no tiene sobrecarga de inicialización, lo que minimiza los inicios en frío en las funciones sin servidor.

La compensación:

• Implementación manual de Gemini Enterprise Agent Platform: A diferencia del SDK, el uso directo de la API no controla automáticamente las diferencias de autenticación entre AI Studio (clave de API) y Gemini Enterprise Agent Platform (IAM). Debes implementar controladores de autenticación separados si deseas admitir ambos entornos.
• Sin tipos ni auxiliares nativos: No obtienes finalizaciones de código ni verificaciones en tiempo de compilación para los objetos de solicitud, a menos que los implementes tú mismo. No hay "auxiliares" del cliente (p.ej., convertidores de función a esquema), por lo que debes escribir esta lógica de forma manual.

Práctica recomendada

Exponemos una especificación legible por máquina que puedes usar para generar definiciones de tipos para tu biblioteca, lo que te evita escribirlas a mano. Descarga la especificación durante el proceso de compilación, genera los tipos y envía el código compilado.

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

Integración del SDK de OpenAI

Si eres una plataforma que prioriza un esquema unificado (OpenAI Chat Completions) sobre las funciones específicas del modelo, esta es la ruta más rápida.

Beneficios:

• Baja fricción: A menudo, puedes agregar compatibilidad con Gemini cambiando baseURL y apiKey. Esta es una forma rápida de integrar implementaciones de "Trae tu propia clave", lo que agrega compatibilidad con Gemini sin escribir código nuevo.
• Restricciones: Esta ruta solo se recomienda si estás restringido al SDK de OpenAI y no necesitas funciones avanzadas de Gemini, como la API de File, o agregar manualmente compatibilidad con herramientas como Fundamentación con la Búsqueda de Google.

La compensación:

• Limitaciones de funciones: La capa de compatibilidad proporciona limitaciones a las capacidades principales de Gemini. Las herramientas disponibles del servidor difieren entre las plataformas y pueden requerir un manejo manual para trabajar con las herramientas de la API de Gemini.
• Sobrecarga de traducción: Debido a que el esquema de OpenAI no se asigna 1:1 a la arquitectura de Gemini, depender de la capa de compatibilidad introduce algunas complejidades que requieren trabajo de implementación adicional para resolver, como asignar una herramienta de "búsqueda" de usuario a la herramienta de plataforma correcta. Si necesitas una cantidad significativa de casos especiales, puede ser más valioso usar un SDK o una API dedicados para cada plataforma.

Práctica recomendada

Cuando sea posible, realiza la integración directamente con la API de Gemini. Sin embargo, para obtener la máxima compatibilidad, considera usar una biblioteca que conozca diferentes proveedores y pueda controlar la asignación de herramientas y mensajes por ti.

Práctica recomendada para todos los socios: identificación del cliente

Cuando realices llamadas a la API de Gemini como plataforma o biblioteca, debes identificar a tu cliente con el encabezado x-goog-api-client.

Esto le permite a Google identificar tus segmentos de tráfico específicos y, si tu biblioteca produce un patrón de error específico, podemos comunicarnos para ayudarte a depurar.

Usa el formato company-product/version (p.ej., acme-framework/1.2.0).

Ejemplos de implementación

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

Próximos pasos

• Visita la descripción general de la biblioteca para obtener información sobre los SDKs de GenAI.
• Consulta la referencia de la API.
• Lee la guía de compatibilidad con OpenAI.