Ottenere text embedding

Questo documento descrive come creare un text embedding utilizzando l'API Text Embeddings di Gemini Enterprise Agent Platform.

L'API di text embedding di Gemini Enterprise Agent Platform utilizza rappresentazioni vettoriali dense: gemini-embedding-001, ad esempio, utilizza vettori a 3072 dimensioni. I modelli di vector embedding denso utilizzano metodi di deep learning simili a quelli utilizzati dai modelli linguistici di grandi dimensioni. A differenza dei vettori sparsi, che tendono a mappare direttamente le parole ai numeri, i vettori densi sono progettati per rappresentare meglio il significato di un testo. Il vantaggio di utilizzare vector embedding densi nell'AI generativa è che, anziché cercare corrispondenze dirette di parole o sintassi, puoi cercare meglio i passaggi che si allineano al significato della query, anche se i passaggi non utilizzano lo stesso linguaggio.

I vettori sono normalizzati, quindi puoi utilizzare la somiglianza del coseno, il prodotto scalare o la distanza euclidea per fornire gli stessi ranking di somiglianza.

• Per scoprire di più sugli embedding, consulta la panoramica delle API di embedding.
• Per scoprire di più sui modelli di text embedding, consulta Text embedding.
• Per informazioni sulle lingue supportate da ciascun modello di embedding, consulta Lingue di testo supportate.

Per vedere un esempio di generazione di text embedding, esegui il notebook "Introduzione ai text embedding + Vector Search" in uno dei seguenti ambienti:

Apri in Colab | Apri in Colab Enterprise | Apri in Agent Platform Workbench | Visualizza su GitHub

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Agent Platform API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Agent Platform API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. Scegli un tipo di attività per il job di embedding.

Limiti dell'API

Per ogni richiesta, hai un limite di 250 testi di input. L'API ha un limite massimo di token di input di 20.000. Gli input che superano questo limite generano un errore 400. Ogni singolo testo di input è ulteriormente limitato a 2048 token; l'eventuale eccesso viene troncato senza avviso. Puoi anche disattivare il troncamento silenzioso impostando autoTruncate su false.

Per saperne di più, consulta Limiti dei text embedding.

Ottieni text embedding per uno snippet di testo

Puoi ottenere i text embedding per uno snippet di testo utilizzando l'API Agent Platform o l'SDK Agent Platform per Python.

Scegli una dimensione di embedding

Per impostazione predefinita, tutti i modelli producono un vettore di embedding di lunghezza intera. Per gemini-embedding-001, questo vettore ha 3072 dimensioni, mentre altri modelli producono vettori di 768 dimensioni. Tuttavia, utilizzando il parametro output_dimensionality, gli utenti possono controllare le dimensioni del vettore di embedding di output. La selezione di una dimensionalità di output inferiore può far risparmiare spazio di archiviazione e aumentare l'efficienza di calcolo per le applicazioni downstream, senza compromettere la qualità.

Gli esempi seguenti utilizzano il modello gemini-embedding-001.

Python

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai
from google.genai.types import EmbedContentConfig

client = genai.Client()
response = client.models.embed_content(
    model="gemini-embedding-001",
    contents=[
        "How do I get a driver's license/learner's permit?",
        "How long is my driver's license valid for?",
        "Driver's knowledge test study guide",
    ],
    config=EmbedContentConfig(
        task_type="RETRIEVAL_DOCUMENT",  # Optional
        output_dimensionality=3072,  # Optional
        title="Driver's License",  # Optional
    ),
)
print(response)
# Example response:
# embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
# statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
# metadata=EmbedContentMetadata(billable_character_count=112)

Go

Scopri come installare o aggiornare l'Go.

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import (
	"context"
	"fmt"
	"io"

	"google.golang.org/genai"
)

// generateEmbedContentWithText shows how to embed content with text.
func generateEmbedContentWithText(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	outputDimensionality := int32(3072)
	config := &genai.EmbedContentConfig{
		TaskType:             "RETRIEVAL_DOCUMENT",  //optional
		Title:                "Driver's License",    //optional
		OutputDimensionality: &outputDimensionality, //optional
	}

	contents := []*genai.Content{
		{
			Parts: []*genai.Part{
				{
					Text: "How do I get a driver's license/learner's permit?",
				},
				{
					Text: "How long is my driver's license valid for?",
				},
				{
					Text: "Driver's knowledge test study guide",
				},
			},
			Role: genai.RoleUser,
		},
	}

	modelName := "gemini-embedding-001"
	resp, err := client.Models.EmbedContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	fmt.Fprintln(w, resp)

	// Example response:
	// embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
	// statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
	// metadata=EmbedContentMetadata(billable_character_count=112)

	return nil
}

Node.js

Installa

npm install @google/genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;

async function generateEmbeddingsForRetrieval(
  projectId = GOOGLE_CLOUD_PROJECT
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
  });

  const prompt = [
    "How do I get a driver's license/learner's permit?",
    "How long is my driver's license valid for?",
    "Driver's knowledge test study guide",
  ];

  const response = await client.models.embedContent({
    model: 'gemini-embedding-001',
    contents: prompt,
    config: {
      taskType: 'RETRIEVAL_DOCUMENT', // Optional
      outputDimensionality: 3072, // Optional
      title: "Driver's License", // Optional
    },
  });

  console.log(response);

  // Example response:
  //  embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
  //  statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
  //  metadata=EmbedContentMetadata(billable_character_count=112)

  return response;
}

Java

Scopri come installare o aggiornare l'Java.

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import com.google.genai.Client;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;
import java.util.List;

