Embeddings

Os embeddings são uma representação numérica de entradas de texto que abrem vários casos de uso exclusivos, como clustering, medição de similaridade e recuperação de informações. Para uma introdução, confira o guia de embeddings.

Ao contrário dos modelos de IA generativa que criam conteúdo novo, o modelo de incorporação do Gemini só transforma 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 seus 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.

Método: models.embedContent

Gera um vetor de embedding de texto da entrada Content usando o modelo de embedding do Gemini especificado.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/{model=models/*}:embedContent

Parâmetros de caminho

model string

Obrigatório. O nome do recurso do modelo. Ele serve como um ID para o modelo usar.

Esse nome precisa corresponder a um nome de modelo retornado pelo método models.list.

Formato: models/{model}. Ele tem o formato models/{model}.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Campos
content object (Content)

Obrigatório. O conteúdo a ser incorporado. Somente os campos parts.text serão contados.

taskType enum (TaskType)

Opcional. Tipo de tarefa opcional para que os embeddings serão usados. Não é compatível com modelos anteriores (models/embedding-001).

title string

Opcional. Um título opcional para o texto. Aplicável somente quando TaskType é RETRIEVAL_DOCUMENT.

Observação: especificar um title para RETRIEVAL_DOCUMENT oferece embeddings de melhor qualidade para recuperação.

outputDimensionality integer

Opcional. Dimensão reduzida opcional para a incorporação de saída. Se definido, os valores excessivos no embedding de saída serão truncados do final. Compatível apenas com modelos mais recentes desde 2024. Não é possível definir esse valor se você estiver usando o modelo anterior (models/embedding-001).

Exemplo de solicitação

Python

from google import genai
from google.genai import types

client = genai.Client()
text = "Hello World!"
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=text,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const text = "Hello World!";
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: text,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

text := "Hello World!"
outputDim := int32(10)
contents := []*genai.Content{
	genai.NewContentFromText(text, genai.RoleUser),
}
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", 
	contents, &genai.EmbedContentConfig{
		OutputDimensionality: &outputDim,
})
if err != nil {
	log.Fatal(err)
}

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

Concha

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?"}]}
    }'

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de EmbedContentResponse.

Método: models.batchEmbedContents

Gera vários vetores de embedding da entrada Content, que consiste em um lote de strings representadas como objetos EmbedContentRequest.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/{model=models/*}:batchEmbedContents

Parâmetros de caminho

model string

Obrigatório. O nome do recurso do modelo. Ele serve como um ID para o modelo usar.

Esse nome precisa corresponder a um nome de modelo retornado pelo método models.list.

Formato: models/{model}. Ele tem o formato models/{model}.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Campos
requests[] object (EmbedContentRequest)

Obrigatório. Solicitações de incorporação para o lote. O modelo em cada uma dessas solicitações precisa corresponder ao modelo especificado BatchEmbedContentsRequest.model.

Exemplo de solicitação

Python

from google import genai
from google.genai import types

client = genai.Client()
texts = [
    "What is the meaning of life?",
    "How much wood would a woodchuck chuck?",
    "How does the brain work?",
]
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const texts = [
  "What is the meaning of life?",
  "How much wood would a woodchuck chuck?",
  "How does the brain work?",
];
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: texts,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

contents := []*genai.Content{
	genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
	genai.NewContentFromText("How much wood would a woodchuck chuck?", genai.RoleUser),
	genai.NewContentFromText("How does the brain work?", genai.RoleUser),
}

outputDim := int32(10)
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", contents, &genai.EmbedContentConfig{
	OutputDimensionality: &outputDim,
})
if err != nil {
	log.Fatal(err)
}

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

Concha

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"requests": [{
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "What is the meaning of life?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How much wood would a woodchuck chuck?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How does the brain work?"}]}, }, ]}' 2> /dev/null | grep -C 5 values

Corpo da resposta

A resposta a um BatchEmbedContentsRequest.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Campos
embeddings[] object (ContentEmbedding)

Apenas saída. Os embeddings de cada solicitação, na mesma ordem em que foram fornecidos na solicitação em lote.

Representação JSON
{
  "embeddings": [
    {
      object (ContentEmbedding)
    }
  ]
}

Método: models.asyncBatchEmbedContent

Enfileira um lote de solicitações models.embedContent para processamento em lote. Temos um manipulador models.batchEmbedContents em GenerativeService, mas ele foi sincronizado. Então, vamos chamar esse de Async para evitar confusão.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/{batch.model=models/*}:asyncBatchEmbedContent

Parâmetros de caminho

batch.model string

Obrigatório. O nome do Model a ser usado para gerar a conclusão.

Formato: models/{model}. Ele tem o formato models/{model}.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Campos
batch.name string

Apenas saída. Identificador. Nome do recurso do lote.

Formato: batches/{batchId}.

batch.displayName string

Obrigatório. O nome definido pelo usuário para este lote.

batch.inputConfig object (InputEmbedContentConfig)

Obrigatório. Configuração de entrada das instâncias em que o processamento em lote é realizado.

batch.output object (EmbedContentBatchOutput)

Apenas saída. A saída da solicitação em lote.

batch.createTime string (Timestamp format)

Apenas saída. A hora em que o lote foi criado.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

batch.endTime string (Timestamp format)

Apenas saída. O horário em que o processamento em lote foi concluído.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

batch.updateTime string (Timestamp format)

Apenas saída. A hora em que o lote foi atualizado pela última vez.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

batch.batchStats object (EmbedContentBatchStats)

Apenas saída. Estatísticas sobre o lote.

batch.state enum (BatchState)

Apenas saída. O estado do lote.

batch.priority string (int64 format)

Opcional. A prioridade do lote. Os lotes com um valor de prioridade mais alto serão processados antes dos lotes com um valor de prioridade mais baixo. Valores negativos são permitidos. O padrão é 0.

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de Operation.

EmbedContentRequest

Solicitação que contém o Content para o modelo incorporar.

Campos
model string

Obrigatório. O nome do recurso do modelo. Ele serve como um ID para o modelo usar.

Esse nome precisa corresponder a um nome de modelo retornado pelo método models.list.

Formato: models/{model}

content object (Content)

Obrigatório. O conteúdo a ser incorporado. Somente os campos parts.text serão contados.

taskType enum (TaskType)

Opcional. Tipo de tarefa opcional para que os embeddings serão usados. Não é compatível com modelos anteriores (models/embedding-001).

title string

Opcional. Um título opcional para o texto. Aplicável somente quando TaskType é RETRIEVAL_DOCUMENT.

Observação: especificar um title para RETRIEVAL_DOCUMENT oferece embeddings de melhor qualidade para recuperação.

outputDimensionality integer

Opcional. Dimensão reduzida opcional para a incorporação de saída. Se definido, os valores excessivos no embedding de saída serão truncados do final. Compatível apenas com modelos mais recentes desde 2024. Não é possível definir esse valor se você estiver usando o modelo anterior (models/embedding-001).

Representação JSON
{
  "model": string,
  "content": {
    object (Content)
  },
  "taskType": enum (TaskType),
  "title": string,
  "outputDimensionality": integer
}

EmbedContentResponse

A resposta a um EmbedContentRequest.

Campos
embedding object (ContentEmbedding)

Apenas saída. O embedding gerado com base no conteúdo de entrada.

Representação JSON
{
  "embedding": {
    object (ContentEmbedding)
  }
}

ContentEmbedding

Uma lista de pontos flutuantes que representa uma incorporação.

Campos
values[] number

Os valores de embedding.

Representação JSON
{
  "values": [
    number
  ]
}

TaskType

Tipo de tarefa para que o embedding será usado.

Tipos enumerados
TASK_TYPE_UNSPECIFIED Valor não definido, que será padrão para um dos outros valores de enumeração.
RETRIEVAL_QUERY Especifica que o texto é uma consulta em uma configuração de pesquisa/recuperação.
RETRIEVAL_DOCUMENT Especifica que o texto é um documento do corpus pesquisado.
SEMANTIC_SIMILARITY Especifica que o texto fornecido será usado para STS.
CLASSIFICATION Especifica que o texto fornecido será classificado.
CLUSTERING Especifica que os embeddings serão usados para clustering.
QUESTION_ANSWERING Especifica que o texto fornecido será usado para responder a perguntas.
FACT_VERIFICATION Especifica que o texto fornecido será usado para verificação de fatos.
CODE_RETRIEVAL_QUERY Especifica que o texto fornecido será usado para recuperação de código.

EmbedContentBatch

Um recurso que representa um lote de solicitações EmbedContent.

Campos
model string

Obrigatório. O nome do Model a ser usado para gerar a conclusão.

Formato: models/{model}.

name string

Apenas saída. Identificador. Nome do recurso do lote.

Formato: batches/{batchId}.

displayName string

Obrigatório. O nome definido pelo usuário para este lote.

inputConfig object (InputEmbedContentConfig)

Obrigatório. Configuração de entrada das instâncias em que o processamento em lote é realizado.

output object (EmbedContentBatchOutput)

Apenas saída. A saída da solicitação em lote.

createTime string (Timestamp format)

Apenas saída. A hora em que o lote foi criado.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

endTime string (Timestamp format)

Apenas saída. O horário em que o processamento em lote foi concluído.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

Apenas saída. A hora em que o lote foi atualizado pela última vez.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

batchStats object (EmbedContentBatchStats)

Apenas saída. Estatísticas sobre o lote.

state enum (BatchState)

Apenas saída. O estado do lote.

priority string (int64 format)

Opcional. A prioridade do lote. Os lotes com um valor de prioridade mais alto serão processados antes dos lotes com um valor de prioridade mais baixo. Valores negativos são permitidos. O padrão é 0.

Representação JSON
{
  "model": string,
  "name": string,
  "displayName": string,
  "inputConfig": {
    object (InputEmbedContentConfig)
  },
  "output": {
    object (EmbedContentBatchOutput)
  },
  "createTime": string,
  "endTime": string,
  "updateTime": string,
  "batchStats": {
    object (EmbedContentBatchStats)
  },
  "state": enum (BatchState),
  "priority": string
}

InputEmbedContentConfig

Configura a entrada para a solicitação em lote.

Campos
source Union type
Obrigatório. A origem da entrada. source pode ser apenas de um dos tipos a seguir:
fileName string

O nome do File que contém as solicitações de entrada.

requests object (InlinedEmbedContentRequests)

As solicitações a serem processadas no lote.

Representação JSON
{

  // source
  "fileName": string,
  "requests": {
    object (InlinedEmbedContentRequests)
  }
  // Union type
}

InlinedEmbedContentRequests

As solicitações a serem processadas no lote, se fornecidas como parte da solicitação de criação do lote.

Campos
requests[] object (InlinedEmbedContentRequest)

Obrigatório. As solicitações a serem processadas no lote.

Representação JSON
{
  "requests": [
    {
      object (InlinedEmbedContentRequest)
    }
  ]
}

InlinedEmbedContentRequest

A solicitação a ser processada no lote.

Campos
request object (EmbedContentRequest)

Obrigatório. A solicitação a ser processada no lote.

metadata object (Struct format)

Opcional. Os metadados a serem associados à solicitação.

Representação JSON
{
  "request": {
    object (EmbedContentRequest)
  },
  "metadata": {
    object
  }
}

EmbedContentBatchOutput

A saída de uma solicitação em lote. Isso é retornado no campo AsyncBatchEmbedContentResponse ou EmbedContentBatch.output.

Campos
output Union type
A saída da solicitação em lote. output pode ser apenas de um dos tipos a seguir:
responsesFile string

Apenas saída. O ID do arquivo que contém as respostas. O arquivo será um JSONL com uma única resposta por linha. As respostas serão mensagens EmbedContentResponse formatadas como JSON. As respostas serão escritas na mesma ordem das solicitações de entrada.

inlinedResponses object (InlinedEmbedContentResponses)

Apenas saída. As respostas às solicitações no lote. Retornado quando o lote foi criado usando solicitações inline. As respostas vão estar na mesma ordem das solicitações de entrada.

Representação JSON
{

  // output
  "responsesFile": string,
  "inlinedResponses": {
    object (InlinedEmbedContentResponses)
  }
  // Union type
}

InlinedEmbedContentResponses

As respostas às solicitações no lote.

Campos
inlinedResponses[] object (InlinedEmbedContentResponse)

Apenas saída. As respostas às solicitações no lote.

Representação JSON
{
  "inlinedResponses": [
    {
      object (InlinedEmbedContentResponse)
    }
  ]
}

InlinedEmbedContentResponse

A resposta a uma única solicitação no lote.

Campos
metadata object (Struct format)

Apenas saída. Os metadados associados à solicitação.

output Union type
A saída da solicitação. output pode ser apenas de um dos tipos a seguir:
error object (Status)

Apenas saída. O erro encontrado ao processar a solicitação.

response object (EmbedContentResponse)

Apenas saída. A resposta à solicitação.

Representação JSON
{
  "metadata": {
    object
  },

  // output
  "error": {
    object (Status)
  },
  "response": {
    object (EmbedContentResponse)
  }
  // Union type
}

EmbedContentBatchStats

Estatísticas sobre o lote.

Campos
requestCount string (int64 format)

Apenas saída. O número de solicitações no lote.

successfulRequestCount string (int64 format)

Apenas saída. O número de solicitações processadas com êxito.

failedRequestCount string (int64 format)

Apenas saída. O número de solicitações que não foram processadas.

pendingRequestCount string (int64 format)

Apenas saída. O número de solicitações que ainda estão pendentes de processamento.

Representação JSON
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}