Rechercher dans un graphique

Ce tutoriel vous explique comment effectuer une recherche sémantique sur vos données graphiques à l'aide de la génération d'embeddings autonomes et de la fonction AI.SEARCH.

Objectifs

Ce tutoriel couvre les tâches suivantes :

  • Créez des tables contenant des informations sur les personnes, les comptes financiers, la propriété des comptes et les transferts de comptes.
  • Utilisez la génération autonome d'embeddings pour simplifier votre workflow de maintenance des embeddings.
  • Créez un graphique qui définit les relations entre les données stockées dans vos tableaux.
  • Utilisez la fonction AI.SEARCH sur les nœuds de votre graphique pour effectuer une recherche sémantique sur les descriptions de compte.
  • Utilisez la fonction AI.SEARCH sur les bords de votre graphique pour effectuer une recherche sémantique sur les notes de transfert de compte.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Cloud de Confiance by S3NS :

  • BigQuery: You incur costs for the data that you process in BigQuery.

Une fois que vous avez terminé les tâches décrites dans ce document, supprimez les ressources que vous avez créées pour éviter que des frais vous soient facturés. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

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. Assurez-vous de disposer du ou des rôles suivants dans le projet : Éditeur de données BigQuery, Administrateur IAM du projet

    Vérifier les rôles

    1. Dans la console Cloud de Confiance , accédez à la page IAM.

      Accéder à IAM
    2. Sélectionnez le projet.
    3. Dans la colonne Compte principal, recherchez toutes les lignes qui vous identifient ou identifient un groupe dont vous faites partie. Pour savoir à quels groupes vous appartenez, contactez votre administrateur.

    4. Pour toutes les lignes qui vous spécifient ou vous incluent, consultez la colonne Rôle pour vous assurer que la liste inclut les rôles requis.

    Attribuer les rôles

    1. Dans la console Cloud de Confiance , accédez à la page IAM.

      Accéder à IAM
    2. Sélectionnez le projet.
    3. Cliquez sur  Accorder l'accès.
    4. Dans le champ Nouveaux comptes principaux, saisissez votre identifiant utilisateur. Il s'agit généralement de l'identifiant associé à un utilisateur dans un pool d'identités de personnel. Pour en savoir plus, consultez Représenter les utilisateurs de pools de personnel dans les stratégies IAM ou contactez votre administrateur.

    5. Cliquez sur Sélectionner un rôle, puis recherchez le rôle.
    6. Pour attribuer des rôles supplémentaires, cliquez sur  Ajouter un autre rôle et ajoutez tous les rôles supplémentaires.
    7. Cliquez sur Enregistrer.

gcloud

  1. Installez la Google Cloud CLI.

  2. Configurez la gcloud CLI afin d'utiliser votre identité fédérée.

    Pour en savoir plus, consultez Se connecter à la gcloud CLI avec votre identité fédérée.

  3. Pour initialiser la gcloud CLI, exécutez la commande suivante :

    gcloud init
  4. Créez ou sélectionnez un projet Cloud de Confiance .

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.
    • Créez un projet Cloud de Confiance  :

      gcloud projects create PROJECT_ID

      Remplacez PROJECT_ID par le nom du projet Cloud de Confiance que vous créez.

    • Sélectionnez le projet Cloud de Confiance que vous avez créé :

      gcloud config set project PROJECT_ID

      Remplacez PROJECT_ID par le nom de votre projet Cloud de Confiance .

  5. Vérifiez que la facturation est activée pour votre projet Cloud de Confiance .

  6. Activez l'API BigQuery :

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

    gcloud services enable bigquery.googleapis.com
  7. Attribuez des rôles à votre compte utilisateur. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants : roles/bigquery.dataEditor, roles/resourcemanager.projectIamAdmin

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

    Remplacez les éléments suivants :

Créer des tables

Pour stocker les tables et le graphique que vous créez dans les exemples suivants, créez un ensemble de données. La requête suivante crée un ensemble de données nommé graph_search :

