1. 概要
「ダークデータ」の苦労は誰もが知っています。クラウド ストレージ バケットに保存されている PDF、画像、テキスト ファイルは、SQL クエリや BI ダッシュボードから完全に隠されています。従来、このデータのロックを解除するには、複雑な OCR パイプライン、手動でのデータ入力、脆弱なカスタム スクリプトが必要でした。
今はもうありません。
このラボでは、テキスト、テーブル、画像にまたがる 400 個の非構造化 PDF ファイルを、関係が自動的に推測されるクリーンな構造化 BigQuery テーブルに変換する方法について説明します。BigQuery Knowledge Catalog と Dataplex を使用して、数分で完了します。
作成するアプリの概要
具体例として、急成長しているフローズン ヨーグルトのフランチャイズ店を想定してみましょう。
このフローズン ヨーグルト店のデータを管理しているとします。レシピとサプライヤーの仕様書が数百件あり、すべて PDF として保存されています。経営陣は、店舗マネージャーと顧客が商品の詳細をクエリできる AI エージェントをリリースしたいと考えています。
最悪のシナリオは次のとおりです。お客様から「Midnight Swirl フローズン ヨーグルトに興味があります。アレルゲンは含まれていますか？」と質問されました。
これに回答するには、通常、システムで次の操作を行う必要があります。
- 「Midnight Swirl」のレシピ PDF を探す。
- 材料（「ココアパウダー」、「乳製品ベース」、「乳化剤 X」など）を読む。
- 数十件のサプライヤー PDF を検索して、特定の材料の仕様書を見つける。
- サプライヤーのシートで、これらの材料に関連する隠れたアレルゲンを確認する。
実行時に 400 個の未加工 PDF を読み取って、これをオンザフライで行う AI エージェントを構築しようとすると、処理が遅く、コストがかかり、ハルシネーションが発生しやすくなります。代わりに、セマンティック推論を使用して、これらすべてをリレーショナル データベースに抽出します。これにより、将来の AI エージェントは高速になり、事実に基づいた SQL データに 100% 基づくようになります。
構築を開始しましょう。
学習内容
- ソースファイル（PDF）用の Cloud Storage バケットを設定する方法
- Knowledge Catalog で Datascan ジョブとセマンティック推論を設定して実行し、ソース PDF からデータを抽出し、接続とコンテキストをセマンティックに推論して BigQuery に保存する方法
- BigQuery エージェントを使用して、新しく作成したデータセットとチャットする方法
要件
2. 始める前に
プロジェクトを作成する
- Google Cloud コンソールのプロジェクト選択ページで、Google Cloud プロジェクトを選択または作成します。
- Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
- Google Cloud 上で動作するコマンドライン環境の Cloud Shell を使用します。Google Cloud コンソールの上部にある「Cloud Shell をアクティブにする」アイコン をクリックします。
![[Cloud Shell をアクティブにする] ボタンの画像](https://codelabs.developers.google.com/static/dark-data-agent-chat/img/91567e2f55467574.png?hl=ja)
- Cloud Shell に接続したら、次のコマンドを使用して、すでに認証済みであることと、プロジェクトがプロジェクト ID に設定されていることを確認します。
gcloud auth list
- Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。
gcloud config list project
- 認証する場合は
gcloud auth login
- プロジェクトが設定されていない場合は、次のコマンドを使用して設定します。
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project <YOUR_PROJECT_ID>
- 必要な API を有効にします。次のコマンドを実行して、必要なすべての API を有効にします。
gcloud services enable \
dataplex.googleapis.com \
datacatalog.googleapis.com \
discoveryengine.googleapis.com \
bigqueryconnection.googleapis.com \
bigquery.googleapis.com \
aiplatform.googleapis.com \
cloudresourcemanager.googleapis.com \
serviceusage.googleapis.com \
storage.googleapis.com
注意点とトラブルシューティング
「ゴースト プロジェクト」 シンドローム |
|
**請求** のバリケード | プロジェクトを有効にしましたが、請求先アカウントを忘れていました。AlloyDB は高性能エンジンです。「ガソリン タンク」（請求）が空の場合、起動しません。 |
API の伝播 の遅延 | [API を有効にする] をクリックしましたが、コマンドラインに |
割り当て の問題 | 新しいトライアル アカウントを使用している場合は、AlloyDB インスタンスのリージョン割り当てに達している可能性があります。 |
「非表示」のサービス エージェント | AlloyDB サービス エージェントに ロールが自動的に付与されない場合があります。 |
3. Google Cloud Storage バケットの設定
このセクションでは、Froyo のレシピとサプライヤーのデータを保存するために、BigQuery 内に組織構造を作成します。特に、Froyo の商品の詳細を保存します。また、Cloud リソース接続を確立します。これは、BigQuery が Cloud Storage などの外部ソースからファイルを読み取ることができる安全な「ブリッジ」として機能します。
始める前に:
このリポジトリには、このプロジェクトで使用するレシピとサプライヤーの PDF ファイルが含まれています。これらのファイルをダウンロードしてください。ファイルをダウンロードする手順は次のとおりです。
Cloud Shell で、次のコマンドを実行します。
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/next-26-keynotes.git
新しく作成したフォルダに移動します。
cd next-26-keynotes
data-cloud-demo フォルダをプルします。
git sparse-checkout set genkey/data-cloud-demo
チェックアウトが完了したら、data-cloud-demo フォルダに移動し、ZIP ファイルを解凍して Codelab アセットにアクセスします。
バケットを作成し、フローズン ヨーグルト（レシピとサプライヤー）の PDF ファイルをアップロードする
- Google Cloud コンソールで、[Cloud Storage のバケット] ページに移動します。
- [作成] をクリックします。
- [**バケットの作成**] ページでユーザーのバケット情報を入力します。次の各ステップの後に、[続行] をクリックして次のステップに進みます。
- In the [**はじめに**] セクションで、バケット名を入力します。例: froyo_data
- [**データの保存場所の選択**] セクションで、[リージョン] を選択し、リージョンを入力します。us-central1
- In the [**オブジェクトへのアクセスを制御する方法を選択する**] セクションで、[このバケットに対する公開アクセス禁止を適用する] チェックボックスをオフにします。
- [作成] をクリックします。
- バケットのリストで、作成したバケットをクリックします。
- バケットの [オブジェクト] タブで、[アップロード] をクリックし、[フォルダをアップロード] をクリックします。
- この Codelab の「始める前に」セクションで抽出した recipes フォルダを選択します。
- [アップロード] をクリックします。
- suppliers フォルダに対してアップロード プロセスを繰り返します。
アップロードすると、バケット構造は次のようになります（バケット名は任意です）。
4. BigQuery 接続の設定
Cloud リソース接続を作成します。これにより、外部ファイルにアクセスするための BigQuery の「ID カード」として機能する一意のサービス アカウントが生成されます。
- [BigQuery] ページに移動します。
- 左側のペインで、 [エクスプローラ] をクリックします。左側のペインが表示されていない場合は、 [左ペインを開く] をクリックしてペインを開きます。
- [エクスプローラ] ペインで、プロジェクト名を開き、[接続] をクリックします。
- [接続] ページで、[接続を作成] をクリックします。
- [接続タイプ] で、[Vertex AI リモートモデル、リモート関数、BigLake、Spanner（Cloud リソース）] を選択します。
- [接続 ID] フィールドに接続 ID 名を入力します。
- bq-connection。この ID は、この Codelab の後半でデータスキャンを設定するときに必要になるため、メモしておいてください。
- [ロケーション タイプ] を [リージョン] に設定し、リージョンを選択します。たとえば、us-central1 などです。接続は、データセットなどの他のリソースと同じリージョンに配置する必要があります。
- [接続を作成] をクリックします。
- [接続へ移動] をクリックします。
- [接続情報] ペインで、以降の手順で使用するサービス アカウント ID をコピーします。サービス アカウントは bqcx-**********-qn3a@gcp-sa-bigquery-condel.iam.gserviceaccount.com のようになります。
5. 権限の設定
- Cloud Storage オブジェクトと Knowledge Catalog にアクセスするために必要な権限を BigQuery 接続に付与する
[IAM と管理] ページに移動し、[プリンシパル別に表示] セクションで [アクセス権を付与] ボタンをクリックし、前のステップでコピーしたサービス アカウントを貼り付けてプリンシパルを追加します。[ロール] セクションで、次のロールの名前を 1 つずつ追加して保存します。
- roles/storage.objectUser
- roles/storage.objectViewer
- roles/bigquery.user
- roles/bigquery.dataEditor
- roles/aiplatform.viewer
- roles/agentplatform.user
- roles/storage.admin
- roles/dataproc.serviceAgent
- roles/dataplex.discoveryPublishingServiceAgent
- roles/dataplex.serviceAgent
- roles/dataplex.securityAdmin
- Cloud Storage バケットにアクセスする権限を Dataplex サービス アカウントに付与する
[IAM と管理] ページに移動し、[プリンシパル別に表示] セクションで [アクセス権を付与] ボタンをクリックし、[新しいプリンシパル] テキストバーに「Dataplex」と入力してプリンシパルを追加します。自動補完されるリストから、次のような Dataplex サービス アカウント プリンシパルを選択します。
service-*********@ gcp-sa-dataplex.iam.gserviceaccount.com
このサービス アカウントに次のロールを付与します。
- roles/storage.objectUser
- roles/storage.objectViewer
- roles/storage.viewer
- roles/dataplex.discoveryBigLakePublishingServiceAgentroles/storage.objectUser
- roles/storage.objectViewer
- roles/storage.viewer
- roles/dataplex.discoveryBigLakePublishingServiceAgentroles/storage.objectUser
- roles/storage.objectViewer
- roles/storage.viewer
- roles/dataplex.discoveryBigLakePublishingServiceAgent
6. Knowledge Catalog の設定
Knowledge Catalog を構築して非構造化データを統合し、非構造化ファイル（PDF レシピや PDF サプライヤーなど）の検出を自動化します。
- curl を使用して DataScan を作成する
このジョブはコンソールから作成することもできますが、このセクションでは、datascan_ID を追加して BigQuery データセットを指定することで、Cloud Storage バケットのスキャンを作成します。その後、Knowledge Catalog は BigQuery に PDF のエントリを自動的に作成します。
関心のある現在の有効なプロジェクトの Cloud Shell ターミナルから、次のコマンドセットを実行します。
# 1. Set your variables
PROJECT_ID="<PROJECT_ID>"
REGION="<REGION>"
ENV_SUFFIX="stg1"
DATASCAN_ID="froyo-data-${ENV_SUFFIX}"
BUCKET_NAME="<BUCKET_NAME>"
# 2. Set this to the Name of the connection you created in Step 7
CONNECTION_ID="<CONNECTION_ID_NAME>"
# 3. Define the API Endpoint
DATAPLEX_API="dataplex.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}"
# 4. Create the DataScan via CURL
echo "Creating Dataplex DataScan: ${DATASCAN_ID}..."
curl -X POST "https://$DATAPLEX_API/dataScans?dataScanId=${DATASCAN_ID}" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"data": {
"resource": "//storage.googleapis.com/projects/'"${PROJECT_ID}"'/buckets/'"${BUCKET_NAME}"'"
},
"executionSpec": {
"trigger": {
"on_demand": {}
}
},
"dataDiscoverySpec": {
"bigqueryPublishingConfig": {
"tableType": "BIGLAKE",
"connection": "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/connections/'"${CONNECTION_ID}"'"
},
"storageConfig": {
"unstructuredDataOptions": {
"entity_inference_enabled": true
}
}
}
}'
上記のプレースホルダ変数の値を置き換えて、コマンドが正常に実行されるようにします。これはジョブを作成するだけで、実行はしません。
- 1 ～ 2 分後、Google Cloud コンソールで [メタデータのキュレーション] ページに移動します。
- [Cloud Storage 検出] タブで、検出スキャン アイテムの名前をクリックします（ソースリンクをクリックしないでください。クリックするとストレージが開きます）。
- 重要なステップ:
ジョブを編集し、[セマンティック推論を有効にする] チェックボックスがオンになっていることを確認します。オンになっていない場合は、オンにしてプロジェクト ID とリージョンを入力し、[保存] をクリックします。
完了したら、Cloud Shell ターミナルから次のコマンドを実行するか、[Cloud Storage 検出] ページで [今すぐ実行] ボタンをクリックします。
gcloud dataplex datascans run $DATASCAN_ID --location=$REGION
- スキャン ジョブが完了するまでに時間がかかります。ジョブが完了したら、公開されたデータセットが存在するかどうかを確認します。ジョブのステータスを確認するには、[メタデータのキュレーション] ページの [Cloud Storage 検出] タブで、最近実行した検出スキャンの名前をクリックします。公開されたデータセットが次のように表示されます。
注: スキャン ステップでエラーが発生した場合は、しばらく待ってから再試行してください（ジョブの作成と実行の完了には数分かかります）。
BigQuery でテーブルを表示するには、[froyo_data] データセットをクリックして移動します。BigQuery でテーブル ID をクリックし、[クエリエディタ] タブで次のクエリを実行します。
SELECT count(*) FROM `agent-data-cloud.froyo_data.froyo_data` LIMIT 1000;
結果は 400 になります（そうでない場合は、戻って Datascan ジョブを再度実行してください）。
7. セマンティック データ抽出
すばらしい。Knowledge Catalog を使用して、これらの非構造化オブジェクトの推論を抽出しましょう。
分析情報機能を使用して、非構造化テーブルから構造化データを抽出する SQL ステートメントを生成します。
- Google Cloud コンソールで、[Knowledge Catalog Search] ページに移動します。
- 分析情報を表示するデータセット テーブルを検索します。検索バーに、前のステップのデータセット / テーブル名「froyo_data」と入力して Enter キーを押します。
- 結果リストで、[TABLE] エントリをクリックします（データセット エントリではありません）。
- [INSIGHTS] タブが表示されます。クリックします（API の有効化が必要な場合は、手順に沿って API を有効にします）。
この時点で API を有効にした場合は、スキャン ジョブを再度実行する必要があります。
- [INSIGHTS] タブに、[EXTRACT] ボタンのプルダウンが表示されます。クリックして [Extract with SQL] オプションを選択します。
[**Extract with SQL**] ダイアログ ポップアップで、[DESTINATION] データセットを Datascan ジョブの結果に表示されたデータセットに設定します。名前の入力を開始すると、自動補完で表示されます。[**Extract**] ボタンをクリックします。この時点で新しいデータセットを作成して抽出することもできます。
これにより、データスキャン推論から抽出された SQL が入力されたタブで BigQuery クエリエディタが開きます。
8. SQL 検証とスキーマ作成
生成されたクエリが適切で、非構造化データとセマンティックに関連している場合は、クエリエディタの [実行] ボタンをクリックして実行します。非構造化メディアの構造化ストレージに必要なスキーマを作成するまでに数分かかります。
完了したら、次のように BigQuery Studio のエクスプローラ ペインでデータセットを開いて、スキーマを確認できます。
よし！データベースの処理を非常に迅速に行うことができました。いよいよ最終テストです。
9. 最終テスト!!!
エージェントが、事実に基づいたリアルで完全な、適切に調整された情報でユーザーの質問に回答するようにします。エージェントが回答するには、ソースの複数のメディア ファイルと参照を参照する必要がある質問をします。
ユーザーの質問は次のとおりです。
I'm really interested in your Midnight Swirl froyo. Are there any allergens in it?
一般的な検索や LLM 検索では、「材料はゼロ」と表示されます。しかし、非構造化メディアをすべて構造化データに変換する完全なセマンティック推論を構築しました。この情報を取得する簡単な SQL を使用します。
SELECT p.product_name, i.ingredient_name, a.allergen_name, category, stability
FROM froyo_data.consistsof c
INNER JOIN froyo_data.product p
ON c.product_id = p.product_id
INNER JOIN froyo_data.ingredient i
ON c.ingredient_id = i.ingredient_name
LEFT OUTER JOIN froyo_data.containsallergen a
ON i.ingredient_id = a.ingredient_id
WHERE
UPPER(p.product_name) LIKE '%MIDNIGHT%SWIRL%'
AND allergen_name IS NOT NULL;
おめでとうございます！結果は次のとおりです。
10. クリーンアップ
このラボが完了したら、スキャン ジョブと、ジョブによって作成された BigQuery テーブルを削除してください。
https://console.cloud.google.com/bigquery/governance/metadata-curation/cloud-storage-discovery に移動します。削除するジョブの横にある縦のその他アイコンをクリックして選択し、[削除] をクリックします。
ジョブがクリーンアップされます。
11. 完了
実装により、隠れたアレルゲンを特定できました。ダークデータはもうありません。パート 2 では、AlloyDB を使用してトランザクション システムでこの BigQuery データを統合し、エージェント アプリケーションのデータニーズを統合します。