Embeddings

A API Gemini oferece modelos de embedding para gerar embeddings de texto, imagens, vídeo e outros conteúdos. Esses embeddings resultantes podem ser usados para tarefas como pesquisa semântica, classificação e clustering, fornecendo resultados mais precisos e sensíveis ao contexto do que as abordagens baseadas em palavras-chave.

O modelo mais recente, gemini-embedding-2, é o primeiro modelo de embedding multimodal na API Gemini. Ele mapeia texto, imagens, vídeo, áudio e documentos em um espaço de embedding unificado, permitindo pesquisa, classificação e clustering entre modalidades em mais de 100 idiomas. Consulte a seção de embeddings multimodais para saber mais. Para casos de uso somente de texto, o gemini-embedding-001 continua disponível.

A criação de sistemas de geração aumentada de recuperação (RAG) é um caso de uso comum para produtos de IA. Os embeddings desempenham um papel fundamental na melhoria significativa das saídas do modelo, com maior precisão factual, coerência e riqueza contextual. Se você preferir usar uma solução de RAG gerenciada, criamos a ferramenta Pesquisa de Arquivos, que facilita o gerenciamento da RAG e é mais econômica.

Gerar embeddings

Use o método embedContent para gerar embeddings de texto:

Python

from google import genai

client = genai.Client()

result = client.models.embed_content(
        model="gemini-embedding-2",
        contents="What is the meaning of life?"
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";

async function main() {

    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: 'What is the meaning of life?',
    });

    console.log(response.embeddings);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", "What is the meaning of life?", null);

System.out.println(response.embeddings().orElse(null));

Go

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []*genai.Content{
        genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
    }
    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-2",
        contents,
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }

    embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(embeddings))
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "model": "models/gemini-embedding-2",
        "content": {
        "parts": [{
            "text": "What is the meaning of life?"
        }]
        }
    }'

Especificar o tipo de tarefa para melhorar o desempenho

É possível usar embeddings para uma ampla variedade de tarefas, desde classificação até pesquisa de documentos. Especificar o tipo de tarefa certo ajuda a otimizar os embeddings para as relações pretendidas, maximizando a precisão e a eficiência.

Tipos de tarefas com o Embeddings 2

Para tarefas somente de texto com gemini-embedding-2, recomendamos que você adicione a instrução da tarefa ao comando. Para isso, formate a consulta e o documento com o prefixo de tarefa correto.

Ao gerar um único embedding com base em uma entrada multimodal, geralmente não recomendamos prefixar a parte de texto da entrada com uma instrução de tarefa. Em alguns casos, ele melhora o desempenho, mas em outros, reduz.

As tabelas a seguir mostram exemplos de como formatar consultas e documentos para casos de uso simétricos e assimétricos usando o modelo gemini-embedding-2.

Casos de uso de recuperação (formato assimétrico)

Em casos de uso assimétricos, adicione o prefixo da tarefa à consulta e aplique a estrutura do documento ao conteúdo que você quer incorporar e recuperar.

Caso de uso Estrutura da consulta Estrutura do documento
Consulta de pesquisa task: search result | query: {content} title: {title} | text: {content}
Se não houver um título, use title: none.
Respostas a perguntas task: question answering | query: {content} title: {title} | text: {content}
Checagem de fatos task: fact checking | query: {content} title: {title} | text: {content}
Recuperação de código task: code retrieval | query: {content} title: {title} | text: {content}

Exemplo de uso

Python

# Generate embedding for a task's query. Use your correct task here:
def prepare_query(query):
    # return f"task: question answering | query: {query}"
    # return f"task: fact checking | query: {query}"
    # return f"task: code retrieval | query: {query}"
    return f"task: search result | query: {query}"

# Generate embedding for document of an asymmetric retrieval task:
def prepare_document(content, title=None):
    if title is None:
        title = "none"
    return f"title: {title} | text: {content}"

Casos de uso de entrada única (formato simétrico)

Em casos de uso simétricos, para a mesma tarefa, use a mesma formatação para a consulta e o documento.

Caso de uso Estrutura de entrada
Classificação task: classification | query: {content}
Clustering task: clustering | query: {content}
Similaridade semântica task: sentence similarity | query: {content}
Não use isso para pesquisa ou recuperação. Ele é destinado à similaridade textual semântica.

Exemplo de uso

Python

