API Text embeddings

Questa guida mostra come utilizzare l'API Text Embeddings per convertire il testo in vettori numerici. Questo documento tratta i seguenti argomenti:

  • Sintassi: chiama l'API utilizzando cURL o l'SDK Python.
  • Richiesta e risposta: scopri di più sui parametri di richiesta e risposta per i modelli di incorporamento di testo.
  • Esempi: visualizza un esempio di codice che mostra come incorporare una stringa di testo.
  • Passaggi successivi: esplora la documentazione correlata.

L'API Text Embeddings converte il testo in vettori numerici chiamati incorporamenti. Queste rappresentazioni vettoriali acquisiscono il significato semantico e il contesto del testo.

Modelli supportati:

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 ulteriori 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. Tieni presente che gemini-embedding-001 supporta un'istanza per richiesta.

Sintassi

curl

PROJECT_ID = PROJECT_ID
REGION = us-central1
MODEL_ID = MODEL_ID

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

Python

PROJECT_ID = PROJECT_ID
REGION = us-central1
MODEL_ID = MODEL_ID

import vertexai
from vertexai.language_models import TextEmbeddingModel

vertexai.init(project=PROJECT_ID, location=REGION)

model = TextEmbeddingModel.from_pretrained(MODEL_ID)
embeddings = model.get_embeddings(...)

Richiesta e risposta

Corpo della richiesta

{
  "instances": [
    {
      "task_type": "RETRIEVAL_DOCUMENT",
      "title": "document title",
      "content": "I would like embeddings for this text!"
    },
  ]
}

Parametri di richiesta

  • instances: obbligatorio. Un elenco di oggetti che contengono il testo da incorporare. Sono supportati i seguenti campi:
    • content (string): il testo per cui generare gli incorporamenti.
    • task_type (string): facoltativo. Specifica l'applicazione downstream prevista per aiutare il modello a produrre incorporamenti di qualità migliore. Se non specifichi un valore, il valore predefinito è RETRIEVAL_QUERY. Per saperne di più sui tipi di attività, consulta Scegliere un tipo di attività di incorporamento.
    • title (string): facoltativo. Un titolo per il contenuto testuale. Questo campo si applica solo quando task_type è RETRIEVAL_DOCUMENT.
  • parameters: (Facoltativo) Un oggetto contenente i seguenti campi:
    • autoTruncate (bool): se true, il testo di input viene troncato se supera la lunghezza massima del modello. Se false, viene restituito un errore per l'input di dimensioni eccessive. Il valore predefinito è true.
    • outputDimensionality (int): la dimensione dell'incorporamento desiderata. Se impostato, gli embedding di output vengono troncati a questa dimensione.

Tipi di attività

La seguente tabella descrive i valori del parametro task_type e i relativi casi d'uso:

