Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

メタデータを拡充するエージェントを構築する

Knowledge Catalog（旧称 Dataplex Universal Catalog）は、組織全体のデータアセットのメタデータを管理します。このメタデータは、エージェントがユーザーの質問に回答するために必要なデータを検出、理解、クエリするために使用するコンテキストを提供します。

Knowledge Catalog はリソースの自動管理、テクニカルスキーマの追跡、説明とデータプロファイルの生成を行いますが、ビジネスコンテキストは次のような他の場所に存在することがよくあります。

内部ドキュメントと Wiki
コードリポジトリ
Google Chat や Slack などのコミュニケーションチャネル

これらのソースからコンテキストを抽出し、メタデータを大規模に継続的に拡充する AI エージェントを構築できます。このチュートリアルでは、dataplex-labs リポジトリのサンプルコードを使用して、次の処理を行うエージェントを構築する方法を説明します。

コンテキストを抽出する: ナレッジベース、ドキュメント、コード、チャットからビジネスコンテキストを抽出して、技術メタデータを拡充します。
ドキュメントを生成する: 抽出されたコンテキストやその他の情報ソースに基づいて、BigQuery テーブルのドキュメントを生成します。
検索と見つけやすさの改善: 生成されたドキュメントを Knowledge Catalog に公開し、検索を通じてエントリを簡単に見つけて理解できるようにします。

始める前に

Knowledge Catalog 拡充エージェントを実行するには、次の要件を満たす必要があります。

必要なロール

拡充エージェントの使用に必要な権限を取得するには、 Google Cloud プロジェクト iam.gserviceaccount.comに対する次の IAM ロールを付与するよう管理者に依頼してください。

BigQuery のサンプルリソースを管理する: BigQuery データ編集者（roles/bigquery.dataEditor）
カタログメタデータを検索する: Dataplex 閲覧者（roles/dataplex.viewer）
カタログメタデータを管理する: Dataplex Catalog 編集者（roles/dataplex.catalogEditor）
Vertex AI の機能（Gemini LLM API）にアクセスするには: Vertex AI ユーザー（roles/aiplatform.user）
サービス API を使用するには: Service Usage ユーザー（roles/serviceusage.serviceUsageConsumer）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、エンリッチメントエージェントの使用に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

エンリッチメントエージェントを使用するには、次の権限が必要です。

bigquery.projects.get/createDatasets
dataplex.projects.search
dataplex.entryGroups.get/updateEntries
aiplatform.endpoints.predict
serviceusage.services.use

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

API を有効にする

Knowledge Catalog エンリッチメントエージェントを使用するには、プロジェクトで次の API を有効にします。

BigQuery API
Knowledge Catalog API
Vertex AI API
Service Usage API

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

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

API を有効にする

依存関係のインストール

サンプルを実行するには、次の Python パッケージとツールが必要です。

google-adk（Agent Development Kit（ADK））
google-cloud-dataplex Knowledge Catalog Python クライアント
google-auth はアプリケーションのデフォルト認証情報を管理します
mcp[cli]: サンプル MCP サーバーのビルド用
認証と構成の gcloud。Google Cloud CLI をインストールするには、Google Cloud SDK のドキュメントをご覧ください。

環境を設定する

gcloud を構成してログインします。
```
gcloud auth application-default login
gcloud config set core/project PROJECT_ID
```
次のように置き換えます。
- PROJECT_ID はプロジェクトの ID に置き換えます。

dataplex-labs リポジトリのクローンを作成し、サンプルソースディレクトリに移動します。

git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
cd dataplex-labs/knowledge_catalog_enrichment_agent/src

依存関係をインストールするには、Python 仮想環境と必要な環境変数を設定する提供のスクリプトを使用します。
```
source env.sh --install
```
クラウドプロジェクトの us リージョンに kc_sample_analytics という名前の BigQuery サンプルデータセットを作成するには、create_data.py スクリプトを実行します。
```
python3 ../sample/data/create_data.py
```
このサンプルには、sample/docs ディレクトリに複数のドキュメントも含まれています。これらのドキュメントはローカルナレッジベースを形成します。拡充エージェントは、このナレッジベースを使用して情報を抽出し、ドキュメントを生成します。

