Embeddings

A API Gemini oferece modelos de embedding de texto para gerar embeddings de palavras, frases, sentenças e código. Esses embeddings fundamentais impulsionam tarefas avançadas de PNL, como pesquisa semântica, classificação e clustering, fornecendo resultados mais precisos e contextualizados do que abordagens baseadas em palavras-chave.

A criação de sistemas de geração aumentada de recuperação (RAG) é um caso de uso comum para embeddings. As incorporações são fundamentais para melhorar significativamente as saídas do modelo com mais acurácia factual, coerência e riqueza contextual. Eles recuperam com eficiência informações relevantes de bases de conhecimento, representadas por incorporações, que são transmitidas como contexto adicional no comando de entrada para modelos de linguagem, orientando-os a gerar respostas mais informadas e precisas.

Para saber mais sobre as variantes de modelo de embedding disponíveis, consulte a seção Versões do modelo. Para aplicativos de nível empresarial e cargas de trabalho de alto volume, sugerimos usar modelos de embedding na Vertex AI.

Gerando 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-001",
        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-001',
        contents: 'What is the meaning of life?',
    });

    console.log(response.embeddings);
}

main();

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-001",
        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-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/gemini-embedding-001",
     "content": {"parts":[{"text": "What is the meaning of life?"}]}
    }'

Também é possível gerar incorporações para vários blocos de uma só vez transmitindo-os como uma lista de strings.

Python

from google import genai

client = genai.Client()

result = client.models.embed_content(
        model="gemini-embedding-001",
        contents= [
            "What is the meaning of life?",
            "What is the purpose of existence?",
            "How do I bake a cake?"
        ])

for embedding in result.embeddings:
    print(embedding)

JavaScript

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

async function main() {

    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-001',
        contents: [
            'What is the meaning of life?',
            'What is the purpose of existence?',
            'How do I bake a cake?'
        ],
    });

    console.log(response.embeddings);
}

main();

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.NewContentFromText("How does photosynthesis work?"),
        genai.NewContentFromText("Tell me about the history of the internet."),
    }
    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-001",
        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-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/gemini-embedding-001",
     "content": [
        {"parts": [{"text": "What is the meaning of life?"}]},
        {"parts": [{"text": "What is the purpose of existence?"}]},
        {"parts": [{"text": "How do I bake a cake?"}]}
        ]
    }'

Especificar o tipo de tarefa para melhorar a performance

É possível usar embeddings para várias 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. Para uma lista completa de 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 de significado entre strings de texto.

Python

from google import genai
from google.genai import types
import numpy as np
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 = [
    np.array(e.values) for e in client.models.embed_content(
        model="gemini-embedding-001",
        contents=texts,
        config=types.EmbedContentConfig(task_type="SEMANTIC_SIMILARITY")).embeddings
]

# Calculate cosine similarity. Higher scores = greater semantic similarity.

embeddings_matrix = np.array(result)
similarity_matrix = cosine_similarity(embeddings_matrix)

for i, text1 in enumerate(texts):
    for j in range(i + 1, len(texts)):
        text2 = texts[j]
        similarity = similarity_matrix[i, j]
        print(f"Similarity between '{text1}' and '{text2}': {similarity:.4f}")

JavaScript

import { GoogleGenAI } from "@google/genai";
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,
        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();

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 -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "contents": [
        {"parts": [{"text": "What is the meaning of life?"}]},
        {"parts": [{"text": "What is the purpose of existence?"}]},
        {"parts": [{"text": "How do I bake a cake?"}]}
    ],
    "embedding_config": {
        "task_type": "SEMANTIC_SIMILARITY"
    }
}'

Confira a seguir um exemplo de saída desse snippet de código:

Similarity between 'What is the meaning of life?' and 'What is the purpose of existence?': 0.9481

Similarity between 'What is the meaning of life?' and 'How do I bake a cake?': 0.7471

Similarity between 'What is the purpose of existence?' and 'How do I bake a cake?': 0.7371

Tipos de tarefas com suporte

Tipo de tarefa Descrição Exemplos
SEMANTIC_SIMILARITY Embeddings otimizados para avaliar a semelhança de texto. Sistemas de recomendação, detecção de duplicidade
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. Indexação de 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 resposta 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 contenham evidências que apoiem ou refutem 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

O modelo de incorporação do Gemini, gemini-embedding-001, é treinado usando a técnica de aprendizado de representação de Matryoshka (MRL, na sigla em inglês), que ensina um modelo a aprender incorporações de alta dimensão com 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, sem sacrificar muito a qualidade. Por padrão, ele gera uma incorporação de 3.072 dimensões, mas é possível truncar para um tamanho menor sem perder a qualidade e economizar espaço de armazenamento. Recomendamos usar dimensões de saída de 768, 1536 ou 3072.

Python

from google import genai
from google.genai import types

client = genai.Client()

result = client.models.embed_content(
    model="gemini-embedding-001",
    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-001',
        content: 'What is the meaning of life?',
        outputDimensionality: 768,
    });

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

main();

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-001",
        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-001:embedContent" \
-H "x-goog-api-key: YOUR_GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "contents": [
        {"parts": [{"text": "What is the meaning of life?"}]}
    ],
    "embedding_config": {
        "output_dimensionality": 768
    }
}'

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

Length of embedding: 768

Como garantir a qualidade em dimensões menores

O embedding de 3.072 dimensões é normalizado. Os embeddings normalizados produzem uma similaridade semântica mais precisa ao comparar a direção do vetor, não a magnitude. Para outras dimensões, incluindo 768 e 1536, é necessário normalizar os embeddings da seguinte forma:

Python

import numpy as np
from numpy.linalg import norm

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 deste 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 incorporações, em diferentes dimensões. O resultado mostra que a performance não está estritamente vinculada ao tamanho da dimensão do embedding. Dimensões menores alcançam pontuações comparáveis às dimensões maiores.

Dimensão MRL Pontuação MTEB
2048 68,16
1536 68,17
768 67,99
512 67,55
256 66,19
128 63,31

Casos de uso

As incorporações de texto são cruciais para vários 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 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

Propriedade Descrição
Código do modelo

API Gemini

gemini-embedding-001
Tipos de dados compatíveis

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, compatível com: 128 a 3072. Recomendado: 768, 1536, 3072
Versões do
Leia os padrões de versão do modelo para mais detalhes.
  • Estável: gemini-embedding-001
  • Experimental: gemini-embedding-exp-03-07
Última atualização Junho de 2025

Aviso sobre o uso responsável

Ao contrário dos modelos de IA generativa que criam conteúdo novo, o modelo de incorporação do Gemini destina-se apenas a transformar o formato dos seus dados de entrada em uma representação numérica. Embora o Google seja responsável por fornecer um modelo de incorporação que transforma o formato dos dados de entrada no formato numérico solicitado, os usuários mantêm total responsabilidade pelos dados inseridos e pelas incorporações 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 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.

Começar 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.