task_type Descrizione Caso d'uso
RETRIEVAL_QUERY Il testo di input è una query in un'impostazione di ricerca o recupero. Utilizza per il testo della query quando cerchi una raccolta di documenti. Accoppia con RETRIEVAL_DOCUMENT per i documenti.
RETRIEVAL_DOCUMENT Il testo di input è un documento in un'impostazione di ricerca o recupero. Utilizza per i documenti di una raccolta in cui verrà eseguita la ricerca. Accoppia con RETRIEVAL_QUERY per la query di ricerca.
SEMANTIC_SIMILARITY Il testo di input viene utilizzato per la somiglianza semantica testuale (STS). Confrontare due testi per determinare la somiglianza di significato.
CLASSIFICATION L'incorporamento verrà utilizzato per le attività di classificazione. Addestramento di un modello per classificare il testo in classi predefinite.
CLUSTERING L'incorporamento verrà utilizzato per le attività di clustering. Raggruppamento di testi simili senza etichette predefinite.
QUESTION_ANSWERING Il testo di input è una query per un sistema di risposta alle domande. Trovare le risposte alle domande all'interno di un insieme di documenti. Utilizza RETRIEVAL_DOCUMENT per i documenti.
FACT_VERIFICATION Il testo inserito è un'affermazione da verificare rispetto a un insieme di documenti. Verificare l'accuratezza fattuale di un'affermazione. Utilizza RETRIEVAL_DOCUMENT per i documenti.
CODE_RETRIEVAL_QUERY Il testo di input è una query per recuperare snippet di codice pertinenti (Java e Python). Cercare in una codebase funzioni o snippet pertinenti. Utilizza RETRIEVAL_DOCUMENT per i documenti del codice.
  • Attività di recupero:
    • Query: utilizza task_type=RETRIEVAL_QUERY per il testo di input che è una query di ricerca.
    • Corpus: utilizza task_type=RETRIEVAL_DOCUMENT per il testo di input che fa parte della raccolta di documenti in cui viene eseguita la ricerca.
  • Attività di similarità:
    • Similarità semantica: utilizza task_type=SEMANTIC_SIMILARITY per entrambi i testi di input per valutare la loro somiglianza complessiva di significato.
  • Nota: SEMANTIC_SIMILARITY non è destinato a casi d'uso di recupero come la ricerca di documenti e il recupero di informazioni. Per questi casi d'uso, utilizza RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY, QUESTION_ANSWERING e FACT_VERIFICATION.

Corpo della risposta

{
  "predictions": [
    {
      "embeddings": {
        "statistics": {
          "truncated": boolean,
          "token_count": integer
        },
        "values": [ number ]
      }
    }
  ]
}

Parametri di risposta

  • predictions: un elenco di oggetti, in cui ogni oggetto corrisponde a un'istanza di input della richiesta. Ogni oggetto contiene il seguente campo:
    • embeddings: l'incorporamento generato dal testo di input. Contiene i seguenti campi:
      • values: un elenco di numeri in virgola mobile che rappresenta il vettore di embedding del testo di input.
      • statistics: le statistiche calcolate dal testo di input. Contiene i seguenti campi:
        • truncated (bool): true se il testo di input è stato troncato perché superava il numero massimo di token consentiti dal modello.
        • token_count (int): il numero di token nel testo di input.

Esempio di risposta

{
  "predictions": [
    {
      "embeddings": {
        "values": [
          0.0058424929156899452,
          0.011848051100969315,
          0.032247550785541534,
          -0.031829461455345154,
          -0.055369812995195389,
          ...
        ],
        "statistics": {
          "token_count": 4,
          "truncated": false
        }
      }
    }
  ]
}

Esempi

Incorporare una stringa di testo

Il seguente esempio mostra come ottenere l'incorporamento per una stringa di testo.

REST

Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt di testo. Il seguente esempio invia una richiesta all'endpoint del modello del publisher.

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

  • PROJECT_ID: il tuo ID progetto
  • TEXT: il testo per cui vuoi generare incorporamenti. 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 ulteriori informazioni, vedi 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

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

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

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

$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.

Nell'URL di questo esempio, nota quanto segue:
  • Utilizza il metodo generateContent per richiedere che la risposta venga restituita dopo essere stata generata completamente. Per ridurre la percezione della latenza per un pubblico umano, trasmetti in streaming la risposta mentre viene generata utilizzando il metodo streamGenerateContent.
  • L'ID modello multimodale si trova alla fine dell'URL prima del metodo (ad esempio, gemini-2.0-flash). Questo campione potrebbe supportare anche altri modelli.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 

from __future__ import annotations

from vertexai.language_models import TextEmbeddingInput, TextEmbeddingModel