メタデータをダウンロード

まず、ダウンロードツールを実行して、BigQuery データセットとそのテーブルのメタデータスナップショットを Knowledge Catalog から抽出します。これにより、ローカルメタデータアーティファクトが作成されます。

--dir 引数で、メタデータファイルが書き込まれるディレクトリを指定します。

python3 -m enrichment.download \
  --dir ../sample/metadata.initial \
  --dataset ${KC_ENRICH_SAMPLE_PROJECT}.kc_sample_analytics

このスクリプトは、sample/metadata ディレクトリ内のテーブルごとに 1 つの Markdown ファイルを作成します。命名規則は <project_id>.<dataset_id>.<table_id>.md です。

メタデータを拡充する

ローカルの Markdown ファイルを作成したら、エンリッチメントエージェントを実行します。エージェントは各ファイルを反復処理し、テーブルに関連する情報を見つけて、引用とともに調査結果を要約し、更新された Markdown ファイルを生成します。

--dir: ローカルメタデータファイルを含むディレクトリを指定します。
--output-dir: 更新されたメタデータファイルのターゲットディレクトリを指定します。
--config-dir: エージェントの手順、MCP ツール、スキルを含むディレクトリを指定します。

python3 -m enrichment.enrich \
  --dir ../sample/metadata.initial \
  --output-dir ../sample/metadata.new \
  --config-dir ../sample/config

メタデータを確認する

拡充されたメタデータファイルには、エージェントが生成したドキュメントが含まれています。変更を Knowledge Catalog に公開する前に、必要に応じてファイルを確認して変更します。

git diff --no-index ../sample/metadata.initial ../sample/metadata.new

メタデータを公開する

公開ツールを実行して、拡充されたメタデータを Knowledge Catalog にデプロイします。

python3 -m src.enrichment.publish --dir ../sample/metadata.new

データに合わせてカスタマイズする

前の手順では、--config-dir 引数を使用して、構成の ../sample/config ディレクトリをエージェントに指定しました。これにより、エージェントは情報の検索場所とさまざまなソースとのやり取りの方法を把握します。

このサンプルには、ローカル MCP サーバーを使用してローカルナレッジベース（sample/docs）内のファイルにアクセスするようにエージェントに指示するデフォルトの構成が付属しています。このワークフローを環境に適用するには、これらの構成ファイルをカスタマイズして、エージェントを内部 Wiki、コードリポジトリ、Google ドライブ、その他のシステムに接続します。

sample/config/ ディレクトリには次のファイルが含まれています。

sample/config/
├─ instructions.md
├─ mcp.json
└─ skills/
    └─ kb-search/
        └─ SKILL.md

instructions.md: 特定のナレッジベースを検索するように指示するなど、組織に関連する詳細情報をエージェントのベースライン指示に追加します。
mcp.json: エージェントが情報ソースのツールにアクセスするために使用できる MCP サーバーを構成します。たとえば、ローカルディレクトリからファイルを読み取るツールなどです。
SKILL.md: エージェントが特定のツールを使用して情報ソースとやり取りする方法を記述します。たとえば、list_contents、read_file、search_content を使用してローカルドキュメントで情報を検索する方法などです。

Knowledge Catalog のサンプルコードを確認する

拡充フローセクションの download ツールと publish ツールは、Knowledge Catalog API を使用してメタデータの読み取りと書き込みを行います。

このセクションでは、これらの API の仕組みについて説明します。この仕組みを理解することで、独自の統合に合わせてサンプルを調整できます。

メタデータの検索と取得

このサンプルでは、次の API を使用してメタデータを検索し、取得します。

SearchEntries: データセットのエントリと位置情報メタデータを取得します。
ListEntries: Catalog EntryGroup 内の BigQuery テーブルを列挙します。
GetEntry: 各 BigQuery テーブルの特定のメタデータを取得します。

