Cómo Usar la API Gemini Embedding 2

La API Gemini Embedding 2 de Google te permite generar embeddings para texto, imágenes, video, audio y PDF. Esta guía te muestra cómo usarla, con ejemplos de código reales que puedes ejecutar hoy mismo.

Nota: Esta guía cubre la versión preliminar pública (gemini-embedding-2-preview). La API puede cambiar antes de su disponibilidad general.

¿Quieres entender primero qué es Gemini Embedding 2? Lee nuestro resumen: ¿Qué es Gemini Embedding 2?

Requisitos Previos

Necesitas:

Una clave de API de Google AI
Python 3.7 o superior
El SDK de Google Generative AI

Instalación

Instala el SDK:

pip install google-generativeai

Configuración Básica

Configura tu clave de API:

import google.generativeai as genai

# Configura tu clave de API
genai.configure(api_key='YOUR_API_KEY')

Para producción, usa variables de entorno:

import os
import google.generativeai as genai

api_key = os.getenv('GEMINI_API_KEY')
genai.configure(api_key=api_key)

Probando con Apidog

Antes de sumergirte en el código, puedes probar la API de Gemini Embedding directamente en Apidog:

Crea una nueva solicitud en Apidog
Establece el método en POST
URL: https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent
Añade encabezado: x-goog-api-key: YOUR_API_KEY
Cuerpo (JSON):

{
  "content": {
    "parts": [{
      "text": "¿Qué es la prueba de API?"
    }]
  }
}

Esto te permite verificar que tu clave de API funciona y ver la estructura de la respuesta antes de escribir código. Puedes guardar esto como un caso de prueba y validar las respuestas de embedding en tu pipeline de CI/CD.

Generando Embeddings de Texto

El caso de uso más simple - incrustar texto:

import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# Generar embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='¿Cuál es el sentido de la vida?'
)

# Obtener el vector de embedding
embedding = result['embedding']
print(f"Dimensiones del embedding: {len(embedding)}")
print(f"Primeros 5 valores: {embedding[:5]}")

Salida:

Embedding dimensions: 3072
First 5 values: [0.0234, -0.0156, 0.0891, -0.0423, 0.0567]

Nota: La estructura de la respuesta es result['embedding'], que devuelve una lista de flotantes. Cada flotante representa una dimensión del vector de embedding.

Usando Instrucciones de Tarea

Las instrucciones de tarea optimizan los embeddings para casos de uso específicos:

# Para consultas de búsqueda
query_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='mejores herramientas de prueba de API',
    task_type='RETRIEVAL_QUERY'
)

# Para documentos que estás indexando
doc_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Apidog es una plataforma de prueba de API...',
    task_type='RETRIEVAL_DOCUMENT'
)

Tipos de tarea disponibles:

RETRIEVAL_QUERY - Usar para consultas de búsqueda
RETRIEVAL_DOCUMENT - Usar para documentos que estás indexando
SEMANTIC_SIMILARITY - Usar para comparar la similitud de contenido
CLASSIFICATION - Usar para tareas de categorización
CLUSTERING - Usar para agrupar contenido similar

Controlando las Dimensiones de Salida

Reduce los costos de almacenamiento usando dimensiones más pequeñas:

# Optimizado para producción: 768 dimensiones
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Tu texto aquí',
    output_dimensionality=768
)

# Equilibrado: 1536 dimensiones
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Tu texto aquí',
    output_dimensionality=1536
)

# Máxima calidad: 3072 dimensiones (por defecto)
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Tu texto aquí',
    output_dimensionality=3072
)

Para la mayoría de las aplicaciones, 768 dimensiones ofrecen una calidad casi máxima con un 75% menos de almacenamiento.

Incrustando Imágenes

Incrusta imágenes para búsqueda visual:

import PIL.Image

# Cargar imagen
image = PIL.Image.open('product-photo.jpg')

# Generar embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=image
)

embedding = result['embedding']

Puedes incrustar hasta 6 imágenes por solicitud:

images = [
    PIL.Image.open('image1.jpg'),
    PIL.Image.open('image2.jpg'),
    PIL.Image.open('image3.jpg')
]

result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=images
)

Incrustando Video

