Genera text embedding utilizzando la funzione AI.GENERATE_EMBEDDING

Questo documento mostra come creare un modello remoto BigQuery ML che fa riferimento a un modello di embedding. Quindi devi utilizzare il modello con la funzione AI.GENERATE_EMBEDDING per creare text embedding utilizzando i dati di una tabella standard di BigQuery.

Sono supportati i seguenti tipi di modelli remoti:

• Modelli remoti su modelli di embedding di Agent Platform.
• Modelli remoti su modelli aperti supportati.

Ruoli obbligatori

Per creare un modello remoto e utilizzare la funzione AI.GENERATE_EMBEDDING, devi disporre dei seguenti ruoli IAM (Identity and Access Management):

• Creare e utilizzare set di dati, tabelle e modelli BigQuery: BigQuery Data Editor (roles/bigquery.dataEditor) nel progetto.

• Creare, delegare e utilizzare le connessioni BigQuery: BigQuery Connections Admin (roles/bigquery.connectionsAdmin) sul tuo progetto.

  Se non hai configurato una connessione predefinita, puoi crearne e impostarne una durante l'esecuzione dell'istruzione CREATE MODEL. Per farlo, devi disporre del ruolo Amministratore BigQuery (roles/bigquery.admin) nel tuo progetto. Per saperne di più, consulta Configura la connessione predefinita.

• Concedi le autorizzazioni al account di servizio della connessione: Project IAM Admin (roles/resourcemanager.projectIamAdmin) sul progetto che contiene l'endpoint della piattaforma Gemini Enterprise Agent. Questo è il progetto attuale per i modelli remoti che crei specificando il nome del modello come endpoint. Questo è il progetto identificato nell'URL per i modelli remoti che crei specificando un URL come endpoint.

• Creare job BigQuery: Utente job BigQuery (roles/bigquery.jobUser) nel progetto.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per eseguire le attività descritte in questo documento. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

• Crea un set di dati: bigquery.datasets.create
• Crea, delega e utilizza una connessione: bigquery.connections.*
• Imposta le autorizzazioni del account di servizio: resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
• Crea un modello ed esegui l'inferenza:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata
• Esegui query sui dati della tabella: bigquery.tables.getData

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Prima di iniziare

1. Nella console Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .

   Ruoli richiesti per selezionare o creare un progetto

   • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per cui ti è stato concesso un ruolo.
   • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.
   Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

   Vai al selettore di progetti

2. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

3. Abilita le API BigQuery, BigQuery Connection e Agent Platform, se non sono già abilitate.

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

   Abilita le API

Crea un set di dati

Crea un set di dati BigQuery per contenere le tue risorse:

Console

1. Nella console Google Cloud , vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

   

   Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro sinistro per aprirlo.

3. Nel riquadro Explorer, fai clic sul nome del progetto.

4. Fai clic su Visualizza azioni > Crea set di dati.

5. Nella pagina Crea set di dati, segui questi passaggi:

   1. In ID set di dati, digita un nome per il set di dati.

   2. Per Tipo di località, seleziona Regione o Multi-regione.

      • Se hai selezionato Regione, seleziona una località dall'elenco Regione.
      • Se hai selezionato Multiregione, seleziona Stati Uniti o Europa dall'elenco Multiregione.

   3. Fai clic su Crea set di dati.

bq

1. Per creare un nuovo set di dati, utilizza il comando bq mk con il flag --location:

   bq --location=LOCATION mk -d DATASET_ID

   Sostituisci quanto segue:

   • LOCATION: la località del set di dati.
   • DATASET_ID: l'ID del set di dati che stai creando.

2. Verifica che il set di dati sia stato creato:

   bq ls

Crea una connessione

Crea una connessione alle risorse Cloud e ottieni il account di servizio della connessione. Crea la connessione nella stessa località del set di dati creato nel passaggio precedente.

Puoi saltare questo passaggio se hai configurato una connessione predefinita o se hai il ruolo Amministratore BigQuery.

