Embeddings

Gli embedding sono una rappresentazione numerica dell'input di testo che apre una serie di casi d'uso unici, come il clustering, la misurazione della somiglianza e il recupero delle informazioni. Per un'introduzione, consulta la guida agli incorporamenti.

A differenza dei modelli di AI generativa che creano nuovi contenuti, il modello Gemini Embedding ha lo scopo di trasformare il formato dei dati di input in una rappresentazione numerica. Sebbene Google sia responsabile di fornire un modello di incorporamento che trasformi il formato dei dati di input nel formato numerico richiesto, gli utenti mantengono la piena responsabilità dei dati inseriti e degli incorporamenti risultanti. Utilizzando il modello Gemini Embedding, confermi di detenere i diritti necessari relativi a qualsiasi contenuto caricato. Non generare contenuti che violano la proprietà intellettuale o i diritti di privacy altrui. L'utilizzo di questo servizio è soggetto alle nostre Norme relative all'uso vietato e ai Termini di servizio di Google.

Metodo: models.embedContent

Genera un vettore di incorporamento di testo dall'input Content utilizzando il modello Gemini Embedding specificato.

Endpoint

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

Parametri del percorso

model string

Obbligatorio. Il nome della risorsa del modello. che funge da ID da utilizzare per il modello.

Questo nome deve corrispondere a un nome di modello restituito dal metodo models.list.

Formato: models/{model}. Assume la forma models/{model}.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Campi
content object (Content)

Obbligatorio. I contenuti da incorporare. Verranno conteggiati solo i campi parts.text.

taskType enum (TaskType)

(Facoltativo) (Facoltativo) Tipo di attività per cui verranno utilizzati gli incorporamenti. Non supportato sui modelli precedenti (models/embedding-001).

title string

(Facoltativo) Un titolo facoltativo per il testo. Applicabile solo quando TaskType è RETRIEVAL_DOCUMENT.

Nota: specificare un title per RETRIEVAL_DOCUMENT fornisce incorporamenti di qualità migliore per il recupero.

outputDimensionality integer

(Facoltativo) Dimensione ridotta facoltativa per l'incorporamento di output. Se impostato, i valori eccessivi nell'incorporamento dell'output vengono troncati dalla fine. Supportato solo dai modelli più recenti a partire dal 2024. Non puoi impostare questo valore se utilizzi il modello precedente (models/embedding-001).

Esempio di richiesta

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))

Conchiglia

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 della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di EmbedContentResponse.

Metodo: models.batchEmbedContents

Genera più vettori di incorporamento dall'input Content, che consiste in un batch di stringhe rappresentate come oggetti EmbedContentRequest.

Endpoint

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

Parametri del percorso

model string

Obbligatorio. Il nome della risorsa del modello. che funge da ID da utilizzare per il modello.

Questo nome deve corrispondere a un nome di modello restituito dal metodo models.list.

Formato: models/{model}. Assume la forma models/{model}.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Campi
requests[] object (EmbedContentRequest)

Obbligatorio. Incorpora le richieste per il batch. Il modello in ciascuna di queste richieste deve corrispondere al modello specificato BatchEmbedContentsRequest.model.

Esempio di richiesta

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))

Conchiglia

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 della risposta

La risposta a una BatchEmbedContentsRequest.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Campi
embeddings[] object (ContentEmbedding)

Solo output. Gli incorporamenti per ogni richiesta, nello stesso ordine in cui sono stati forniti nella richiesta batch.

Rappresentazione JSON
{
  "embeddings": [
    {
      object (ContentEmbedding)
    }
  ]
}

Metodo: models.asyncBatchEmbedContent

Mette in coda un batch di richieste models.embedContent per l'elaborazione batch. Abbiamo un gestore models.batchEmbedContents in GenerativeService, ma è stato sincronizzato. Quindi, per evitare confusione, lo chiamiamo Async.

Endpoint

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

Parametri del percorso

batch.model string

Obbligatorio. Il nome di Model da utilizzare per generare il completamento.

Formato: models/{model}. Assume la forma models/{model}.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Campi
batch.name string

Solo output. Identificatore. Nome risorsa del batch.

Formato: batches/{batchId}.

batch.displayName string

Obbligatorio. Il nome definito dall'utente di questo batch.

