このページは Cloud Translation API によって翻訳されました。

AlloyDB での生成 AI とエージェントアプリケーション用の Toolbox のインストールと設定

1. 概要

データベース向け生成 AI ツールボックスは、Google のオープンソースサーバーであり、データベースを操作するための生成 AI ツールを簡単に構築できます。これにより、接続プーリングや認証などの複雑な処理を処理することで、ツールをより簡単、迅速、安全に開発できます。エージェントがデータベース内のデータにアクセスできるようにする生成 AI ツールを構築できます。ツールボックスには次の機能があります。

開発の簡素化: 10 行未満のコドでツールをエージェントに統合し、複数のエージェントやフレームワーク間でツールを再利用し、新しいバージョンのツールを簡単にデプロイできます。

パフォーマンスの向上: 接続プーリング、認証などのベストプラクティス。

セキュリティの強化: 認証が統合され、データへのアクセスがより安全になりました。

エンドツーエンドのオブザーバビリティ: OpenTelemetry のサポートが組み込まれた、すぐに使用できる指標とトレース。

Toolbox は、アプリケーションのオケストレーションフレームワークとデータベースの間にあり、ツールの変更、配布、呼び出しに使用されるコントロールプレーンを提供します。ツールの保存と更新を一元化できるため、ツールの管理が簡素化されます。エージェントとアプリケーション間でツールを共有し、アプリケーションを再デプロイしなくてもツールを更新できます。

作成するアプリの概要

このラボでは、ツールを使用してシンプルなデータベース（AlloyDB）クエリを実行するアプリケーションを構築します。このクエリは、エージェントまたは生成 AI アプリケーションから呼び出すことができます。そのために、

ツールボックスをインストールする
Toolbox サーバーでツール（AlloyDB でタスクを実行するように設計されているツール）を設定します。
Cloud Run に Toolbox をデプロイする
デプロイされた Cloud Run エンドポイントでツールをテストする
Toolbox を呼び出す Cloud Run 関数を作成する

要件

ブラウザ（Chrome、Firefox など）
課金が有効になっている Google Cloud プロジェクト（次のセクションの手順）。

2. 始める前に

プロジェクトを作成する

Google Cloud コンソールのプロジェクト選択ページで、Google Cloud プロジェクトを選択または作成します。
Cloud プロジェクトに対して課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
Google Cloud 上で動作するコマンドライン環境の Cloud Shell を使用します。Google Cloud コンソールの上部にある [Cloud Shell をアクティブにする] をクリックします。

Cloud Shell を有効にするボタンの画像

Cloud Shell に接続したら、次のコマンドを使用して、認証が完了しているかどうかと、プロジェクトが正しいプロジェクト ID に設定されているかどうかを確認します。

gcloud auth list

Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。

gcloud config list project

プロジェクトが設定されていない場合は、次のコマンドを使用して設定します。

gcloud config set project <YOUR_PROJECT_ID>

Cloud Shell ターミナルで次のコマンドを 1 つずつ実行して、必要な API を有効にします。

以下のコマンドを 1 つ実行することもできますが、トライアルアカウントをご利用の場合は、これらの機能を一括で有効にすると割り当ての問題が発生する可能性があります。そのため、コマンドは 1 行に 1 つずつ指定します。

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

gcloud コマンドの代わりに、コンソールで各プロダクトを検索するか、このリンクを使用して確認することもできます。

いずれかの API が不足している場合は、実装中にいつでも有効にできます。

gcloud コマンドとその使用方法については、ドキュメントをご覧ください。

3. データベースの設定

このラボでは、小売データを保持するデータベースとして AlloyDB を使用します。クラスタを使用して、データベースやログなどのすべてのリソースを保持します。各クラスタには、データへのアクセスポイントを提供するプライマリインスタンスがあります。テーブルには実際のデータが保持されます。

e コマースデータセットを読み込む AlloyDB クラスタ、インスタンス、テーブルを作成しましょう。

クラスタとインスタンスを作成する

