Incorporamenti di testo

Incorporamenti per il testo (text-embedding-004) è il nome del modello che supporta gli incorporamenti di testo. Gli incorporamenti di testo sono una tecnica NLP che converte i dati testuali in vettori numerici che possono essere elaborati da algoritmi di machine learning, in particolare nei modelli di grandi dimensioni. Queste rappresentazioni vettoriali sono progettate per acquisire il significato semantico e il contesto delle parole che rappresentano.

Sono disponibili diverse versioni per gli incorporamenti. text-embedding-004 è il modello di incorporamento stabile più recente con qualità AI avanzata, mentre text-multilingual-embedding-002 è un modello ottimizzato per un'ampia gamma di lingue diverse dall'inglese.

Per esplorare questo modello nella console, consulta la scheda Incorporamenti per il modello di testo in Model Garden.
Vai a Model Garden

Casi d'uso

Ricerca semantica: gli incorporamenti di testo possono essere utilizzati per rappresentare sia la query dell'utente sia l'universo dei documenti in uno spazio vettoriale ad alta dimensionalità. I documenti più semanticamente simili alla query dell'utente avranno una distanza più breve nello spazio vettoriale e possono essere classificati in una posizione più elevata nei risultati di ricerca.

Classificazione del testo: addestra un modello che mappa gli incorporamenti di testo alle etichette di categoria corrette (ad es. gatto o cane, spam e non spam). Una volta addestrato, il modello può essere utilizzato per classificare nuovi input di testo in una o più categorie in base agli incorporamenti.

Lingue di testo supportate

Tutti i modelli di incorporamento del testo supportano e sono stati valutati sul testo in lingua inglese. I modelli textembedding-gecko-multilingual@001 e text-multilingual-embedding-002 supportano inoltre e sono stati valutati nelle seguenti lingue:

  • 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)
  • /8/9, Afrikaans/9, Afrikaans/9, Afrikaans/9, Afrikaans/1, Afrikaans/1, Afrikaans/1, Afrikaans/Armenian, Afrikaans/1, Afrikaans/Armenian, Afrikaans/Armenian,AlbanianAmharicArabicAzerbaijaniBasqueBelarusiasnBengaliBulgarianBurmeseCatalanCebuanoChichewaChineseCorsicanCzechDanishDutchEnglishEsperantoEstonianFilipinoFinnishFrenchGalicianGeorgianGermanGreekGujaratiHaitian CreoleHausaHawaiianHebrewHindiHmongHungarianIcelandicIgboIndonesianIrishItalianJapaneseJavaneseKannadaKazakhKhmerKoreanKurdishKyrgyzLaoLatinLatvianLithuanianLuxembourgishMacedonianMalagasyMalayMalayalamMalteseMaoriMarathiMongolianNepaliNorwegianPashtoPersianPolishPortuguesePunjabiRomanianRussianSamoanScottish GaelicSerbianShonaSindhiSinhalaSlovakSlovenianSomaliSothoSpanishSundaneseSwahiliSwedishTajikTamilTeluguThaiTurkishUkrainianUrduUzbekVietnameseWelshWest FrisianXhosaYiddishYorubaZulu

Richiesta HTTP

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/textembedding-gecko:predict

Versioni modello

Per utilizzare una versione del modello stabile, specifica il numero di versione del modello, ad esempio text-embedding-004. Ogni versione stabile è disponibile per sei mesi dopo la data di rilascio della versione stabile successiva.

La tabella seguente contiene le versioni dei modelli stabili disponibili:

modello textembedding-gecko Data di uscita Data di interruzione
incorporamento-testo-004 14 maggio 2024 14 maggio 2025
text-embedding-preview-0409 9 aprile 2024 27 giugno 2024
text-multilingual-embedding-002 14 maggio 2024 14 maggio 2025
text-multilingual-embedding-preview-0409 9 aprile 2024 27 giugno 2024
textembedding-gecko@003 12 dicembre 2023 12 dicembre 2024
textembedding-gecko-multilingual@001 2 novembre 2023 12 dicembre 2024
textembedding-gecko@002
(pregresso, ma ancora supportato)		 2 novembre 2023 9 ottobre 2024
textembedding-gecko@001 7 giugno 2023 9 ottobre 2024
multimodalembedding@001 12 febbraio 2024 12 febbraio 2025

Per saperne di più, consulta Versioni dei modelli e ciclo di vita.

Corpo della richiesta

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

L'API Vertex AI PaLM Embedding esegue previsioni online (in tempo reale) per ottenere incorporamenti dal testo di input.

L'API accetta un massimo di 3072 token di input e restituisce incorporamenti vettoriali a 768 dimensioni. Utilizza i seguenti parametri per il modello di incorporamenti di testo textembedding-gecko. Per ulteriori informazioni, consulta la panoramica degli incorporamenti di testo.

