Eseguire la ricerca semantica e la generazione aumentata dal recupero

Questo tutorial ti guida nell'intero processo di creazione e utilizzo di text embedding per la ricerca semantica e la generazione RAG (Retrieval-Augmented Generation).

Questo tutorial spiega le seguenti attività:

• Creazione di un modello remoto BigQuery ML su un modello di incorporamento Vertex AI.
• Utilizzo del modello remoto con la funzione ML.GENERATE_EMBEDDING per generare incorporamenti dal testo in una tabella BigQuery.
• Creazione di un indice vettoriale per indicizzare gli incorporamenti al fine di migliorare il rendimento della ricerca.
• Utilizzando la funzione VECTOR_SEARCH con gli incorporamenti per cercare testo simile.
• Esegui RAG generando testo con la funzione ML.GENERATE_TEXT e utilizzando i risultati della ricerca vettoriale per aumentare l'input del prompt e migliorare i risultati.

Questo tutorial utilizza la tabella pubblica BigQuery patents-public-data.google_patents_research.publications.

Ruoli e autorizzazioni richiesti

• Per creare una connessione, devi disporre del seguente ruolo Identity and Access Management (IAM):

  • roles/bigquery.connectionAdmin

• Per concedere le autorizzazioni al account di servizio della connessione, devi disporre della seguente autorizzazione:

  • resourcemanager.projects.setIamPolicy

• Le autorizzazioni IAM necessarie in questo tutorial per le restanti operazioni BigQuery sono incluse nei seguenti due ruoli:

  • BigQuery Data Editor (roles/bigquery.dataEditor) per creare modelli, tabelle e indici.
  • Utente BigQuery (roles/bigquery.user) per eseguire i job BigQuery.

Costi

In questo documento, utilizzi i seguenti componenti fatturabili di Google Cloud:

• BigQuery ML: You incur costs for the data that you process in BigQuery.
• Vertex AI: You incur costs for calls to the Vertex AI service that's represented by the remote model.

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero avere diritto a una prova gratuita.

Per ulteriori informazioni sui prezzi di BigQuery, consulta la sezione Prezzi di BigQuery nella documentazione di BigQuery.

Per saperne di più sui prezzi di Vertex AI, consulta la pagina Prezzi di Vertex AI.

Prima di iniziare

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Enable the APIs

Crea un set di dati

Crea un set di dati BigQuery per archiviare il tuo modello ML.

Console

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

   Vai alla pagina BigQuery

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

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

   

4. Nella pagina Crea set di dati:

   • In ID set di dati, inserisci bqml_tutorial.

   • Per Tipo di località, seleziona Più regioni e poi Stati Uniti (più regioni negli Stati Uniti).

   • Lascia invariate le restanti impostazioni predefinite e fai clic su Crea set di dati.

bq

Per creare un nuovo set di dati, utilizza il comando bq mk con il flag --location. Per un elenco completo dei possibili parametri, consulta la documentazione di riferimento del comando bq mk --dataset.

1. Crea un set di dati denominato bqml_tutorial con la località dei dati impostata su US e una descrizione di BigQuery ML tutorial dataset:

   bq --location=US mk -d \
    --description "BigQuery ML tutorial dataset." \
    bqml_tutorial

   Anziché utilizzare il flag --dataset, il comando utilizza la scorciatoia -d. Se ometti -d e --dataset, il comando crea un set di dati per impostazione predefinita.

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

   bq ls

API

Chiama il metodo datasets.insert con una risorsa dataset definita.

{
  "datasetReference": {
     "datasetId": "bqml_tutorial"
  }
}

BigQuery DataFrames

Prima di provare questo esempio, segui le istruzioni di configurazione di BigQuery DataFrames nella guida rapida di BigQuery che utilizza BigQuery DataFrames. Per ulteriori informazioni, consulta la documentazione di riferimento di BigQuery DataFrames.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, vedi Configurare ADC per un ambiente di sviluppo locale.

import google.cloud.bigquery

bqclient = google.cloud.bigquery.Client()
bqclient.create_dataset("bqml_tutorial", exists_ok=True)

Crea una connessione

Crea una connessione risorsa Cloud e ottieni il account di servizio della connessione. Crea la connessione nella stessa posizione del set di dati creato nel passaggio precedente.

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