# Generate embedding for query & document of your task.
def prepare_query_and_document(content):
    # return f'task: clustering | query: {content}'
    # return f'task: sentence similarity | query: {content}'
    return f'task: classification | query: {content}'

É importante que a tarefa seja usada de forma consistente. Por exemplo, se os documentos forem incorporados com f'task: classification | query: {content}', a consulta também precisará ser incorporada seguindo esse formato de tarefa.

Tipos de tarefa com embeddings 1

Para gemini-embedding-001, é possível especificar o task_type no método embedContent. Para ver uma lista completa dos tipos de tarefas compatíveis, consulte a tabela Tipos de tarefas compatíveis.

O exemplo a seguir mostra como usar SEMANTIC_SIMILARITY para verificar a semelhança no significado de strings de textos.

Python

from google import genai
from google.genai import types
import pandas as pd
from sklearn.metrics.pairwise import cosine_similarity

client = genai.Client()

texts = [
    "What is the meaning of life?",
    "What is the purpose of existence?",
    "How do I bake a cake?",
]

result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(task_type="SEMANTIC_SIMILARITY")
)

# Create a 3x3 table to show the similarity matrix
df = pd.DataFrame(
    cosine_similarity([e.values for e in result.embeddings]),
    index=texts,
    columns=texts,
)

print(df)

JavaScript

import { GoogleGenAI } from "@google/genai";
// npm i compute-cosine-similarity
import * as cosineSimilarity from "compute-cosine-similarity";

async function main() {
    const ai = new GoogleGenAI({});

    const texts = [
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?",
    ];

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-001',
        contents: texts,
        config: { taskType: 'SEMANTIC_SIMILARITY' },
    });

    const embeddings = response.embeddings.map(e => e.values);

    for (let i = 0; i < texts.length; i++) {
        for (let j = i + 1; j < texts.length; j++) {
            const text1 = texts[i];
            const text2 = texts[j];
            const similarity = cosineSimilarity(embeddings[i], embeddings[j]);
            console.log(`Similarity between '${text1}' and '${text2}': ${similarity.toFixed(4)}`);
        }
    }
}

main();

Java

import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;
import java.util.List;

Client client = new Client();

