グラフを検索する

このチュートリアルでは、自律型エンベディング生成と AI.SEARCH 関数を使用して、グラフデータに対してセマンティック検索を行う方法について説明します。

目標

このチュートリアルでは、次のタスクについて説明します。

  • ユーザー、金融口座、口座の所有権、口座の移行に関する情報を保持するテーブルを作成します。
  • 自律型エンベディング生成を使用して、エンベディングのメンテナンス ワークフローを簡素化します。
  • テーブルに保存されているデータ間の関係を定義するグラフを作成します。
  • グラフノードで AI.SEARCH 関数を使用して、アカウントの説明に対してセマンティック検索を実行します。
  • グラフエッジで AI.SEARCH 関数を使用して、アカウント移行メモに対してセマンティック検索を実行します。

費用

このドキュメントでは、課金対象である次の Cloud de Confiance by S3NSコンポーネントを使用します。

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

このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

始める前に

コンソール

  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. プロジェクトに次のロールがあることを確認します。 BigQuery データ編集者、プロジェクト IAM 管理者

    ロールを確認する

    1. Cloud de Confiance コンソールで、[IAM] ページに移動します。

      IAM に移動
    2. プロジェクトを選択します。

    3. [プリンシパル] 列で、自分または自分が所属するグループの行をすべて確認します。所属するグループについては、管理者にお問い合わせください。

    4. 自分のメールアドレスを含む行の [ロール] 列で、ロールのリストに必要なロールが含まれているかどうか確認します。

    ロールを付与する

    1. Cloud de Confiance コンソールで、[IAM] ページに移動します。

      IAM に移動
    2. プロジェクトを選択します。
    3. [ アクセスを許可] をクリックします。

    4. [新しいプリンシパル] フィールドに、ユーザー ID を入力します。 これは通常、Workforce Identity プール内のユーザーの ID です。詳細については、IAM ポリシーで Workforce プールユーザーを表すをご覧いただくか、管理者にお問い合わせください。

    5. [ロールを選択] をクリックし、ロールを検索します。
    6. 追加のロールを付与するには、 [別のロールを追加] をクリックして各ロールを追加します。
    7. [保存] をクリックします。

gcloud

  1. Google Cloud CLI をインストールします。

  2. フェデレーション ID（連携 ID）を使用するように gcloud CLI を構成します。

    詳細については、連携 ID を使用して gcloud CLI にログインするをご覧ください。

  3. gcloud CLI を初期化するには、次のコマンドを実行します。

    gcloud init

  4. Cloud de Confiance プロジェクトを作成または選択します。

    プロジェクトの選択または作成に必要なロール

    • プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
    • プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。詳しくは、ロールを付与する方法をご覧ください。

    • Cloud de Confiance プロジェクトを作成します。

      gcloud projects create PROJECT_ID

      PROJECT_ID は、作成する Cloud de Confiance プロジェクトの名前に置き換えます。

    • 作成した Cloud de Confiance プロジェクトを選択します。

      gcloud config set project PROJECT_ID

      PROJECT_ID は、 Cloud de Confiance プロジェクトの名前に置き換えます。

  5. Cloud de Confiance プロジェクトに対して課金が有効になっていることを確認します。

  6. BigQuery API を有効にします。

    API を有効にするために必要なロール

    API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。ロールを付与する方法を確認する。

    gcloud services enable bigquery.googleapis.com

  7. ユーザー アカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。 roles/bigquery.dataEditor, roles/resourcemanager.projectIamAdmin 

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

    次のように置き換えます。

テーブルを作成する

次の例で作成するテーブルとグラフを保存するには、データセットを作成します。次のクエリは、graph_search という名前のデータセットを作成します。

CREATE SCHEMA IF NOT EXISTS graph_search;

次の表には、ユーザーとアカウントに関する情報と、これらの各エンティティ間の関係が記載されています。

  • Person: 人物に関する情報。
  • Account: 銀行口座に関する情報。
  • PersonOwnAccount: どのアカウントを誰が所有しているかに関する情報。
  • AccountTransferAccount: アカウント間の転送に関する情報。

これらのテーブルを作成するには、次の 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
);

Account テーブルと AccountTransferAccount テーブルは、自律型エンベディング生成を使用して、description 列と notes 列のエンベディングを維持します。

このチュートリアルでは、BigQuery で実行され、短い文字列に適した embeddinggemma-300m モデルを使用します。128 個を超えるトークンを含む長い文字列の場合は、text-embedding-005 などの別のエンベディング モデルを選択する必要があります。詳細については、エンベディング モデルの選択をご覧ください。

データの挿入

次のクエリは、テーブルにサンプルデータを挿入します。INSERT ステートメントでは、エンベディング列が省略されています。BigQuery はこれらの列を自動的に入力します。

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

グラフを作成する

次のクエリでは、CREATE PROPERTY GRAPH ステートメントを使用して、graph_search データセットに FinGraph というグラフを作成します。Account テーブルと Person テーブルはノードテーブルです。AccountTransferAccount テーブルと PersonOwnAccount テーブルはエッジテーブルで、ノードテーブル間の関係を表します。

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

ノードを検索

次のクエリは、旅行と休暇のアカウントの所有者を示します。最初のクエリでは、DECLARE ステートメントを使用して similar_account という変数を作成します。この変数は、accounts for leisure travel and vacation に意味的に最も類似した説明を持つアカウントを検索する AI.SEARCH の呼び出しを含む DEFAULT 句で初期化されます。クエリは、AI.SEARCH の呼び出しで top_k 引数を 2 に設定して、結果の数を制限します。2 番目のクエリは、アカウントの説明とともにアカウント所有者の名前を返すグラフクエリです。

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;

次のような結果になります。

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

エッジを検索

次のクエリは、食品の支払いに関連するアカウントの移行を行ったユーザーを示します。最初のクエリでは、AI.SEARCH 関数を使用して food_transfers という変数を設定しています。この変数には、関連付けられたメモが food に最も意味的に類似している転送の注文番号が保持されます。クエリは、AI.SEARCH の呼び出しで top_k 引数を 2 に設定して、結果の数を制限します。2 番目のクエリは、送金メモとともにアカウント所有者の名前を返すグラフクエリです。

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;

次のような結果になります。

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

ベクトル インデックスを作成する

ベクトル インデックスを使用すると、検索のレイテンシと計算コストを削減できます。このチュートリアルのテーブルは小さすぎて、ベクトル インデックスを使用できません。ベクトル インデックスは、テーブルが大きく、通常は数百万行ある場合に便利です。BigQuery には、IVF と TreeAH の 2 種類のインデックスがあります。インデックスの作成とタイプの選択の詳細については、ベクトル インデックスを管理するをご覧ください。

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

プロジェクトを削除する

    Cloud de Confiance プロジェクトを削除する:

    gcloud projects delete PROJECT_ID

次のステップ