Crea una connessione a una risorsa Cloud da utilizzare per il modello remoto e recupera il account di servizio della connessione. Crea la connessione nella stessa posizione del set di dati che hai creato nel passaggio precedente.

Seleziona una delle seguenti opzioni:

Console

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Explorer, fai clic su Aggiungi dati:

   

   Si apre la finestra di dialogo Aggiungi dati.

3. Nel riquadro Filtra per, seleziona Applicazioni aziendali nella sezione Tipo di origine dati.

   In alternativa, nel campo Cerca origini dati, puoi inserire Vertex AI.

4. Nella sezione Origini dati in evidenza, fai clic su Vertex AI.

5. Fai clic sulla scheda della soluzione Vertex AI Models: BigQuery Federation.

6. Nell'elenco Tipo di connessione, seleziona Modelli remoti di Vertex AI, funzioni remote e BigLake (risorsa Cloud).

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

8. Fai clic su Crea connessione.

9. Fai clic su Vai alla connessione.

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

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 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 serviziot di sistema univoco e lo associa alla connessione.

   Risoluzione dei problemi: se viene visualizzato 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 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": "[e-mail]"}
   

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 Configurare l'autenticazione per le librerie client.

Il seguente esempio crea una connessione di risorsa 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 di Terraform in un progetto Google Cloud , completa i passaggi 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 di Terraform deve avere la propria directory (chiamata anche modulo radice).

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

   (Facoltativo) Copia il codice da GitHub. Questa operazione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

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

   terraform init

   (Facoltativo) Per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

Applica le modifiche

1. Rivedi 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 di Terraform eseguendo il comando seguente e inserendo yes al prompt:

   terraform apply

   Attendi che Terraform visualizzi il messaggio "Apply complete!" (Applicazione completata).

3. Apri il tuo Google Cloud progetto 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 attive nel tuo progetto Google Cloud .

Concedi l'accesso al account di servizio

Concedi al account di servizio della connessione il ruolo Utente Vertex AI. Devi concedere questo ruolo nello stesso progetto che hai creato o selezionato nella sezione Prima di iniziare. La concessione del ruolo in un progetto diverso genera l'errore [e-mail] does not have the permission to access resource.

Per concedere il ruolo, segui questi passaggi:

1. Vai alla pagina IAM e amministrazione.

   Vai a IAM e amministrazione

2. Fai clic su Concedi l'accesso.

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

4. Nel campo Seleziona un ruolo, scegli Vertex AI e poi seleziona Ruolo utente Vertex AI.

5. Fai clic su Salva.

Crea il modello remoto per la generazione di incorporamenti di testo

Crea un modello remoto che rappresenti un modello di generazione di text embedding Vertex AI ospitato:

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

   Vai a BigQuery

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

   CREATE OR REPLACE MODEL `bqml_tutorial.embedding_model`
     REMOTE WITH CONNECTION `us.CONNECTION_ID`
     OPTIONS (ENDPOINT = 'text-embedding-005');

   Sostituisci CONNECTION_ID con l'ID della tua connessione BigQuery.

   Quando visualizzi i dettagli della connessione nella console Google Cloud , CONNECTION_ID è il valore nell'ultima sezione dell'ID connessione completo visualizzato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection.

   Il completamento della query richiede diversi secondi, dopodiché il modello embedding_model viene visualizzato nel set di dati bqml_tutorial nel riquadro Explorer. Poiché la query utilizza un'istruzione CREATE MODEL per creare un modello, non ci sono risultati della query.

Generare incorporamenti di testo

Genera incorporamenti di testo dagli abstract dei brevetti utilizzando la funzione ML.GENERATE_EMBEDDING e poi scrivili in una tabella BigQuery in modo che possano essere cercati.

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

   Vai a BigQuery

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

   CREATE OR REPLACE TABLE `bqml_tutorial.embeddings` AS
   SELECT * FROM ML.GENERATE_EMBEDDING(
     MODEL `bqml_tutorial.embedding_model`,
     (
       SELECT *, abstract AS content
       FROM `patents-public-data.google_patents_research.publications`
       WHERE LENGTH(abstract) > 0 AND LENGTH(title) > 0 AND country = 'Singapore'
     )
   )
   WHERE LENGTH(ml_generate_embedding_status) = 0;