List<String> texts =
    Arrays.asList(
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?");

EmbedContentConfig config =
    EmbedContentConfig.builder().taskType("SEMANTIC_SIMILARITY").build();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-001", texts, config);

List<ContentEmbedding> embeddings = response.embeddings().get();

for (int i = 0; i < texts.size(); i++) {
  for (int j = i + 1; j < texts.size(); j++) {
    List<Float> v1 = embeddings.get(i).values().get();
    List<Float> v2 = embeddings.get(j).values().get();
    double dotProduct = 0.0;
    double normA = 0.0;
    double normB = 0.0;
    for (int k = 0; k < v1.size(); k++) {
      dotProduct += v1.get(k) * v2.get(k);
      normA += v1.get(k) * v1.get(k);
      normB += v2.get(k) * v2.get(k);
    }
    double similarity = dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
    System.out.printf(
        "Similarity between '%s' and '%s': %.4f%n", texts.get(i), texts.get(j), similarity);
  }
}

Go

package main

import (
    "context"
    "fmt"
    "log"
    "math"

    "google.golang.org/genai"
)

// cosineSimilarity calculates the similarity between two vectors.
func cosineSimilarity(a, b []float32) (float64, error) {
    if len(a) != len(b) {
        return 0, fmt.Errorf("vectors must have the same length")
    }

    var dotProduct, aMagnitude, bMagnitude float64
    for i := 0; i < len(a); i++ {
        dotProduct += float64(a[i] * b[i])
        aMagnitude += float64(a[i] * a[i])
        bMagnitude += float64(b[i] * b[i])
    }

    if aMagnitude == 0 || bMagnitude == 0 {
        return 0, nil
    }

    return dotProduct / (math.Sqrt(aMagnitude) * math.Sqrt(bMagnitude)), nil
}

func main() {
    ctx := context.Background()
    client, _ := genai.NewClient(ctx, nil)
    defer client.Close()

    texts := []string{
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?",
    }

    var contents []*genai.Content
    for _, text := range texts {
        contents = append(contents, genai.NewContentFromText(text, genai.RoleUser))
    }

    result, _ := client.Models.EmbedContent(ctx,
        "gemini-embedding-001",
        contents,
        &genai.EmbedContentRequest{TaskType: genai.TaskTypeSemanticSimilarity},
    )

    embeddings := result.Embeddings

    for i := 0; i < len(texts); i++ {
        for j := i + 1; j < len(texts); j++ {
            similarity, _ := cosineSimilarity(embeddings[i].Values, embeddings[j].Values)
            fmt.Printf("Similarity between '%s' and '%s': %.4f\n", texts[i], texts[j], similarity)
        }
    }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -d '{
    "taskType": "SEMANTIC_SIMILARITY",
    "content": {
        "parts": [
        {
            "text": "What is the meaning of life?"
        },
        {
            "text": "How much wood would a woodchuck chuck?"
        },
        {
            "text": "How does the brain work?"
        }
        ]
    }
    }'

Os snippets de código vão mostrar como os diferentes blocos de texto são semelhantes entre si quando executados.

Tipos de tarefas com suporte

Tipos de tarefas compatíveis com gemini-embedding-001:

Tipo de tarefa Descrição Exemplos
SEMANTIC_SIMILARITY Embeddings otimizados para avaliar a similaridade de texto. Sistemas de recomendação, detecção de duplicatas
CLASSIFICAÇÃO Embeddings otimizados para classificar textos de acordo com rótulos predefinidos. Análise de sentimento, detecção de spam
CLUSTERING Embeddings otimizados para agrupar textos com base nas semelhanças deles. Organização de documentos, pesquisa de mercado, detecção de anomalias
RETRIEVAL_DOCUMENT Embeddings otimizados para pesquisa de documentos. Indexar artigos, livros ou páginas da Web para pesquisa.
RETRIEVAL_QUERY Embeddings otimizados para consultas de pesquisa gerais. Use RETRIEVAL_QUERY para consultas e RETRIEVAL_DOCUMENT para documentos a serem recuperados. Pesquisa personalizada
CODE_RETRIEVAL_QUERY Embeddings otimizados para recuperação de blocos de código com base em consultas de linguagem natural. Use CODE_RETRIEVAL_QUERY para consultas e RETRIEVAL_DOCUMENT para blocos de código a serem recuperados. Sugestões de código e pesquisa
QUESTION_ANSWERING Embeddings para perguntas em um sistema de respostas a perguntas, otimizados para encontrar documentos que respondam à pergunta. Use QUESTION_ANSWERING para perguntas e RETRIEVAL_DOCUMENT para documentos a serem recuperados. Caixa de chat
FACT_VERIFICATION Embeddings para declarações que precisam ser verificadas, otimizados para recuperar documentos que contêm evidências que apoiam ou refutam a declaração. Use FACT_VERIFICATION para o texto de destino e RETRIEVAL_DOCUMENT para os documentos a serem recuperados. Sistemas automatizados de checagem de fatos

Como controlar o tamanho do embedding

Tanto gemini-embedding-001 quanto gemini-embedding-2 são treinados usando a técnica de aprendizado de representações de Matryoshka (MRL, na sigla em inglês), que ensina um modelo a aprender embeddings de alta dimensão que têm segmentos iniciais (ou prefixos) que também são versões úteis e mais simples dos mesmos dados.

Use o parâmetro output_dimensionality para controlar o tamanho do vetor de embedding de saída. Selecionar uma dimensionalidade de saída menor pode economizar espaço de armazenamento e aumentar a eficiência computacional para aplicativos downstream, sacrificando pouco em termos de qualidade. Por padrão, os dois modelos geram um embedding de 3.072 dimensões, mas é possível truncá-lo para um tamanho menor sem perder qualidade para economizar espaço de armazenamento. Recomendamos o uso de 768, 1536 ou 3072 dimensões de saída.

Python

from google import genai
from google.genai import types

client = genai.Client()

result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="What is the meaning of life?",
    config=types.EmbedContentConfig(output_dimensionality=768)
)

[embedding_obj] = result.embeddings
embedding_length = len(embedding_obj.values)

print(f"Length of embedding: {embedding_length}")

JavaScript

import { GoogleGenAI } from "@google/genai";

async function main() {
    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: 'What is the meaning of life?',
        config: { outputDimensionality: 768 },
    });

    const embeddingLength = response.embeddings[0].values.length;
    console.log(`Length of embedding: ${embeddingLength}`);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();

EmbedContentConfig config =
    EmbedContentConfig.builder().outputDimensionality(768).build();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", "What is the meaning of life?", config);