Cloud コンソールで AlloyDB ページに移動します。

Cloud コンソールのほとんどのページは、コンソールの検索バーを使用して簡単に見つけることができます。

そのページで [クラスタを作成] を選択します。

次のような画面が表示されます。次の値を使用してクラスタとインスタンスを作成します（リポジトリからアプリケーションコードをクローンする場合は、値が一致していることを確認してください）。

cluster id: "vector-cluster"
password: "alloydb"
PostgreSQL 15 互換
リージョン: 「us-central1」
ネットワーキング: 「default」

デフォルトのネットワークを選択すると、次のような画面が表示されます。[接続の設定] を選択します。
[自動的に割り当てられた IP 範囲を使用する] を選択し、[続行] をクリックします。情報を確認したら、[CREATE CONNECTION] を選択します。
ネットワークが設定されたら、クラスタの作成を続行できます。[クラスタを作成] をクリックして、クラスタの設定を完了します。

インスタンス ID を「

vector-instance"

クラスタの作成には 10 分ほどかかります。作成が完了すると、作成したクラスタの概要を示す画面が表示されます。

4. データの取り込み

次に、店舗に関するデータを含むテーブルを追加します。AlloyDB に移動し、プライマリクラスタと AlloyDB Studio を選択します。

インスタンスの作成が完了するまで待つ必要があります。完了したら、クラスタの作成時に作成した認証情報を使用して AlloyDB にログインします。PostgreSQL の認証には、次のデータを使用します。

ユーザー名: 「postgres」
データベース: 「postgres」
パスワード: 「alloydb」

AlloyDB Studio で認証に成功すると、エディタに SQL コマンドを入力できるようになります。最後のウィンドウの右側にあるプラス記号を使用して、複数のエディタウィンドウを追加できます。

必要に応じて、[実行]、[フォーマット]、[クリア] の各オプションを使用して、エディタウィンドウに AlloyDB のコマンドを入力できます。

拡張機能を有効にする

このアプリの作成では、拡張機能 pgvector と google_ml_integration を使用します。pgvector 拡張機能を使用すると、ベクトルエンベディングを保存して検索できます。google_ml_integration 拡張機能には、Vertex AI 予測エンドポイントにアクセスして SQL で予測を取得するために使用する関数が用意されています。次の DDL を実行して、これらの拡張機能を有効にします。

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

データベースで有効になっている拡張機能を確認するには、次の SQL コマンドを実行します。

select extname, extversion from pg_extension;

テーブルを作成する

次の DDL ステートメントを使用してテーブルを作成します。

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

上記のコマンドが正常に実行されると、データベース内のテーブルが表示されます。

データを取り込む

このラボでは、この SQL ファイルに約 72 件のレコードのテストデータがあります。id, name, description, quantity, price, image_url フィールドが含まれています。他のフィールドは、ラボの後半で入力します。

そこから行/挿入ステートメントをコピーし、空のエディタタブに貼り付けて、[実行] を選択します。

テーブルの内容を表示するには、[エクスプローラ] セクションを開いて、apparels という名前のテーブルが表示されるまで展開します。省略記号（⋮）を選択すると、テーブルに対してクエリを実行するオプションが表示されます。新しいエディタタブで SELECT ステートメントが開きます。

権限を付与

次のステートメントを実行して、embedding 関数の実行権限をユーザー postgres に付与します。

GRANT EXECUTE ON FUNCTION embedding TO postgres;

AlloyDB サービスアカウントに Vertex AI ユーザーロールを付与する

Cloud Shell ターミナルに移動し、次のコマンドを実行します。

PROJECT_ID=$(gcloud config get-value project)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

5. コンテキストのエンベディングを作成する

コンピュータにとって、テキストを処理するよりも数値を処理するほうがはるかに簡単です。エンベディングシステムは、テキストをベクトルエンベディングと呼ばれる一連の浮動小数点数に変換します。これは、文言や使用言語に関係なくテキストを表すものです。

