GSP1288

概要

アプリケーションで Spanner データベースを検索する際、入力した検索フレーズが実際に保存されているテキストに含まれていないとしても、関連するデータをすばやく特定できるとしたらどうでしょうか。Vertex AI のテキスト エンベディングの力を活用して Spanner 内でベクトル検索を行うことで、これを実現できるようになりました。

Spanner は、グローバル規模でのトランザクション整合性と、高可用性を実現する自動かつ同期的なレプリケーションを備えたフルマネージドのデータベース サービスです。AI 機能を活用して、生成 AI アプリケーションの構築や、特定の検索語との関連性に基づいて Spanner データベース内のデータを抽出するなどのタスクも実行できます。

ベクトル検索とは、（キーワードの完全一致ではなく）セマンティックな意味に基づいて同様のアイテムをすばやく見つけるために使用できる手法のことで、音声、画像、動画、テキストをはじめ、さまざまな種類のデータに適用できます。特にテキストでは、ベクトル検索を適用することで、検索語や検索フレーズとコンテンツが完全に一致していなくても、類似したテキスト アイテムを検索できます。

このラボでは、Spanner でベクトル検索を構成する際の基礎として、まず、テキスト エンベディング（テキストのセマンティックな意味を数値で表すベクトル）を生成して保存する方法を学びます。次に、これらのテキスト エンベディングを使用して、高速の類似検索を行う方法を学びます。Codelab「Spanner ベクトル検索を使ってみる」を基に作成されたこのハンズオンラボでは、自転車商品のデータセットを使用し、Spanner におけるベクトル検索の活用方法を示しながら、テキストが完全に一致しない場合でも検索フレーズに最も関連性の高い商品を見つける方法を紹介します。

演習内容

このラボでは、次の方法について学びます。

• Spanner でエンベディング モデルを作成し、Vertex AI モデルのエンドポイントに設定する
• Spanner でテーブルを作成してデータを読み込む
• Spanner でテキスト エンベディングを生成して保存する
• テキスト エンベディングを使用して、Spanner でベクトル検索を実行する

設定と要件

[ラボを開始] ボタンをクリックする前に

こちらの説明をお読みください。ラボには時間制限があり、一時停止することはできません。タイマーは、Google Cloud のリソースを利用できる時間を示しており、[ラボを開始] をクリックするとスタートします。

このハンズオンラボでは、シミュレーションやデモ環境ではなく実際のクラウド環境を使って、ラボのアクティビティを行います。そのため、ラボの受講中に Google Cloud にログインおよびアクセスするための、新しい一時的な認証情報が提供されます。

このラボを完了するためには、下記が必要です。

• 標準的なインターネット ブラウザ（Chrome を推奨）

注: このラボの実行には、シークレット モード（推奨）またはシークレット ブラウジング ウィンドウを使用してください。これにより、個人アカウントと受講者アカウント間の競合を防ぎ、個人アカウントに追加料金が発生しないようにすることができます。

• ラボを完了するための時間（開始後は一時停止できません）

注: このラボでは、受講者アカウントのみを使用してください。別の Google Cloud アカウントを使用すると、そのアカウントに料金が発生する可能性があります。

ラボを開始して Google Cloud コンソールにログインする方法

1. [ラボを開始] ボタンをクリックします。ラボの料金をお支払いいただく必要がある場合は、表示されるダイアログでお支払い方法を選択してください。 左側の [ラボの詳細] ペインには、以下が表示されます。

   • [Google Cloud コンソールを開く] ボタン
   • 残り時間
   • このラボで使用する必要がある一時的な認証情報
   • このラボを行うために必要なその他の情報（ある場合）

2. [Google Cloud コンソールを開く] をクリックします（Chrome ブラウザを使用している場合は、右クリックして [シークレット ウィンドウで開く] を選択します）。

   ラボでリソースがスピンアップし、別のタブで [ログイン] ページが表示されます。

   ヒント: タブをそれぞれ別のウィンドウで開き、並べて表示しておきましょう。

   注: [アカウントの選択] ダイアログが表示されたら、[別のアカウントを使用] をクリックします。

