Gemini 3 Flash と AlloyDB を使用してリアルタイムの余剰エンジンを構築する

1. 概要

この Codelab では、インテリジェンスをデータレイヤのファーストクラス市民として扱う、持続可能な余剰共有アプリ「Neighbor Loop」を構築します。

Gemini 3.0 Flash と AlloyDB AI を統合することで、基本的なストレージからデータベース内インテリジェンスの領域へと移行できます。マルチモーダル アイテム分析とセマンティック検索を SQL 内で直接実行する方法を学び、レイテンシとアーキテクチャの肥大化という「AI 税」を排除します。

1da27e0c4d9a33e0.jpeg

作成するアプリの概要

コミュニティの余剰品を共有するための、高パフォーマンスの「スワイプしてマッチング」ウェブ アプリケーション。

学習内容

  • ワンクリック プロビジョニング: AI ワークロード用に設計された AlloyDB クラスタとインスタンスを設定する方法。
  • データベース内エンベディング: INSERT ステートメント内で text-embedding-005 ベクトルを直接生成する。
  • マルチモーダル推論: Gemini 3.0 Flash を使用してアイテムを「見て」、ウィットに富んだデートスタイルのプロフィールを自動的に生成します。
  • セマンティック検索: ai.if() 関数を使用して SQL クエリ内でロジックベースの「バイブチェック」を実行し、数学だけでなくコンテキストに基づいて結果をフィルタします。

アーキテクチャ

Neighbor Loop は、従来のアプリケーション レイヤのボトルネックを回避します。データを pull して処理する代わりに、以下を使用します。

  1. AlloyDB AI: ベクトルをリアルタイムで生成して保存します。
  2. Google Cloud Storage: 画像を保存します。
  3. Gemini 3.0 Flash: SQL を介して画像データとテキストデータに対して 1 秒未満の推論を実行します。
  4. Cloud Run: 軽量な単一ファイルの Flask バックエンドをホストします。

要件

  • ブラウザ(Chrome、Firefox など)
  • 課金を有効にした Google Cloud プロジェクト
  • SQL と Python に関する基本的な知識。

2. 始める前に

プロジェクトを作成する

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

[Cloud Shell をアクティブにする] ボタンの画像

  1. Cloud Shell に接続したら、次のコマンドを使用して、すでに認証済みであることと、プロジェクトがプロジェクト ID に設定されていることを確認します。
gcloud auth list
  1. Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。
gcloud config list project
  1. プロジェクトが設定されていない場合は、次のコマンドを使用して設定します。
gcloud config set project <YOUR_PROJECT_ID>
  1. 必要な API を有効にする: リンクにアクセスして API を有効にします。

または、gcloud コマンドを使用することもできます。gcloud コマンドとその使用方法については、ドキュメントをご覧ください。

注意点とトラブルシューティング

「ゴースト プロジェクト」症候群

gcloud config set project を実行したが、実際にはコンソール UI で別のプロジェクトを表示している。左上のプルダウンでプロジェクト ID を確認してください。

お支払いバリケード

プロジェクトを有効にしたが、請求先アカウントを忘れた。AlloyDB は高性能エンジンです。「ガソリン タンク」(課金)が空の状態では始動しません。

API 伝播ラグ

[API を有効にする] をクリックしたのに、コマンドラインに Service Not Enabled と表示される。60 秒ほど待ちます。クラウドがニューロンを起動するまで、しばらくお待ちください。

割り当ての沼

新しいトライアル アカウントを使用している場合、AlloyDB インスタンスのリージョン割り当てに達する可能性があります。us-central1 が失敗した場合は、us-east1 を試してください。

「非表示」のサービス エージェント

AlloyDB サービス エージェントに aiplatform.user ロールが自動的に付与されない場合があります。SQL クエリが Gemini と通信できない場合は、通常、これが原因です。

3. データベースの設定

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

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

  1. ボタンをクリックするか、Google Cloud コンソール ユーザーがログインしているブラウザに以下のリンクをコピーします。

  1. このステップが完了すると、リポジトリがローカルの Cloud Shell エディタにクローンされ、プロジェクト フォルダから以下のコマンドを実行できるようになります(プロジェクト ディレクトリにいることを確認することが重要です)。