たとえば、海辺の宿泊施設は「海辺」、「ビーチフロント」、「客室から海まで歩いて行ける」、「sur la mer」、「на берегу океана」などと呼ばれます。これらの用語はすべて見た目は異なりますが、意味的な意味や機械学習の用語では、埋め込みが非常に近いはずです。

データとコンテキストの準備ができたので、SQL を実行して商品説明のエンベディングをテーブルの embedding フィールドに追加します。使用できるエンベディングモデルはさまざまです。Vertex AI の text-embedding-005 を使用します。プロジェクト全体で同じエンベディングモデルを使用してください。

注: 古い Google Cloud プロジェクトを使用している場合は、textembedding-gecko などの古いバージョンのテキストエンベディングモデルを引き続き使用する必要があります。

[AlloyDB Studio] タブに戻り、次の DML を入力します。

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

toys テーブルをもう一度見て、エンベディングを確認します。変更を確認するには、SELECT ステートメントを再実行してください。

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

次のように、おもちゃの説明のエンベディングベクトルが返されます。これは浮動小数点の配列のように見えます。

注: 無料枠で新しく作成された Google Cloud プロジェクトでは、エンベディングモデルに対して 1 秒あたりに許可されるエンベディングリクエストの数に関して、割り当ての問題が発生する可能性があります。ID のフィルタクエリを使用して、エンベディングの生成時に 1 ～ 5 件のレコードを選択することをおすすめします。

6. ベクトル検索を実行する

テーブル、データ、エンベディングがすべて準備できたので、ユーザーの検索テキストのリアルタイムベクトル検索を実行しましょう。

お客様から次のような質問を受けたとします。

「I want a white plush teddy bear toy with a floral pattern」

一致する項目は、次のクエリを実行すると見つけることができます。

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

このクエリを詳しく見てみましょう。

このクエリでは、

ユーザーの検索テキストは「I want a white plush teddy bear toy with a floral pattern.」です。
モデル text-embedding-005 を使用して、embedding() メソッドでエンベディングに変換しています。このステップは、テーブル内のすべてのアイテムにエンベディング関数を適用した最後のステップとよく似ています。
「<=>」は、COSINE SIMILARITY 距離メソッドの使用を表します。使用可能なすべての類似性測定については、pgvector のドキュメントをご覧ください。
エンベディング方法の結果をベクトル型に変換し、データベースに保存されているベクトルと互換性を持たせています。
LIMIT 5 は、検索テキストの最近傍を 5 つ抽出することを表します。

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

検索結果をご覧のとおり、検索テキストに非常に近い一致が見つかりました。テキストを変更して、結果がどのように変化するかを確認してみます。

7. ツールボックスの操作用に AlloyDB を準備する

Toolbox の設定に備えて、新しいツールがデータベースにアクセスできるように、AlloyDB インスタンスでパブリック IP 接続を有効にします。

AlloyDB インスタンスに移動し、[編集] をクリックして [プライマリインスタンスの編集] ページに移動します。
[パブリック IP 接続] セクションに移動し、[パブリック IP を有効にする] チェックボックスをオンにして、Cloud Shell マシンの IP アドレスを入力します。
Cloud Shell マシンの IP アドレスを取得するには、Cloud Shell ターミナルに移動して ifconfig と入力します。結果から eth0 の inet アドレスを特定し、最後の 2 桁を 0.0 に置き換えて、マスクサイズを「/16」にします。たとえば、「XX.XX.0.0/16」のようにします（XX は数字です）。
この IP を、インスタンスの編集ページの承認済み外部ネットワークの [ネットワーク] テキストボックスに貼り付けます。

完了したら、[インスタンスを更新] をクリックします。

完了するまでに数分かかります。

8. ツールボックスのインストール

ツールの詳細を保存するプロジェクトフォルダを作成できます。この場合は、おもちゃ屋のデータを使用するため、「toystore」という名前のフォルダを作成して移動します。Cloud Shell ターミナルに移動し、プロジェクトが選択され、ターミナルのプロンプトに表示されていることを確認します。Cloud Shell ターミナルから次のコマンドを実行します。

