Embeddings

As embeddings são uma representação numérica da entrada de texto que abrem vários casos de uso exclusivos, como agrupamento, medição de similaridade e recuperação de informações. Para uma introdução, consulte o guia de incorporação.

Método: models.embedContent

Gera um vetor de embedding de texto a partir 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 em 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 o 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, valores excessivos na incorporação de saída serão truncados a partir 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="text-embedding-004",
    contents=text,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)
embed.py

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: "text-embedding-004",
  contents: text,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);
embed.js

Concha

curl "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/text-embedding-004",
    "content": {
    "parts":[{
      "text": "Hello world"}]}, }' 2> /dev/null | head
embed.sh

Corpo da resposta

A resposta a uma EmbedContentRequest.

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

Campos
embedding object (ContentEmbedding)

Apenas saída. A incorporação gerada pelo conteúdo de entrada.

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

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. Insira solicitações para o lote. O modelo em cada uma dessas solicitações precisa corresponder ao BatchEmbedContentsRequest.model especificado.

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="text-embedding-004",
    contents=texts,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)
embed.py

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: "text-embedding-004",
  contents: texts,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);
embed.js

Concha

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

Corpo da resposta

A resposta para uma BatchEmbedContentsRequest.

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

Campos
embeddings[] object (ContentEmbedding)

Apenas saída. As incorporações de cada solicitação, na mesma ordem fornecida na solicitação em lote.

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

EmbedContentRequest

Solicitação que contém o Content para a incorporação do modelo.

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 em 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 o 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, valores excessivos na incorporação de saída serão truncados a partir 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
}

ContentEmbedding

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

Campos
values[] number

Os valores de embedding.

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

TaskType

Tipo de tarefa para a qual o embedding será usado.

Enums
TASK_TYPE_UNSPECIFIED Valor não definido, que vai ser padrão para um dos outros valores de tipo enumerado.
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 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 a verificação de fatos.
CODE_RETRIEVAL_QUERY Especifica que o texto fornecido será usado para recuperar o código.