Seleziona una delle seguenti opzioni:

Console

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Explorer:

   

   Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro sinistro per aprirlo.

3. Nel riquadro Explorer, espandi il nome del progetto, quindi fai clic su Connessioni.

4. Nella pagina Connessioni, fai clic su Crea connessione.

5. In Tipo di connessione, scegli Modelli remoti di Vertex AI, funzioni remote, BigLake e Spanner (risorsa Cloud).

6. Nel campo ID connessione, inserisci un nome per la connessione.

7. In Tipo di località, seleziona una località per la connessione. La connessione deve essere collocata insieme alle altre risorse, ad esempio i set di dati.

8. Fai clic su Crea connessione.

9. Fai clic su Vai alla connessione.

10. Nel riquadro Informazioni sulla connessione, copia l'ID account di servizio da utilizzare in un passaggio successivo.

SQL

Utilizza l'istruzione CREATE CONNECTION:

1. Nella console Google Cloud , vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, inserisci la seguente istruzione:

   CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
   OPTIONS (
     connection_type = "CLOUD_RESOURCE",
     friendly_name = "FRIENDLY_NAME",
     description = "DESCRIPTION"
     );

   Sostituisci quanto segue:

   • CONNECTION_NAME: il nome della connessione nel formato PROJECT_ID.LOCATION.CONNECTION_ID, LOCATION.CONNECTION_ID o CONNECTION_ID. Se il progetto o la località vengono omessi, vengono dedotti dal progetto e dalla località in cui viene eseguita l'istruzione.
   • FRIENDLY_NAME (facoltativo): un nome descrittivo per la connessione.
   • DESCRIPTION (facoltativo): una descrizione della connessione.

3. Fai clic su Esegui.

Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.

bq

1. In un ambiente a riga di comando, crea una connessione:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   Il parametro --project_id sostituisce il progetto predefinito.

   Sostituisci quanto segue:

   • REGION: la tua regione di connessione
   • PROJECT_ID: il tuo ID progetto Google Cloud
   • CONNECTION_ID: un ID per la tua connessione

   Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema univoco e lo associa alla connessione.

   Risoluzione dei problemi: se ricevi il seguente errore di connessione, aggiorna Google Cloud SDK:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Recupera e copia l'ID del account di servizio da utilizzare in un passaggio successivo:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   L'output è simile al seguente:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel."}
   

Python

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

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

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

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

Java

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

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.connection.v1.CloudResourceProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

public class CreateConnection {

  /**
   * Creates a BigQuery connection to a Cloud Resource. A Cloud Resource connection provisions a
   * service account that can be granted access to other Google Cloud resources for federated
   * queries.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the connection (for example, "us-central1").
   * @param connectionId The ID of the connection to create (for example, "example-connection-id").
   */
  public static void createConnection(String projectId, String location, String connectionId) {
    LocationName parent = LocationName.of(projectId, location);

    // CloudResourceProperties provisions a managed Google Cloud service account on creation.
    CloudResourceProperties cloudResourceProperties = CloudResourceProperties.newBuilder().build();
    Connection connection =
        Connection.newBuilder()
            .setFriendlyName("Example Connection")
            .setDescription("Cloud Resource connection for federated queries.")
            .setCloudResource(cloudResourceProperties)
            .build();

    CreateConnectionRequest request =
        CreateConnectionRequest.newBuilder()
            .setParent(parent.toString())
            .setConnectionId(connectionId)
            .setConnection(connection)
            .build();

    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      Connection response = client.createConnection(request);

      System.out.printf("Successfully created connection: %s%n", response.getName());
      System.out.printf("Friendly name: %s%n", response.getFriendlyName());
      System.out.printf(
          "Service Account: %s%n", response.getCloudResource().getServiceAccountId());
    } catch (AlreadyExistsException err) {
      System.err.printf(
          "error: connection '%s' already exists in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to create connection '%s' in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    }
  }

Terraform

Utilizza la risorsa google_bigquery_connection.

Nota: per creare oggetti BigQuery utilizzando Terraform, devi attivare l'API Cloud Resource Manager.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

L'esempio seguente crea una connessione alle risorse Cloud denominata my_cloud_resource_connection nella regione US:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Per applicare la configurazione Terraform in un progetto Google Cloud , completa i passaggi descritti nelle sezioni seguenti.

Prepara Cloud Shell

1. Avvia Cloud Shell.

2. Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

   Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo principale).

1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

