Despliegue local de EmbeddingGemma 2: guía para evaluar el riesgo de migración

Desplegar EmbeddingGemma 2 en local no significa que puedas sustituir sin más tu servicio de embeddings actual. Cambiar el runtime suele requerir pocos ajustes en la aplicación, pero modificar la representación normalmente obliga a regenerar los vectores. La estrategia más segura consiste en separar tres decisiones: cómo ejecutar el modelo, si los vectores existentes siguen siendo compatibles y si la recuperación multimodal ofrece resultados suficientemente buenos para tu corpus.

La decisión de migración, resumida

Conviene usar EmbeddingGemma 2 cuando necesitas embeddings locales de texto, código, imágenes, vídeo o audio dentro de una misma familia de modelos y puedes asumir una regeneración controlada. No cambies primero el encoder de consultas en producción para “ponerte al día” después con los documentos: el modelo de embeddings forma parte del esquema del índice, aunque la dimensión del vector parezca la misma.

La ficha del modelo de Google registra 61.36 en MTEB multilingual v2, 78.68 en MTEB code v1, 67.84 NDCG@5 en recuperación de documentos visuales, 50.67 Hit@1 en recuperación de vídeo y 69.54 MRR@10 en recuperación de audio, todo ello con 768 dimensiones. Son referencias útiles, pero no sustituyen las pruebas con tus propias consultas.

Qué cambia —y qué no— al pasar a EmbeddingGemma 2

EmbeddingGemma 2 proyecta texto, código, imágenes, vídeo y audio en un espacio compartido de 768 dimensiones. El checkpoint es modular: la guía oficial para desarrolladores describe una configuración de 270M solo para texto, otra de 440M para texto y visión, una de 570M para texto y audio, y una configuración completa de 740M. Desactivar un encoder reduce los pesos cargados y la memoria máxima, pero no crea por sí solo un espacio semántico nuevo.

Esta diferencia es clave durante la migración. Una consulta de texto generada con la configuración de 270M puede compararse con un embedding de documento de EmbeddingGemma 2 generado con la configuración completa, porque Google documenta que todas comparten un espacio vectorial compatible. Eso no significa que puedas consultar sin riesgo un vector antiguo de EmbeddingGemma 1, Qwen, Nomic o de un proveedor de APIs con EmbeddingGemma 2 solo porque también tenga 768 coordenadas.

El formato de las tareas también forma parte del contrato. Para recuperación asimétrica, EmbeddingGemma 2 espera una instrucción de consulta como task: search result | query: ... y un formato para documentos como title: ... | text: .... La recuperación de código tiene su propia instrucción. Si tu pipeline anterior usaba otros prefijos, una segmentación distinta, otra normalización o campos embebidos diferentes, registra esos cambios como una nueva versión de representación y valídalos como parte de la migración.

Compatibilidad de runtimes: elige la ruta local más sencilla

Empieza con Sentence Transformers para asegurar la corrección

La ficha oficial del modelo documenta google/embeddinggemma-2 con Sentence Transformers y Transformers. Instala los extras multimodales si necesitas trabajar con contenido multimedia:

pip install -U "sentence-transformers[image,audio,video]" transformers

Es la mejor ruta de referencia para una migración porque los nombres de los prompts, el truncado, la normalización y el tratamiento de entradas multimodales siguen los ejemplos oficiales. No tiene por qué ser la opción con menor latencia, pero ofrece una línea base fiable antes de empezar a optimizar.

Una prueba mínima para texto sería esta:

from sentence_transformers import SentenceTransformer

model = SentenceTransformer(
    "google/embeddinggemma-2",
    config_kwargs={"vision_config": None, "audio_config": None},
)
query = model.encode(
    "embedding model migration",
    prompt_name="SearchQuery",
    truncate_dim=256,
    normalize_embeddings=True,
)
document = model.encode(
    "Rebuild vectors when the embedding representation changes.",
    prompt_name="Document",
    truncate_dim=256,
    normalize_embeddings=True,
)
print(model.similarity(query, document).item())

Ejecuta esta prueba antes de introducir un servidor, cuantización o una base de datos vectorial. Así comprobarás que el checkpoint, los prompts de tarea, la dimensión y la normalización funcionan de forma coherente.

Usa otros runtimes solo después de comprobar la paridad de funciones

La guía de desarrollo de Google incluye vLLM, Hugging Face Transformers, Sentence Transformers, SGLang, MLX, Ollama, LM Studio y LiteRT entre las herramientas compatibles para desarrollo o despliegue. Toma esa lista como una señal de disponibilidad, no como una garantía de que todos los runtimes ofrecen la misma combinación de texto, imagen, vídeo, audio, entradas intercaladas, prefijos de tarea, truncado y batching.

