Ottenere incorporamenti di testo

Questo documento descrive come creare un text embedding utilizzando l'API Text embeddings di Vertex AI.

L'API Vertex AI Text Embeddings utilizza rappresentazioni vettoriali dense: gemini-embedding-001, ad esempio, utilizza vettori a 3072 dimensioni. I modelli di incorporamento vettoriale 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 gli incorporamenti vettoriali 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 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 di embedding.
• Per scoprire di più sui modelli di text embedding, consulta Text embedding.
• Per informazioni sulle lingue supportate da ciascun modello di incorporamento, consulta Lingue di testo supportate.

Per visualizzare un esempio di recupero di text embedding, esegui il notebook "Getting Started with Text Embeddings + Vertex AI Vector Search" in uno dei seguenti ambienti:

Apri in Colab | Apri in Colab Enterprise | Apri in Vertex AI 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 Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

Limiti dell'API

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

Per saperne di più, consulta Limiti di incorporamento del testo.

Recuperare gli incorporamenti di testo per un frammento di testo

Puoi ottenere incorporamenti di testo per un frammento di testo utilizzando l'API Vertex AI o l'SDK Vertex AI per Python.

Scegli una dimensione di incorporamento

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 incorporamento di output. La selezione di una dimensionalità di output più piccola può consentire di risparmiare spazio di archiviazione e aumentare l'efficienza di calcolo per le applicazioni downstream, sacrificando poco in termini di qualità.

Gli esempi riportati di seguito 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 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_VERTEXAI=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 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_VERTEXAI=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 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_VERTEXAI=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 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_VERTEXAI=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,tranne textembedding-gecko@001. La lunghezza massima del 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 di incorporamento del testo.
• 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, 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 embedding di Google e di testo open source disponibili.

Modelli Google

Puoi ottenere incorporamenti di testo utilizzando i seguenti modelli:

Nome modello	Descrizione	Dimensioni di output	Lunghezza massima della sequenza	Lingue di testo supportate
gemini-embedding-001	Prestazioni all'avanguardia in 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
text-embedding-005	Specializzato in attività in inglese e di programmazione.	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 incorporamento superiore, gemini-embedding-001 è il nostro modello di grandi dimensioni progettato per offrire le massime prestazioni.

Modelli aperti

Puoi ottenere incorporamenti di testo utilizzando i seguenti modelli:

Nome modello	Descrizione	Dimensioni di output	Lunghezza massima della sequenza	Lingue di testo supportate
multilingual-e5-small	Parte della famiglia E5 di modelli di text embedding. La variante Small contiene 12 livelli.	Fino a 384	512 token	Lingue supportate
multilingual-e5-large	Parte della famiglia E5 di modelli di text embedding. 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.

Aggiungere un embedding a un database vettoriale

Dopo aver generato l'embedding, puoi aggiungerlo a un database vettoriale, come Vector Search. Ciò consente il recupero a bassa latenza ed è fondamentale man mano che le dimensioni dei dati aumentano.

Per saperne di più su Vector Search, consulta la panoramica di Vector Search.

Passaggi successivi

• Per saperne di più sui limiti di frequenza, consulta la sezione Limiti di frequenza dell'AI generativa su Vertex AI.
• Per ottenere previsioni batch per gli incorporamenti, consulta Ottenere previsioni batch per gli incorporamenti di testo
  • Per scoprire di più sugli embedding multimodali, consulta Ottenere embedding multimodali.
• Per ottimizzare un embedding, vedi Ottimizzare gli embedding di testo.
• Per saperne 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.