sh run.sh
  1. 次に、UI を使用します(ターミナルのリンクをクリックするか、ターミナルの [ウェブでプレビュー] リンクをクリックします)。
  2. プロジェクト ID、クラスタ名、インスタンス名の詳細を入力して開始します。
  3. ログがスクロールしている間にコーヒーを飲みながら、バックグラウンドでどのように処理が行われているかについて、こちらで確認できます。

注意点とトラブルシューティング

「忍耐」の問題

データベース クラスタは重いインフラストラクチャです。「停止しているように見える」ためにページを更新したり、Cloud Shell セッションを強制終了したりすると、部分的にプロビジョニングされた「ゴースト」インスタンスが作成され、手動で介入しないと削除できなくなる可能性があります。

リージョンの不一致

us-central1 で API を有効にしたが、asia-south1 でクラスタをプロビジョニングしようとすると、割り当ての問題やサービス アカウントの権限の遅延が発生する可能性があります。ラボ全体で 1 つのリージョンを使用してください。

ゾンビ クラスタ

以前に同じ名前のクラスタを使用し、削除していない場合、スクリプトはクラスタ名がすでに存在することを示すことがあります。クラスタ名はプロジェクト内で一意にする必要があります。

Cloud Shell のタイムアウト

コーヒー ブレイクに 30 分かかると、Cloud Shell がスリープ状態になり、sh run.sh プロセスが切断される可能性があります。タブをアクティブな状態に保ってください。

4. スキーマのプロビジョニング

AlloyDB クラスタとインスタンスが実行されたら、AlloyDB Studio SQL エディタに移動して AI 拡張機能を有効にし、スキーマをプロビジョニングします。

1e3ac974b18a8113.png

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

  • ユーザー名: 「postgres」
  • データベース: 「postgres」
  • パスワード: 「alloydb」(または作成時に設定したパスワード)

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

28cb9a8b6aa0789f.png

エディタ ウィンドウで 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;

テーブルを作成する

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

-- Items Table (The "Profile" you swipe on)
CREATE TABLE items (
   item_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
   owner_id UUID,
   provider_name TEXT,
   provider_phone TEXT,
   title TEXT,
   bio TEXT,
   category TEXT,
   image_url TEXT,
   item_vector VECTOR(768),
   status TEXT DEFAULT 'available',
   created_at TIMESTAMP DEFAULT NOW()
);

-- Swipes Table (The Interaction)
CREATE TABLE swipes (
   swipe_id SERIAL PRIMARY KEY,
   swiper_id UUID,
   item_id UUID REFERENCES items(item_id),
   direction TEXT CHECK (direction IN ('left', 'right')),
   is_match BOOLEAN DEFAULT FALSE,
   created_at TIMESTAMP DEFAULT NOW()
);

item_vector 列には、テキストのベクトル値を格納できます。

権限を付与

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

GRANT EXECUTE ON FUNCTION embedding TO postgres;

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

Google Cloud IAM コンソールから、AlloyDB サービス アカウント(service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com のようなアカウント)に「Vertex AI ユーザー」ロールへのアクセス権を付与します。PROJECT_NUMBER にはプロジェクト番号が入ります。

または、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"

AlloyDB に Gemini 3 Flash モデルを登録する

AlloyDB クエリエディタから次の SQL ステートメントを実行します。

CALL google_ml.create_model(
   model_id => 'gemini-3-flash-preview',
   model_request_url => 'https://aiplatform.googleapis.com/v1/projects/<<YOUR_PROJECT_ID>>/locations/global/publishers/google/models/gemini-3-flash-preview:generateContent',
   model_qualified_name => 'gemini-3-flash-preview',
   model_provider => 'google',
   model_type => 'llm',
   model_auth_type => 'alloydb_service_agent_iam'
);
--replace <<YOUR_PROJECT_ID>> with your project id.

注意点とトラブルシューティング

「パスワードを忘れる」ループ

「ワンクリック」設定を使用し、パスワードを忘れた場合は、コンソールのインスタンスの基本情報ページに移動し、[編集] をクリックして postgres パスワードをリセットします。

「拡張機能が見つかりません」というエラー

CREATE EXTENSION が失敗した場合、多くは、インスタンスが最初のプロビジョニングから「メンテナンス」または「更新中」の状態のままになっていることが原因です。インスタンスの作成ステップが完了しているかどうかを確認し、必要に応じて数秒待ちます。