   Copia il codice campione nel file main.tf appena creato.

   Facoltativamente, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
4. Salva le modifiche.
5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.

   terraform init

   Facoltativamente, per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

Applica le modifiche

1. Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative:

   terraform plan

   Apporta le correzioni necessarie alla configurazione.

2. Applica la configurazione Terraform eseguendo il comando seguente e inserendo yes al prompt:

   terraform apply

   Attendi che Terraform visualizzi il messaggio "Apply complete!".

3. Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud , vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

Nota: gli esempi di Terraform in genere presuppongono che le API richieste siano abilitate nel tuo progetto Google Cloud .

Concedi un ruolo al account di servizio della connessione al modello remoto

Devi concedere al account di servizio della connessione il ruolo Agent Platform User.

Se prevedi di specificare l'endpoint come URL quando crei il modello remoto, ad esempio endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-005', concedi questo ruolo nello stesso progetto che specifichi nell'URL.

Se prevedi di specificare l'endpoint utilizzando il nome del modello quando crei il modello remoto, ad esempio endpoint = 'text-embedding-005', concedi questo ruolo nello stesso progetto in cui prevedi di creare il modello remoto.

La concessione del ruolo in un progetto diverso genera l'errore bqcx-1234567890-wxyz@gcp-sa-bigquery-condel. does not have the permission to access resource.

Per concedere il ruolo, segui questi passaggi:

Console

1. Vai alla pagina IAM e amministrazione.

   Vai a IAM e amministrazione

2. Fai clic su Concedi l'accesso.

   Viene visualizzata la finestra di dialogo Aggiungi entità.

3. Nel campo Nuove entità, inserisci l'ID del account di servizio che hai copiato in precedenza.

4. Nel campo Seleziona un ruolo, cerca Agent Platform User.

5. Fai clic su Salva.

gcloud

Utilizza il comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

Sostituisci quanto segue:

• PROJECT_NUMBER: il numero del tuo progetto
• MEMBER: l'ID del account di servizio che hai copiato in precedenza

Scegli un metodo di deployment dei modelli aperti

Se stai creando un modello remoto su un modello aperto supportato, puoi eseguire automaticamente il deployment del modello aperto contemporaneamente alla creazione del modello remoto specificando l'ID modello di Agent Platform Model Garden o Hugging Face nell'istruzione CREATE MODEL. In alternativa, puoi eseguire manualmente il deployment del modello aperto, quindi utilizzarlo con il modello remoto specificando l'endpoint del modello nell'istruzione CREATE MODEL. Per saperne di più, consulta Esegui il deployment di modelli aperti.

Crea un modello remoto BigQuery ML

Crea un modello remoto:

Modelli Agent Platform

1. Nella console Google Cloud , vai alla pagina BigQuery.

   Vai a BigQuery

2. Utilizzando l'editor SQL, crea un modello remoto:

   CREATE OR REPLACE MODEL
   `PROJECT_ID.DATASET_ID.MODEL_NAME`
   REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
   OPTIONS (ENDPOINT = 'ENDPOINT');

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto.
   • DATASET_ID: l'ID del set di dati che conterrà il modello. Questo set di dati deve trovarsi nella stessa località della connessione che stai utilizzando.
   • MODEL_NAME: il nome del modello.
   • REGION: la regione utilizzata dalla connessione.
   • CONNECTION_ID: l'ID della tua connessione BigQuery.

     Puoi ottenere questo valore visualizzando i dettagli della connessione nella console Google Cloud e copiando il valore nell'ultima sezione dell'ID connessione completamente qualificato mostrato in ID connessione. Ad esempio, projects/myproject/locations/connection_location/connections/myconnection.

