Como Usar a API Gemini Embedding 2?

A API Gemini Embedding 2 do Google permite gerar embeddings para texto, imagens, vídeo, áudio e PDFs. Este guia mostra como usá-la, com exemplos de código reais que você pode executar hoje.

Nota: Este guia aborda a versão de prévia pública (gemini-embedding-2-preview). A API pode mudar antes da disponibilidade geral.

Quer entender primeiro o que é o Gemini Embedding 2? Leia nossa visão geral: O que é o Gemini Embedding 2?

Pré-requisitos

Você precisa de:

Uma chave de API do Google AI
Python 3.7 ou superior
O SDK do Google Generative AI

Instalação

Instale o SDK:

pip install google-generativeai

Configuração Básica

Configure sua chave de API:

import google.generativeai as genai

# Defina sua chave de API
genai.configure(api_key='YOUR_API_KEY')

Para produção, use variáveis de ambiente:

import os
import google.generativeai as genai

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

Testando com Apidog

Antes de mergulhar no código, você pode testar a API Gemini Embedding diretamente no Apidog:

Captura de tela do Apidog mostrando como testar a API Gemini Embedding 2

Crie uma nova requisição no Apidog
Defina o método como POST
URL: https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent
Adicione o cabeçalho: x-goog-api-key: YOUR_API_KEY
Corpo (JSON):

{
  "content": {
    "parts": [{
      "text": "What is API testing?"
    }]
  }
}

Isso permite verificar se sua chave de API funciona e ver a estrutura da resposta antes de escrever o código. Você pode salvar isso como um caso de teste e validar respostas de embedding em seu pipeline de CI/CD.

Gerando Embeddings de Texto

O caso de uso mais simples - embutir texto:

import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# Gerar embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Qual é o sentido da vida?'
)

# Obter o vetor de embedding
embedding = result['embedding']
print(f"Dimensões do embedding: {len(embedding)}")
print(f"Primeiros 5 valores: {embedding[:5]}")

Saída:

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

Nota: A estrutura da resposta é result['embedding'], que retorna uma lista de floats. Cada float representa uma dimensão do vetor de embedding.

Usando Instruções de Tarefa

As instruções de tarefa otimizam os embeddings para casos de uso específicos:

# Para consultas de busca
query_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='melhores ferramentas de teste de API',
    task_type='RETRIEVAL_QUERY'
)

# Para documentos que você está indexando
doc_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Apidog é uma plataforma de teste de API...',
    task_type='RETRIEVAL_DOCUMENT'
)

Tipos de tarefa disponíveis:

RETRIEVAL_QUERY - Usar para consultas de busca
RETRIEVAL_DOCUMENT - Usar para documentos que você está indexando
SEMANTIC_SIMILARITY - Usar para comparar similaridade de conteúdo
CLASSIFICATION - Usar para tarefas de categorização
CLUSTERING - Usar para agrupar conteúdo semelhante

Controlando as Dimensões de Saída

Reduza os custos de armazenamento usando dimensões menores:

# Otimizado para produção: 768 dimensões
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Seu texto aqui',
    output_dimensionality=768
)

# Equilibrado: 1536 dimensões
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Seu texto aqui',
    output_dimensionality=1536
)

# Qualidade máxima: 3072 dimensões (padrão)
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Seu texto aqui',
    output_dimensionality=3072
)

Para a maioria das aplicações, 768 dimensões oferecem qualidade quase máxima com 75% menos armazenamento.

Embutindo Imagens

Embuta imagens para busca visual:

import PIL.Image

# Carregar imagem
image = PIL.Image.open('product-photo.jpg')

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

embedding = result['embedding']

Você pode embutir até 6 imagens por requisição:

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
)

Embutindo Vídeo

Embuta conteúdo de vídeo para busca de vídeo:

# Primeiro, faça o upload do arquivo de vídeo
video_file = genai.upload_file(path='demo-video.mp4')

# Aguardar processamento
import time
while video_file.state.name == 'PROCESSING':
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

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

embedding = result['embedding']

Limites de vídeo:

Máximo de 128 segundos por requisição
Formatos: MP4, MOV
Codecs: H264, H265, AV1, VP9