次のコードは、データセットを検索してエントリグループを見つけ、含まれているすべてのテーブルを一覧表示して、特定のメタデータを取得する方法を示しています。

import google.cloud.dataplex_v1 as dataplex

BIGQUERY_TABLE_TYPE = "projects/dataplex-types/locations/global/entryTypes/bigquery-table"
OVERVIEW_ASPECT_TYPE = "projects/dataplex-types/locations/global/aspectTypes/overview"

catalog = dataplex.CatalogServiceClient()

dataset_reference = '...'   # project_id.dataset_id
project_id, dataset_id = dataset_reference.split('.')

# 1. Search for dataset to determine its location
search_response = catalog.search_entries(
    request=dataplex.SearchEntriesRequest(
        name=f"projects/{project_id}/locations/global",
        query=f"type=dataset name={dataset_id}",
        page_size=1
    )
)
dataset_entry = search_response.results[0].dataplex_entry
location_id = dataset_entry.entry_source.location

# 2. List resources in the underlying group
entry_group_name = f"projects/{project_id}/locations/{location_id}/entryGroups/@bigquery"
entry_filter = f'parent_entry="{dataset_entry.name}"'
list_response = catalog.list_entries(
    request=dataplex.ListEntriesRequest(
        parent=entry_group_name,
        entry_filter=entry_filter,
    )
)

# 3. Retrieve metadata for each table in the list
for table_entry in list_response.entries:
    entry = catalog.get_entry(
        request=dataplex.GetEntryRequest(
            name=table_entry.name,
            view="CUSTOM",
            aspect_types=[OVERVIEW_ASPECT_TYPE]
        )
    )

テーブルメタデータの更新

次のコードは、生成されたドキュメントをテーブルの概要アスペクトに公開し、そのメタデータを更新する方法を示しています。

import google.cloud.dataplex_v1 as dataplex
import google.protobuf.field_mask_pb2 as field_mask_pb2
import google.protobuf.json_format as jsonpb

OVERVIEW_ASPECT_TYPE = "projects/dataplex-types/locations/global/aspectTypes/overview"
OVERVIEW_ASPECT_KEY = "dataplex-types.global.overview"

catalog = dataplex.CatalogServiceClient()

table_reference = "..."    # project_id.dataset_id.table_id
project_id, dataset_id, table_id = table_reference.split('.')

entry_data = {
    "name": f"bigquery.googleapis.com/projects/{project_id}/datasets/{dataset_id}/tables/{table_id}",
    "aspects": {
        OVERVIEW_ASPECT_KEY: {
            "aspectType": OVERVIEW_ASPECT_TYPE,
            "data": {
                "content": "...", # content parsed from local markdown file
                "contentType": "MARKDOWN"
            }
        }
    }
}

entry = dataplex.Entry()
jsonpb.ParseDict(entry_data, entry._pb)

catalog.update_entry(
    request=dataplex.UpdateEntryRequest(
        entry=entry,
        update_mask=field_mask_pb2.FieldMask(paths=["aspects"]),
        aspect_keys=[OVERVIEW_ASPECT_KEY],
    )
)

次のステップ

メタデータの操作について詳細を確認する。
Gemini CLI を使用してデータコンテキストをテストします。
アスペクトを管理してメタデータを拡充する方法を確認する。
Python 用 Knowledge Catalog クライアントライブラリで利用可能な他のクラスとメソッドを確認する。
他の Knowledge Catalog のユースケースを試す。

メタデータを拡充するエージェントを構築する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

必要なロール

必要な権限

API を有効にする

依存関係のインストール

環境を設定する

メタデータをダウンロード

メタデータを拡充する

メタデータを確認する

メタデータを公開する

データに合わせてカスタマイズする

Knowledge Catalog のサンプルコードを確認する

メタデータの検索と取得

テーブル メタデータの更新

次のステップ

メタデータを拡充するエージェントを構築する

テーブルメタデータの更新