batch.inputConfig object (InputEmbedContentConfig)

Obbligatorio. Configurazione di input delle istanze su cui viene eseguita l'elaborazione batch.

batch.output object (EmbedContentBatchOutput)

Solo output. L'output della richiesta batch.

batch.createTime string (Timestamp format)

Solo output. L'ora in cui è stato creato il batch.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

batch.endTime string (Timestamp format)

Solo output. L'ora in cui è stata completata l'elaborazione batch.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

batch.updateTime string (Timestamp format)

Solo output. L'ora dell'ultimo aggiornamento del batch.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

batch.batchStats object (EmbedContentBatchStats)

Solo output. Statistiche sul batch.

batch.state enum (BatchState)

Solo output. Lo stato del batch.

batch.priority string (int64 format)

(Facoltativo) La priorità del batch. I batch con un valore di priorità più alto vengono elaborati prima di quelli con un valore di priorità più basso. Sono consentiti valori negativi. Il valore predefinito è 0.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di Operation.

EmbedContentRequest

Richiesta contenente Content per il modello da incorporare.

Campi
model string

Obbligatorio. Il nome della risorsa del modello. che funge da ID da utilizzare per il modello.

Questo nome deve corrispondere a un nome di modello restituito dal metodo models.list.

Formato: models/{model}

content object (Content)

Obbligatorio. I contenuti da incorporare. Verranno conteggiati solo i campi parts.text.

taskType enum (TaskType)

(Facoltativo) (Facoltativo) Tipo di attività per cui verranno utilizzati gli incorporamenti. Non supportato sui modelli precedenti (models/embedding-001).

title string

(Facoltativo) Un titolo facoltativo per il testo. Applicabile solo quando TaskType è RETRIEVAL_DOCUMENT.

Nota: specificare un title per RETRIEVAL_DOCUMENT fornisce incorporamenti di qualità migliore per il recupero.

outputDimensionality integer

(Facoltativo) Dimensione ridotta facoltativa per l'incorporamento di output. Se impostato, i valori eccessivi nell'incorporamento dell'output vengono troncati dalla fine. Supportato solo dai modelli più recenti a partire dal 2024. Non puoi impostare questo valore se utilizzi il modello precedente (models/embedding-001).

Rappresentazione JSON
{
  "model": string,
  "content": {
    object (Content)
  },
  "taskType": enum (TaskType),
  "title": string,
  "outputDimensionality": integer
}

EmbedContentResponse

La risposta a un EmbedContentRequest.

Campi
embedding object (ContentEmbedding)

Solo output. L'incorporamento generato dai contenuti di input.

Rappresentazione JSON
{
  "embedding": {
    object (ContentEmbedding)
  }
}

ContentEmbedding

Un elenco di numeri in virgola mobile che rappresentano un embedding.

Campi
values[] number

I valori di incorporamento.

Rappresentazione JSON
{
  "values": [
    number
  ]
}

TaskType

Tipo di attività per cui verrà utilizzato l'incorporamento.

Enum
TASK_TYPE_UNSPECIFIED Valore non impostato, che verrà impostato su uno degli altri valori enum.
RETRIEVAL_QUERY Specifica che il testo indicato è una query in un'impostazione di ricerca/recupero.
RETRIEVAL_DOCUMENT Specifica che il testo indicato è un documento del corpus in cui viene eseguita la ricerca.
SEMANTIC_SIMILARITY Specifica che il testo indicato verrà utilizzato per STS.
CLASSIFICATION Specifica che il testo indicato verrà classificato.
CLUSTERING Specifica che gli embedding verranno utilizzati per il clustering.
QUESTION_ANSWERING Specifica che il testo fornito verrà utilizzato per rispondere alle domande.
FACT_VERIFICATION Specifica che il testo fornito verrà utilizzato per la verifica dei fatti.
CODE_RETRIEVAL_QUERY Specifica che il testo fornito verrà utilizzato per il recupero del codice.

EmbedContentBatch

Una risorsa che rappresenta un batch di richieste EmbedContent.

Campi
model string

Obbligatorio. Il nome di Model da utilizzare per generare il completamento.

Formato: models/{model}.

name string

Solo output. Identificatore. Nome risorsa del batch.

Formato: batches/{batchId}.