ContentEmbedding embeddingObj = response.embeddings().get().get(0);
int embeddingLength = embeddingObj.values().get().size();

System.out.println("Length of embedding: " + embeddingLength);

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    // The client uses Application Default Credentials.
    // Authenticate with 'gcloud auth application-default login'.
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    contents := []*genai.Content{
        genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
    }

    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-2",
        contents,
        &genai.EmbedContentRequest{OutputDimensionality: 768},
    )
    if err != nil {
        log.Fatal(err)
    }

    embedding := result.Embeddings[0]
    embeddingLength := len(embedding.Values)
    fmt.Printf("Length of embedding: %d\n", embeddingLength)
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H 'Content-Type: application/json' \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -d '{
        "content": {"parts":[{ "text": "What is the meaning of life?"}]},
        "output_dimensionality": 768
    }'

Exemplo de saída do snippet de código:

Length of embedding: 768

Como garantir a qualidade em dimensões menores

Enquanto os embeddings padrão de 3.072 dimensões são sempre normalizados, o Gemini Embedding 2 também normaliza automaticamente as dimensões truncadas (por exemplo, 768, 1.536). Isso garante que a similaridade semântica seja calculada pela direção do vetor, e não pela magnitude, fornecendo resultados mais precisos de imediato.

Modelos mais antigos: se você estiver usando gemini-embedding-001, normalize manualmente as dimensões que não sejam 3072 da seguinte maneira:

Python

import numpy as np
from numpy.linalg import norm

# Only for embeddings from `gemini-embedding-001`
embedding_values_np = np.array(embedding_obj.values)
normed_embedding = embedding_values_np / np.linalg.norm(embedding_values_np)

print(f"Normed embedding length: {len(normed_embedding)}")
print(f"Norm of normed embedding: {np.linalg.norm(normed_embedding):.6f}") # Should be very close to 1

Exemplo de saída desse snippet de código:

Normed embedding length: 768
Norm of normed embedding: 1.000000

A tabela a seguir mostra as pontuações do MTEB, um comparativo de mercado usado com frequência para embeddings, para diferentes dimensões. O resultado mostra que o desempenho não está estritamente vinculado ao tamanho da dimensão do embedding, com dimensões menores alcançando pontuações comparáveis às de dimensões maiores.

Dimensão do MRL Pontuação do MTEB (Gemini Embedding 001)
2048 68.16
1536 68,17
768 67,99
512 67,55
256 66.19
128 63,31

Embeddings multimodais

O modelo gemini-embedding-2 aceita entradas multimodais, permitindo incorporar imagens, vídeos, áudios e documentos junto com texto. Todas as modalidades são mapeadas no mesmo espaço de embedding, permitindo pesquisa e comparação multimodais.

Modalidades e limites aceitos

O limite máximo geral de tokens de entrada é de 8.192 tokens.

Modalidade Especificações e limites
Texto Aceita até 8.192 tokens.
Imagem Máximo de 6 imagens por solicitação. Formatos aceitos: PNG, JPEG.
Áudio Duração máxima de 180 segundos. Formatos aceitos: MP3, WAV.
Vídeo Duração máxima de 120 segundos. Formatos aceitos: MP4, MOV. Codecs compatíveis: H264, H265, AV1, VP9.
O sistema processa no máximo 32 frames por vídeo: vídeos curtos (≤32s) são amostrados a 1 fps, enquanto vídeos mais longos são amostrados de maneira uniforme para 32 frames. As faixas de áudio não são processadas em arquivos de vídeo.
Documentos (PDF) Máximo de 1 arquivo por solicitação, com até 6 páginas.

Como incorporar imagens

O exemplo a seguir mostra como incorporar uma imagem usando gemini-embedding-2.

As imagens podem ser fornecidas como dados inline ou como arquivos enviados pela API Files.

Python

from google import genai
from google.genai import types

with open('example.png', 'rb') as f:
    image_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=image_bytes,
            mime_type='image/png',
        ),
    ]
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("example.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'image/png',
                data: imgBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("example.png"));

Content content = Content.fromParts(Part.fromBytes(imageBytes, "image/png"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));

REST

IMG_PATH="/path/to/your/image.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "image/png",
                    "data": "'"${IMG_BASE64}"'"
                }
            }]
        }
    }'

Agregação de embeddings