public class EmbeddingsDocRetrievalWithTxt {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-embedding-001";
    embedContent(modelId);
  }

  // Shows how to embed content with text.
  public static EmbedContentResponse embedContent(String modelId) {
    // Client Initialization. Once created, it can be reused for multiple requests.
    try (Client client = Client.builder().location("global").vertexAI(true).build()) {

      EmbedContentResponse response =
          client.models.embedContent(
              modelId,
              List.of(
                  "How do I get a driver's license/learner's permit?",
                  "How long is my driver's license valid for?",
                  "Driver's knowledge test study guide"),
              EmbedContentConfig.builder()
                  .taskType("RETRIEVAL_DOCUMENT")
                  .outputDimensionality(3072)
                  .title("Driver's License")
                  .build());

      System.out.println(response);
      // Example response:
      // embeddings=Optional[[ContentEmbedding{values=Optional[[-0.035855383, 0.008127963, ... ]]
      // statistics=Optional[ContentEmbeddingStatistics{truncated=Optional[false],
      // tokenCount=Optional[11.0]}]}]],
      // metadata=Optional[EmbedContentMetadata{billableCharacterCount=Optional[153]}]}
      return response;
    }
  }
}

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

• PROJECT_ID: il tuo ID progetto. .
• TEXT: il testo per cui vuoi generare gli embedding. Limite: cinque testi di massimo 2048 token per testo per tutti i modelli,ad eccezione di textembedding-gecko@001. La lunghezza massima dei token di input per textembedding-gecko@001 è 3072. Per gemini-embedding-001, ogni richiesta può includere un solo testo di input. Per saperne di più, consulta Limiti dei text embedding.
• AUTO_TRUNCATE: se impostato su false, il testo che supera il limite di token causa l'errore della richiesta. Il valore predefinito è true.

Metodo HTTP e URL:

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict

Corpo JSON della richiesta:

{
  "instances": [
    { "content": "TEXT"}
  ],
  "parameters": { 
    "autoTruncate": AUTO_TRUNCATE 
  }
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict"

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente. Tieni presente che values è stato troncato per risparmiare spazio.

Risposta

{
  "predictions": [
    {
      "embeddings": {
        "statistics": {
          "truncated": false,
          "token_count": 6
        },
        "values": [ ... ]
      }
    }
  ]
}

Comando curl di esempio

MODEL_ID="gemini-embedding-001"
PROJECT_ID=PROJECT_ID

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/${MODEL_ID}:predict -d \
$'{
  "instances": [
    { "content": "What is life?"}
  ],
}'

Modelli supportati

Le tabelle seguenti mostrano i modelli di text embedding di Google e open source disponibili.

Modelli Google

Puoi ottenere text embedding utilizzando i seguenti modelli:

Nome modello	Descrizione	Dimensioni di output	Lunghezza massima della sequenza	Lingue supportate per il testo
gemini-embedding-001	Prestazioni allo stato dell'arte per attività in inglese, multilingue e di programmazione. Unifica i modelli precedentemente specializzati come text-embedding-005 e text-multilingual-embedding-002 e ottiene prestazioni migliori nei rispettivi domini. Per maggiori dettagli, leggi il nostro report tecnico.	fino a 3072	2048 token	Lingue di testo supportate
gemini-embedding-2	Ideale per l'incorporamento di stringhe lunghe, inclusi dati multilingue e non strutturati. Supporta una combinazione di testo, immagini, audio, video e file PDF.	fino a 3072	8192 token	Lingue di testo supportate
text-embedding-005	Specializzato in attività di programmazione e in inglese.	fino a 768	2048 token	Inglese
text-multilingual-embedding-002	Specializzato in attività multilingue.	fino a 768	2048 token	Lingue di testo supportate

Per una qualità di embedding superiore, gemini-embedding-001 è il nostro modello di grandi dimensioni progettato per fornire le massime prestazioni.

Modelli aperti

Puoi ottenere text embedding utilizzando i seguenti modelli:

Nome modello	Descrizione	Dimensioni di output	Lunghezza massima della sequenza	Lingue supportate per il testo
multilingual-e5-small	Fa parte della famiglia di modelli di text embedding E5. La variante Small contiene 12 livelli.	Fino a 384	512 token	Lingue supportate
multilingual-e5-large	Fa parte della famiglia di modelli di text embedding E5. La variante Large contiene 24 livelli.	Fino a 1024	512 token	Lingue supportate

Per iniziare, consulta la scheda del modello della famiglia E5. Per saperne di più sui modelli aperti, consulta Modelli aperti per MaaS

Aggiungi un embedding a un database vettoriale

Dopo aver generato l'embedding, puoi aggiungerlo a un database vettoriale, come Vector Search. In questo modo, il recupero avviene con bassa latenza, il che è fondamentale man mano che le dimensioni dei dati aumentano.

Per scoprire di più su Vector Search, consulta Panoramica di Vector Search.

Passaggi successivi

• Per saperne di più sui limiti di frequenza, consulta Quote e limiti di sistema di Agent Platform.
• Per ottenere previsioni in batch per gli embedding, consulta Ottieni inferenze di embedding del testo in batch
  • Per scoprire di più sugli embedding multimodali, consulta Genera embedding multimodali
• Per ottimizzare un embedding, consulta Ottimizza i text embedding
• Per scoprire di più sulla ricerca alla base di text-embedding-005 e text-multilingual-embedding-002, consulta il documento di ricerca Gecko: Versatile Text Embeddings Distilled from Large Language Models.