La compilazione di questa richiesta richiede circa 5 minuti.

La generazione di incorporamenti utilizzando la funzione ML.GENERATE_EMBEDDING potrebbe non riuscire a causa delle quote o della mancata disponibilità del servizio Vertex AI LLM. I dettagli dell'errore vengono restituiti nella colonna ml_generate_embedding_status. Una colonna ml_generate_embedding_status vuota indica che la generazione dell'incorporamento è riuscita.

Per metodi alternativi di generazione di incorporamenti di testo in BigQuery, consulta il tutorial Incorpora testo con modelli TensorFlow preaddestrati.

Crea un indice vettoriale

Se crei un indice vettoriale su una colonna di incorporamento, una ricerca vettoriale eseguita su quella colonna utilizza la tecnica di ricerca Approximate Nearest Neighbor. Questa tecnica migliora le prestazioni della ricerca vettoriale, con il compromesso di ridurre il richiamo e quindi restituire risultati più approssimativi.

Per creare un indice vettoriale, utilizza l'istruzione CREATE VECTOR INDEX DDL (Data Definition Language):

1. Vai alla pagina BigQuery.

   Vai a BigQuery

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

   CREATE OR REPLACE VECTOR INDEX my_index
   ON `bqml_tutorial.embeddings`(ml_generate_embedding_result)
   OPTIONS(index_type = 'IVF',
     distance_type = 'COSINE',
     ivf_options = '{"num_lists":500}')

In genere la creazione di un indice vettoriale richiede solo pochi secondi. Occorrono altri 2 o 3 minuti prima che l'indice vettoriale venga compilato e sia pronto per l'uso.

Verifica la disponibilità dell'indice vettoriale

L'indice vettoriale viene compilato in modo asincrono. Puoi verificare se l'indice è pronto per essere utilizzato eseguendo una query sulla visualizzazione INFORMATION_SCHEMA.VECTOR_INDEXES e verificando che il valore della colonna coverage_percentage sia maggiore di 0 e che il valore della colonna last_refresh_time non sia NULL.

1. Vai alla pagina BigQuery.

   Vai a BigQuery

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

   SELECT table_name, index_name, index_status,
   coverage_percentage, last_refresh_time, disable_reason
   FROM `PROJECT_ID.bqml_tutorial.INFORMATION_SCHEMA.VECTOR_INDEXES`

   Sostituisci PROJECT_ID con l'ID progetto.

Esegui una ricerca di similarità del testo utilizzando l'indice vettoriale

Utilizza la funzione VECTOR_SEARCH per cercare brevetti pertinenti che corrispondono agli incorporamenti generati da una query di testo.

L'argomento top_k determina il numero di corrispondenze da restituire, in questo caso cinque. L'opzione fraction_lists_to_search determina la percentuale di elenchi di indici vettoriali da cercare. L'indice vettoriale che hai creato ha 500 elenchi, quindi il valore fraction_lists_to_search di .01 indica che questa ricerca vettoriale scansiona cinque di questi elenchi. Un valore fraction_lists_to_search inferiore, come mostrato qui, fornisce un richiamo inferiore e prestazioni più rapide. Per saperne di più sugli elenchi di indici vettoriali, consulta l'num_lists opzione di indice vettoriale.

Il modello utilizzato per generare gli incorporamenti in questa query deve essere lo stesso di quello utilizzato per generare gli incorporamenti nella tabella con cui esegui il confronto, altrimenti i risultati di ricerca non saranno accurati.