   • ENDPOINT: il nome di un modello di embedding da utilizzare. Per saperne di più, consulta ENDPOINT.

     Il modello Agent Platform specificato deve essere disponibile nella località in cui stai creando il modello remoto. Per saperne di più, consulta Località.

Nuovi modelli aperti

1. Nella console Google Cloud , vai alla pagina BigQuery.

   Vai a BigQuery

2. Utilizzando l'editor SQL, crea un modello remoto:

   CREATE OR REPLACE MODEL
   `PROJECT_ID.DATASET_ID.MODEL_NAME`
   REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
   OPTIONS (
     {HUGGING_FACE_MODEL_ID = 'HUGGING_FACE_MODEL_ID' |
        MODEL_GARDEN_MODEL_NAME = 'MODEL_GARDEN_MODEL_NAME'}
     [, HUGGING_FACE_TOKEN = 'HUGGING_FACE_TOKEN' ]
     [, MACHINE_TYPE = 'MACHINE_TYPE' ]
     [, MIN_REPLICA_COUNT = MIN_REPLICA_COUNT ]
     [, MAX_REPLICA_COUNT = MAX_REPLICA_COUNT ]
     [, RESERVATION_AFFINITY_TYPE = {'NO_RESERVATION' | 'ANY_RESERVATION' | 'SPECIFIC_RESERVATION'} ]
     [, RESERVATION_AFFINITY_KEY = 'compute.googleapis.com/reservation-name' ]
     [, RESERVATION_AFFINITY_VALUES = RESERVATION_AFFINITY_VALUES ]
     [, ENDPOINT_IDLE_TTL = ENDPOINT_IDLE_TTL ]
   );

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto.
   • DATASET_ID: l'ID del set di dati che conterrà il modello. Questo set di dati deve trovarsi nella stessa località della connessione che stai utilizzando.
   • MODEL_NAME: il nome del modello.
   • REGION: la regione utilizzata dalla connessione.
   • CONNECTION_ID: l'ID della tua connessione BigQuery.

     Puoi ottenere questo valore visualizzando i dettagli della connessione nella console Google Cloud e copiando il valore nell'ultima sezione dell'ID connessione completamente qualificato mostrato in ID connessione. Ad esempio, projects/myproject/locations/connection_location/connections/myconnection.

   • HUGGING_FACE_MODEL_ID: un valore STRING che specifica l'ID del modello per un modello Hugging Face supportato, nel formato provider_name/model_name. Ad esempio, deepseek-ai/DeepSeek-R1. Puoi ottenere l'ID modello facendo clic sul nome del modello nell'hub dei modelli Hugging Face e copiando l'ID modello dalla parte superiore della scheda del modello.
   • MODEL_GARDEN_MODEL_NAME: un valore STRING che specifica l'ID e la versione di un modello Model Garden di Gemini Enterprise Agent Platform supportato, nel formato publishers/publisher/models/model_name@model_version. Ad esempio, publishers/openai/models/gpt-oss@gpt-oss-120b. Puoi ottenere l'ID modello facendo clic sulla scheda del modello in Model Garden di Agent Platform e copiando l'ID modello dal campo ID modello. Puoi ottenere la versione predefinita del modello copiandola dal campo Versione nella scheda del modello. Per visualizzare altre versioni del modello che puoi utilizzare, fai clic su Esegui il deployment del modello, quindi sul campo ID risorsa.
   • HUGGING_FACE_TOKEN: un valore STRING che specifica il token di accesso utente di Hugging Face da utilizzare. Puoi specificare un valore per questa opzione solo se specifichi anche un valore per l'opzione HUGGING_FACE_MODEL_ID.

     Il token deve avere almeno il ruolo read, ma sono accettabili anche token con un ambito più ampio. Questa opzione è obbligatoria quando il modello identificato dal valore HUGGING_FACE_MODEL_ID è un modello Hugging Face con accesso limitato o privato.