Para cada runtime candidato, verifica con una petición real cinco aspectos: la revisión exacta del checkpoint, las modalidades de entrada que utilizas, las dimensiones de salida, la normalización posterior al truncado y el comportamiento de los prefijos de consulta y documento. Un runtime que sirva texto rápidamente, pero ignore tu flujo de documentos visuales, no equivale al modelo completo.

Un servidor nativo compacto es una optimización, no el plan de migración

El repositorio público embeddinggemma.c ofrece un servidor especializado de estilo C11/Metal para EmbeddingGemma 300M, con variantes para CPU, Metal, CUDA, ROCm e Intel XPU. Su README documenta un endpoint compatible con OpenAI, /v1/embeddings, dimensiones de 768/512/256/128 y una descarga del modelo Q4_0 de 278 MB. El proyecto informa de una comparación controlada en un Apple M5 Max frente a la compilación b8981 de llama.cpp, con una ventaja de media geométrica de 1.25×; son resultados de rendimiento específicos del proyecto, no una comparación de calidad ni una prueba de paridad multimodal con el checkpoint de 740M.

Lo más útil para una migración es la forma de su API. Si tu aplicación ya utiliza embeddings con formato OpenAI, un servidor local compatible con ese endpoint puede reducir el trabajo de adaptación. Aun así, conserva el resultado de Sentence Transformers como referencia de corrección hasta que el comportamiento de modalidades y prefijos del servidor coincida con el de tu pipeline de producción.

Riesgo de reconstrucción del índice: la dimensión es solo una parte del problema

Regenera los embeddings cuando cambie la función de origen a vector

Da por necesaria una reconstrucción completa si cambias la familia del modelo, la versión, el prefijo de tarea, la normalización, la segmentación, la política de truncado, los campos incluidos o la semántica de similitud. La guía de migración de Qdrant y el análisis de migración de modelos de Nalar insisten en el mismo punto operativo: los vectores de documentos y consultas deben pertenecer a la misma versión de representación. Que tengan la misma dimensión no demuestra compatibilidad semántica.

No cortes un vector antiguo de 768 dimensiones y lo conviertas en un vector de 256 dimensiones de EmbeddingGemma 2. Las salidas Matryoshka de EmbeddingGemma 2 se entrenan para tamaños de truncado compatibles y deben volver a normalizarse después del truncado. La ficha del modelo publica las siguientes puntuaciones de referencia oficiales:

La ficha oficial también registra 67.84 NDCG@5 en recuperación de documentos visuales y 50.67 Hit@1 en recuperación de vídeo con 768 dimensiones; úsalos como líneas base completas, sin inventar valores para dimensiones reducidas. La conclusión fiable es direccional: 256d queda mucho más cerca de la calidad completa que 128d, y las puntuaciones multimodales caen con mayor intensidad en 128d. Regenera todos los vectores con el checkpoint oficial y la dimensión elegida; no recortes vectores procedentes de otro modelo.

El espacio compartido de EmbeddingGemma 2 puede evitar trabajo innecesario

Hay una excepción importante. Si tu corpus ya estaba embebido con EmbeddingGemma 2 y solo vas a cargar un subconjunto distinto de sus encoders, la guía de desarrollo de Google indica que las configuraciones comparten un mismo espacio vectorial. Una consulta de texto puede compararse con el vector de un documento generado por el modelo completo. En ese caso, no necesitas regenerar los vectores de texto existentes únicamente porque el proceso de servicio vaya a cargar también soporte para visión o audio.

Aun así, necesitarás nuevos vectores para los registros que incorporen contenido multimedia. Un índice solo de texto no puede recuperar una imagen, un vídeo o un elemento de audio que nunca se haya embebido. Por tanto, añadir recuperación multimodal implica una migración incremental del corpus aunque el checkpoint del modelo no cambie.

Haz el cambio con un patrón blue-green o con vectores con nombre

En un sistema activo, el patrón de migración de Qdrant ofrece una plantilla clara: crea una colección nueva, escribe los registros nuevos en ambas versiones, regenera los vectores a partir de los datos fuente autorizados, compara Recall@10/MRR/nDCG@10, cambia un alias y conserva la colección antigua para poder volver atrás. La guía de Qdrant utiliza la versión 1.19.0, un ejemplo de 512 dimensiones y lotes de 100 puntos; son valores ilustrativos, no requisitos de EmbeddingGemma 2.

