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
- Endpoint
- Parâmetros de caminho
- Corpo da solicitação
- Corpo da resposta
- Escopos de autorização
- Exemplo de solicitação
Gera um vetor de embedding de texto da entrada Content
usando o modelo de embedding do Gemini especificado.
Endpoint
posthttps: / /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:
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
Node.js
Go
Concha
Corpo da resposta
Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de EmbedContentResponse
.
Método: models.batchEmbedContents
- Endpoint
- Parâmetros de caminho
- Corpo da solicitação
- Corpo da resposta
- Escopos de autorização
- Exemplo de solicitação
Gera vários vetores de embedding da entrada Content
, que consiste em um lote de strings representadas como objetos EmbedContentRequest
.
Endpoint
posthttps: / /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:
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
Node.js
Go
Concha
Corpo da resposta
A resposta a um BatchEmbedContentsRequest
.
Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:
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 ( |
Método: models.asyncBatchEmbedContent
- Endpoint
- Parâmetros de caminho
- Corpo da solicitação
- Corpo da resposta
- Escopos de autorização
- EmbedContentRequest
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
posthttps: / /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:
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.
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
).
EmbedContentResponse
A resposta a um EmbedContentRequest
.
embedding
object (ContentEmbedding
)
Apenas saída. O embedding gerado com base no conteúdo de entrada.
Representação JSON |
---|
{
"embedding": {
object ( |
ContentEmbedding
Uma lista de pontos flutuantes que representa uma incorporação.
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
- Representação JSON
- InputEmbedContentConfig
- InlinedEmbedContentRequests
- InlinedEmbedContentRequest
- EmbedContentBatchOutput
- InlinedEmbedContentResponses
- InlinedEmbedContentResponse
- EmbedContentBatchStats
Um recurso que representa um lote de solicitações EmbedContent
.
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
Configura a entrada para a solicitação em lote.
source
Union type
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
As solicitações a serem processadas no lote, se fornecidas como parte da solicitação de criação do lote.
requests[]
object (InlinedEmbedContentRequest
)
Obrigatório. As solicitações a serem processadas no lote.
Representação JSON |
---|
{
"requests": [
{
object ( |
InlinedEmbedContentRequest
A solicitação a ser processada no lote.
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 ( |
EmbedContentBatchOutput
A saída de uma solicitação em lote. Isso é retornado no campo AsyncBatchEmbedContentResponse
ou EmbedContentBatch.output
.
output
Union type
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
As respostas às solicitações no lote.
inlinedResponses[]
object (InlinedEmbedContentResponse
)
Apenas saída. As respostas às solicitações no lote.
Representação JSON |
---|
{
"inlinedResponses": [
{
object ( |
InlinedEmbedContentResponse
A resposta a uma única solicitação no lote.
metadata
object (Struct
format)
Apenas saída. Os metadados associados à solicitação.
output
Union type
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 ( |
EmbedContentBatchStats
Estatísticas sobre o lote.
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 } |