     Alcuni modelli con limitazioni richiedono l'accettazione esplicita dei relativi Termini di servizio prima che venga concesso l'accesso. Per accettare questi termini, segui questi passaggi:

     1. Vai alla pagina del modello sul sito web di Hugging Face.
     2. Individua e leggi i Termini di servizio del modello. Un link al contratto di servizio si trova in genere nella scheda del modello.
     3. Accetta i termini come richiesto nella pagina.
   • MACHINE_TYPE: un valore STRING che specifica il tipo di macchina da utilizzare per il deployment del modello su Agent Platform. Per informazioni sui tipi di macchine supportati, consulta Tipi di macchine. Se non specifichi un valore per l'opzione MACHINE_TYPE, viene utilizzato il tipo di macchina predefinito di Model Garden della piattaforma agente per il modello.
   • MIN_REPLICA_COUNT: un valore INT64 che specifica il numero minimo di repliche della macchina utilizzate durante il deployment del modello su un endpoint della piattaforma agente. Il servizio aumenta o diminuisce il numero di repliche in base al carico di inferenza sull'endpoint. Il numero di repliche utilizzate non è mai inferiore al valore MIN_REPLICA_COUNT e mai superiore al valore MAX_REPLICA_COUNT. Il valore MIN_REPLICA_COUNT deve essere compreso nell'intervallo [1, 4096]. Il valore predefinito è 1.
   • MAX_REPLICA_COUNT: un valore INT64 che specifica il numero massimo di repliche della macchina utilizzate durante il deployment del modello su un endpoint della piattaforma agente. Il servizio aumenta o diminuisce il numero di repliche in base al carico di inferenza sull'endpoint. Il numero di repliche utilizzate non è mai inferiore al valore MIN_REPLICA_COUNT e mai superiore al valore MAX_REPLICA_COUNT. Il valore MAX_REPLICA_COUNT deve essere compreso nell'intervallo [1, 4096]. Il valore predefinito è il valore MIN_REPLICA_COUNT.
   • RESERVATION_AFFINITY_TYPE: determina se il modello di cui è stato eseguito il deployment utilizza le prenotazioni di Compute Engine per fornire la disponibilità garantita delle macchine virtuali (VM) durante la generazione delle previsioni e specifica se il modello utilizza le VM di tutte le prenotazioni disponibili o solo di una prenotazione specifica. Per saperne di più, consulta Affinità di prenotazione di Compute Engine.

     Puoi utilizzare solo le prenotazioni di Compute Engine condivise con Agent Platform. Per saperne di più, consulta Consenti l'utilizzo di una prenotazione.

     I valori supportati sono:

     • NO_RESERVATION: non viene utilizzata alcuna prenotazione quando viene eseguito il deployment del modello in un endpoint Agent Platform. Specificare NO_RESERVATION ha lo stesso effetto di non specificare un'affinità di prenotazione.
     • ANY_RESERVATION: il deployment del modello della piattaforma agente utilizza le macchine virtuali (VM) delle prenotazioni di Compute Engine che si trovano nel progetto corrente o che sono condivise con il progetto e che sono configurate per l'utilizzo automatico. Vengono utilizzate solo le VM che soddisfano le seguenti qualifiche:
       • Utilizzano il tipo di macchina specificato dal valore MACHINE_TYPE.
       • Se il set di dati BigQuery in cui stai creando il modello remoto è una singola regione, la prenotazione deve trovarsi nella stessa regione. Se il set di dati si trova nella multiregione US, la prenotazione deve trovarsi nella regione us-central1. Se il set di dati si trova nella multiregione EU, la prenotazione deve trovarsi nella regione europe-west4.

       Se la capacità delle prenotazioni disponibili non è sufficiente o se non vengono trovate prenotazioni adatte, il sistema esegue il provisioning di VM di Compute Engine on demand per soddisfare i requisiti delle risorse.