Incrusta contenido de video para búsqueda de video:

# Primero, sube el archivo de video
video_file = genai.upload_file(path='demo-video.mp4')

# Esperar el procesamiento
import time
while video_file.state.name == 'PROCESSING':
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

# Generar embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=video_file
)

embedding = result['embedding']

Límites de video:

Máximo 128 segundos por solicitud
Formatos: MP4, MOV
Códecs: H264, H265, AV1, VP9

Incrustando Audio

Incrusta audio sin transcripción:

# Subir archivo de audio
audio_file = genai.upload_file(path='podcast-episode.mp3')

# Esperar el procesamiento
while audio_file.state.name == 'PROCESSING':
    time.sleep(2)
    audio_file = genai.get_file(audio_file.name)

# Generar embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=audio_file
)

embedding = result['embedding']

Límites de audio:

Máximo 80 segundos por solicitud
Formatos: MP3, WAV

Incrustando Documentos PDF

Incrusta páginas de PDF para búsqueda de documentos:

# Subir PDF
pdf_file = genai.upload_file(path='user-manual.pdf')

# Esperar el procesamiento
while pdf_file.state.name == 'PROCESSING':
    time.sleep(2)
    pdf_file = genai.get_file(pdf_file.name)

# Generar embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=pdf_file
)

embedding = result['embedding']

Límites de PDF:

Máximo 6 páginas por solicitud
Procesa tanto texto como contenido visual

Embeddings Multimodales (Texto + Imagen)

Combina múltiples tipos de contenido en un solo embedding:

import PIL.Image

image = PIL.Image.open('product.jpg')
text = "Auriculares inalámbricos de alta calidad con cancelación de ruido"

# Incrustar ambos juntos
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=[text, image]
)

embedding = result['embedding']

Esto captura relaciones entre el texto y la imagen en un solo embedding.

Procesamiento por Lotes

Procesa múltiples elementos de manera eficiente:

texts = [
    "Primer documento sobre pruebas de API",
    "Segundo documento sobre automatización",
    "Tercer documento sobre rendimiento"
]

embeddings = []
for text in texts:
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=text,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )
    embeddings.append(result['embedding'])

print(f"Se generaron {len(embeddings)} embeddings")

Para lotes grandes, usa la API de lotes para un ahorro del 50% en costos.

Construyendo un Sistema de Búsqueda Semántica

Aquí tienes un ejemplo completo usando Gemini Embedding 2 para búsqueda semántica.

Paso 1: Instalar Dependencias

pip install google-generativeai numpy scikit-learn

Paso 2: Incrustar Tus Documentos

import google.generativeai as genai
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity

genai.configure(api_key='YOUR_API_KEY')

# Documentos de ejemplo
documents = [
    "Apidog es una plataforma de prueba de API para desarrolladores",
    "Las API REST usan métodos HTTP como GET, POST, PUT, DELETE",
    "GraphQL proporciona un lenguaje de consulta para APIs",
    "La documentación de la API ayuda a los desarrolladores a entender los endpoints",
    "Postman es una herramienta popular para pruebas de API"
]

# Generar embeddings para todos los documentos
doc_embeddings = []
for doc in documents:
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=doc,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )
    doc_embeddings.append(result['embedding'])

# Convertir a array de numpy
doc_embeddings = np.array(doc_embeddings)

Paso 3: Crear Función de Búsqueda

def search(query, top_k=3):
    # Incrustar la consulta
    query_result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=query,
        task_type='RETRIEVAL_QUERY',
        output_dimensionality=768
    )
    query_embedding = np.array([query_result['embedding']])

    # Calcular similitudes
    similarities = cosine_similarity(query_embedding, doc_embeddings)[0]

    # Obtener los mejores resultados
    top_indices = np.argsort(similarities)[::-1][:top_k]

    results = []
    for idx in top_indices:
        results.append({
            'document': documents[idx],
            'score': similarities[idx]
        })

    return results

Paso 4: Buscar

# Probar la búsqueda
results = search("¿Qué herramientas puedo usar para probar APIs?")

for i, result in enumerate(results, 1):
    print(f"{i}. Puntuación: {result['score']:.4f}")
    print(f"   {result['document']}\n")

