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 della fornitura di un modello di incorporamento che trasforma 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 del 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)
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: "gemini-embedding-001",
  contents: text,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);
embed.js

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))
embed.go

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

Corpo della risposta

La risposta a un EmbedContentRequest.

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

Campi
embedding object (ContentEmbedding)

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

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

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

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))
embed.go

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
embed.sh

Corpo della risposta

La risposta a un 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)
    }
  ]
}

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 del 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
}

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.