API de EmbeddingGemma 2: despliegue local y casos de uso multimodales

Buscar una API de EmbeddingGemma 2 obliga a hacer una distinción importante: la API de embeddings alojada de Google es Gemini Embedding 2, mientras que EmbeddingGemma 2 es un modelo abierto pensado principalmente para inferencia local y en dispositivos edge. Esto lo convierte en una opción interesante para búsquedas multimodales privadas, aunque tendrás que elegir y gestionar por tu cuenta la capa que lo sirve.

¿Está disponible EmbeddingGemma 2 como API de Google?

EmbeddingGemma 2 ya se ha publicado oficialmente, pero la documentación actual de la API Gemini gestionada por Google menciona gemini-embedding-2, no embeddinggemma-2. La ficha del modelo EmbeddingGemma 2 y la guía para desarrolladores de Google describen un modelo descargable que se utiliza con bibliotecas locales como Sentence Transformers.

El endpoint local /v1/embeddings lo expone el runtime que despliegues, no Google Cloud. Si te referías al servicio gestionado, la documentación de Gemini Embedding 2 muestra el SDK en la nube y los formatos de las peticiones; utiliza gemini-embedding-2, no embeddinggemma-2.

from google import genai

client = genai.Client()
result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="A private semantic search service",
)
print(result.embeddings)

La llamada gestionada utiliza la API alojada de Google, mientras que el modelo local queda sujeto a las credenciales y los límites del runtime que despliegues.

Qué incluye realmente el modelo local

EmbeddingGemma 2 es un modelo multimodal de embeddings con 740 millones de parámetros. Su diseño separa un núcleo de texto de 270M de los codificadores opcionales de visión y audio, de modo que cada despliegue puede cargar únicamente las modalidades que necesita. Google y DeepMind lo orientan a la recuperación de texto, código, imágenes, vídeo y audio, no a la generación de texto.

La ficha del modelo describe un espacio vectorial compartido para comparar distintos tipos de contenido. La cifra de 740M corresponde al modelo completo; la guía para desarrolladores de Google muestra que los codificadores pueden utilizarse de forma selectiva, por lo que la memoria ocupada y el cómputo activo pueden ser menores en rutas que solo procesen texto y omitan visión y audio.

Elige la forma de servirlo según el destino del despliegue

Sentence Transformers para una aplicación Python

En un servicio Python, la vía documentada oficialmente consiste en utilizar el checkpoint google/embeddinggemma-2 mediante Sentence Transformers. Esta opción ofrece control directo sobre el procesamiento por lotes, la ubicación del dispositivo, los prompts, la normalización y el truncado de los vectores.

En un flujo de recuperación conviene utilizar instrucciones independientes para las consultas y los documentos. Los ejemplos de Google emplean un prefijo de búsqueda para la consulta y un formato de documento como title: none | text: .... La opción más segura es llamar a model.encode con el nombre del prompt correspondiente, en lugar de generar ambos embeddings mediante una llamada genérica.

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("google/embeddinggemma-2")

query_vector = model.encode(
    "How do I rotate an API key?",
    prompt_name="query",
    normalize_embeddings=True,
)
document_vectors = model.encode(
    [
        "title: API keys | text: Rotate keys from the security settings page.",
        "title: Billing | text: Download invoices from the billing page.",
    ],
    prompt_name="document",
    normalize_embeddings=True,
)

Elige esta vía si necesitas control desde Python; si varios servicios requieren un contrato HTTP estable, utiliza un runtime que exponga el modelo mediante HTTP.

Ollama para disponer rápidamente de un endpoint REST local

La página de EmbeddingGemma 2 en Ollama ofrece una API local sencilla en http://localhost:11434/api/embed:

ollama pull embeddinggemma-2

curl http://localhost:11434/api/embed \\
  -d '{
    "model": "embeddinggemma-2",
    "input": "A private semantic search service"
  }'

Ollama muestra etiquetas de modelo como 270m, 440m, 570m y 740m; los tamaños visibles de los paquetes van aproximadamente de 378 MB a 1,3 GB. Trátalas como variantes del modelo empaquetadas por separado, no como etiquetas intercambiables del checkpoint completo de 740M. Antes de diseñar un contrato de producción, comprueba la etiqueta instalada y las modalidades de entrada compatibles: la descripción de la familia es multimodal, pero las variantes visibles no documentan todas las modalidades con el mismo nivel de detalle.

Aun así, necesitarás mantener coherentes los prefijos de tarea, el modelo y las dimensiones, además de reconstruir el índice si cambias de modelo.

Runtimes edge para desplegarlo en dispositivos

