Questo tutorial mostra come eseguire la ricerca semantica sui dati del grafico utilizzando la
generazione autonoma di embedding
e la
funzione AI.SEARCH.
Obiettivi
Questo tutorial spiega le seguenti attività:- Crea tabelle che contengano informazioni su persone, conti finanziari, proprietà dell'account e trasferimenti dell'account.
- Utilizza la generazione autonoma di embedding per semplificare il flusso di lavoro di manutenzione degli embedding.
- Crea un grafico che definisca le relazioni tra i dati archiviati nelle tabelle.
- Utilizza la
funzione
AI.SEARCHnei nodi del grafico per eseguire la ricerca semantica nelle descrizioni degli account. - Utilizza la funzione
AI.SEARCHsui bordi del grafico per eseguire la ricerca semantica nelle note sul trasferimento dell'account.
Costi
In questo documento vengono utilizzati i seguenti componenti fatturabili di Cloud de Confiance by S3NS:
- BigQuery: You incur costs for the data that you process in BigQuery.
Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per saperne di più, consulta Esegui la pulizia.
Prima di iniziare
Console
-
In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Cloud de Confiance project.
Enable the BigQuery API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.-
Assicurati di disporre dei seguenti ruoli nel progetto: Editor dati BigQuery, Amministratore IAM progetto
Controlla i ruoli
-
Nella console Cloud de Confiance vai alla pagina IAM.
Vai a IAM - Seleziona il progetto.
-
Nella colonna Entità, trova tutte le righe che identificano te o un gruppo di cui fai parte. Per scoprire a quali gruppi appartieni, contatta il tuo amministratore.
- Per tutte le righe che ti specificano o ti includono, controlla la colonna Ruolo per verificare se l'elenco dei ruoli include i ruoli richiesti.
Concedi i ruoli
-
Nella console Cloud de Confiance vai alla pagina IAM.
Vai a IAM - Seleziona il progetto.
- Fai clic su Concedi l'accesso.
-
Nel campo Nuove entità, inserisci il tuo identificatore dell'utente. In genere si tratta dell'identificatore di un utente in un pool di identità della forza lavoro. Per maggiori dettagli, consulta Rappresenta gli utenti del pool di forza lavoro nelle policy IAM o contatta l'amministratore.
- Fai clic su Seleziona un ruolo, quindi cerca il ruolo.
- Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo successivo.
- Fai clic su Salva.
-
gcloud
-
Installa Google Cloud CLI.
-
Configura gcloud CLI per utilizzare la tua identità federata.
Per ulteriori informazioni, vedi Accedi a gcloud CLI con la tua identità federata.
-
Per inizializzare gcloud CLI, esegui questo comando:
gcloud init -
Crea o seleziona un Cloud de Confiance progetto.
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 il quale ti è stato concesso un ruolo.
-
Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto
(
roles/resourcemanager.projectCreator), che contiene l'autorizzazioneresourcemanager.projects.create. Scopri come concedere i ruoli.
-
Creare un progetto Cloud de Confiance :
gcloud projects create PROJECT_ID
Sostituisci
PROJECT_IDcon un nome per il progetto Cloud de Confiance che stai creando. -
Seleziona il progetto Cloud de Confiance che hai creato:
gcloud config set project PROJECT_ID
Sostituisci
PROJECT_IDcon il nome del progetto Cloud de Confiance .
-
Verifica che la fatturazione sia attivata per il tuo progetto Cloud de Confiance .
Abilita l'API BigQuery:
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (
roles/serviceusage.serviceUsageAdmin), che include l'autorizzazioneserviceusage.services.enable. Scopri come concedere i ruoli.gcloud services enable bigquery.googleapis.com
-
Concedi ruoli al tuo account utente. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli IAM:
roles/bigquery.dataEditor, roles/resourcemanager.projectIamAdmingcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto.USER_IDENTIFIER: l'identificatore del tuo account utente account. Per esempi, vedi Rappresenta gli utenti del pool di forza lavoro nelle policy IAM.ROLE: il ruolo IAM che concedi al tuo account utente.
Crea tabelle
Per archiviare le tabelle e il grafico che crei negli esempi seguenti,
crea un set di dati.
La seguente query crea un set di dati denominato graph_search:
CREATE SCHEMA IF NOT EXISTS graph_search;
Le tabelle seguenti contengono informazioni su persone e account e sulle relazioni tra ciascuna di queste entità:
Person: informazioni sulle persone.Account: informazioni sui conti bancari.PersonOwnAccount: informazioni su chi è il proprietario di quali account.AccountTransferAccount: informazioni sui trasferimenti tra conti.
Per creare queste tabelle, esegui le seguenti
istruzioni CREATE TABLE:
CREATE OR REPLACE TABLE graph_search.Person (
id INT64,
name STRING,
PRIMARY KEY (id) NOT ENFORCED
);
CREATE OR REPLACE TABLE graph_search.Account (
id INT64,
create_time TIMESTAMP,
is_blocked BOOL,
description STRING,
description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
GENERATED ALWAYS AS (
AI.EMBED(description, model => 'embeddinggemma-300m')
) STORED OPTIONS( asynchronous = TRUE ),
PRIMARY KEY (id) NOT ENFORCED
);
CREATE OR REPLACE TABLE graph_search.PersonOwnAccount (
id INT64 NOT NULL,
account_id INT64 NOT NULL,
create_time TIMESTAMP,
PRIMARY KEY (id, account_id) NOT ENFORCED,
FOREIGN KEY (id) REFERENCES graph_search.Person(id) NOT ENFORCED,
FOREIGN KEY (account_id) REFERENCES graph_search.Account(id) NOT ENFORCED
);
CREATE OR REPLACE TABLE graph_search.AccountTransferAccount (
id INT64 NOT NULL,
to_id INT64 NOT NULL,
amount FLOAT64,
create_time TIMESTAMP NOT NULL,
order_number STRING,
notes STRING,
notes_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
GENERATED ALWAYS AS (
AI.EMBED(notes, model => 'embeddinggemma-300m')
) STORED OPTIONS( asynchronous = TRUE ),
PRIMARY KEY (id, to_id, create_time) NOT ENFORCED,
FOREIGN KEY (id) REFERENCES graph_search.Account(id) NOT ENFORCED,
FOREIGN KEY (to_id) REFERENCES graph_search.Account(id) NOT ENFORCED
);
Le tabelle Account e AccountTransferAccount utilizzano la generazione di incorporamenti autonomi
per mantenere gli incorporamenti per le colonne description e notes.
In questo tutorial utilizziamo il modello embeddinggemma-300m perché viene eseguito in
BigQuery e funziona bene per le stringhe brevi. Per le stringhe più lunghe
che superano i 128 token, devi scegliere un modello di incorporamento diverso, ad esempio
text-embedding-005. Per saperne di più, leggi l'articolo su come
scegliere un modello di incorporamento.
Inserisci i dati
Le seguenti query inseriscono alcuni dati di esempio nelle tabelle. Le istruzioni
INSERT
omettono le colonne di incorporamento e BigQuery le compila
automaticamente.
INSERT INTO graph_search.Account
(id, create_time, is_blocked, description)
VALUES
(7,"2020-01-10 06:22:20.222",false,"Fund for a refreshing tropical vacation"),
(16,"2020-01-27 17:55:09.206",true,"Fund for a rainy day!"),
(20,"2020-02-18 05:44:20.655",false,"Saving up for travel");
INSERT INTO graph_search.Person
(id, name)
VALUES
(1,"Alex"),
(2,"Dana"),
(3,"Lee");
INSERT INTO graph_search.AccountTransferAccount
(id, to_id, amount, create_time, order_number, notes)
VALUES
(7,16,300,"2020-08-29 15:28:58.647","304330008004315", "wedding present"),
(7,16,100,"2020-10-04 16:55:05.342","304120005529714", "birthday gift"),
(16,20,300,"2020-09-25 02:36:14.926","103650009791820", "for shared cost of dinner"),
(20,7,500,"2020-10-04 16:55:05.342","304120005529714", "fees for tuition"),
(20,16,200,"2020-10-17 03:59:40.247","302290001484851", "loved the lunch");
INSERT INTO graph_search.PersonOwnAccount
(id, account_id, create_time)
VALUES
(1,7,"2020-01-10 06:22:20.222"),
(2,20,"2020-01-27 17:55:09.206"),
(3,16,"2020-02-18 05:44:20.655");
Creare un grafico
La seguente query utilizza l'istruzione
CREATE PROPERTY GRAPH
per creare un grafico denominato FinGraph nel set di dati graph_search.
Le tabelle Account e Person sono le tabelle dei nodi. Le tabelle
AccountTransferAccount e PersonOwnAccount
sono le tabelle perimetrali, che rappresentano le relazioni tra le tabelle dei nodi.
CREATE OR REPLACE PROPERTY GRAPH graph_search.FinGraph
NODE TABLES (graph_search.Account, graph_search.Person)
EDGE TABLES (
graph_search.PersonOwnAccount
SOURCE KEY (id) REFERENCES Person (id)
DESTINATION KEY (account_id) REFERENCES Account (id)
LABEL Owns,
graph_search.AccountTransferAccount
SOURCE KEY (id) REFERENCES Account (id)
DESTINATION KEY (to_id) REFERENCES Account (id)
LABEL Transfers
);
Cerca nodi
Le seguenti query mostrano chi è il proprietario degli account per viaggi di piacere e vacanze. La prima query utilizza un'istruzione
DECLARE
per creare una variabile denominata
similar_account. La variabile viene inizializzata nella clausola DEFAULT con
una chiamata a AI.SEARCH che trova gli account le cui
descrizioni sono semanticamente più simili a
accounts for leisure travel and vacation. La query imposta l'argomento
top_k su 2 nella chiamata a AI.SEARCH per limitare il numero di
risultati. La seconda query è una query del grafico che restituisce il nome del proprietario dell'account
insieme alla descrizione dell'account.
DECLARE similar_account DEFAULT ((
SELECT ARRAY_AGG(base.id)
FROM
AI.SEARCH(
(SELECT * FROM graph_search.Account WHERE description_embedding IS NOT NULL),
'description',
'accounts for leisure travel and vacation',
top_k => 2)
));
GRAPH graph_search.FinGraph
MATCH (p:Person)-[:Owns]->(a:Account)
WHERE a.id IN UNNEST(similar_account)
RETURN p.name, a.description;
Il risultato è simile al seguente:
+------+-----------------------------------------+
| name | description |
+------+-----------------------------------------+
| Dana | Saving up for travel |
| Alex | Fund for a refreshing tropical vacation |
+------+-----------------------------------------+
Cerca bordi
Le seguenti query mostrano chi ha effettuato trasferimenti di account correlati ai pagamenti per il cibo.
La prima query utilizza la funzione AI.SEARCH per popolare una variabile chiamata food_transfers. Questa variabile contiene il numero d'ordine dei
trasferimenti la cui nota associata è semanticamente più simile a
food. La query imposta l'argomento top_k su 2 nella chiamata a
AI.SEARCH per limitare il numero di
risultati. La seconda query è una query del grafico che restituisce il nome del proprietario dell'account
insieme alla nota di trasferimento.
DECLARE food_transfers DEFAULT ((
SELECT ARRAY_AGG(base.order_number)
FROM
AI.SEARCH(
(SELECT * FROM graph_search.AccountTransferAccount WHERE notes_embedding IS NOT NULL),
'notes',
'food',
top_k => 2)
));
GRAPH graph_search.FinGraph
MATCH (p:Person)-[:Owns]->(:Account)-[t:Transfers]->(:Account)
WHERE t.order_number IN UNNEST(food_transfers)
RETURN p.name, t.notes;
Il risultato è simile al seguente:
+------+---------------------------+
| name | notes |
+------+---------------------------+
| Dana | loved the lunch |
| Lee | for shared cost of dinner |
+------+---------------------------+
Crea un indice vettoriale
Gli indici vettoriali riducono la latenza e il costo di calcolo delle ricerche. Le tabelle di questo tutorial sono troppo piccole per utilizzare un indice vettoriale. Gli indici vettoriali sono utili quando le tabelle sono grandi, in genere con milioni di righe. BigQuery offre due tipi di indice: IVF e TreeAH. Per saperne di più sulla creazione di un indice e sulla scelta di un tipo, consulta Gestire gli indici vettoriali.
Esegui la pulizia
Per evitare che al tuo Account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.
Elimina il progetto
Elimina un progetto Cloud de Confiance :
gcloud projects delete PROJECT_ID
Passaggi successivi
- Scopri di più su BigQuery Graph.
- Scopri come creare ed eseguire query su un grafico.
- Scopri di più sulla creazione di un indice vettoriale e sull'esecuzione della ricerca semantica e di RAG.