Ao trabalhar com conteúdo multimodal, a forma como você estrutura sua entrada afeta a saída do embedding:

  • Várias partes (agregadas): adicionar várias entradas diretamente ao parâmetro contents produz um embedding agregado para todas as entradas.
  • Vários objetos Content (separados): ao encapsular cada entrada em um objeto Content e transmiti-las no parâmetro contents, embeddings separados são retornados para cada entrada.
  • Representação no nível do post: para objetos complexos, como posts de redes sociais com vários itens de mídia, recomendamos agregar embeddings separados (por exemplo, por média) para criar uma representação coerente no nível do post.

O exemplo a seguir mostra como criar um embedding agregado para entrada de texto e imagem. Basta adicionar várias entradas ao parâmetro contents:

Python

from google import genai
from google.genai import types

client = genai.Client()

with open('dog.png', 'rb') as f:
    image_bytes = f.read()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        "An image of a dog",
        types.Part.from_bytes(
            data=image_bytes,
            mime_type='image/png',
        ),
    ]
)

# This produces one embedding
for embedding in result.embeddings:
    print(embedding.values)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("dog.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [
            'An image of a dog',
            {
                inlineData: {
                    mimeType: 'image/png',
                    data: imgBase64,
                },
            },
        ],
    });

    // This produces one embedding
    for (const embedding of response.embeddings) {
        console.log(embedding.values);
    }
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("dog.png"));

Content content =
    Content.fromParts(
        Part.fromText("An image of a dog"),
        Part.fromBytes(imageBytes, "image/png"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

// This produces one embedding
for (ContentEmbedding embedding : response.embeddings().orElse(Collections.emptyList())) {
  System.out.println(embedding.values().orElse(Collections.emptyList()));
}

REST

IMG_PATH="/path/to/your/dog.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [
                {"text": "An image of a dog"},
                {
                    "inline_data": {
                        "mime_type": "image/png",
                        "data": "'"${IMG_BASE64}"'"
                    }
                }
            ]
        }
    }'

Por outro lado, se você usar objetos Content dentro do parâmetro contents, ele vai retornar embeddings separados. Este exemplo cria vários embeddings em uma chamada de embedding:

Python

from google import genai
from google.genai import types

client = genai.Client()

with open('dog.png', 'rb') as f:
    image_bytes = f.read()

result = client.models.embed_content(
    model="gemini-embedding-2",
    contents=[
        types.Content(parts=[types.Part.from_text(text="task: classification | query: An image of a dog")]),
        types.Content(
            parts=[
                types.Part.from_bytes(
                    data=image_bytes,
                    mime_type="image/png",
                ),
            ]
        ),
    ],
)

# This produces two embeddings
for embedding in result.embeddings:
    print(embedding.values)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("dog.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [
            { parts: [{ text: 'task: classification | query: An image of a dog' }] },
            {
                parts: [{
                    inlineData: {
                        mimeType: 'image/png',
                        data: imgBase64,
                    },
                }],
            },
        ],
    });

    // This produces two embeddings
    for (const embedding of response.embeddings) {
        console.log(embedding.values);
    }
}

main();

Java

import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("dog.png"));

List<Content> contents =
    Arrays.asList(
        Content.fromParts(Part.fromText("task: classification | query: An image of a dog")),
        Content.fromParts(Part.fromBytes(imageBytes, "image/png")));

// Embed each Content object separately to produce separate embeddings
for (Content content : contents) {
  EmbedContentResponse response =
      client.models.embedContent("gemini-embedding-2", content, null);
  for (ContentEmbedding embedding : response.embeddings().orElse(Collections.emptyList())) {
    System.out.println(embedding.values().orElse(Collections.emptyList()));
  }
}

REST

IMG_PATH="/path/to/your/dog.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:batchEmbedContents" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "requests": [
            {
                "model": "models/gemini-embedding-2",
                "content": {"parts": [{"text": "task: classification | query: An image of a dog"}]}
            },
            {
                "model": "models/gemini-embedding-2",
                "content": {"parts": [{"inline_data": {"mime_type": "image/png", "data": "'"${IMG_BASE64}"'"}}]}
            }
        ]
    }'

Como incorporar áudio

O exemplo a seguir mostra como incorporar um arquivo de áudio usando gemini-embedding-2.

Os arquivos de áudio podem ser fornecidos como dados inline ou como arquivos enviados pela API Files.

Python

from google import genai
from google.genai import types