3. 必要に応じて、下のユーザー名をコピーして、[ログイン] ダイアログに貼り付けます。

   {{{user_0.username | "Username"}}}

   [ラボの詳細] ペインでもユーザー名を確認できます。

4. [次へ] をクリックします。

5. 以下のパスワードをコピーして、[ようこそ] ダイアログに貼り付けます。

   {{{user_0.password | "Password"}}}

   [ラボの詳細] ペインでもパスワードを確認できます。

6. [次へ] をクリックします。

   重要: ラボで提供された認証情報を使用する必要があります。Google Cloud アカウントの認証情報は使用しないでください。 注: このラボでご自身の Google Cloud アカウントを使用すると、追加料金が発生する場合があります。

7. その後次のように進みます。

   • 利用規約に同意してください。
   • 一時的なアカウントなので、復元オプションや 2 要素認証プロセスは設定しないでください。
   • 無料トライアルには登録しないでください。

その後、このタブで Google Cloud コンソールが開きます。

注: Google Cloud のプロダクトやサービスにアクセスするには、ナビゲーション メニューをクリックするか、[検索] フィールドにサービス名またはプロダクト名を入力します。

タスク 1. Spanner でエンベディング モデルを作成し、Vertex AI モデルのエンドポイントに設定する

このラボ環境では、cymbal-retail という名前の Spanner インスタンスと cymbal-bicycles という名前のデータベースがすでにプロビジョニングされています。

このタスクでは、テキスト エンベディングの生成に使用するエンベディング モデルを作成して設定し、Spanner での一連のワークフローを開始します。これにより、後のタスクに必要となる Spanner サービス アカウントの作成も自動的に開始されます。具体的には、EmbeddingsModel というエンベディング モデルを作成し、 という名前の Vertex AI テキスト エンベディング モデルのエンドポイントに設定します。

1. Google Cloud コンソールで、ナビゲーション メニュー（）> [すべてのプロダクトを表示] をクリックします。[データベース] で、[Spanner] をクリックします。

2. [インスタンス] ページで、Cymbal Retail Spanner Instance という名前のインスタンスをクリックして、インスタンスの詳細を確認します。

3. [データベース] で、cymbal-bicycles という名前のデータベースをクリックします。

4. [データベース] の下の Spanner メニューで、[Spanner Studio] をクリックします。

5. Spanner Studio ページで、[新しい SQL エディタタブ] をクリックして新しいクエリ ウィンドウを開きます。

6. エンベディング モデルを作成して Vertex AI モデルのエンドポイントに設定するには、次のクエリをコピーしてクエリ ウィンドウに貼り付け、[実行] をクリックします。

CREATE MODEL EmbeddingsModel INPUT( content STRING(MAX), ) OUTPUT( embeddings STRUCT<statistics STRUCT<truncated BOOL, token_count FLOAT32>, values ARRAY<FLOAT32>>, ) REMOTE OPTIONS ( endpoint = '//aiplatform.googleapis.com/projects/{{{project_0.project_id |Project ID}}}/locations/{{{project_0.default_region |Region}}}/publishers/google/models/{{{project_0.startup_script.gemini_embedding_model_id | model_name | disablehighlight }}}' );

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 エンベディング モデルを作成し、Vertex AI モデルのエンドポイントに設定する。

クエリが正常に実行されると、「更新完了」というメッセージが表示されます。

Spanner Studio を開いたまま、次のタスクに進みます。

タスク 2. 新しいテーブルを作成して商品データを読み込む

エンベディング モデルの作成と設定が完了したので、次に、ベクトル検索用のテキスト エンベディングを生成するためのデータが必要になります。

このタスクでは、Cymbal Bicycles という架空の会社の商品を対象に、商品名や在庫数などの商品情報を格納する列と、商品説明のベクトル エンベディング（次のタスクで生成）を格納するための列を備えた新しいテーブルを作成します。最後に、Cymbal Bicycles の商品データのサンプルを Spanner のテーブルに読み込みます。