Salida:

1. Score: 0.8234
   Apidog is an API testing platform for developers

2. Score: 0.7891
   Postman is a popular API testing tool

3. Score: 0.6543
   API documentation helps developers understand endpoints

Construyendo un Sistema RAG

Usa Gemini Embedding 2 para la Generación Aumentada por Recuperación (RAG).

Paso 1: Configurar la Base de Conocimiento

import google.generativeai as genai
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity

genai.configure(api_key='YOUR_API_KEY')

# Base de conocimiento
knowledge_base = [
    "Apidog soporta APIs REST, GraphQL y WebSocket",
    "Puedes crear casos de prueba y ejecutarlos automáticamente",
    "Apidog genera documentación de API a partir de tus solicitudes",
    "Los servidores simulados te ayudan a probar antes de que el backend esté listo",
    "Las características de colaboración en equipo incluyen espacios de trabajo compartidos"
]

# Incrustar la base de conocimiento
kb_embeddings = []
for doc in knowledge_base:
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=doc,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )
    kb_embeddings.append(result['embedding'])

kb_embeddings = np.array(kb_embeddings)

Paso 2: Crear Función de Consulta RAG

def rag_query(question):
    # 1. Incrustar la pregunta
    query_result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=question,
        task_type='RETRIEVAL_QUERY',
        output_dimensionality=768
    )
    query_embedding = np.array([query_result['embedding']])

    # 2. Encontrar contexto relevante
    similarities = cosine_similarity(query_embedding, kb_embeddings)[0]
    top_idx = np.argmax(similarities)
    context = knowledge_base[top_idx]

    # 3. Generar respuesta con contexto
    prompt = f"""Contexto: {context}

Pregunta: {question}

Responde a la pregunta basándote en el contexto proporcionado."""

    model = genai.GenerativeModel('gemini-2.0-flash-exp')
    response = model.generate_content(prompt)

    return response.text

Paso 3: Consultar tu Sistema RAG

# Probar RAG
answer = rag_query("¿Puede Apidog generar documentación?")
print(answer)

Esto recupera el contexto más relevante de tu base de conocimiento y lo usa para generar respuestas precisas.

Almacenando Embeddings en una Base de Datos Vectorial

Usa ChromaDB para almacenar y consultar embeddings:

import chromadb
import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# Inicializar ChromaDB
client = chromadb.Client()
collection = client.create_collection(name="my_documents")

# Documentos a indexar
documents = [
    "Las pruebas de API aseguran que tus endpoints funcionen correctamente",
    "Las API REST siguen los principios de la arquitectura sin estado",
    "GraphQL permite a los clientes solicitar datos específicos"
]

# Generar y almacenar embeddings
for i, doc in enumerate(documents):
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=doc,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )

    collection.add(
        embeddings=[result['embedding']],
        documents=[doc],
        ids=[f"doc_{i}"]
    )

# Consultar la colección
query = "¿Cómo pruebo mi API?"
query_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=query,
    task_type='RETRIEVAL_QUERY',
    output_dimensionality=768
)

results = collection.query(
    query_embeddings=[query_result['embedding']],
    n_results=2
)

print("Mejores resultados:")
for doc in results['documents'][0]:
    print(f"- {doc}")

Manejo de Errores

Maneja los errores de la API con gracia:

import google.generativeai as genai
from google.api_core import exceptions

genai.configure(api_key='YOUR_API_KEY')

def safe_embed(content):
    try:
        result = genai.embed_content(
            model='models/gemini-embedding-2-preview',
            content=content,
            output_dimensionality=768
        )
        return result['embedding']

    except exceptions.InvalidArgument as e:
        print(f"Entrada inválida: {e}")
        # Ejemplo: Contenido demasiado largo o formato no soportado
        return None

    except exceptions.ResourceExhausted as e:
        print(f"Cuota excedida: {e}")
        # Ejemplo: Límite de tasa alcanzado o cuota agotada
        return None

    except exceptions.DeadlineExceeded as e:
        print(f"Tiempo de espera de la solicitud agotado: {e}")
        # Ejemplo: Problemas de red o respuesta lenta
        return None

    except Exception as e:
        print(f"Error inesperado: {e}")
        return None