     • SPECIFIC_RESERVATION: il deployment del modello Agent Platform utilizza le VM solo dalla prenotazione specificata nel valore RESERVATION_AFFINITY_VALUES. Questa prenotazione deve essere configurata per l'utilizzo con target specifico. Il deployment non riesce se la prenotazione specificata non ha capacità sufficiente.
   • RESERVATION_AFFINITY_KEY: la stringa compute.googleapis.com/reservation-name. Devi specificare questa opzione quando il valore RESERVATION_AFFINITY_TYPE è SPECIFIC_RESERVATION.
   • RESERVATION_AFFINITY_VALUES: un valore ARRAY<STRING> che specifica il nome completo della risorsa della prenotazione di Compute Engine, nel seguente formato:
     
     projects/myproject/zones/reservation_zone/reservations/reservation_name

     Ad esempio, RESERVATION_AFFINITY_values = ['projects/myProject/zones/us-central1-a/reservations/myReservationName'].

     Puoi ottenere il nome e la zona della prenotazione dalla pagina Prenotazioni della console Google Cloud . Per saperne di più, consulta Visualizza le prenotazioni.

     Devi specificare questa opzione quando il valore RESERVATION_AFFINITY_TYPE è SPECIFIC_RESERVATION.

   • ENDPOINT_IDLE_TTL: un valore INTERVAL che specifica la durata dell'inattività dopo la quale il modello aperto viene automaticamente disinstallato dall'endpoint della piattaforma agente.

     Per attivare l'annullamento del deployment automatico, specifica un valore valore letterale dell'intervallo compreso tra 390 minuti (6,5 ore) e 7 giorni. Ad esempio, specifica INTERVAL 8 HOUR per annullare il deployment del modello dopo 8 ore di inattività. Il valore predefinito è 390 minuti (6,5 ore).

     L'inattività del modello è definita come il tempo trascorso dall'esecuzione di una delle seguenti operazioni sul modello:

     • Esecuzione dell'istruzione CREATE MODEL.
     • Esecuzione dell'istruzione ALTER MODEL con l'argomento DEPLOY_MODEL impostato su TRUE.
     • Invio di una richiesta di inferenza all'endpoint del modello. Ad esempio, eseguendo la funzione AI.GENERATE_EMBEDDING o AI.GENERATE_TEXT.

     Ognuna di queste operazioni reimposta il timer di inattività su zero. La reimpostazione viene attivata all'inizio del job BigQuery che esegue l'operazione.

     Dopo l'annullamento del deployment del modello, le richieste di inferenza inviate al modello restituiscono un errore. L'oggetto del modello BigQuery rimane invariato, inclusi i metadati del modello. Per utilizzare nuovamente il modello per l'inferenza, devi eseguirne nuovamente il deployment eseguendo l'istruzione ALTER MODEL sul modello e impostando l'opzione DEPLOY_MODEL su TRUE.

Modelli open di cui è stato eseguito il deployment

1. Nella console Google Cloud , vai alla pagina BigQuery.

   Vai a BigQuery

2. Utilizzando l'editor SQL, crea un modello remoto:

   CREATE OR REPLACE MODEL
   `PROJECT_ID.DATASET_ID.MODEL_NAME`
   REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
   OPTIONS (
     ENDPOINT = 'https://ENDPOINT_REGION-aiplatform.googleapis.com/v1/projects/ENDPOINT_PROJECT_ID/locations/ENDPOINT_REGION/endpoints/ENDPOINT_ID'
   );

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto.
   • DATASET_ID: l'ID del set di dati che conterrà il modello. Questo set di dati deve trovarsi nella stessa località della connessione che stai utilizzando.
   • MODEL_NAME: il nome del modello.
   • REGION: la regione utilizzata dalla connessione.
   • CONNECTION_ID: l'ID della tua connessione BigQuery.

     Puoi ottenere questo valore visualizzando i dettagli della connessione nella console Google Cloud e copiando il valore nell'ultima sezione dell'ID connessione completamente qualificato mostrato in ID connessione. Ad esempio, projects/myproject/locations/connection_location/connections/myconnection.