def embed_text() -> list[list[float]]:
    """Embeds texts with a pre-trained, foundational model.

    Returns:
        A list of lists containing the embedding vectors for each input text
    """

    # A list of texts to be embedded.
    texts = ["banana muffins? ", "banana bread? banana muffins?"]
    # The dimensionality of the output embeddings.
    dimensionality = 3072
    # The task type for embedding. Check the available tasks in the model's documentation.
    task = "RETRIEVAL_DOCUMENT"

    model = TextEmbeddingModel.from_pretrained("gemini-embedding-001")
    kwargs = dict(output_dimensionality=dimensionality) if dimensionality else {}

    embeddings = []
    # gemini-embedding-001 takes one input at a time
    for text in texts:
        text_input = TextEmbeddingInput(text, task)
        embedding = model.get_embeddings([text_input], **kwargs)
        print(embedding)
        # Example response:
        # [[0.006135190837085247, -0.01462465338408947, 0.004978656303137541, ...]]
        embeddings.append(embedding[0].values)

    return embeddings

Go

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Go.

Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

import (
	"context"
	"fmt"
	"io"

	aiplatform "cloud.google.com/go/aiplatform/apiv1"
	"cloud.google.com/go/aiplatform/apiv1/aiplatformpb"

	"google.golang.org/api/option"
	"google.golang.org/protobuf/types/known/structpb"
)

// embedTexts shows how embeddings are set for gemini-embedding-001 model
func embedTexts(w io.Writer, project, location string) error {
	// location := "us-central1"
	ctx := context.Background()

	apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)
	dimensionality := 3072
	model := "gemini-embedding-001"
	texts := []string{"banana muffins? ", "banana bread? banana muffins?"}

	client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	if err != nil {
		return err
	}
	defer client.Close()

	endpoint := fmt.Sprintf("projects/%s/locations/%s/publishers/google/models/%s", project, location, model)
	allEmbeddings := make([][]float32, 0, len(texts))
	// gemini-embedding-001 takes 1 input at a time
	for _, text := range texts {
		instances := make([]*structpb.Value, 1)
		instances[0] = structpb.NewStructValue(&structpb.Struct{
			Fields: map[string]*structpb.Value{
				"content":   structpb.NewStringValue(text),
				"task_type": structpb.NewStringValue("QUESTION_ANSWERING"),
			},
		})

		params := structpb.NewStructValue(&structpb.Struct{
			Fields: map[string]*structpb.Value{
				"outputDimensionality": structpb.NewNumberValue(float64(dimensionality)),
			},
		})

		req := &aiplatformpb.PredictRequest{
			Endpoint:   endpoint,
			Instances:  instances,
			Parameters: params,
		}
		resp, err := client.Predict(ctx, req)
		if err != nil {
			return err
		}

		// Process the prediction for the single text
		// The response will contain one prediction because we sent one instance.
		if len(resp.Predictions) == 0 {
			return fmt.Errorf("no predictions returned for text \"%s\"", text)
		}

		prediction := resp.Predictions[0]
		embeddingValues := prediction.GetStructValue().Fields["embeddings"].GetStructValue().Fields["values"].GetListValue().Values

		currentEmbedding := make([]float32, len(embeddingValues))
		for j, value := range embeddingValues {
			currentEmbedding[j] = float32(value.GetNumberValue())
		}
		allEmbeddings = append(allEmbeddings, currentEmbedding)
	}

	if len(allEmbeddings) > 0 {
		fmt.Fprintf(w, "Dimensionality: %d. Embeddings length: %d", len(allEmbeddings[0]), len(allEmbeddings))
	} else {
		fmt.Fprintln(w, "No texts were processed.")
	}
	return nil
}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Java.

Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

import static java.util.stream.Collectors.toList;