IAM の伝播ギャップ

gcloud IAM コマンドを実行しましたが、SQL CALL が権限エラーで失敗します。IAM の変更が Google バックボーンに反映されるまでに少し時間がかかることがあります。一息つきましょう。

ベクトル ディメンションの不一致

items テーブルは VECTOR(768) に設定されています。後で別のモデル(1536 次元のモデルなど)を使用しようとすると、挿入が急増します。text-embedding-005 を使用する。

プロジェクト ID の入力ミス

create_model 呼び出しで、角かっこ « » を残したり、プロジェクト ID を誤って入力したりすると、モデルの登録は成功したように見えますが、最初の実際のクエリで失敗します。文字列を再確認してください。

5. 画像ストレージ(Google Cloud Storage)

余剰アイテムの写真を保存するには、GCS バケットを使用します。このデモアプリでは、画像を一般公開して、スワイプカードにすぐに表示されるようにします。

  1. バケットを作成する: GCP プロジェクトに新しいバケット(例: neighborloop-images)を作成します。データベースやアプリケーションと同じリージョンに作成することをおすすめします。
  2. 公開アクセスを構成する: * バケットの [権限] タブに移動します。
  3. allUsers プリンシパルを追加します。
  4. Storage オブジェクト閲覧者ロール(すべてのユーザーが写真を表示できるようにするため)と Storage オブジェクト作成者ロール(デモのアップロード用)を割り当てます。

代替手段(サービス アカウント): パブリック アクセスを使用しない場合は、アプリケーションのサービス アカウントに AlloyDB への完全アクセス権と、オブジェクトを安全に管理するために必要な Storage ロールが付与されていることを確認します。

注意点とトラブルシューティング

リージョン ドラッグ

データベースが us-central1 にあり、バケットが europe-west1 にある場合、AI の速度は文字どおり低下します。「雰囲気チェック」は高速で行われますが、UI の画像を取得する処理は遅く感じられます。同じリージョンに配置してください。

バケット名の一意性

バケット名はグローバルな名前空間です。バケットに neighborloop-images という名前を付けようとすると、他のユーザーがすでにその名前を使用している可能性があります。作成に失敗した場合は、ランダムな接尾辞を追加します。

「クリエイター」と「視聴者」の混同

「作成者」と「閲覧者」の混同: 「閲覧者」のみを追加すると、ユーザーが新しいアイテムをリストしようとしたときに、アプリがクラッシュします。これは、アプリにファイルを書き込む権限がないためです。この特定のデモ設定には両方が必要です。

6. アプリケーションを作成しましょう

このリポジトリをプロジェクトにクローンして、手順を確認しましょう。

  1. このリポジトリのクローンを作成するには、Cloud Shell ターミナル(ルート ディレクトリまたはこのプロジェクトを作成する場所)から次のコマンドを実行します。
git clone https://github.com/AbiramiSukumaran/neighbor-loop

これによりプロジェクトが作成されます。これは Cloud Shell エディタで確認できます。

53a398aff6ba7d5b.png

  1. Gemini API キーを取得する方法
  2. Google AI Studio にアクセスする: aistudio.google.com にアクセスします。
  3. ログイン: Google Cloud プロジェクトで使用しているのと同じ Google アカウントを使用します。
  4. API キーを作成する:
  5. 左側のサイドバーで [API キーを取得] をクリックします。
  6. [新しいプロジェクトで API キーを作成] ボタンをクリックします。
  7. キーをコピーする: キーが生成されたら、コピーアイコンをクリックします。
  8. 次に、.env ファイルに環境変数を設定します。
GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>
DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<HOST_IP>>:<<PORT>>/postgres
GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>

プレースホルダ <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>. の値を置き換えます。

注意点とトラブルシューティング

複数のアカウントに関する混乱

複数の Google アカウント(個人用と仕事用)にログインしている場合、AI Studio がデフォルトで間違ったアカウントにログインすることがあります。右上のアバターが GCP プロジェクト アカウントと一致していることを確認します。

「無料枠」の割り当てに達した

無料枠を使用している場合は、レート制限(RPM - 1 分あたりのリクエスト数)があります。Neighbor Loop で「スワイプ」が速すぎると、429 Too Many Requests エラーが発生することがあります。スピードを落として!