Embutindo Áudio

Embuta áudio sem transcrição:

# Fazer upload do arquivo de áudio
audio_file = genai.upload_file(path='podcast-episode.mp3')

# Aguardar processamento
while audio_file.state.name == 'PROCESSING':
    time.sleep(2)
    audio_file = genai.get_file(audio_file.name)

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

embedding = result['embedding']

Limites de áudio:

Máximo de 80 segundos por requisição
Formatos: MP3, WAV

Embutindo Documentos PDF

Embuta páginas de PDF para busca de documentos:

# Fazer upload do PDF
pdf_file = genai.upload_file(path='user-manual.pdf')

# Aguardar processamento
while pdf_file.state.name == 'PROCESSING':
    time.sleep(2)
    pdf_file = genai.get_file(pdf_file.name)

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

embedding = result['embedding']

Limites de PDF:

Máximo de 6 páginas por requisição
Processa tanto o conteúdo de texto quanto o visual

Embeddings Multimodais (Texto + Imagem)

Combine vários tipos de conteúdo em um único embedding:

import PIL.Image

image = PIL.Image.open('product.jpg')
text = "Fones de ouvido sem fio de alta qualidade com cancelamento de ruído"

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

embedding = result['embedding']

Isso captura as relações entre o texto e a imagem em um único embedding.

Processamento em Lotes

Processe vários itens eficientemente:

texts = [
    "Primeiro documento sobre teste de API",
    "Segundo documento sobre automação",
    "Terceiro documento sobre desempenho"
]

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"Gerados {len(embeddings)} embeddings")

Para grandes lotes, use a API de lote para economizar 50% nos custos.

Construindo um Sistema de Busca Semântica

Aqui está um exemplo completo usando o Gemini Embedding 2 para busca semântica.

Passo 1: Instalar Dependências

pip install google-generativeai numpy scikit-learn

Passo 2: Embutir Seus 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 exemplo
documents = [
    "Apidog é uma plataforma de teste de API para desenvolvedores",
    "APIs REST usam métodos HTTP como GET, POST, PUT, DELETE",
    "GraphQL fornece uma linguagem de consulta para APIs",
    "A documentação de API ajuda os desenvolvedores a entender os endpoints",
    "Postman é uma ferramenta popular de teste de API"
]

# Gerar embeddings para todos os 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'])

# Converter para array numpy
doc_embeddings = np.array(doc_embeddings)

Passo 3: Criar Função de Busca

def search(query, top_k=3):
    # Embutir a 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 similaridades
    similarities = cosine_similarity(query_embedding, doc_embeddings)[0]

    # Obter os melhores 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

Passo 4: Buscar

# Testar a busca
results = search("Quais ferramentas posso usar para teste de API?")

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

Saída:

1. Pontuação: 0.8234
   Apidog é uma plataforma de teste de API para desenvolvedores

2. Pontuação: 0.7891
   Postman é uma ferramenta popular de teste de API

3. Pontuação: 0.6543
   A documentação de API ajuda os desenvolvedores a entender os endpoints

Construindo um Sistema RAG

Use o Gemini Embedding 2 para Geração Aumentada por Recuperação (RAG).

Passo 1: Configurar Base de Conhecimento

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 conhecimento
knowledge_base = [
    "Apidog suporta APIs REST, GraphQL e WebSocket",
    "Você pode criar casos de teste e executá-los automaticamente",
    "Apidog gera documentação de API a partir de suas requisições",
    "Servidores mock ajudam você a testar antes que o backend esteja pronto",
    "Recursos de colaboração em equipe incluem workspaces compartilhados"
]

# Embutir base de conhecimento
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)

Passo 2: Criar Função de Consulta RAG

def rag_query(question):
    # 1. Embutir a pergunta
    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. Gerar resposta com contexto
    prompt = f"""Contexto: {context}

Pergunta: {question}

Responda à pergunta com base no contexto fornecido."""

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

    return response.text

Passo 3: Consultar Seu Sistema RAG

# Testar RAG
answer = rag_query("O Apidog pode gerar documentação?")
print(answer)

Isso recupera o contexto mais relevante da sua base de conhecimento e o usa para gerar respostas precisas.