with open('example.mp3', 'rb') as f:
    audio_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=audio_bytes,
            mime_type='audio/mpeg',
        ),
    ]
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const audioBase64 = fs.readFileSync("example.mp3", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'audio/mpeg',
                data: audioBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] audioBytes = Files.readAllBytes(Paths.get("example.mp3"));

Content content = Content.fromParts(Part.fromBytes(audioBytes, "audio/mpeg"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));

REST

AUDIO_PATH="/path/to/your/example.mp3"
AUDIO_BASE64=$(base64 -w0 "${AUDIO_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "audio/mpeg",
                    "data": "'"${AUDIO_BASE64}"'"
                }
            }]
        }
    }'

Incorporando vídeo

O exemplo a seguir mostra como incorporar um vídeo usando gemini-embedding-2.

Os vídeos podem ser fornecidos como dados inline ou como arquivos enviados pela API Files.

Python

from google import genai
from google.genai import types

client = genai.Client()

with open('example.mp4', 'rb') as f:
    video_bytes = f.read()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=video_bytes,
            mime_type='video/mp4',
        ),
    ]
)

print(result.embeddings[0].values)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const videoBase64 = fs.readFileSync("example.mp4", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'video/mp4',
                data: videoBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;

Client client = new Client();

byte[] videoBytes = Files.readAllBytes(Paths.get("example.mp4"));

Content content = Content.fromParts(Part.fromBytes(videoBytes, "video/mp4"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(
    response.embeddings().get().get(0).values().orElse(Collections.emptyList()));

REST

VIDEO_PATH="/path/to/your/video.mp4"
VIDEO_BASE64=$(base64 -w0 "${VIDEO_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "video/mp4",
                    "data": "'"${VIDEO_BASE64}"'"
                }
            }]
        }
    }'

Se você precisar incorporar vídeos com mais de 120 segundos, divida-os em segmentos sobrepostos e incorpore esses blocos individualmente.

Como incorporar documentos

Documentos em formato PDF podem ser incorporados diretamente. O modelo processa o conteúdo visual e de texto de cada página.

Os PDFs podem ser fornecidos como dados inline ou como arquivos enviados pela API Files.

Como o modelo processa PDFs

Quando você incorpora um PDF, o modelo processa o documento usando recursos visuais e de texto:

  • Representação visual: o modelo renderiza cada página como uma imagem, o que consome 258 tokens por página.
  • Extração de texto: o modelo extrai o texto do documento. Para PDFs nativos (que contêm texto digital), o modelo extrai o texto diretamente. Para PDFs digitalizados (que contêm imagens de texto), o modelo executa automaticamente o reconhecimento óptico de caracteres (OCR) para extrair o texto.

Para calcular a contagem total de tokens de um PDF, adicione os tokens visuais (258 por página) aos tokens de texto. As entradas precisam se ajustar ao limite de 8.192 tokens do modelo (compartilhado entre todas as modalidades). O sistema trunca silenciosamente as entradas que excedem esse limite.

Limites de PDF

  • Arquivos por solicitação: é possível enviar no máximo 1 arquivo PDF.
  • Limite de páginas: é possível enviar no máximo 6 páginas por arquivo. Para garantir a melhor qualidade, recomendamos usar uma página por PDF.

O exemplo a seguir mostra como incorporar um PDF usando gemini-embedding-2:

Python

from google import genai
from google.genai import types

with open('example.pdf', 'rb') as f:
    pdf_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=pdf_bytes,
            mime_type='application/pdf',
        ),
    ]
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const pdfBase64 = fs.readFileSync("example.pdf", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'application/pdf',
                data: pdfBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] pdfBytes = Files.readAllBytes(Paths.get("example.pdf"));

Content content = Content.fromParts(Part.fromBytes(pdfBytes, "application/pdf"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));

REST

PDF_PATH="/path/to/your/example.pdf"
PDF_BASE64=$(base64 -w0 "${PDF_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "application/pdf",
                    "data": "'"${PDF_BASE64}"'"
                }
            }]
        }
    }'

Casos de uso

Os embeddings de texto são cruciais para uma variedade de casos de uso comuns de IA, como:

Armazenamento de embeddings

Ao levar embeddings para a produção, é comum usar bancos de dados vetoriais para armazenar, indexar e recuperar embeddings de alta dimensão com eficiência. O Google Cloud oferece serviços de dados gerenciados que podem ser usados para essa finalidade, incluindo busca vetorial 2.0 da Gemini Enterprise Agent Platform, BigQuery, AlloyDB e Cloud SQL.