1. Vai alla pagina BigQuery.

   Vai a BigQuery

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

   SELECT query.query, base.publication_number, base.title, base.abstract
   FROM VECTOR_SEARCH(
     TABLE `bqml_tutorial.embeddings`, 'ml_generate_embedding_result',
     (
     SELECT ml_generate_embedding_result, content AS query
     FROM ML.GENERATE_EMBEDDING(
     MODEL `bqml_tutorial.embedding_model`,
     (SELECT 'improving password security' AS content))
     ),
     top_k => 5, options => '{"fraction_lists_to_search": 0.01}')

   L'output è simile al seguente:

   +-----------------------------+--------------------+-------------------------------------------------+-------------------------------------------------+
   |            query            | publication_number |                       title                     |                      abstract                   |
   +-----------------------------+--------------------+-------------------------------------------------+-------------------------------------------------+
   | improving password security | SG-120868-A1       | Data storage device security method and a...    | Methods for improving security in data stora... |
   | improving password security | SG-10201610585W-A  | Passsword management system and process...      | PASSSWORD MANAGEMENT SYSTEM AND PROCESS ...     |
   | improving password security | SG-148888-A1       | Improved system and method for...               | IMPROVED SYSTEM AND METHOD FOR RANDOM...        |
   | improving password security | SG-194267-A1       | Method and system for protecting a password...  | A system for providing security for a...        |
   | improving password security | SG-120868-A1       | Data storage device security...                 | Methods for improving security in data...       |
   +-----------------------------+--------------------+-------------------------------------------------+-------------------------------------------------+
   

Crea il modello remoto per la generazione di testo

Crea un modello remoto che rappresenti un modello di generazione di testo Vertex AI ospitato:

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

   Vai a BigQuery

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

   CREATE OR REPLACE MODEL `bqml_tutorial.text_model`
     REMOTE WITH CONNECTION `us.CONNECTION_ID`
     OPTIONS (ENDPOINT = 'gemini-1.5-flash-002');

   Sostituisci CONNECTION_ID con l'ID della tua connessione BigQuery.

   Quando visualizzi i dettagli della connessione nella console Google Cloud , CONNECTION_ID è il valore nell'ultima sezione dell'ID connessione completo visualizzato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection.

   Il completamento della query richiede diversi secondi, dopodiché il modello text_model viene visualizzato nel set di dati bqml_tutorial nel riquadro Explorer. Poiché la query utilizza un'istruzione CREATE MODEL per creare un modello, non ci sono risultati della query.

Generare testo arricchito dai risultati della ricerca vettoriale

Inserisci i risultati di ricerca come prompt per generare testo con la funzione ML.GENERATE_TEXT

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

   Vai a BigQuery

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

   SELECT ml_generate_text_llm_result AS generated, prompt
   FROM ML.GENERATE_TEXT(
     MODEL `bqml_tutorial.text_model`,
     (
       SELECT CONCAT(
         'Propose some project ideas to improve user password security using the context below: ',
         STRING_AGG(
           FORMAT("patent title: %s, patent abstract: %s", base.title, base.abstract),
           ',\n')
         ) AS prompt,
       FROM VECTOR_SEARCH(
         TABLE `bqml_tutorial.embeddings`, 'ml_generate_embedding_result',
         (
           SELECT ml_generate_embedding_result, content AS query
           FROM ML.GENERATE_EMBEDDING(
             MODEL `bqml_tutorial.embedding_model`,
            (SELECT 'improving password security' AS content)
           )
         ),
       top_k => 5, options => '{"fraction_lists_to_search": 0.01}')
     ),
     STRUCT(600 AS max_output_tokens, TRUE AS flatten_json_output));

   L'output è simile al seguente:

   +------------------------------------------------+------------------------------------------------------------+
   |            generated                           | prompt                                                     |
   +------------------------------------------------+------------------------------------------------------------+
   | These patents suggest several project ideas to | Propose some project ideas to improve user password        |
   | improve user password security.  Here are      | security using the context below: patent title: Active     |
   | some, categorized by the patent they build     | new password entry dialog with compact visual indication   |
   | upon:                                          | of adherence to password policy, patent abstract:          |
   |                                                | An active new password entry dialog provides a compact     |
   | **I. Projects based on "Active new password    | visual indication of adherence to password policies. A     |
   | entry dialog with compact visual indication of | visual indication of progress towards meeting all          |
   | adherence to password policy":**               | applicable password policies is included in the display    |
   |                                                | and updated as new password characters are being...        |
   +------------------------------------------------+------------------------------------------------------------+
    

Esegui la pulizia

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini, elimini anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Passaggi successivi

• Prova l'esercitazione Analizzare i PDF in una pipeline di generazione RAG (Retrieval Augmented Generation) per scoprire come creare una pipeline RAG basata sui contenuti PDF analizzati.