Incorporamenti di testo

Incorporamenti per il testo (textembedding-gecko) è 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 dagli algoritmi di machine learning, in particolare dai modelli di grandi dimensioni. Queste rappresentazioni vettoriali sono progettate per acquisire il significato e il contesto semantico delle parole che rappresentano.

Sono disponibili diverse versioni per gli incorporamenti. textembedding-gecko@003 è il modello di incorporamento stabile più recente con qualità AI migliorata e textembedding-gecko-multilingual@001 è 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 dimensione. I documenti più semanticamente simili alla query dell'utente avranno una distanza più breve nello spazio vettoriale e possono avere un ranking più alto nei risultati di ricerca.

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

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 la versione più recente del modello, specifica con il suffisso @latest, ad esempio textembedding-gecko@latest.

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

La seguente tabella contiene le versioni del modello stabile disponibili:

modello textembedding-gecko Data di uscita Data di interruzione
testoembedding-gecko@003 12 dicembre 2023 Non applicabile
testoembedding-gecko@002 2 novembre 2023 9 ottobre 2024
textembedding-gecko-multilingual@001 2 novembre 2023 Non applicabile
testoembedding-gecko@001 7 giugno 2023 9 ottobre 2024
text-embedding-preview-0409 9 aprile 2024 Da aggiornare a una versione stabile.
text-multilingual-embedding-preview-0409 9 aprile 2024 Da aggiornare a una versione stabile.

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

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 rappresentazioni distribuite di 768 dimensioni di vettori. Utilizza i seguenti parametri per il modello di incorporamenti di testo textembedding-gecko. Per maggiori informazioni, consulta la panoramica sugli incorporamenti di testo.

Parametro Description Valori accettati

content

Il testo per il quale 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 e 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 il quale 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:

arricciatura

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 in formato JSON simile alla risposta di esempio.

Python

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

from typing import List

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 = "textembedding-gecko@003",
) -> 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]
    embeddings = model.get_embeddings(inputs)
    return [embedding.values for embedding in embeddings]

Node.js

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

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

async function main(
  project,
  model = 'textembedding-gecko@003',
  texts = 'banana bread?;banana muffins?',
  task = 'RETRIEVAL_DOCUMENT',
  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 match = apiEndpoint.match(/(?<Location>\w+-\w+)/);
  const location = match ? match.groups.Location : 'us-centra11';
  const endpoint = `projects/${project}/locations/${location}/publishers/google/models/${model}`;

  async function callPredict() {
    const instances = texts
      .split(';')
      .map(e => helpers.toValue({content: e, taskType: task}));
    const request = {endpoint, instances};
    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 di configurazione di Java riportate nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java Vertex AI.

Per eseguire l'autenticazione in Vertex AI, configura le 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.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 = "textembedding-gecko@003";
    predictTextEmbeddings(
        endpoint,
        project,
        model,
        List.of("banana bread?", "banana muffins?"),
        "RETRIEVAL_DOCUMENT");
  }

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

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 era più lungo del numero massimo di token consentiti e se è stato troncato.
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
        }
      }
    }
  ]
}