CREATE SCHEMA IF NOT EXISTS graph_search;

Les tableaux suivants contiennent des informations sur les personnes et les comptes, ainsi que sur les relations entre chacune de ces entités :

  • Person : informations sur les personnes.
  • Account : informations sur les comptes bancaires.
  • PersonOwnAccount : informations sur les propriétaires des comptes.
  • AccountTransferAccount : informations sur les transferts entre comptes.

Pour créer ces tables, exécutez les instructions CREATE TABLE suivantes :

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
);

Les tables Account et AccountTransferAccount utilisent la génération autonome d'embeddings pour gérer les embeddings de leurs colonnes description et notes.

Dans ce tutoriel, nous utilisons le modèle embeddinggemma-300m, car il s'exécute dans BigQuery et fonctionne bien pour les chaînes courtes. Pour les chaînes plus longues qui dépassent 128 jetons, vous devez choisir un autre modèle d'embedding, tel que text-embedding-005. Pour en savoir plus, consultez Choisir un modèle d'embedding.

Insérer des données

Les requêtes suivantes insèrent des exemples de données dans vos tables. Les instructions INSERT omettent les colonnes d'intégration, que BigQuery renseigne automatiquement.

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");

Créer un graphique

La requête suivante utilise l'instruction CREATE PROPERTY GRAPH pour créer un graphique appelé FinGraph dans l'ensemble de données graph_search. Les tables Account et Person sont les tables de nœuds. Les tables AccountTransferAccount et PersonOwnAccount sont les tables d'arêtes, qui représentent les relations entre les tables de nœuds.

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
);

Rechercher des nœuds

Les requêtes suivantes montrent qui possède des comptes pour les voyages de loisirs et les vacances. La première requête utilise une instruction DECLARE pour créer une variable appelée similar_account. La variable est initialisée dans la clause DEFAULT avec un appel à AI.SEARCH qui recherche les comptes dont les descriptions sont les plus proches sémantiquement de accounts for leisure travel and vacation. La requête définit l'argument top_k sur 2 dans l'appel à AI.SEARCH pour limiter le nombre de résultats. La deuxième requête est une requête de graphique qui renvoie le nom du propriétaire du compte ainsi que la description du compte.

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;

Le résultat ressemble à ce qui suit :

+------+-----------------------------------------+
| name | description                             |
+------+-----------------------------------------+
| Dana | Saving up for travel                    |
| Alex | Fund for a refreshing tropical vacation |
+------+-----------------------------------------+

Rechercher des arêtes

Les requêtes suivantes montrent qui a effectué des transferts de compte liés à des paiements de nourriture. La première requête utilise la fonction AI.SEARCH pour remplir une variable appelée food_transfers. Cette variable contient le numéro de commande des transferts dont la note associée est la plus proche sémantiquement de food. La requête définit l'argument top_k sur 2 dans l'appel à AI.SEARCH pour limiter le nombre de résultats. La deuxième requête est une requête de graphique qui renvoie le nom du propriétaire du compte ainsi que la note de transfert.

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;

Le résultat ressemble à ce qui suit :

+------+---------------------------+
| name | notes                     |
+------+---------------------------+
| Dana | loved the lunch           |
| Lee  | for shared cost of dinner |
+------+---------------------------+

Créer un index vectoriel

Les index vectoriels réduisent la latence et le coût de calcul de vos recherches. Les tables de ce tutoriel sont trop petites pour utiliser un index vectoriel. Les index vectoriels sont utiles lorsque vos tables sont volumineuses, généralement avec des millions de lignes. BigQuery propose deux types d'index : IVF et TreeAH. Pour en savoir plus sur la création d'un index et le choix d'un type, consultez Gérer les index vectoriels.

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

Supprimer le projet

    Supprimer un projet Cloud de Confiance  :

    gcloud projects delete PROJECT_ID

Étapes suivantes