公開された鍵のセキュリティ

鍵を含む .env ファイルを誤って git commit した場合。.gitignore には必ず .env を追加してください。

「接続タイムアウト」の空白

.env ファイルでプライベート IP アドレスを使用したが、VPC の外部(ローカルマシンなど)から接続しようとしている。プライベート IP には、同じ Google Cloud ネットワーク内からのみアクセスできます。パブリック IP に切り替える

ポート 5432 の想定

5432 は標準の PostgreSQL ポートですが、Auth Proxy を使用している場合、AlloyDB では特定のポート構成が必要になることがあります。このラボでは、ホスト文字列の末尾に :5432 を使用していることを確認してください。

「承認済みネットワーク」ゲートキーパー

パブリック IP があっても、コードを実行しているマシンの IP アドレスを許可リストに登録していない場合、AlloyDB は「接続を拒否」します。修正方法: AlloyDB インスタンスの設定で、0.0.0.0/0(一時的なテストのみ)または特定の IP を承認済みネットワークに追加します。

SSL / TLS handshake の失敗

AlloyDB では、安全な接続が推奨されます。DATABASE_URL でドライバが正しく指定されていない場合(pg8000 を使用している場合など)、ハンドシェイクがサイレントに失敗し、一般的な「データベースにアクセスできません」というエラーが表示されることがあります。

「プライマリ プールと読み取りプール」のスワップ

プライマリ インスタンスではなく、読み取りプールの IP アドレスを誤ってコピーした場合、アプリはアイテムの検索では機能しますが、新しいアイテムをリストしようとすると「読み取り専用」エラーでクラッシュします。書き込みには常にプライマリ インスタンスの IP を使用します。

7. コードを確認する

あなたの持ち物の「出会い系プロフィール」

c2c543562cc9b353.png

ユーザーがアイテムの写真をアップロードする際に、長い説明を書く必要がないようにする必要があります。Gemini 3 Flash を使用して商品を「見て」、出品情報を書いてもらいます。

バックエンドでは、ユーザーはタイトルと写真を提供するだけです。残りの処理は Gemini が行います。