   • ENDPOINT_REGION: la regione in cui è stato eseguito il deployment del modello aperto.
   • ENDPOINT_PROJECT_ID: il progetto in cui è stato eseguito il deployment del modello aperto.
   • ENDPOINT_ID: l'ID dell'endpoint HTTPS utilizzato dal modello aperto. Puoi ottenere l'ID endpoint individuando il modello aperto nella pagina Previsione online e copiando il valore nel campo ID.

Genera text embedding

Genera text embedding con la funzione AI.GENERATE_EMBEDDING utilizzando i dati di testo di una colonna della tabella o di una query.

In genere, utilizzeresti un modello di text embedding per i casi d'uso di solo testo e un modello di embedding multimodale per i casi d'uso di ricerca cross-modale, in cui gli embedding per i contenuti testuali e visivi vengono generati nello stesso spazio semantico.

Testo di Agent Platform

Genera text embedding utilizzando un modello remoto su un modello di text embedding di Agent Platform:

SELECT *
FROM AI.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• DATASET_ID: l'ID del set di dati che contiene il modello.
• MODEL_NAME: il nome del modello remoto su un modello di embedding.
• TABLE_NAME: il nome della tabella che contiene il testo da incorporare. Questa tabella deve avere una colonna denominata content oppure puoi utilizzare un alias per utilizzare una colonna con un nome diverso.
• CONTENT_QUERY: una query il cui risultato contiene una colonna STRING denominata content.
• TASK_TYPE: un valore letterale STRING che specifica l'applicazione downstream prevista per aiutare il modello a produrre embedding di qualità migliore. TASK_TYPE accetta i seguenti valori:
  • RETRIEVAL_QUERY: specifica che il testo fornito è una query in un'impostazione di ricerca o recupero.
  • RETRIEVAL_DOCUMENT: specifica che il testo fornito è un documento in un contesto di ricerca o recupero.

    Quando utilizzi questo tipo di attività, è utile includere il titolo del documento nell'istruzione della query per migliorare la qualità dell'embedding. Il titolo del documento deve trovarsi in una colonna denominata title o con alias title, ad esempio:

          SELECT *
          FROM
            AI.GENERATE_EMBEDDING(
              MODEL mydataset.embedding_model,
              (SELECT abstract as content, header as title, publication_number
              FROM mydataset.publications),
              STRUCT('RETRIEVAL_DOCUMENT' as task_type)
          );
          

    Se specifichi la colonna del titolo nella query di input, viene compilato il campo title del corpo della richiesta inviata al modello. Se specifichi un valore title quando utilizzi un altro tipo di attività, l'input viene ignorato e non ha alcun effetto sui risultati dell'embedding.

  • SEMANTIC_SIMILARITY: specifica che il testo specificato verrà utilizzato per la similarità testuale semantica (STS).
  • CLASSIFICATION: specifica che gli embedding verranno utilizzati per la classificazione.
  • CLUSTERING: specifica che gli embedding verranno utilizzati per il clustering.
  • QUESTION_ANSWERING: specifica che gli embedding verranno utilizzati per rispondere alle domande.
  • FACT_VERIFICATION: specifica che gli embedding verranno utilizzati per la verifica dei fatti.
  • CODE_RETRIEVAL_QUERY: specifica che gli embedding verranno utilizzati per il recupero del codice.
• OUTPUT_DIMENSIONALITY: un valore INT64 che specifica il numero di dimensioni da utilizzare per la generazione degli embedding. Ad esempio, se specifichi 256 AS output_dimensionality, la colonna di output embedding contiene un embedding a 256 dimensioni per ogni valore di input.