1. Spanner Studio のクエリエディタで、[実行] と同じメニューバーにある [クリア] をクリックして、前のクエリを削除します。

2. products という名前の新しいテーブルを作成するために、次のクエリをコピーしてクエリ ウィンドウに貼り付け、[実行] をクリックします。

CREATE TABLE products ( categoryId INT64 NOT NULL, productId INT64 NOT NULL, productName STRING(MAX) NOT NULL, productDescription STRING(MAX) NOT NULL, productDescriptionEmbedding ARRAY<FLOAT32>, createTime TIMESTAMP NOT NULL OPTIONS ( allow_commit_timestamp = true ), inventoryCount INT64 NOT NULL, priceInCents INT64, ) PRIMARY KEY(categoryId, productId);

productDescriptionEmbedding という列の型は ARRAY<FLOAT32> で、次のタスクで作成するベクトル値を格納できます。

クエリが正常に実行されると、「更新完了」というメッセージが表示されます。

3. [実行] と同じメニューバーにある [クリア] をもう一度クリックして、前のクエリを削除します。

4. テーブルにデータを読み込むには、次のクエリをコピーしてクエリ ウィンドウに貼り付け、[実行] をクリックします。

このクエリでは商品の小さなサンプルが読み込まれますが、テーブルに読み込まれる 10 件の各商品について、必要な情報はすべて含まれています。

INSERT INTO products (categoryId, productId, productName, productDescription, createTime, inventoryCount, priceInCents) VALUES (1, 1, "Cymbal Helios Helmet", "Safety meets style with the Cymbal children's bike helmet. Its lightweight design, superior ventilation, and adjustable fit ensure comfort and protection on every ride. Stay bright and keep your child safe under the sun with Cymbal Helios!", PENDING_COMMIT_TIMESTAMP(), 100, 10999), (1, 2, "Cymbal Sprout", "Let their cycling journey begin with the Cymbal Sprout, the ideal balance bike for beginning riders ages 2-4 years. Its lightweight frame, low seat height, and puncture-proof tires promote stability and confidence as little ones learn to balance and steer. Watch them sprout into cycling enthusiasts with Cymbal Sprout!", PENDING_COMMIT_TIMESTAMP(), 10, 13999), (1, 3, "Cymbal Spark Jr.", "Light, vibrant, and ready for adventure, the Spark Jr. is the perfect first bike for young riders (ages 5-8). Its sturdy frame, easy-to-use brakes, and puncture-resistant tires inspire confidence and endless playtime. Let the spark of cycling ignite with Cymbal!", PENDING_COMMIT_TIMESTAMP(), 34, 13900), (1, 4, "Cymbal Summit", "Conquering trails is a breeze with the Summit mountain bike. Its lightweight aluminum frame, responsive suspension, and powerful disc brakes provide exceptional control and comfort for experienced bikers navigating rocky climbs or shredding downhill. Reach new heights with Cymbal Summit!", PENDING_COMMIT_TIMESTAMP(), 0, 79999), (1, 5, "Cymbal Breeze", "Cruise in style and embrace effortless pedaling with the Breeze electric bike. Its whisper-quiet motor and long-lasting battery let you conquer hills and distances with ease. Enjoy scenic rides, commutes, or errands with a boost of confidence from Cymbal Breeze!", PENDING_COMMIT_TIMESTAMP(), 72, 129999), (1, 6, "Cymbal Trailblazer Backpack", "Carry all your essentials in style with the Trailblazer backpack. Its water-resistant material, multiple compartments, and comfortable straps keep your gear organized and accessible, allowing you to focus on the adventure. Blaze new trails with Cymbal Trailblazer!", PENDING_COMMIT_TIMESTAMP(), 24, 7999), (1, 7, "Cymbal Phoenix Lights", "See and be seen with the Phoenix bike lights. Powerful LEDs and multiple light modes ensure superior visibility, enhancing your safety and enjoyment during day or night rides. Light up your journey with Cymbal Phoenix!", PENDING_COMMIT_TIMESTAMP(), 87, 3999), (1, 8, "Cymbal Windstar Pump", "Flat tires are no match for the Windstar pump. Its compact design, lightweight construction, and high-pressure capacity make inflating tires quick and effortless. Get back on the road in no time with Cymbal Windstar!", PENDING_COMMIT_TIMESTAMP(), 36, 24999), (1, 9,"Cymbal Odyssey Multi-Tool","Be prepared for anything with the Odyssey multi-tool. This handy gadget features essential tools like screwdrivers, hex wrenches, and tire levers, keeping you ready for minor repairs and adjustments on the go. Conquer your journey with Cymbal Odyssey!", PENDING_COMMIT_TIMESTAMP(), 52, 999), (1, 10,"Cymbal Nomad Water Bottle","Stay hydrated on every ride with the Nomad water bottle. Its sleek design, BPA-free construction, and secure lock lid make it the perfect companion for staying refreshed and motivated throughout your adventures. Hydrate and explore with Cymbal Nomad!", PENDING_COMMIT_TIMESTAMP(), 42, 1299);