prompt = """
You are a witty community manager for NeighborLoop.
Analyze this surplus item and return JSON:
{
   "bio": "First-person witty dating-style profile bio for the product, not longer than 2 lines",
   "category": "One-word category",
   "tags": ["tag1", "tag2"]
}
"""
response = genai_client.models.generate_content(
   model="gemini-3-flash-preview",
   contents=[types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"), prompt],
   config=types.GenerateContentConfig(response_mime_type="application/json")
)

21f871a1b549efcf.png

リアルタイムのデータベース内エンベディング

aa783a459f1b02da.png

AlloyDB の最も優れた機能の一つは、SQL コンテキストから離れることなくエンベディングを生成できることです。Python でエンベディング モデルを呼び出してベクトルを DB に戻すのではなく、embedding() 関数を使用して 1 つの INSERT ステートメントですべてを行います。

INSERT INTO items (owner_id, provider_name, provider_phone, title, bio, category, image_url, status, item_vector)
VALUES (
   :owner, :name, :phone, :title, :bio, :cat, :url, 'available',
   embedding('text-embedding-005', :title || ' ' || :bio)::vector
)

これにより、すべてのアイテムが投稿された瞬間に、その意味で「検索可能」になります。これは、Neighbor Loop アプリの「商品の出品」機能をカバーする部分です。

商品掲載機能のスクリーンショットを追加

Gemini 3.0 による高度なベクトル検索とスマート フィルタリング

標準のキーワード検索には制限があります。「椅子を修理するもの」を検索した場合、従来のデータベースでは、タイトルに「椅子」という単語が含まれていなければ、何も返されない可能性があります。Neighbor Loop は、AlloyDB AI の高度なベクトル検索でこの問題を解決しています。

pgvector 拡張機能と AlloyDB の最適化されたストレージを使用することで、非常に高速な類似性検索を実行できます。しかし、真の「魔法」は、ベクトルの近接性と LLM ベースのロジックを組み合わせたときに起こります。

AlloyDB AI を使用すると、SQL クエリ内で Gemini などのモデルを直接呼び出すことができます。つまり、ai.if() 関数を使用して、ロジックベースの「サニティ チェック」を含むセマンティック検出を実行できます。

SELECT item_id, title, bio, category, image_url,
      1 - (item_vector <=> embedding('text-embedding-005', :query)::vector) as score
FROM items
WHERE status = 'available'
 AND item_vector IS NOT NULL
 AND ai.if(
       prompt => 'Does this text: "' || bio ||'" match the user request: "' ||  :query || '", at least 60%? "',
       model_id => 'gemini-3-flash-preview'
     ) 
ORDER BY score DESC
LIMIT 5

このクエリは、ロジックをデータに移行するという、アーキテクチャの大きな転換を表しています。Gemini 3 Flash は、数千件の結果をアプリケーション コードに pull してフィルタするのではなく、データベース エンジン内で「バイブチェック」を実行します。これにより、レイテンシが短縮され、下り(外向き)費用が削減されます。また、結果が数学的に類似しているだけでなく、コンテキストに関連していることが保証されます。

セマンティック検索機能のスクリーンショット

「スワイプしてマッチ」のループ

UI はクラシックなトランプのデッキです。

左にスワイプ: 破棄。

右にスワイプ: マッチしました!

スワイプしてマッチングする機能のスクリーンショット

右にスワイプすると、バックエンドはスワイプ テーブルにインタラクションを記録し、アイテムを一致としてマークします。フロントエンドは、プロバイダの連絡先情報を示すモーダルを即座にトリガーし、集荷を手配できるようにします。

8. Cloud Run にデプロイしましょう

  1. プロジェクトがクローンされている Cloud Shell ターミナルから次のコマンドを実行して、Cloud Run にデプロイします。プロジェクトのルートフォルダ内にいることを確認してください。

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

gcloud beta run deploy neighbor-loop \
   --source . \
   --region=us-central1 \
   --network=<<YOUR_NETWORK_NAME>> \
   --subnet=<<YOUR_SUBNET_NAME>> \
   --allow-unauthenticated \
   --vpc-egress=all-traffic \
   --set-env-vars GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>,DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<PRIVATE_IP_HOST>>:<<PORT>>/postgres,GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>

プレースホルダ <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>> の値を置き換えます。

コマンドが完了すると、サービス URL が出力されます。コピーします。

  1. Cloud Run サービス アカウントに AlloyDB クライアント ロールを付与します。これにより、サーバーレス アプリケーションがデータベースに安全にトンネリングできるようになります。

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

# 1. Get your Project ID and Project Number
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

# 2. Grant the AlloyDB Client role
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/alloydb.client"

サービス URL(先ほどコピーした Cloud Run エンドポイント)を使用して、アプリをテストします。古い電動工具の写真をアップロードすると、Gemini が残りの処理を行います。

注意点とトラブルシューティング

「修正に失敗」のループ

デプロイが完了しても URL で 500 Internal Server Error が返される場合は、ログを確認してください。これは通常、環境変数の欠落(DATABASE_URL の入力ミスなど)や、Cloud Run サービス アカウントに GCS バケットからの読み取り権限がないことが原因です。

IAM の「シャドー」ロール

ユーザーにデプロイ権限がある場合でも、Cloud Run サービス アカウント(通常は [project-number]-compute@developer.gserviceaccount.com)には、データベースへの接続を実際に確立するための AlloyDB Client ロールが必要です。

9. 高度なトラブルシューティング

b6cdd3785d5461a9.jpeg

10. デモ

エンドポイントをテストに使用できるようになります。

ただし、数日間のデモ目的であれば、次の方法を試すことができます。

11. クリーンアップ

このラボが完了したら、AlloyDB クラスタとインスタンスを忘れずに削除してください。

クラスタとそのインスタンスをクリーンアップする必要があります。

12. 完了

Google Cloud を使用して、持続可能なコミュニティ向けの Neighbor Loop アプリを正常に構築できました。エンベディングと Gemini 3 Flash AI ロジックを AlloyDB に移行することで、アプリは驚くほど高速になり(デプロイ設定による)、コードは非常にクリーンになります。Google が保存しているのは、単なるデータではなく、意図です。

Gemini 3 Flash のスピードと AlloyDB の最適化されたベクトル処理の組み合わせは、コミュニティ主導のプラットフォームにとってまさに次のフロンティアです。