import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictRequest;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.OptionalInt;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class PredictTextEmbeddingsSample {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // Details about text embedding request structure and supported models are available in:
    // https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-text-embeddings
    String endpoint = "us-central1-aiplatform.googleapis.com:443";
    String project = "YOUR_PROJECT_ID";
    String model = "gemini-embedding-001";
    predictTextEmbeddings(
        endpoint,
        project,
        model,
        List.of("banana bread?", "banana muffins?"),
        "QUESTION_ANSWERING",
        OptionalInt.of(3072));
  }

  // Gets text embeddings from a pretrained, foundational model.
  public static List<List<Float>> predictTextEmbeddings(
      String endpoint,
      String project,
      String model,
      List<String> texts,
      String task,
      OptionalInt outputDimensionality)
      throws IOException {
    PredictionServiceSettings settings =
        PredictionServiceSettings.newBuilder().setEndpoint(endpoint).build();
    Matcher matcher = Pattern.compile("^(?<Location>\\w+-\\w+)").matcher(endpoint);
    String location = matcher.matches() ? matcher.group("Location") : "us-central1";
    EndpointName endpointName =
        EndpointName.ofProjectLocationPublisherModelName(project, location, "google", model);

    List<List<Float>> floats = new ArrayList<>();
    // You can use this prediction service client for multiple requests.
    try (PredictionServiceClient client = PredictionServiceClient.create(settings)) {
      // gemini-embedding-001 takes one input at a time.
      for (int i = 0; i < texts.size(); i++) {
        PredictRequest.Builder request = 
            PredictRequest.newBuilder().setEndpoint(endpointName.toString());
        if (outputDimensionality.isPresent()) {
          request.setParameters(
              Value.newBuilder()
                  .setStructValue(
                      Struct.newBuilder()
                          .putFields(
                              "outputDimensionality", valueOf(outputDimensionality.getAsInt()))
                          .build()));
        }
        request.addInstances(
            Value.newBuilder()
                .setStructValue(
                    Struct.newBuilder()
                        .putFields("content", valueOf(texts.get(i)))
                        .putFields("task_type", valueOf(task))
                        .build()));
        PredictResponse response = client.predict(request.build());

        for (Value prediction : response.getPredictionsList()) {
          Value embeddings = prediction.getStructValue().getFieldsOrThrow("embeddings");
          Value values = embeddings.getStructValue().getFieldsOrThrow("values");
          floats.add(
              values.getListValue().getValuesList().stream()
                  .map(Value::getNumberValue)
                  .map(Double::floatValue)
                  .collect(toList()));
        }
      }
      return floats;
    }
  }

  private static Value valueOf(String s) {
    return Value.newBuilder().setStringValue(s).build();
  }

  private static Value valueOf(int n) {
    return Value.newBuilder().setNumberValue(n).build();
  }
}

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Node.js.

Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

async function main(
  project,
  model = 'gemini-embedding-001',
  texts = 'banana bread?;banana muffins?',
  task = 'QUESTION_ANSWERING',
  dimensionality = 0,
  apiEndpoint = 'us-central1-aiplatform.googleapis.com'
) {
  const aiplatform = require('@google-cloud/aiplatform');
  const {PredictionServiceClient} = aiplatform.v1;
  const {helpers} = aiplatform; // helps construct protobuf.Value objects.
  const clientOptions = {apiEndpoint: apiEndpoint};
  const location = 'us-central1';
  const endpoint = `projects/${project}/locations/${location}/publishers/google/models/${model}`;

  async function callPredict() {
    const instances = texts
      .split(';')
      .map(e => helpers.toValue({content: e, task_type: task}));

    const client = new PredictionServiceClient(clientOptions);
    const parameters = helpers.toValue(
      dimensionality > 0 ? {outputDimensionality: parseInt(dimensionality)} : {}
    );
    const allEmbeddings = []
    // gemini-embedding-001 takes one input at a time.
    for (const instance of instances) {
      const request = {endpoint, instances: [instance], parameters};
      const [response] = await client.predict(request);
      const predictions = response.predictions;

      const embeddings = predictions.map(p => {
        const embeddingsProto = p.structValue.fields.embeddings;
        const valuesProto = embeddingsProto.structValue.fields.values;
        return valuesProto.listValue.values.map(v => v.numberValue);
      });

      allEmbeddings.push(embeddings[0])
    }


    console.log('Got embeddings: \n' + JSON.stringify(allEmbeddings));
  }

  callPredict();
}