# Usarlo
embedding = safe_embed("Tu texto aquí")
if embedding:
    print("Embedding generado con éxito")
else:
    print("Fallo al generar embedding")

Mensajes de Error Comunes:

InvalidArgument: Content exceeds maximum length - Reduce el tamaño de la entrada
ResourceExhausted: Quota exceeded - Espera o actualiza el plan
Unauthenticated: API key not valid - Revisa tu clave de API
PermissionDenied: Model not available - Verifica el nombre del modelo

Límites de Tasa y Mejores Prácticas

Límites de Tasa:

Nivel gratuito: 60 solicitudes por minuto
Nivel de pago: Límites más altos según tu plan

Mejores Prácticas:

Usa dimensiones apropiadas: 768 para producción, 3072 solo cuando necesites la máxima calidad

Solicitudes por lotes: Procesa múltiples elementos juntos cuando sea posible

Almacena en caché los embeddings: No vuelvas a incrustar el mismo contenido

Usa instrucciones de tarea: Mejoran la precisión para casos de uso específicos

Maneja errores: Implementa lógica de reintento con retroceso exponencial

Monitorea los costos: Rastrea tu uso de tokens

Optimización de Costos

Reduce los costos con estas estrategias:

1. Usa dimensiones más pequeñas:

# 768 dimensiones = 75% menos almacenamiento
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=text,
    output_dimensionality=768
)

2. Usa la API por lotes para tareas no urgentes:

# Ahorro del 50% en costos para procesamiento por lotes
# (La implementación de la API por lotes depende de tu configuración)

3. Almacena en caché los embeddings:

import hashlib
import json

embedding_cache = {}

def get_embedding_cached(content):
    # Crear clave de caché
    cache_key = hashlib.md5(content.encode()).hexdigest()

    # Comprobar caché
    if cache_key in embedding_cache:
        return embedding_cache[cache_key]

    # Generar embedding
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=content,
        output_dimensionality=768
    )

    # Almacenar en caché
    embedding_cache[cache_key] = result['embedding']

    return result['embedding']

Problemas Comunes y Soluciones

Problema: "Clave de API inválida"

# Solución: Revisa tu clave de API
import os
api_key = os.getenv('GEMINI_API_KEY')
if not api_key:
    print("¡Clave de API no configurada!")

Problema: "Contenido demasiado largo"

# Solución: Divide el texto largo en fragmentos
def chunk_text(text, max_tokens=8000):
    # Fragmentación simple basada en palabras
    words = text.split()
    chunks = []
    current_chunk = []

    for word in words:
        current_chunk.append(word)
        if len(current_chunk) >= max_tokens:
            chunks.append(' '.join(current_chunk))
            current_chunk = []

    if current_chunk:
        chunks.append(' '.join(current_chunk))

    return chunks

# Incrustar cada fragmento
for chunk in chunk_text(long_text):
    embedding = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=chunk
    )

Problema: "Tiempo de espera de procesamiento de archivo agotado"

# Solución: Aumenta el tiempo de espera para archivos grandes
import time

video_file = genai.upload_file(path='large-video.mp4')

max_wait = 300  # 5 minutos
waited = 0
while video_file.state.name == 'PROCESSING' and waited < max_wait:
    time.sleep(5)
    waited += 5
    video_file = genai.get_file(video_file.name)

if video_file.state.name == 'PROCESSING':
    print("Tiempo de espera de procesamiento de archivo agotado")
else:
    # Generar embedding
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=video_file
    )

Próximos Pasos

Ahora sabes cómo usar la API Gemini Embedding 2. Aquí tienes qué probar a continuación:

Construir un sistema de búsqueda semántica para tu documentación
Crear una aplicación RAG con contexto multimodal
Implementar búsqueda visual para catálogos de productos
Configurar búsqueda de audio para contenido de podcasts o videos
Experimentar con diferentes dimensiones para optimizar costos

La API es sencilla, pero las posibilidades son enormes. Comienza con embeddings de texto, luego añade imágenes, video o audio según lo requiera tu caso de uso.

¿Probando tu implementación? Usa Apidog para probar los endpoints de la API de Gemini, validar las respuestas y automatizar tus pruebas de pipeline de embedding.