  Per i modelli remoti su modelli gemini-embedding-2-preview o gemini-embedding-001, il valore OUTPUT_DIMENSIONALITY deve essere compreso nell'intervallo [1, 3072]. Il valore predefinito è 3072. Per i modelli remoti rispetto ai modelli text-embedding, il valore OUTPUT_DIMENSIONALITY deve essere compreso nell'intervallo [1, 768]. Il valore predefinito è 768.

Esempio: incorpora il testo in una tabella

L'esempio seguente mostra una richiesta di incorporamento della colonna content della tabella text_data:

SELECT *
FROM
  AI.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE mydataset.text_data,
    STRUCT('CLASSIFICATION' AS task_type)
  );

Testo aperto

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Nota: per fornire un feedback o richiedere assistenza per questa funzionalità, contatta [e-mail].

Genera text embedding utilizzando un modello remoto su un modello di embedding aperto:

SELECT *
FROM AI.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
);

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• DATASET_ID: l'ID del set di dati che contiene il modello.
• MODEL_NAME: il nome del modello remoto su un modello di embedding.
• TABLE_NAME: il nome della tabella che contiene il testo da incorporare. Questa tabella deve avere una colonna denominata content oppure puoi utilizzare un alias per utilizzare una colonna con un nome diverso.
• CONTENT_QUERY: una query il cui risultato contiene una colonna STRING denominata content.

Agent Platform multimodale

Genera text embedding utilizzando un modello remoto su un modello di embedding multimodale di Agent Platform:

SELECT *
FROM AI.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• DATASET_ID: l'ID del set di dati che contiene il modello.
• MODEL_NAME: il nome del modello remoto su un modello multimodalembedding@001.
• TABLE_NAME: il nome della tabella che contiene il testo da incorporare. Questa tabella deve avere una colonna denominata content oppure puoi utilizzare un alias per utilizzare una colonna con un nome diverso.
• CONTENT_QUERY: una query il cui risultato contiene una colonna STRING denominata content.
• OUTPUT_DIMENSIONALITY: un valore INT64 che specifica il numero di dimensioni da utilizzare per la generazione degli embedding. I valori validi sono 128, 256, 512 e 1408. Il valore predefinito è 1408. Ad esempio, se specifichi 256 AS output_dimensionality, la colonna di output embedding contiene un embedding a 256 dimensioni per ogni valore di input.

Esempio: utilizza gli embedding per classificare la somiglianza semantica

L'esempio seguente incorpora una raccolta di recensioni di film e le ordina in base alla distanza del coseno rispetto alla recensione "Questo film era nella media" utilizzando la funzione VECTOR_SEARCH. Una distanza minore indica una maggiore somiglianza semantica.

Per saperne di più sulla ricerca vettoriale e sull'indice vettoriale, consulta Introduzione alla ricerca vettoriale.

CREATE TEMPORARY TABLE movie_review_embeddings AS (
  SELECT *
  FROM
    AI.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "This movie was fantastic" AS content
        UNION ALL
        SELECT "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "This movie was just okay..." AS content
        UNION ALL
        SELECT "This movie was terrible." AS content
      )
    )
);

WITH average_review_embedding AS (
  SELECT embedding
  FROM
    AI.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (SELECT "This movie was average" AS content)
    )
)
SELECT
  base.content AS content,
  distance AS distance_to_average_review
FROM
  VECTOR_SEARCH(
    TABLE movie_review_embeddings,
    "embedding",
    (SELECT embedding FROM average_review_embedding),
    distance_type=>"COSINE",
    top_k=>-1
  )
ORDER BY distance_to_average_review;

Il risultato è simile al seguente:

+------------------------------------------+----------------------------+
| content                                  | distance_to_average_review |
+------------------------------------------+----------------------------+
| This movie was just okay...              | 0.062789813467745592       |
| This movie was fantastic                 |  0.18579561313064263       |
| This movie was terrible.                 |  0.35707466240930985       |
| This was the best movie I've ever seen!! |  0.41844932504542975       |
+------------------------------------------+----------------------------+

Passaggi successivi

• Scopri come utilizzare gli incorporamenti di testo e immagini per eseguire una ricerca semantica da testo a immagine.
• Scopri come utilizzare i text embedding per la ricerca semantica e la Retrieval Augmented Generation (RAG).