mkdir toystore

cd toystore

次のコマンドを実行して、新しいフォルダにツールボックスをダウンロードしてインストールします。

# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Cloud Shell エディタに切り替えます。新しく作成したフォルダ「toystore」を開き、tools.yaml という新しいファイルを作成します。以下の内容をコピーします。YOUR_PROJECT_ID を置き換え、他の接続の詳細がすべて正しいことを確認します。

sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

このツールでは、ユーザーの検索テキスト（カスタムトイの説明）に最も近い一致を見つけて、その価格を返します。クエリを変更して、最も類似したおもちゃの上位 5 個の平均価格を検索することもできます。

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

ツールの定義が完了しました。

tools.yaml の構成の詳細については、こちらのドキュメントをご覧ください。

Cloud Shell ターミナルに切り替えて、次のコマンドを入力して、ツール構成でツールボックスサーバーを起動します。

./toolbox --tools_file "tools.yaml"

クラウドでウェブプレビューモードでサーバーを起動すると、get-toy-price. という名前の新しいツールを使用して Toolbox サーバーが稼働していることを確認できます。

9. ツールボックスの Cloud Run デプロイ

このツールを実際に使用できるように、Cloud Run にデプロイしましょう。

このページの手順に沿って、[Cloud Run にデプロイする] セクションの 3 番目の項目にある gcloud run deploy toolbox コマンドまで進みます。VPC ネットワークメソッドを使用している場合の 2 番目のオプションではなく、1 番目のオプションが必要です。
正常にデプロイされると、Toolbox サーバーの Cloud Run デプロイエンドポイントが提供されます。CURL コマンドを使用してテストします。

これで、エージェントアプリケーションで新しくデプロイしたツールを使用できるようになりました。

10. アプリを Toolbox に接続する

このパートでは、ツールがアプリケーションのニーズに応じて動作し、レスポンスを取得することをテストするための小さなアプリケーションを作成します。

Google Colab に移動して、新しいノートブックを開きます。
ノートブックで次のコマンドを実行します。

pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
tool = toolbox.load_tool("get-toy-price")

# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)

次のような結果が表示されます。

これは、ツールキット toolbox-langchain. を使用する Python アプリケーションで明示的に呼び出されるツールです。

このツールを使用して、LangGraph 統合アプリケーション内のエージェントにバインドする場合は、langgraph ツールキットを使用して簡単に行えます。
詳しくは、コードスニペットをご覧ください。

11. クラウドに移行しましょう。

この Python コードスニペットを Cloud Run Functions でラップして、サーバーレスにしましょう。

ソースをコードリポジトリフォルダからコピーして、Cloud Functions に配置します。
Cloud Run Functions コンソールに移動し、[関数を作成] をクリックします。
デモ用アプリケーションでは認証なしのままにして、次のページで Python 3.11 ランタイムを選択します。
手順 1 で共有したソースリポジトリから main.py ファイルと requirements.txt ファイルをコピーし、それぞれのファイルに貼り付けます。
関数をデプロイすると、価格予測ツールがおもちゃ屋のウェブアプリケーションでアクセスできる REST エンドポイントが作成されます。
エンドポイントは次のようになります。

https://us-central1-*****.cloudfunctions.net/toolbox-toys

Cloud Functions コンソールで直接テストするには、[テスト] タブに移動し、リクエスト入力として次のように入力します。

{

               "`search`"`:` "`White plush toy`"

}

[関数をテスト] をクリックするか、Cloud Shell ターミナルで実行します。結果が右側の [出力] のタイトルの下に表示されます。

12. 完了

これで、データベース、プラットフォーム、生成 AI オーケストレーションフレームワークをまたいで相互作用し、エージェントアプリケーションの作成に役立つ、堅牢で真にモジュラーなツールを作成できました。

AlloyDB での生成 AI とエージェント アプリケーション用の Toolbox のインストールと設定