クエリが正常に実行されると、「このステートメントで 10 行が挿入されました。返された行はありません」というメッセージが表示されます。

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 新しいテーブルを作成して商品データを読み込む。

タスク 3. 商品データのテキスト エンベディングを生成して保存する

タスク 1 でエンベディング モデルを作成する際に、Vertex AI モデルのエンドポイントを介してエンベディング モデルにアクセスするために使用される Spanner サービス アカウントの作成も開始されています。

このタスクではまず、このサービス アカウントに Vertex AI エンドポイントへアクセスするために必要なロールが付与されていることを確認します。次に、クエリを実行して商品説明のエンベディングを生成し、products テーブルに保存します。

Spanner サービス アカウントに Cloud Spanner API サービス エージェントのロールを付与する

1. Google Cloud コンソールのナビゲーション メニュー（）で、[IAM と管理] > [IAM] を選択します。

2. [アクセス権を付与] をクリックします。

3. [新しいプリンシパル] に、Spanner サービス アカウント ID（service-@gcp-sa-spanner.iam.gserviceaccount.com）を入力します。

注: このサービス アカウントが表示されない場合は、タスク 1 で開始されたサービス アカウントのプロビジョニングがまだ完了していない可能性があります。このウィンドウを閉じ、3 分待ってから手順 2～3 を繰り返します。

4. [ロールを選択] で、フィルタを使用して Cloud Spanner API サービス エージェントを検索し、選択して [ロール] ボックスに設定します。

5. [保存] をクリックします。

注: No change - principal already exists on the policy（変更なし - プリンシパルはすでにポリシーに存在します）」というメッセージが表示された場合は、ロールを再度付与しようとせずに、次のセクションに進んでください。

productDescriptionEmbedding 列を更新して、生成されたテキスト エンベディングを保存する

Spanner サービス アカウントに適切なロールが付与されていることを確認したので、商品説明のテキスト エンベディングを生成し、products テーブルに追加します。

1. タスク 1 のステップ 1～4 に沿って、Spanner Studio に戻ります。

2. 次のクエリをコピーしてクエリ ウィンドウに貼り付け、生成されたエンベディングで productDescriptionEmbedding という名前の列を更新し、[実行] をクリックします。

UPDATE products p1 SET productDescriptionEmbedding = (SELECT embeddings.values from ML.PREDICT(MODEL EmbeddingsModel, (SELECT productDescription as content FROM products p2 where p2.productId=p1.productId))) WHERE categoryId=1; 注: Permission denied on the resource（リソースへのアクセスが拒否されました）のようなエラー メッセージが表示された場合は、前の手順で付与した権限が完全に反映されるまで数分待ってから、クエリを再実行してください。

クエリが正常に実行されると、「クエリによって 10 行が更新されました」というメッセージが表示されます。

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 商品データのテキスト エンベディングを生成して保存する。

Spanner Studio を開いたまま、次のタスクに進みます。

タスク 4. Spanner でテキスト エンベディングを使用してベクトル検索を行う

商品説明のテキスト エンベディングを生成して保存したので、データに対して初のリアルタイムのベクトル検索を行う準備が整いました。

