Embeddings

A API Gemini oferece modelos de embedding de texto para gerar embeddings de palavras, frases, sentenças e código. Tarefas de embeddings, como pesquisa semântica, classificação e agrupamento, 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 produtos de IA. As incorporações são fundamentais para melhorar significativamente as saídas do modelo com mais acurácia 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 e reduz os custos da RAG.

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-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 "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -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 trechos de uma 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 "Content-Type: application/json" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -d '{
    "content": {
        "parts": [
        {
            "text": "What is the meaning of life?"
        },
        {
            "text": "How much wood would a woodchuck chuck?"
        },
        {
            "text": "How does the brain work?"
        }
        ]
    },
    "taskType": "SEMANTIC_SIMILARITY"
    }'

Especifique 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 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";
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 "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 o quanto os diferentes trechos de texto são semelhantes entre si quando executados.

Tipos de tarefas com suporte

Tipo de tarefa Descrição Exemplos
SEMANTIC_SIMILARITY Embeddings otimizados para avaliar a similaridade 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, otimizadas para recuperar documentos que contenham evidências a favor ou contra 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 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 truncá-la 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 '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 para 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 do 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 token[*]

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
Leia os padrões de versão do modelo para mais detalhes.
  • Estável: gemini-embedding-001
Última atualização Junho de 2025

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

Embeddings em lote

Se a latência não for um problema, use o modelo de incorporações do Gemini com a API Batch. Isso permite um throughput muito maior com 50% do preço padrão de incorporação. Encontre exemplos de como começar no livro de receitas da API Batch.

Aviso sobre o uso responsável

Ao contrário dos modelos de IA generativa que criam novos conteúdos, o modelo de incorporação do Gemini foi criado apenas para 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.