Un diseño con vectores con nombre puede mantener las representaciones antigua y nueva en una misma colección, siempre que tu base de datos vectorial lo permita y el flujo de actualización escriba ambas de forma coherente. La guía de migración de vectorizadores de Weaviate recomienda utilizar aliases de colección en producción, ya que la colección antigua puede conservarse para una reversión inmediata y eliminarse después de validar el cambio. Su alternativa —añadir un vector a la colección existente— puede incrementar el almacenamiento de forma permanente y resulta más adecuada para comparar que para mantener un estado final limpio.

Calidad multimodal: valida justo las partes que cambian

El espacio compartido de EmbeddingGemma 2 solo aporta valor si el comportamiento de recuperación encaja con tus datos. Un benchmark basado únicamente en texto puede confirmar que la migración no ha roto la búsqueda textual y, al mismo tiempo, pasar por alto fallos en páginas de PDF, gráficos, pies de imagen, fotogramas de vídeo, clips de audio o registros intercalados.

Empieza con conjuntos etiquetados y separados:

1. Consulta de texto → fragmento de texto.
2. Consulta de código → fragmento de código.
3. Consulta de texto → imagen o documento visual.
4. Consulta de texto → fotograma de vídeo o segmento de audio.
5. Consulta mixta de texto y contenido multimedia → documento mixto.
6. Consulta multilingüe → documento en los idiomas que atiendes.

Usa 768d o 512d como primera línea base multimodal. La ficha oficial del modelo asigna 280 tokens por imagen, 140 por fotograma de vídeo y 25 por segundo de audio dentro de un contexto compartido de 8,192 tokens. Las entradas mixtas consumen el mismo presupuesto, así que un registro con texto, imágenes y vídeo deja menos espacio para cada componente que una entrada de una sola modalidad.

La ficha del modelo también indica que 128d provoca una caída de calidad mayor en las tareas multimodales que en las tareas exclusivamente textuales. Por eso, 128d puede ser un candidato inicial razonable para un índice de texto grande, pero no debería ser la opción predeterminada para un archivo multimedia mixto. Compara 256d con tus consultas reales de documentos visuales y de recuperación entre modalidades antes de aceptar el ahorro de almacenamiento.

Compara un pipeline unificado con EmbeddingGemma 2 y tu pipeline actual separado para texto e imágenes usando las mismas consultas; no deduzcas la calidad multimodal únicamente de la arquitectura de espacio compartido del modelo.

Plan de despliegue gradual para un sistema RAG existente

1. Documenta el contrato actual. Registra el ID del modelo, la revisión del checkpoint, los prefijos, la segmentación, las dimensiones, la métrica, la normalización, los campos de origen y todas las modalidades indexadas.
2. Prepara un conjunto de evaluación representativo. Incluye objetivos de Recall@k, MRR o nDCG, además de conjuntos separados para texto, código, documentos visuales, audio, vídeo, idiomas y consultas largas.
3. Establece la línea base local. Procesa primero el mismo corpus con Sentence Transformers. Registra la latencia de generación de embeddings, la latencia de búsqueda, la memoria, el tamaño del índice, los errores y la distribución de puntuaciones.
4. Crea un índice candidato versionado. Mantén IDs de documento estables y conserva el texto o los contenidos multimedia fuente fuera del almacén vectorial para que la regeneración sea reproducible.
5. Coordina las escrituras durante la regeneración. Usa una instantánea de la fuente más la reproducción de cambios, o escribe los registros nuevos y actualizados en ambas versiones de representación.
6. Replica en segundo plano las consultas de producción. Compara los resultados ordenados, la tasa de respuestas vacías, la latencia y la relevancia etiquetada sin modificar las respuestas visibles para los usuarios.
7. Haz el cambio de forma atómica. Vincula el encoder de consultas de EmbeddingGemma 2 y su índice correspondiente bajo una misma versión o alias. No despliegues nunca el nuevo encoder de consultas contra el índice antiguo como estado intermedio.
8. Conserva la posibilidad de volver atrás. Mantén el índice y el flujo de consultas antiguos hasta que el tráfico representativo supere los umbrales de aceptación; después detén las escrituras dobles y recupera el almacenamiento.

Preguntas frecuentes

¿Puede EmbeddingGemma 2 funcionar solo con CPU?

Sí, siempre que utilices un runtime compatible con CPU. La ficha del modelo recomienda float32 cuando bfloat16 no está disponible, y la configuración solo para texto tiene 270M parámetros. El rendimiento en CPU depende del runtime, la precisión, el batching y el hardware, así que debes medirlo con tu propio corpus en lugar de reutilizar cifras obtenidas en GPU.

Elegir runtime implica equilibrar la corrección de la implementación de referencia, la paridad de funciones, la eficiencia del servicio y el coste de validar una nueva versión del sistema de recuperación.