このタスクでは、クエリを実行して「I'd like to buy a starter bike for my 3 year old child」というフレーズに基づく類似検索を行い、商品データにこのテキストの完全一致が含まれていないとしても関連性が最も高い上位 5 件の商品をすばやく取得します。

1. Spanner Studio のクエリエディタで、[実行] と同じメニューバーにある [クリア] をクリックして、前のクエリを削除します。

2. テキスト エンベディングを使用してベクトル検索を行うには、次のクエリをコピーしてクエリ ウィンドウに貼り付け、[実行] をクリックします。

SELECT productName, productDescription, inventoryCount, COSINE_DISTANCE( productDescriptionEmbedding, ( SELECT embeddings.values FROM ML.PREDICT( MODEL EmbeddingsModel, (SELECT "I'd like to buy a starter bike for my 3 year old child" as content) ) ) ) as distance FROM products WHERE inventoryCount > 0 ORDER BY distance LIMIT 5;

このクエリは、productDescriptionEmbedding 列の値を使用して、検索フレーズ「I'd like to buy a starter bike for my 3 year old child」と意味的に最も類似している上位 5 件のデータベース行を検索します。

注目する点として、検索フレーズのエンベディングは、このクエリで動的に生成されます。上記のコード内の「I'd like to buy a starter bike for my 3 year old child」の部分を任意の新しい検索語句に置き換えて、このクエリをさらに試してみてください。

出力は次のようになります。

productName	productDescription	inventoryCount	distance
Cymbal Sprout	Let their cycling journey begin with the Cymbal Sprout, the ideal balance bike for beginning riders ages 2-4 years...	10	0.3094387191860244
Cymbal Spark Jr.	Light, vibrant, and ready for adventure, the Spark Jr. is the perfect first bike for young riders (ages 5-8)...	34	0.3412342902117166
Cymbal Helios Helmet	Safety meets style with the Cymbal children's bike helmet...	100	0.4197863319656684
Cymbal Breeze	Cruise in style and embrace effortless pedaling with the Breeze electric bike...	72	0.485231776523978
Cymbal Phoenix Lights	See and be seen with the Phoenix bike lights...	87	0.5251486508206732

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 Spanner でテキスト エンベディングを使用してベクトル検索を行う。

お疲れさまでした

このラボでは、Spanner でエンベディング モデルを作成して Vertex AI モデルのエンドポイントに設定する方法、Spanner のテーブルでテキスト エンベディングを生成して保存する方法、保存したテキスト エンベディングを使用して Spanner でベクトル検索を行う方法を学びました。

次のステップと詳細情報

• 「ベクトル検索とエンベディング」コースで、ベクトル検索とエンベディングの主要なコンセプトについて詳しく学ぶ。
• ベクトル検索に関する Spanner のドキュメント「K 近傍法を探索して Spanner でベクトル類似性検索を行う」と、ベクトル インデックスに関するドキュメント「ベクトル インデックス」を確認する。
• このラボ用に調整された、Derek Downey、Rose Liu、Chow Lin による Codelab「Spanner ベクトル検索を使ってみる」を確認する。
• 「Cloud Spanner インスタンスの作成と管理」コースで、Spanner に関する他のハンズオンラボに取り組む。

Google Cloud トレーニングと認定資格

Google Cloud トレーニングと認定資格を通して、Google Cloud 技術を最大限に活用できるようになります。必要な技術スキルとベスト プラクティスについて取り扱うクラスでは、学習を継続的に進めることができます。トレーニングは基礎レベルから上級レベルまであり、オンデマンド、ライブ、バーチャル参加など、多忙なスケジュールにも対応できるオプションが用意されています。認定資格を取得することで、Google Cloud テクノロジーに関するスキルと知識を証明できます。

マニュアルの最終更新日: 2025 年 10 月 28 日

ラボの最終テスト日: 2025 年 10 月 28 日

Copyright 2026 Google LLC. All rights reserved. Google および Google のロゴは Google LLC の商標です。その他すべての企業名および商品名はそれぞれ各社の商標または登録商標です。