Parametro Descrizione Valori accettabili

content

Il testo per cui vuoi generare gli incorporamenti. Testo

task_type

Il parametro "task_type" è definito come l'applicazione downstream prevista per aiutare il modello a produrre incorporamenti di qualità migliore. È una stringa che può assumere uno dei seguenti valori. RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING, QUESTION_ANSWERING, FACT_VERIFICATION.

title

Il titolo dell'incorporamento. Testo

Richiesta di esempio

REST

Per testare un prompt di testo utilizzando l'API Vertex AI, invia una richiesta POST all'endpoint del modello del publisher.

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

  • PROJECT_ID: il tuo ID progetto.
  • TEXT: il testo per cui vuoi generare incorporamenti.

Metodo HTTP e URL: 

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/textembedding-gecko@003:predict

Corpo JSON della richiesta: 

{
  "instances": [
    { "content": "TEXT"}
  ],
}

Per inviare la richiesta, scegli una delle seguenti 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/textembedding-gecko@003: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/textembedding-gecko@003:predict" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla risposta di esempio.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python. 

from typing import List, Optional

from vertexai.language_models import TextEmbeddingInput, TextEmbeddingModel


def embed_text(
    texts: List[str] = ["banana muffins? ", "banana bread? banana muffins?"],
    task: str = "RETRIEVAL_DOCUMENT",
    model_name: str = "text-embedding-004",
    dimensionality: Optional[int] = 256,
) -> List[List[float]]:
    """Embeds texts with a pre-trained, foundational model."""
    model = TextEmbeddingModel.from_pretrained(model_name)
    inputs = [TextEmbeddingInput(text, task) for text in texts]
    kwargs = dict(output_dimensionality=dimensionality) if dimensionality else {}
    embeddings = model.get_embeddings(inputs, **kwargs)
    return [embedding.values for embedding in embeddings]

Node.js

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

Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

async function main(
  project,
  model = 'text-embedding-004',
  texts = 'banana bread?;banana muffins?',
  task = 'QUESTION_ANSWERING',
  outputDimensionality = 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}`;
  const parameters =
    outputDimensionality > 0
      ? helpers.toValue(outputDimensionality)
      : helpers.toValue(256);

  async function callPredict() {
    const instances = texts
      .split(';')
      .map(e => helpers.toValue({content: e, taskType: task}));
    const request = {endpoint, instances, parameters};
    const client = new PredictionServiceClient(clientOptions);
    const [response] = await client.predict(request);
    console.log('Got predict response');
    const predictions = response.predictions;
    for (const prediction of predictions) {
      const embeddings = prediction.structValue.fields.embeddings;
      const values = embeddings.structValue.fields.values.listValue.values;
      console.log('Got prediction: ' + JSON.stringify(values));
    }
  }

  callPredict();
}

Java

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

Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 = "text-embedding-004";
    predictTextEmbeddings(
        endpoint,
        project,
        model,
        List.of("banana bread?", "banana muffins?"),
        "QUESTION_ANSWERING",
        OptionalInt.of(256));
  }

  // 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);

    // You can use this prediction service client for multiple requests.
    try (PredictionServiceClient client = PredictionServiceClient.create(settings)) {
      PredictRequest.Builder request =
          PredictRequest.newBuilder().setEndpoint(endpointName.toString());
      if (outputDimensionality.isPresent()) {
        request.setParameters(
            Value.newBuilder()
                .setStructValue(
                    Struct.newBuilder()
                        .putFields("outputDimensionality", valueOf(outputDimensionality.getAsInt()))
                        .build()));
      }
      for (int i = 0; i < texts.size(); i++) {
        request.addInstances(
            Value.newBuilder()
                .setStructValue(
                    Struct.newBuilder()
                        .putFields("content", valueOf(texts.get(i)))
                        .putFields("taskType", valueOf(task))
                        .build()));
      }
      PredictResponse response = client.predict(request.build());
      List<List<Float>> floats = new ArrayList<>();
      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();
  }
}

Corpo della risposta

{
  "predictions": [
    {
      "embeddings": {
        "statistics": {
          "truncated": boolean,
          "token_count": integer
        },
        "values": [ number ]
      }
    }
  ]
}
Elemento risposta Descrizione
embeddings Il risultato generato dal testo di input.
statistics Le statistiche calcolate dal testo di input.
truncated Indica se il testo di input è stato troncato e più lungo del numero massimo di token consentiti.
tokenCount Numero di token del testo di input.
values Il campo values contiene i vettori di incorporamento corrispondenti alle parole 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
        }
      }
    }
  ]
}