Cercare un grafico

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.SEARCH nei nodi del grafico per eseguire la ricerca semantica nelle descrizioni degli account.
  • Utilizza la funzione AI.SEARCH sui 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

  1. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. 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 the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  4. Assicurati di disporre dei seguenti ruoli nel progetto: Editor dati BigQuery, Amministratore IAM progetto

    Controlla i ruoli

    1. Nella console Cloud de Confiance vai alla pagina IAM.

      Vai a IAM
    2. Seleziona il progetto.
    3. 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.

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

    1. Nella console Cloud de Confiance vai alla pagina IAM.

      Vai a IAM
    2. Seleziona il progetto.
    3. Fai clic su Concedi l'accesso.
    4. 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.

    5. Fai clic su Seleziona un ruolo, quindi cerca il ruolo.
    6. Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo successivo.
    7. Fai clic su Salva.

gcloud

  1. Installa Google Cloud CLI.

  2. Configura gcloud CLI per utilizzare la tua identità federata.

    Per ulteriori informazioni, vedi Accedi a gcloud CLI con la tua identità federata.

  3. Per inizializzare gcloud CLI, esegui questo comando:

    gcloud init
  4. 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'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.
    • Creare un progetto Cloud de Confiance :

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con 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_ID con il nome del progetto Cloud de Confiance .

  5. Verifica che la fatturazione sia attivata per il tuo progetto Cloud de Confiance .

  6. 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'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    gcloud services enable bigquery.googleapis.com
  7. Concedi ruoli al tuo account utente. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli IAM: roles/bigquery.dataEditor, roles/resourcemanager.projectIamAdmin

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Sostituisci quanto segue:

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