Google AI Edge documenta EmbeddingGemma V2 en su guía de Universal Embedder, mientras que la documentación de modelos de embeddings de LiteRT-LM describe un patrón de servicio local compatible con OpenAI que utiliza /v1/embeddings. Esta vía tiene sentido cuando el funcionamiento sin conexión y la privacidad en el dispositivo pesan más que la comodidad de un despliegue cloud convencional.

Para un servidor con hardware convencional, empieza con Sentence Transformers u Ollama. Pásate a un runtime específico para edge cuando el funcionamiento offline, la privacidad, el tamaño de arranque o la integración con el dispositivo sean requisitos fundamentales.

Casos de uso multimodales que justifican un modelo más grande

EmbeddingGemma 2 resulta especialmente interesante cuando un proyecto necesita un único espacio de recuperación para varios tipos de contenido.

Búsqueda de código y recuperación para desarrolladores

La tabla de evaluación publicada registra una puntuación MTEB Code de 78.68 para EmbeddingGemma 2, frente a 68.76 para EmbeddingGemma 1 en el benchmark de código citado. Es un motivo razonable para probarlo en búsquedas dentro de repositorios, recuperación de documentación de API y sistemas RAG centrados en código, pero no garantiza los mismos resultados con tu combinación de idiomas o tu base de código.

Cuándo no compensa migrar al modelo más grande

En un pipeline que solo recibe texto OCR convencional, la compatibilidad multimodal puede añadir complejidad sin mejorar la calidad de recuperación. Un usuario de Paperless-ngx resumió así el dilema:

“I'm not sure embeddinggemma-2 is any better than regular embeddinggemma for the plain OCR that paperless-ngx sends to the model. seems like a lot more work for the same results.” — u/Great-Cow7256, Reddit

No es un resultado de benchmark, pero refleja bien la prueba que debe guiar la migración: compara la calidad de recuperación sobre tu corpus real antes de reconstruir un índice de texto que ya funciona.

Qué dimensión elegir: 768d, 512d, 256d o 128d

La documentación de embeddings de Google explica el truncado al estilo Matryoshka para EmbeddingGemma 2, por lo que puedes elegir una representación más pequeña después de generar los embeddings. Los vectores pequeños reducen el almacenamiento del índice y el tamaño de las transferencias, aunque la calidad cae con la configuración más agresiva.

Estas cifras proceden de la tabla de evaluación publicada en la página del modelo en Ollama. Empieza con 768d para un índice multimodal nuevo; elige 512d o 256d si el almacenamiento es una prioridad, y utiliza 128d solo después de probarlo con una carga de trabajo centrada en texto.

No mezcles dimensiones dentro de un mismo índice vectorial. Si una base de datos existente almacena vectores de 768 dimensiones, cambiar a 256d exige volver a generar los embeddings de los documentos indexados y reconstruir el índice. Los vectores de consulta deben utilizar el mismo modelo, prompts, normalización y dimensión que los vectores de los documentos.

Toma la decisión según el flujo de trabajo, no el tamaño del modelo

Usa Gemini Embedding 2 si necesitas un endpoint de Google gestionado. Elige Sentence Transformers para controlar el proceso desde Python, Ollama para disponer rápidamente de un servicio HTTP local y AI Edge/LiteRT-LM cuando el despliegue offline en dispositivos sea importante.

Mantén un modelo de texto más pequeño si el corpus está compuesto por OCR sencillo y el índice actual ya alcanza el nivel de relevancia que necesitas. EmbeddingGemma 2 puede simplificar una arquitectura multimodal, pero no mejora automáticamente una arquitectura que solo trabaja con texto.

Preguntas frecuentes sobre la API de EmbeddingGemma 2

¿Se puede utilizar EmbeddingGemma 2 a través de la API Gemini?

La documentación de la API Gemini gestionada por Google identifica actualmente gemini-embedding-2. EmbeddingGemma 2 se documenta principalmente como un modelo abierto para inferencia local, aunque algunos runtimes locales pueden exponer endpoints compatibles con API.

¿Puede EmbeddingGemma 2 funcionar en una CPU?

La inferencia en CPU se puede utilizar con runtimes locales que ofrezcan explícitamente un backend para CPU; la referencia relevante es la documentación de embeddings de AI Edge de Google. El rendimiento seguirá dependiendo del hardware, la cuantización, el tamaño del lote y la modalidad.

¿Es necesario reconstruir los vectores existentes?

Por lo general, sí, si cambias el modelo de embeddings, el formato de las tareas, la política de normalización o la dimensión de los vectores. Guarda junto al índice el identificador del modelo, la dimensión y los metadatos de preprocesamiento para poder reproducir la migración.