Os tutoriais a seguir mostram como usar outros bancos de dados de vetores de terceiros com o Gemini Embedding.

Versões do modelo

Gemini Embedding 2

Propriedade Descrição
Código do modelo

API Gemini

gemini-embedding-2
Tipos de dados aceitos

Entrada

Texto, imagem, vídeo, áudio, PDF

Saída

Embeddings de textos
Limites de tokens[*]

Limite de tokens de entrada

8.192

Tamanho da dimensão de saída

Flexível, aceita: 128 - 3072, Recomendado: 768, 1536, 3072
Versões
Leia os padrões de versão do modelo para mais detalhes.
  • Estável: gemini-embedding-2
Atualização mais recente Abril de 2026

Embedding do Gemini

Propriedade Descrição
Código do modelo

API Gemini

gemini-embedding-001
Tipos de dados aceitos

Entrada

Texto

Saída

Embeddings de textos
Limites de tokens[*]

Limite de tokens de entrada

2.048

Tamanho da dimensão de saída

Flexível, aceita: 128 - 3072, Recomendado: 768, 1536, 3072
Versões
Leia os padrões de versão do modelo para mais detalhes.
  • Estável: gemini-embedding-001
Atualização mais recente Junho de 2025

Para modelos de embeddings descontinuados, acesse a página Descontinuações.

Migração do gemini-embedding-001

Os espaços de embedding entre gemini-embedding-001 e gemini-embedding-2 são incompatíveis. Isso significa que não é possível comparar diretamente os embeddings gerados por um modelo com os embeddings gerados pelo outro. Se você estiver fazendo upgrade para gemini-embedding-2, será necessário incorporar novamente todos os dados atuais.

Além da incompatibilidade, há várias outras diferenças importantes entre os dois modelos:

  • Especificação do tipo de tarefa: com gemini-embedding-001, você especifica o tipo de tarefa usando o parâmetro task_type (por exemplo, SEMANTIC_SIMILARITY, RETRIEVAL_DOCUMENT). Com gemini-embedding-2, o parâmetro task_type não é compatível. Em vez disso, inclua as instruções da tarefa diretamente no comando para tarefas somente de texto. Consulte Tipos de tarefas com Embeddings 2 para saber como formatar comandos para diferentes casos de uso.

  • Agregação de embedding: gemini-embedding-001 gera embeddings individuais para cada string em uma lista de entradas. Por outro lado, gemini-embedding-2 produz um único embedding agregado quando várias entradas (como texto e imagens) são fornecidas diretamente em uma solicitação. Para gerar embeddings separados para entradas individuais, envolva cada entrada em um objeto Content ou use a API Batch. Consulte Agregação de embedding para mais informações.

  • Normalização: se você usar output_dimensionality para solicitar embeddings com menos de 3.072 dimensões, o gemini-embedding-2 vai normalizar automaticamente esses embeddings truncados. Com gemini-embedding-001, é necessário fazer a normalização manual para dimensões diferentes de 3072. Consulte Como garantir a qualidade de dimensões menores para mais detalhes.

Embeddings em lote

Se a latência não for uma preocupação, use os modelos de embeddings do Gemini com a API Batch. Isso permite uma capacidade muito maior por 50% do preço padrão do Embedding. Encontre exemplos de como começar no guia de início rápido da API Batch.

Aviso de uso responsável

Ao contrário dos modelos de IA generativa que criam conteúdo, o modelo de embedding do Gemini tem como objetivo apenas transformar o formato dos dados de entrada em uma representação numérica. Embora o Google seja responsável por fornecer um modelo de embedding que transforma o formato dos dados de entrada no formato numérico solicitado, os usuários mantêm total responsabilidade pelos dados inseridos e pelos embeddings resultantes. Ao usar o modelo de embedding do Gemini, você confirma que tem os direitos necessários sobre qualquer conteúdo que enviar. Não gere conteúdo que viole os direitos de propriedade intelectual ou os direitos de privacidade de terceiros. O uso deste serviço está sujeito à nossa Política de Uso Proibido e aos Termos de Serviço do Google.

Comece a criar com embeddings

Confira o notebook de início rápido de embeddings para conhecer os recursos do modelo e aprender a personalizar e visualizar seus embeddings.