Armazenando Embeddings em um Banco de Dados Vetorial

Use o ChromaDB para armazenar e 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 para indexar
documents = [
    "O teste de API garante que seus endpoints funcionem corretamente",
    "APIs REST seguem princípios de arquitetura sem estado",
    "GraphQL permite que clientes solicitem dados específicos"
]

# Gerar e armazenar 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 a coleção
query = "Como testo minha 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("Melhores resultados:")
for doc in results['documents'][0]:
    print(f"- {doc}")

Tratamento de Erros

Lide com erros da API de forma elegante:

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}")
        # Exemplo: Conteúdo muito longo ou formato não suportado
        return None

    except exceptions.ResourceExhausted as e:
        print(f"Cota excedida: {e}")
        # Exemplo: Limite de taxa atingido ou cota esgotada
        return None

    except exceptions.DeadlineExceeded as e:
        print(f"Tempo limite da requisição: {e}")
        # Exemplo: Problemas de rede ou resposta lenta
        return None

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

# Usar
embedding = safe_embed("Seu texto aqui")
if embedding:
    print("Embedding gerado com sucesso")
else:
    print("Falha ao gerar embedding")

Mensagens de Erro Comuns:

InvalidArgument: Content exceeds maximum length - Reduza o tamanho da entrada
ResourceExhausted: Quota exceeded - Espere ou atualize seu plano
Unauthenticated: API key not valid - Verifique sua chave de API
PermissionDenied: Model not available - Verifique o nome do modelo

Limitação de Taxa e Melhores Práticas

Limites de Taxa:

Camada gratuita: 60 requisições por minuto
Camada paga: Limites maiores com base no seu plano

Melhores Práticas:

Use dimensões apropriadas: 768 para produção, 3072 apenas quando precisar de qualidade máxima

Requisições em lote: Processe vários itens juntos sempre que possível

Armazene embeddings em cache: Não re-embuta o mesmo conteúdo

Use instruções de tarefa: Elas melhoram a precisão para casos de uso específicos

Lide com erros: Implemente lógica de retry com backoff exponencial

Monitore custos: Rastreie seu uso de tokens

Otimização de Custos

Reduza os custos com estas estratégias:

1. Use dimensões menores:

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

2. Use a API de lote para tarefas não urgentes:

# 50% de economia de custos para processamento em lote
# (A implementação da API de lote depende da sua configuração)

3. Armazene embeddings em cache:

import hashlib
import json

embedding_cache = {}

def get_embedding_cached(content):
    # Criar chave de cache
    cache_key = hashlib.md5(content.encode()).hexdigest()

    # Verificar cache
    if cache_key in embedding_cache:
        return embedding_cache[cache_key]

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

    # Armazenar no cache
    embedding_cache[cache_key] = result['embedding']

    return result['embedding']

Problemas Comuns e Soluções

Problema: "Chave de API inválida"

# Solução: Verifique sua chave de API
import os
api_key = os.getenv('GEMINI_API_KEY')
if not api_key:
    print("Chave de API não definida!")

Problema: "Conteúdo muito longo"

# Solução: Divida o texto longo em pedaços
def chunk_text(text, max_tokens=8000):
    # Agrupamento simples baseado em palavras
    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

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

Problema: "Tempo limite de processamento de arquivo"

# Solução: Aumente o tempo de espera para arquivos 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("Tempo limite de processamento de arquivo")
else:
    # Gerar embedding
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=video_file
    )

Próximos Passos

Agora você sabe como usar a API Gemini Embedding 2. Aqui está o que tentar a seguir:

Construa um sistema de busca semântica para sua documentação
Crie um aplicativo RAG com contexto multimodal
Implemente busca visual para catálogos de produtos
Configure busca de áudio para conteúdo de podcast ou vídeo
Experimente com diferentes dimensões para otimizar custos

A API é direta, mas as possibilidades são enormes. Comece com embeddings de texto, depois adicione imagens, vídeo ou áudio conforme seu caso de uso exigir.

Testando sua implementação? Use o Apidog para testar os endpoints da API Gemini, validar respostas e automatizar seus testes de pipeline de embedding.