Lingue di testo supportate

Tutti i modelli di incorporamento di testo supportano il testo in lingua inglese e sono stati valutati in base a questo.

Il modello text-multilingual-embedding-002 supporta anche le seguenti lingue. È stato valutato nelle lingue dell'elenco Lingue valutate.

  • Lingue valutate: Arabic (ar), Bengali (bn), English (en), Spanish (es), German (de), Persian (fa), Finnish (fi), French (fr), Hindi (hi), Indonesian (id), Japanese (ja), Korean (ko), Russian (ru), Swahili (sw), Telugu (te), Thai (th), Yoruba (yo), Chinese (zh)
  • Lingue supportate: Afrikaans, Albanian, Amharic, Arabic, Armenian, Azerbaijani, Basque, Belarusiasn, Bengali, Bulgarian, Burmese, Catalan, Cebuano, Chichewa, Chinese, Corsican, Czech, Danish, Dutch, English, Esperanto, Estonian, Filipino, Finnish, French, Galician, Georgian, German, Greek, Gujarati, Haitian Creole, Hausa, Hawaiian, Hebrew, Hindi, Hmong, Hungarian, Icelandic, Igbo, Indonesian, Irish, Italian, Japanese, Javanese, Kannada, Kazakh, Khmer, Korean, Kurdish, Kyrgyz, Lao, Latin, Latvian, Lithuanian, Luxembourgish, Macedonian, Malagasy, Malay, Malayalam, Maltese, Maori, Marathi, Mongolian, Nepali, Norwegian, Pashto, Persian, Polish, Portuguese, Punjabi, Romanian, Russian, Samoan, Scottish Gaelic, Serbian, Shona, Sindhi, Sinhala, Slovak, Slovenian, Somali, Sotho, Spanish, Sundanese, Swahili, Swedish, Tajik, Tamil, Telugu, Thai, Turkish, Ukrainian, Urdu, Uzbek, Vietnamese, Welsh, West Frisian, Xhosa, Yiddish, Yoruba, Zulu.

Il modello gemini-embedding-001 supporta le seguenti lingue:

Arabic, Bengali, Bulgarian, Chinese (Simplified and Traditional), Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovenian, Spanish, Swahili, Swedish, Thai, Turkish, Ukrainian, Vietnamese, Afrikaans, Amharic, Assamese, Azerbaijani, Belarusian, Bosnian, Catalan, Cebuano, Corsican, Welsh, Dhivehi, Esperanto, Basque, Persian, Filipino (Tagalog), Frisian, Irish, Scots Gaelic, Galician, Gujarati, Hausa, Hawaiian, Hmong, Haitian Creole, Armenian, Igbo, Icelandic, Javanese, Georgian, Kazakh, Khmer, Kannada, Krio, Kurdish, Kyrgyz, Latin, Luxembourgish, Lao, Malagasy, Maori, Macedonian, Malayalam, Mongolian, Meiteilon (Manipuri), Marathi, Malay, Maltese, Myanmar (Burmese), Nepali, Nyanja (Chichewa), Odia (Oriya), Punjabi, Pashto, Sindhi, Sinhala (Sinhalese), Samoan, Shona, Somali, Albanian, Sesotho, Sundanese, Tamil, Telugu, Tajik, Uyghur, Urdu, Uzbek, Xhosa, Yiddish, Yoruba, Zulu.

Versioni modello

Per utilizzare un modello stabile attuale, specifica il numero di versione del modello, ad esempio gemini-embedding-001.

Specificare un modello senza un numero di versione non è consigliato perché è un puntatore legacy a un altro modello e non è stabile.

Per saperne di più, consulta Versioni e ciclo di vita del modello.

Passaggi successivi

Scopri di più sugli incorporamenti di testo: