Ottenere embedding multimodali

Il modello di incorporamenti multimodali genera vettori di 1408 dimensioni* in base all'input fornito, che può includere una combinazione di dati di immagini, testo e video. I vettori di incorporamento possono quindi essere utilizzati per attività successive come la classificazione delle immagini o la moderazione dei contenuti video.

Il vettore di embedding dell'immagine e il vettore di embedding del testo si trovano nello stesso spazio semantico con la stessa dimensione. Di conseguenza, questi vettori possono essere utilizzati in modo intercambiabile per casi d'uso come la ricerca di immagini per testo o di video per immagine.

Per i casi d'uso di embedding di solo testo, consigliamo di utilizzare l'API Text Embeddings di Vertex AI. Ad esempio, l'API di embedding di testo potrebbe essere migliore per la ricerca semantica basata sul testo, il clustering, l'analisi di documenti nel formato lungo e altri casi d'uso di recupero di testo o risposta a domande. Per ulteriori informazioni, consulta la sezione Ottenere gli embedding di testo.

Modelli supportati

Puoi ottenere embedding multimodali utilizzando il seguente modello:

  • multimodalembedding

Best practice

Quando utilizzi il modello di embedding multimodale, prendi in considerazione i seguenti aspetti relativi all'input:

  • Testo nelle immagini: il modello può distinguere il testo nelle immagini, in modo simile al riconoscimento ottico dei caratteri (OCR). Se devi distinguere tra una descrizione dei contenuti dell'immagine e il testo all'interno di un'immagine, valuta la possibilità di utilizzare la progettazione di prompt per specificare i contenuti target. Ad esempio, anziché solo "gatto", specifica "immagine di un gatto" o "il testo "gatto"", a seconda del caso d'uso.




    Il testo "gatto"
    immagine di testo con la parola gatto




    immagine di un gatto
    immagine di un gatto
    Credito immagine: Manja Vitolic su Unsplash.
  • Somiglianze di embedding: il prodotto scalare degli embedding non è una probabilità calibrata. Il prodotto scalare è una metrica di somiglianza e potrebbe avere distribuzioni dei punteggi diverse per casi d'uso diversi. Di conseguenza, evita di utilizzare una soglia di valore fisso per misurare la qualità. Utilizza invece approcci di ranking per il recupero o la funzione sigmoide per la classificazione.

Utilizzo delle API

Limiti dell'API

Quando utilizzi il modello multimodalembedding per gli embedding di testo e immagini, si applicano i seguenti limiti:

Limite Valore e descrizione
Dati di testo e immagini
Numero massimo di richieste API al minuto per progetto 120
Lunghezza massima del testo 32 token (~32 parole)

La lunghezza massima del testo è di 32 token (circa 32 parole). Se l'input supera i 32 token, il modello lo accorcia internamente a questa lunghezza.
Lingua Inglese
Formati delle immagini BMP, GIF, JPG, PNG
Dimensioni dell'immagine Immagini con codifica base64: 20 MB (se transcodificate in PNG)
Immagini archiviate in Cloud Storage: 20 MB (formato file originale)

La dimensione massima accettata per le immagini è 20 MB. Per evitare un aumento della latenza della rete, utilizza immagini più piccole. Inoltre, il modello ridimensiona le immagini in modo che abbiano una risoluzione di 512 x 512 pixel. Di conseguenza, non è necessario fornire immagini con una risoluzione più elevata.
Dati video
Audio supportato N/A: il modello non prende in considerazione i contenuti audio durante la generazione di embedding video
Formati video AVI, FLV, MKV, MOV, MP4, MPEG, MPG, WEBM e WMV
Durata massima del video (Cloud Storage) Nessun limite. Tuttavia, è possibile analizzare solo 2 minuti di contenuti alla volta.

Prima di iniziare

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

    8.

  8. Configura l'autenticazione per il tuo ambiente.

    Select the tab for how you plan to use the samples on this page:

    Java

    Per utilizzare gli Java esempi in questa pagina in un ambiente di sviluppo locale, installa e inizializza l'interfaccia alla gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. Update and install gcloud components:

      gcloud components update
      gcloud components install beta

    4. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud.

    Node.js

    Per utilizzare gli Node.js esempi in questa pagina in un ambiente di sviluppo locale, installa e inizializza l'interfaccia alla gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. Update and install gcloud components:

      gcloud components update
      gcloud components install beta

    4. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud.

    Python

    Per utilizzare gli Python esempi in questa pagina in un ambiente di sviluppo locale, installa e inizializza l'interfaccia alla gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. Update and install gcloud components:

      gcloud components update
      gcloud components install beta

    4. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud.

    REST

    Per utilizzare gli esempi dell'API REST in questa pagina in un ambiente di sviluppo locale, utilizza le credenziali fornite a gcloud CLI.

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. Update and install gcloud components:

      gcloud components update
      gcloud components install beta

    Per saperne di più, consulta Eseguire l'autenticazione per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud.

  9. Per utilizzare l'SDK Python, segui le istruzioni riportate in Installare l'SDK Vertex AI per Python. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Vertex AI SDK for Python.
  10. Facoltativo. Esamina i prezzi di questa funzionalità. I prezzi degli incorporamenti dipendono dal tipo di dati inviati (ad es. immagini o testo) e dalla modalità utilizzata per determinati tipi di dati (ad es. Video Plus, Video Standard o Video Essential).

Località

Una località è una regione che puoi specificare in una richiesta per controllare dove vengono archiviati i dati at-rest. Per un elenco delle regioni disponibili, consulta Località dell'IA generativa su Vertex AI.

Messaggi di errore

Errore di superamento della quota

google.api_core.exceptions.ResourceExhausted: 429 Quota exceeded for
aiplatform.googleapis.com/online_prediction_requests_per_base_model with base
model: multimodalembedding. Please submit a quota increase request.

Se è la prima volta che ricevi questo errore, utilizza la console Google Cloud per richiedere un aumento della quota per il tuo progetto. Utilizza i seguenti filtri prima di richiedere l'aumento:

  • Service ID: aiplatform.googleapis.com
  • metric: aiplatform.googleapis.com/online_prediction_requests_per_base_model
  • base_model:multimodalembedding

Vai a Quote

Se hai già inviato una richiesta di aumento della quota, attendi prima di inviarne un'altra. Se devi aumentare ulteriormente la quota, ripeti la richiesta di aumento della quota con la giustificazione per una richiesta di quota sostenuta.

Specifica gli embedding di dimensioni inferiori

Per impostazione predefinita, una richiesta di incorporamento restituisce un vettore di tipo float di 1408 per un tipo di dati. Puoi anche specificare incorporamenti di dimensioni inferiori (vettori di tipo float da 128, 256 o 512) per i dati di testo e immagine. Questa opzione ti consente di eseguire l'ottimizzazione in base alla latenza e allo spazio di archiviazione o alla qualità in base a come prevedi di utilizzare gli embedding. Gli embedding di dimensioni inferiori offrono una riduzione delle esigenze di archiviazione e una latenza inferiore per le attività di embedding successive (come ricerca o consigli), mentre gli embedding di dimensioni superiori offrono una maggiore accuratezza per le stesse attività.

REST

Puoi accedere alle dimensioni di livello inferiore aggiungendo il campo parameters.dimension. Il parametro accetta uno dei seguenti valori: 128, 256, 512 o 1408. La risposta include l'embedding di questa dimensione.

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

  • LOCATION: la regione del progetto. Ad esempio, us-central1, europe-west2 o asia-northeast3. Per un elenco delle regioni disponibili, consulta Località dell'IA generativa su Vertex AI.
  • PROJECT_ID: il tuo ID progetto Google Cloud.
  • IMAGE_URI: l'URI Cloud Storage dell'immagine di destinazione per cui ottenere gli embedding. Ad esempio, gs://my-bucket/embeddings/supermarket-img.png.

    Puoi anche fornire l'immagine come una stringa di byte con codifica base64:

    [...]
"image": {
  "bytesBase64Encoded": "B64_ENCODED_IMAGE"
}
[...]
  • TEXT: il testo target per cui ottenere gli embedding. Ad esempio, a cat.
  • EMBEDDING_DIMENSION: il numero di dimensioni di incorporamento. I valori più bassi consentono di ridurre la latenza quando si utilizzano questi embedding per le attività successive, mentre i valori più elevati offrono una maggiore precisione. Valori disponibili: 128, 256, 512 e 1408 (predefinito).

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict

Corpo JSON della richiesta: 

{
  "instances": [
    {
      "image": {
        "gcsUri": "IMAGE_URI"
      },
      "text": "TEXT"
    }
  ],
  "parameters": {
    "dimension": EMBEDDING_DIMENSION
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict"

PowerShell

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict" | Select-Object -Expand Content
L'embedding del modello restituisce un vettore di tipo float della dimensione specificata. Le seguenti risposte di esempio sono abbreviate per motivi di spazio.

128 dimensioni:

{
  "predictions": [
    {
      "imageEmbedding": [
        0.0279239565,
        [...128 dimension vector...]
        0.00403284049
      ],
      "textEmbedding": [
        0.202921599,
        [...128 dimension vector...]
        -0.0365431122
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

256 dimensioni:

{
  "predictions": [
    {
      "imageEmbedding": [
        0.248620048,
        [...256 dimension vector...]
        -0.0646447465
      ],
      "textEmbedding": [
        0.0757875815,
        [...256 dimension vector...]
        -0.02749932
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Dimensioni 512:

{
  "predictions": [
    {
      "imageEmbedding": [
        -0.0523675755,
        [...512 dimension vector...]
        -0.0444030389
      ],
      "textEmbedding": [
        -0.0592851527,
        [...512 dimension vector...]
        0.0350437127
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python 

import vertexai

from vertexai.vision_models import Image, MultiModalEmbeddingModel

# TODO(developer): Update & uncomment line below
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

# TODO(developer): Try different dimenions: 128, 256, 512, 1408
embedding_dimension = 128

model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding@001")
image = Image.load_from_file(
    "gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png"
)

embeddings = model.get_embeddings(
    image=image,
    contextual_text="Colosseum",
    dimension=embedding_dimension,
)

print(f"Image Embedding: {embeddings.image_embedding}")
print(f"Text Embedding: {embeddings.text_embedding}")

# Example response:
# Image Embedding: [0.0622573346, -0.0406507477, 0.0260440577, ...]
# Text Embedding: [0.27469793, -0.146258667, 0.0222803634, ...]

Inviare una richiesta di incorporamento (immagine e testo)

Utilizza i seguenti esempi di codice per inviare una richiesta di incorporamento con dati di immagini e testo. Gli esempi mostrano come inviare una richiesta con entrambi i tipi di dati, ma puoi anche utilizzare il servizio con un singolo tipo di dati.

Ottenere gli embedding di testo e immagini

REST

Per ulteriori informazioni sulle richieste del modello multimodalembedding, consulta la documentazione di riferimento dell'API del modello multimodalembedding.

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

  • LOCATION: la regione del progetto. Ad esempio, us-central1, europe-west2 o asia-northeast3. Per un elenco delle regioni disponibili, consulta Località dell'IA generativa su Vertex AI.
  • PROJECT_ID: il tuo ID progetto Google Cloud.
  • TEXT: il testo target per cui ottenere gli embedding. Ad esempio, a cat.
  • B64_ENCODED_IMG: l'immagine di destinazione per cui ottenere gli embedding. L'immagine deve essere specificata come stringa di byte codificata in base64.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict

Corpo JSON della richiesta: 

{
  "instances": [
    {
      "text": "TEXT",
      "image": {
        "bytesBase64Encoded": "B64_ENCODED_IMG"
      }
    }
  ]
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict"

PowerShell

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict" | Select-Object -Expand Content
L'embedding restituito dal modello è un vettore di numeri in virgola mobile di 1408 elementi. La seguente risposta di esempio è abbreviata per motivi di spazio. 
{
  "predictions": [
    {
      "textEmbedding": [
        0.010477379,
        -0.00399621,
        0.00576670747,
        [...]
        -0.00823613815,
        -0.0169572588,
        -0.00472954148
      ],
      "imageEmbedding": [
        0.00262696808,
        -0.00198890246,
        0.0152047109,
        -0.0103145819,
        [...]
        0.0324628279,
        0.0284924973,
        0.011650892,
        -0.00452344026
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

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. 

import vertexai
from vertexai.vision_models import Image, MultiModalEmbeddingModel

# TODO(developer): Update & uncomment line below
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding@001")
image = Image.load_from_file(
    "gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png"
)

embeddings = model.get_embeddings(
    image=image,
    contextual_text="Colosseum",
    dimension=1408,
)
print(f"Image Embedding: {embeddings.image_embedding}")
print(f"Text Embedding: {embeddings.text_embedding}")
# Example response:
# Image Embedding: [-0.0123147098, 0.0727171078, ...]
# Text Embedding: [0.00230263756, 0.0278981831, ...]

Node.js

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

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

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
// const bastImagePath = "YOUR_BASED_IMAGE_PATH"
// const textPrompt = 'YOUR_TEXT_PROMPT';
const aiplatform = require('@google-cloud/aiplatform');

// Imports the Google Cloud Prediction service client
const {PredictionServiceClient} = aiplatform.v1;

// Import the helper module for converting arbitrary protobuf.Value objects.
const {helpers} = aiplatform;

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};
const publisher = 'google';
const model = 'multimodalembedding@001';

// Instantiates a client
const predictionServiceClient = new PredictionServiceClient(clientOptions);

async function predictImageFromImageAndText() {
  // Configure the parent resource
  const endpoint = `projects/${project}/locations/${location}/publishers/${publisher}/models/${model}`;

  const fs = require('fs');
  const imageFile = fs.readFileSync(baseImagePath);

  // Convert the image data to a Buffer and base64 encode it.
  const encodedImage = Buffer.from(imageFile).toString('base64');

  const prompt = {
    text: textPrompt,
    image: {
      bytesBase64Encoded: encodedImage,
    },
  };
  const instanceValue = helpers.toValue(prompt);
  const instances = [instanceValue];

  const parameter = {
    sampleCount: 1,
  };
  const parameters = helpers.toValue(parameter);

  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);
  console.log('Get image embedding response');
  const predictions = response.predictions;
  console.log('\tPredictions :');
  for (const prediction of predictions) {
    console.log(`\t\tPrediction : ${JSON.stringify(prediction)}`);
  }
}

await predictImageFromImageAndText();

Java

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

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


import com.google.cloud.aiplatform.v1beta1.EndpointName;
import com.google.cloud.aiplatform.v1beta1.PredictResponse;
import com.google.cloud.aiplatform.v1beta1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1beta1.PredictionServiceSettings;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import com.google.protobuf.InvalidProtocolBufferException;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.Base64;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class PredictImageFromImageAndTextSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace this variable before running the sample.
    String project = "YOUR_PROJECT_ID";
    String textPrompt = "YOUR_TEXT_PROMPT";
    String baseImagePath = "YOUR_BASE_IMAGE_PATH";

    // Learn how to use text prompts to update an image:
    // https://cloud.google.com/vertex-ai/docs/generative-ai/image/edit-images
    Map<String, Object> parameters = new HashMap<String, Object>();
    parameters.put("sampleCount", 1);

    String location = "us-central1";
    String publisher = "google";
    String model = "multimodalembedding@001";

    predictImageFromImageAndText(
        project, location, publisher, model, textPrompt, baseImagePath, parameters);
  }

  // Update images using text prompts
  public static void predictImageFromImageAndText(
      String project,
      String location,
      String publisher,
      String model,
      String textPrompt,
      String baseImagePath,
      Map<String, Object> parameters)
      throws IOException {
    final String endpoint = String.format("%s-aiplatform.googleapis.com:443", location);
    final PredictionServiceSettings predictionServiceSettings =
        PredictionServiceSettings.newBuilder().setEndpoint(endpoint).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (PredictionServiceClient predictionServiceClient =
        PredictionServiceClient.create(predictionServiceSettings)) {
      final EndpointName endpointName =
          EndpointName.ofProjectLocationPublisherModelName(project, location, publisher, model);

      // Convert the image to Base64
      byte[] imageData = Base64.getEncoder().encode(Files.readAllBytes(Paths.get(baseImagePath)));
      String encodedImage = new String(imageData, StandardCharsets.UTF_8);

      JsonObject jsonInstance = new JsonObject();
      jsonInstance.addProperty("text", textPrompt);
      JsonObject jsonImage = new JsonObject();
      jsonImage.addProperty("bytesBase64Encoded", encodedImage);
      jsonInstance.add("image", jsonImage);

      Value instanceValue = stringToValue(jsonInstance.toString());
      List<Value> instances = new ArrayList<>();
      instances.add(instanceValue);

      Gson gson = new Gson();
      String gsonString = gson.toJson(parameters);
      Value parameterValue = stringToValue(gsonString);

      PredictResponse predictResponse =
          predictionServiceClient.predict(endpointName, instances, parameterValue);
      System.out.println("Predict Response");
      System.out.println(predictResponse);
      for (Value prediction : predictResponse.getPredictionsList()) {
        System.out.format("\tPrediction: %s\n", prediction);
      }
    }
  }

  // Convert a Json string to a protobuf.Value
  static Value stringToValue(String value) throws InvalidProtocolBufferException {
    Value.Builder builder = Value.newBuilder();
    JsonFormat.parser().merge(value, builder);
    return builder.build();
  }
}

Inviare una richiesta di incorporamento (video, immagine o testo)

Quando invii una richiesta di incorporamento, puoi specificare solo un video di input o una combinazione di dati video, immagine e testo.

Modalità di incorporamento dei video

Esistono tre modalità che puoi utilizzare con gli incorporamenti video: Di base, Standard o Plus. La modalità corrisponde alla densità degli embedding generati, che può essere specificata dalla configurazione interval_sec nella richiesta. Per ogni intervallo di video con una durata di interval_sec viene generato un embedding. La durata minima dell'intervallo tra i video è di 4 secondi. La durata degli intervalli superiore a 120 secondi potrebbe influire negativamente sulla qualità degli embedding generati.

I prezzi per l'inserimento di video dipendono dalla modalità utilizzata. Per ulteriori informazioni, consulta la sezione Prezzi.

La seguente tabella riassume le tre modalità che puoi utilizzare per gli incorporamenti video:

Modalità Numero massimo di incorporamenti al minuto Intervallo di incorporamento video (valore minimo)
Essential 4 15

Corrisponde a: intervalSec >= 15
Standard 8 8

Questo corrisponde a: 8 <= intervalSec < 15
Plus 15 4

Questo corrisponde a: 4 <= intervalSec < 8

Best practice per l'incorporamento dei video

Tieni presente quanto segue quando invii richieste di incorporamento di video:

  • Per generare un singolo embedding per i primi due minuti di un video di input di qualsiasi durata, utilizza la seguente impostazione videoSegmentConfig:

    request.json:

    // other request body content
"videoSegmentConfig": {
  "intervalSec": 120
}
// other request body content

  • Per generare l'embedding di un video di durata superiore a due minuti, puoi inviare più richieste che specificano le ore di inizio e di fine nel videoSegmentConfig:

    request1.json:

    // other request body content
"videoSegmentConfig": {
  "startOffsetSec": 0,
  "endOffsetSec": 120
}
// other request body content

    request2.json:

    // other request body content
"videoSegmentConfig": {
  "startOffsetSec": 120,
  "endOffsetSec": 240
}
// other request body content

Ottenere gli incorporamenti dei video

Utilizza il seguente esempio per ottenere gli embedding solo per i contenuti video.

REST

Per ulteriori informazioni sulle richieste del modello multimodalembedding, consulta la documentazione di riferimento dell'API del modello multimodalembedding.

L'esempio seguente utilizza un video in Cloud Storage. Puoi anche utilizzare il campo video.bytesBase64Encoded per fornire una rappresentazione in stringa codificata in Base64 del video.

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

  • LOCATION: la regione del progetto. Ad esempio, us-central1, europe-west2 o asia-northeast3. Per un elenco delle regioni disponibili, consulta Località dell'IA generativa su Vertex AI.
  • PROJECT_ID: il tuo ID progetto Google Cloud.
  • VIDEO_URI: l'URI Cloud Storage del video di destinazione per cui ottenere gli embedding. Ad esempio, gs://my-bucket/embeddings/supermarket-video.mp4.

    Puoi anche fornire il video come stringa di byte codificata in base64:

    [...]
"video": {
  "bytesBase64Encoded": "B64_ENCODED_VIDEO"
}
[...]
  • videoSegmentConfig (START_SECOND, END_SECOND, INTERVAL_SECONDS). Facoltativo. I segmenti video specifici (in secondi) per i quali vengono generati gli incorporamenti.

    Ad esempio:

    [...]
"videoSegmentConfig": {
  "startOffsetSec": 10,
  "endOffsetSec": 60,
  "intervalSec": 10
}
[...]

    Questa configurazione specifica i dati video da 10 a 60 secondi e genera embedding per i seguenti intervalli di video di 10 secondi: [10, 20), [20, 30), [30, 40), [40, 50), [50, 60). Questo intervallo di video ("intervalSec": 10) rientra nella modalità di incorporamento video standard e all'utente viene applicata la tariffa della modalità standard.

    Se ometti videoSegmentConfig, il servizio utilizza i seguenti valori predefiniti: "videoSegmentConfig": { "startOffsetSec": 0, "endOffsetSec": 120, "intervalSec": 16 }. Questo intervallo di video ("intervalSec": 16) rientra nella modalità di incorporamento video di base e all'utente viene applicata la tariffa di base.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict

Corpo JSON della richiesta: 

{
  "instances": [
    {
      "video": {
        "gcsUri": "VIDEO_URI",
        "videoSegmentConfig": {
          "startOffsetSec": START_SECOND,
          "endOffsetSec": END_SECOND,
          "intervalSec": INTERVAL_SECONDS
        }
      }
    }
  ]
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict"

PowerShell

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict" | Select-Object -Expand Content
L'embedding restituito dal modello è un vettore di numeri in virgola mobile di 1408 elementi. Le seguenti risposte di esempio sono abbreviate per motivi di spazio.

Risposta (video di 7 secondi, nessun videoSegmentConfig specificato):

{
  "predictions": [
    {
      "videoEmbeddings": [
        {
          "endOffsetSec": 7,
          "embedding": [
            -0.0045467657,
            0.0258095954,
            0.0146885719,
            0.00945400633,
            [...]
            -0.0023291884,
            -0.00493789,
            0.00975185353,
            0.0168156829
          ],
          "startOffsetSec": 0
        }
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Risposta (video di 59 secondi con la seguente configurazione del segmento video: "videoSegmentConfig": { "startOffsetSec": 0, "endOffsetSec": 60, "intervalSec": 10 }):

{
  "predictions": [
    {
      "videoEmbeddings": [
        {
          "endOffsetSec": 10,
          "startOffsetSec": 0,
          "embedding": [
            -0.00683252793,
            0.0390476175,
            [...]
            0.00657121744,
            0.013023301
          ]
        },
        {
          "startOffsetSec": 10,
          "endOffsetSec": 20,
          "embedding": [
            -0.0104404651,
            0.0357737206,
            [...]
            0.00509833824,
            0.0131902946
          ]
        },
        {
          "startOffsetSec": 20,
          "embedding": [
            -0.0113538112,
            0.0305239167,
            [...]
            -0.00195809244,
            0.00941874553
          ],
          "endOffsetSec": 30
        },
        {
          "embedding": [
            -0.00299320649,
            0.0322436653,
            [...]
            -0.00993082579,
            0.00968887936
          ],
          "startOffsetSec": 30,
          "endOffsetSec": 40
        },
        {
          "endOffsetSec": 50,
          "startOffsetSec": 40,
          "embedding": [
            -0.00591270532,
            0.0368893594,
            [...]
            -0.00219071587,
            0.0042470959
          ]
        },
        {
          "embedding": [
            -0.00458270218,
            0.0368121453,
            [...]
            -0.00317760976,
            0.00595594104
          ],
          "endOffsetSec": 59,
          "startOffsetSec": 50
        }
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

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. 

import vertexai

from vertexai.vision_models import MultiModalEmbeddingModel, Video
from vertexai.vision_models import VideoSegmentConfig

# TODO(developer): Update & uncomment line below
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding@001")

embeddings = model.get_embeddings(
    video=Video.load_from_file(
        "gs://cloud-samples-data/vertex-ai-vision/highway_vehicles.mp4"
    ),
    video_segment_config=VideoSegmentConfig(end_offset_sec=1),
)

# Video Embeddings are segmented based on the video_segment_config.
print("Video Embeddings:")
for video_embedding in embeddings.video_embeddings:
    print(
        f"Video Segment: {video_embedding.start_offset_sec} - {video_embedding.end_offset_sec}"
    )
    print(f"Embedding: {video_embedding.embedding}")

# Example response:
# Video Embeddings:
# Video Segment: 0.0 - 1.0
# Embedding: [-0.0206376351, 0.0123456789, ...]

Ottenere incorporamenti di immagini, testo e video

Utilizza il seguente esempio per ottenere embedding per contenuti video, di testo e immagine.

REST

Per ulteriori informazioni sulle richieste del modello multimodalembedding, consulta la documentazione di riferimento dell'API del modello multimodalembedding.

L'esempio seguente utilizza dati di immagini, testo e video. Puoi utilizzare qualsiasi combinazione di questi tipi di dati nel corpo della richiesta.

Inoltre, questo esempio utilizza un video archiviato in Cloud Storage. Puoi anche utilizzare il campo video.bytesBase64Encoded per fornire una rappresentazione in stringa codificata in Base64 del video.

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

  • LOCATION: la regione del progetto. Ad esempio, us-central1, europe-west2 o asia-northeast3. Per un elenco delle regioni disponibili, consulta Località dell'IA generativa su Vertex AI.
  • PROJECT_ID: il tuo ID progetto Google Cloud.
  • TEXT: il testo target per cui ottenere gli embedding. Ad esempio, a cat.
  • IMAGE_URI: l'URI Cloud Storage dell'immagine di destinazione per cui ottenere gli embedding. Ad esempio, gs://my-bucket/embeddings/supermarket-img.png.

    Puoi anche fornire l'immagine come una stringa di byte con codifica base64:

    [...]
"image": {
  "bytesBase64Encoded": "B64_ENCODED_IMAGE"
}
[...]
  • VIDEO_URI: l'URI Cloud Storage del video di destinazione per cui ottenere gli embedding. Ad esempio, gs://my-bucket/embeddings/supermarket-video.mp4.

    Puoi anche fornire il video come stringa di byte codificata in base64:

    [...]
"video": {
  "bytesBase64Encoded": "B64_ENCODED_VIDEO"
}
[...]
  • videoSegmentConfig (START_SECOND, END_SECOND, INTERVAL_SECONDS). Facoltativo. I segmenti video specifici (in secondi) per i quali vengono generati gli incorporamenti.

    Ad esempio:

    [...]
"videoSegmentConfig": {
  "startOffsetSec": 10,
  "endOffsetSec": 60,
  "intervalSec": 10
}
[...]

    Questa configurazione specifica i dati video da 10 a 60 secondi e genera embedding per i seguenti intervalli di video di 10 secondi: [10, 20), [20, 30), [30, 40), [40, 50), [50, 60). Questo intervallo di video ("intervalSec": 10) rientra nella modalità di incorporamento video standard e all'utente viene applicata la tariffa della modalità standard.

    Se ometti videoSegmentConfig, il servizio utilizza i seguenti valori predefiniti: "videoSegmentConfig": { "startOffsetSec": 0, "endOffsetSec": 120, "intervalSec": 16 }. Questo intervallo di video ("intervalSec": 16) rientra nella modalità di incorporamento video di base e all'utente viene applicata la tariffa di base.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict

Corpo JSON della richiesta: 

{
  "instances": [
    {
      "text": "TEXT",
      "image": {
        "gcsUri": "IMAGE_URI"
      },
      "video": {
        "gcsUri": "VIDEO_URI",
        "videoSegmentConfig": {
          "startOffsetSec": START_SECOND,
          "endOffsetSec": END_SECOND,
          "intervalSec": INTERVAL_SECONDS
        }
      }
    }
  ]
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict"

PowerShell

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/multimodalembedding@001:predict" | Select-Object -Expand Content
L'embedding restituito dal modello è un vettore di numeri in virgola mobile di 1408 elementi. La seguente risposta di esempio è abbreviata per motivi di spazio. 
{
  "predictions": [
    {
      "textEmbedding": [
        0.0105433334,
        -0.00302835181,
        0.00656806398,
        0.00603460241,
        [...]
        0.00445805816,
        0.0139605571,
        -0.00170318608,
        -0.00490092579
      ],
      "videoEmbeddings": [
        {
          "startOffsetSec": 0,
          "endOffsetSec": 7,
          "embedding": [
            -0.00673126569,
            0.0248149596,
            0.0128901172,
            0.0107588246,
            [...]
            -0.00180952181,
            -0.0054573305,
            0.0117037306,
            0.0169312079
          ]
        }
      ],
      "imageEmbedding": [
        -0.00728622358,
        0.031021487,
        -0.00206603738,
        0.0273937676,
        [...]
        -0.00204976718,
        0.00321615417,
        0.0121978866,
        0.0193375275
      ]
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

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. 

import vertexai

from vertexai.vision_models import Image, MultiModalEmbeddingModel, Video
from vertexai.vision_models import VideoSegmentConfig

# TODO(developer): Update & uncomment line below
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

model = MultiModalEmbeddingModel.from_pretrained("multimodalembedding@001")

image = Image.load_from_file(
    "gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png"
)
video = Video.load_from_file(
    "gs://cloud-samples-data/vertex-ai-vision/highway_vehicles.mp4"
)

embeddings = model.get_embeddings(
    image=image,
    video=video,
    video_segment_config=VideoSegmentConfig(end_offset_sec=1),
    contextual_text="Cars on Highway",
)

print(f"Image Embedding: {embeddings.image_embedding}")

# Video Embeddings are segmented based on the video_segment_config.
print("Video Embeddings:")
for video_embedding in embeddings.video_embeddings:
    print(
        f"Video Segment: {video_embedding.start_offset_sec} - {video_embedding.end_offset_sec}"
    )
    print(f"Embedding: {video_embedding.embedding}")

print(f"Text Embedding: {embeddings.text_embedding}")
# Example response:
# Image Embedding: [-0.0123144267, 0.0727186054, 0.000201397663, ...]
# Video Embeddings:
# Video Segment: 0.0 - 1.0
# Embedding: [-0.0206376351, 0.0345234685, ...]
# Text Embedding: [-0.0207006838, -0.00251058186, ...]

Passaggi successivi