Ottenere text embedding

Questo documento descrive come creare un text embedding utilizzando la Gemini Enterprise Agent Platform Text embeddings API.

L'API Text embeddings di Gemini Enterprise Agent Platform utilizza rappresentazioni di vettori densi: gemini-embedding-001, ad esempio, utilizza vettori a 3072 dimensioni. I modelli di vector embedding densi 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 gli embedding di vettori 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 la stessa lingua.

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 saperne di più sugli embedding, consulta la panoramica delle API Embeddings.
• Per saperne di più sui modelli di text embedding, consulta Text embeddings.
• Per informazioni sulle lingue supportate da ogni modello di embedding, consulta Lingue di testo supportate.

Per vedere un esempio di recupero di text embedding, esegui il notebook "Getting Started with Text Embeddings + Agent Platform 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 Google Cloud account. Se non hai mai utilizzato Google Cloud, crea un account per valutare il rendimento dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per eseguire, testare e implementare i carichi di lavoro.

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.

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.

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, puoi utilizzare al massimo 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 in modo silenzioso. Puoi anche disattivare il troncamento silenzioso impostando autoTruncate su false.

Per ulteriori informazioni, consulta Limiti di text embedding.

Recuperare i text embedding per un frammento di testo

Puoi recuperare i text embedding per un frammento di testo utilizzando l'API Agent Platform o l'SDK Agent Platform per Python.

Scegliere una dimensione di embedding

Per impostazione predefinita, tutti i modelli producono un vettore di embedding a lunghezza intera. Per gemini-embedding-001, questo vettore ha 3072 dimensioni, mentre altri modelli producono vettori a 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 più piccola può consentire di risparmiare spazio di archiviazione e aumentare l'efficienza computazionale per le applicazioni downstream, sacrificando poco in termini di 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 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 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](/resource-manager/docs/creating-managing-projects#identifiers). .
• TEXT: il testo per cui vuoi generare gli embedding per. Limite: cinque testi di massimo 2048 token per testo per tutti i modelli tranne 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 ulteriori informazioni, consulta Limiti di text embedding.
• AUTO_TRUNCATE: se impostato su false, il testo che supera il limite di token causa l'esito negativo 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, e 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 Google e open source disponibili.

Modelli Google

Puoi recuperare i text embedding utilizzando i seguenti modelli:

Nome modello	Descrizione	Dimensioni di output	Lunghezza massima della sequenza	Lingue di testo supportate
gemini-embedding-001	Prestazioni allo stato dell'arte per attività in inglese, multilingue e di codice. Unifica i modelli precedentemente specializzati come text-embedding-005 e text-multilingual-embedding-002 e ottiene prestazioni migliori nei rispettivi domini. Per maggiori dettagli, consulta il nostro report tecnico.	fino a 3072	2048 token	Lingue di testo supportate
text-embedding-005	Specializzato in attività in inglese e di codice.	fino a 768	2048 token	Inglese
text-multilingual-embedding-002	Specializzato in attività multilingue.	fino a 768	2048 token	Lingue di testo supportate

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

Modelli aperti

Puoi recuperare i text embedding utilizzando i seguenti modelli:

Nome modello	Descrizione	Dimensioni di output	Lunghezza massima della sequenza	Lingue di testo supportate
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 model card. Per ulteriori informazioni sui modelli open source, consulta Modelli open source per MaaS

Aggiungere un embedding a un database vettoriale

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

Per saperne 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 batch per gli embedding, consulta Ottenere inferenze di text embedding batch
  • Per saperne di più sugli embedding multimodali, consulta Ottenere embedding multimodali
• Per ottimizzare un embedding, consulta Ottimizzare i text embedding
• Per saperne di più sulla ricerca alla base di text-embedding-005 e text-multilingual-embedding-002, consulta l'articolo di ricerca Gecko: Versatile Text Embeddings Distilled from Large Language Models.