displayName string

Obbligatorio. Il nome definito dall'utente di questo batch.

inputConfig object (InputEmbedContentConfig)

Obbligatorio. Configurazione di input delle istanze su cui viene eseguita l'elaborazione batch.

output object (EmbedContentBatchOutput)

Solo output. L'output della richiesta batch.

createTime string (Timestamp format)

Solo output. L'ora in cui è stato creato il batch.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

endTime string (Timestamp format)

Solo output. L'ora in cui è stata completata l'elaborazione batch.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

Solo output. L'ora dell'ultimo aggiornamento del batch.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

batchStats object (EmbedContentBatchStats)

Solo output. Statistiche sul batch.

state enum (BatchState)

Solo output. Lo stato del batch.

priority string (int64 format)

(Facoltativo) La priorità del batch. I batch con un valore di priorità più alto vengono elaborati prima di quelli con un valore di priorità più basso. Sono consentiti valori negativi. Il valore predefinito è 0.

Rappresentazione 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 l'input della richiesta batch.

Campi
source Union type
Obbligatorio. L'origine dell'input. source può essere solo uno dei seguenti:
fileName string

Il nome di File contenente le richieste di input.

requests object (InlinedEmbedContentRequests)

Le richieste da elaborare nel batch.

Rappresentazione JSON
{

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

InlinedEmbedContentRequests

Le richieste da elaborare nel batch, se fornite nell'ambito della richiesta di creazione del batch.

Campi
requests[] object (InlinedEmbedContentRequest)

Obbligatorio. Le richieste da elaborare nel batch.

Rappresentazione JSON
{
  "requests": [
    {
      object (InlinedEmbedContentRequest)
    }
  ]
}

InlinedEmbedContentRequest

La richiesta da elaborare nel batch.

Campi
request object (EmbedContentRequest)

Obbligatorio. La richiesta da elaborare nel batch.

metadata object (Struct format)

(Facoltativo) I metadati da associare alla richiesta.

Rappresentazione JSON
{
  "request": {
    object (EmbedContentRequest)
  },
  "metadata": {
    object
  }
}

EmbedContentBatchOutput

L'output di una richiesta batch. Questo valore viene restituito nel campo AsyncBatchEmbedContentResponse o EmbedContentBatch.output.

Campi
output Union type
L'output della richiesta batch. output può essere solo uno dei seguenti:
responsesFile string

Solo output. L'ID file del file contenente le risposte. Il file sarà un file JSONL con una sola risposta per riga. Le risposte saranno messaggi EmbedContentResponse formattati come JSON. Le risposte verranno scritte nello stesso ordine delle richieste di input.

inlinedResponses object (InlinedEmbedContentResponses)

Solo output. Le risposte alle richieste nel batch. Restituito quando il batch è stato creato utilizzando richieste incorporate. Le risposte saranno nello stesso ordine delle richieste di input.

Rappresentazione JSON
{

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

InlinedEmbedContentResponses

Le risposte alle richieste nel batch.

Campi
inlinedResponses[] object (InlinedEmbedContentResponse)

Solo output. Le risposte alle richieste nel batch.

Rappresentazione JSON
{
  "inlinedResponses": [
    {
      object (InlinedEmbedContentResponse)
    }
  ]
}

InlinedEmbedContentResponse

La risposta a una singola richiesta nel batch.

Campi
metadata object (Struct format)

Solo output. I metadati associati alla richiesta.

output Union type
L'output della richiesta. output può essere solo uno dei seguenti:
error object (Status)

Solo output. L'errore riscontrato durante l'elaborazione della richiesta.

response object (EmbedContentResponse)

Solo output. La risposta alla richiesta.

Rappresentazione JSON
{
  "metadata": {
    object
  },

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

EmbedContentBatchStats

Statistiche sul batch.

Campi
requestCount string (int64 format)

Solo output. Il numero di richieste nel batch.

successfulRequestCount string (int64 format)

Solo output. Il numero di richieste elaborate correttamente.

failedRequestCount string (int64 format)

Solo output. Il numero di richieste che non sono state elaborate.

pendingRequestCount string (int64 format)

Solo output. Il numero di richieste per le quali l'elaborazione è ancora in attesa.

Rappresentazione JSON
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}