google-cloud-solution-hybrid-search-alloydb

AlloyDB を使用した動的ハイブリッド検索

このスキルでは、構造化データセットのフィルタリング、ベクトル検索インデックス、ファセットメタデータフィルタリング、セマンティックな再ランキング、再現率の評価、データベース内 AI 検証、データベース抽象化レイヤー、サーバーレスアプリケーションのホスティングを組み合わせた、安全で低レイテンシーかつ高精度なハイブリッド検索ソリューションを設計、実装するためのワークフローを提供します。

帰属表示

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、 使用上の帰属表示を必ず読み、その指示に従ってください。

ワークフローの概要

ワークフローは次のフェーズで構成されています。

1. 要件の調査。ユーザーが支援を必要としているクラウドワークロードまたはユースケースに関する詳細な要件を収集します。
2. ソリューションアーキテクチャ。フェーズ 1 で収集した要件を使用して、クラウドワークロードまたはユースケースの詳細なソリューションアーキテクチャを作成します。
3. ソリューションの検証。作成したソリューションを検証する計画を立て、検証手順とスクリプトを作成して、検証を実行します。
4. ソリューションのパッケージ化と提示。作成したコンテンツをまとめ、ソリューションを提示します。

ワークフローに関する重要な注意事項：

• フェーズの厳格な分離：フェーズ 1（要件の調査）でユーザーに確認の質問をする際は、アーキテクチャ設計、クラウドサービス、コンポーネントの対応関係について、推奨、提案、概要の提示をしてはいけません。これにより、全体像を理解する前にアーキテクチャを性急に決定したり、誤った情報を生成したりすることを防ぎます。
• 承認が得られるまで停止：「続行前に承認を得る」よう指示された手順では、必ず実行を停止し、完了したタスクをユーザーに提示して、ユーザーから明示的な承認が得られるまで待ってください。その応答内で、後続のタスクを実行したり、追加のガイダンスを生成したりしてはいけません。
• 生成するすべてのコンテンツの根拠を確認：すべてのフェーズのすべてのタスクで、まず次のリソースを確認してください。

  • プロダクトのマッピング、

  • 必要なガイダンスが記載された設計上の推奨事項。ガイダンスに必要な情報がない場合は、次のリソースを使用して、生成するコンテンツの根拠を確認してください。

  • Google Developer Knowledge MCP サーバー： https://developers.google.com/knowledge/mcp.md.txt

    • サーバー：https://developerknowledge.googleapis.com/mcp
      • ツール：
        • developerknowledge:search_documents
        • developerknowledge:get_documents
        • developerknowledge:answer_query

  • https://github.com/google/skills の関連スキル

  • 関連ガイダンスに記載された Google Cloud の公式ドキュメント

プロダクト名の変更と用語

ソリューション設計、アーキテクチャ図、ドキュメントを作成する際は、最新のプロダクト名を確認するために、Google Cloud の最新ドキュメントを参照してください。以下の表は、把握しておくべき名称の対応例です。基盤となる API、Terraform リソース、IAM ロールには、以前の識別子が引き続き使用される場合があります。

以前の名称	更新後の名称	備考
Vertex AI	Gemini Enterprise Agent Platform	Gemini Enterprise Agent Platform は、初出後に Agent Platform と短縮できます
Vertex AI Embedding	Gemini Enterprise Agent Platform のテキスト埋め込み	Gemini Enterprise Agent Platform で利用できるテキスト埋め込みモデルを指します
Vertex AI Matching Engine	Vector Search

フェーズ 1：要件の調査

このフェーズでは、Google Cloud で設計、デプロイするハイブリッド検索ワークロードに関する詳細な要件をユーザーから収集する必要があります。 提示された要件を確認する：ユーザーのプロンプトに、カタログの規模、検索方式、ファセット属性、レイテンシの目標など、機能要件または非機能要件がすでに含まれている場合は、回答でそれらの要件をすべて明示的に確認し、再度提示する必要があります。ユーザーがプロンプトですでに示した要件について、説明や再説明を求めてはいけません。

以下の手順を指定された順序どおりに実行してください。

• ステップ 1：ワークロードの機能要件をユーザーに説明してもらいます。カタログデータセットの詳細（例：e コマースのアパレル、小売商品、特許データベース）、検索方式（自然言語テキスト、ビジュアル検索、属性フィルター）、ファセットフィルタリング用のメタデータ属性（例：category、sub_category、color、gender、price）、品質チェック（再ランキング、LLM による検証）を含めてください。

• ステップ 2：以下の 6 つの非機能要件カテゴリすべてについて、ユーザーに明示的に説明を求める必要があります。各カテゴリは重要なアーキテクチャの柱であり、いずれかを考慮しないと、安全性、信頼性、効率性に欠けるソリューションになるおそれがあるためです（いずれも省略してはいけません）。

  • セキュリティ、プライバシー、コンプライアンス：例：プライベート VPC エンドポイント、Private Service Connect、Direct VPC Egress、アクセス制御。
  • 信頼性：例：高可用性、フェイルオーバー、災害復旧の目標（RTO/RPO）、リージョン構成かマルチリージョンの AlloyDB トポロジか。
  • コスト：例：コンピューティング、データベースインスタンス、Gemini Enterprise Agent Platform API 呼び出しの予算上の制約。
  • オペレーショナルエクセレンス：例：モニタリング、ロギング、ダッシュボード、自動デプロイ。
  • パフォーマンス：例：クエリの P95 レイテンシ目標（例：< 100ms）、ベクトル検索の再現率目標（例：> 95%）、カタログ商品の規模、QPS の想定値。
  • サステナビリティ：例：カーボンフットプリント、低炭素リージョンの選択。

• ステップ 3：ワークロードが現在、他のクラウドプロバイダーまたはオンプレミスで稼働しているかどうかをユーザーに尋ねます。

  • ユーザーの回答が「はい」の場合は、現在のデプロイのアーキテクチャを説明してもらいます。
  • ユーザーの回答が「いいえ」の場合は、次のステップに進みます。

• ステップ 4：他のワークロード、製品、ツールとの依存関係があれば、ユーザーに説明してもらいます（例：既存の在庫データベース、ERP システム、Java や Python などのアプリケーション実行時言語）。

• ステップ 5：これまでにユーザーから提供された情報を確認し、機能要件、非機能要件、依存関係に曖昧さ、競合、矛盾がないかを確認します。競合を特定するために、すべての要件を相互に照らし合わせる必要があります。

  ユーザーが提示した要件に曖昧さ、競合、矛盾を見つけた場合は、それぞれについて以下を必ず行ってください。

  • 各矛盾がどこにあるかを正確に特定し、要件が両立せず、同時に満たせない理由をユーザーに説明します。根本的な矛盾を設計上の選択肢に関する質問として扱ってはいけません（例：競合する要件をどのように実装または設定するかを尋ねる）。
  • 矛盾を解決するために、どのようなトレードオフを優先するかユーザーに確認します。
  • ユーザーが選択を委ねた場合（例：「最善だと思う方法で進めてください」「お任せします」と回答した場合）は、曖昧さや矛盾を解消する明確な提案を提示し、その理由を説明して、提案を承認するようユーザーに求めます。

  重要：特定した曖昧さや矛盾が、上記のガイダンスに従ってすべて解決されるまで、アーキテクチャ設計や Google Cloud 製品の推奨を提示してはいけません。

• Step 6: ユーザーが提示した機能要件と非機能要件を、統合された要件概要にまとめます。

• Step 7: 生成した要件概要をユーザーに提示し、承認を得てください（ユーザーは、Phase 2 に進む前に「yes」または「I approve」と明示的に回答する必要があります）。

重要: このフェーズで生成した要件概要を確認し、すべての曖昧さと矛盾を解消するまでは、アーキテクチャ図、アーキテクチャの説明、または製品の推奨事項の生成に進まないでください。

Phase 2: ソリューションアーキテクチャ

Task 2.1: ワークロードに必要な Google Cloud の製品と機能を特定します。

• Step 1: ユーザーのワークロードの各コンポーネントに適した製品と機能を推奨し、Google Cloud 製品を優先します。

  重要: 推奨する Google Cloud の製品と機能は、 製品マッピングのガイダンスに必ず準拠してください。

• Step 4: 生成した製品の推奨事項をユーザーに提示し、Task 2.2 に進む前に承認を得てください（ユーザーは「yes」または「I approve」と明示的に回答する必要があります）。

  重要: 生成した製品の推奨事項をユーザーと確認するまでは、アーキテクチャ図の生成に進まないでください。

Task 2.2: アーキテクチャ図と説明を生成します

• Step 1: Mermaid 形式でアーキテクチャ図を生成します： https://github.com/mermaid-js/mermaid.

  図には、収集した要件と製品の推奨事項に基づいて、アーキテクチャのコンポーネント間のデータフローとリクエストフローを示す必要があります。図には、取り込みパイプラインとサービングパイプラインの両方を必ず明示してください。

  アーキテクチャ図に示すデータフローとリクエストフローの例を以下に示します。

  • 取り込みパイプライン: カタログデータ -> AlloyDB テーブル (apparels) -> ファセットの B-Tree インデックス -> テキスト埋め込み (text-embedding-005) -> ScaNN ベクトルインデックス。
  • サービングパイプライン: ユーザーブラウザー -> Cloud Run Web アプリ -> データベース用 MCP Toolbox -> AlloyDB の単一クエリによるハイブリッド検索（ScaNN ベクトル検索 + SQL WHERE フィルター）-> ai.rank リランカー -> Gemini Pro ai.generate による品質検証 -> 検証済みの結果 -> ユーザーブラウザー。

• Step 2: 各コンポーネントの目的、コンポーネント間の関係、タスクフローまたはデータフローを説明する説明文を生成します。

• Step 3: 生成したアーキテクチャ図と説明をユーザーに提示し、Task 2.3 に進む前に承認を得てください（ユーザーは「yes」または「I approve」と明示的に回答する必要があります）。

  重要: 生成したアーキテクチャの説明をユーザーと確認するまでは、設計上の推奨事項の生成に進まないでください。

タスク 2.3：設計上の推奨事項を生成する

• ステップ 1：ワークロードの要件に基づいて、アーキテクチャ内の各コンポーネントを最適に構成するための設計上の推奨事項とベストプラクティスを生成します。

  重要：

  • 設計上の推奨事項を生成する際は、以下を考慮してください。
    • フェーズ 1 で収集した機能要件。
    • フェーズ 1 で収集した非機能要件。
  • 生成する設計上の推奨事項を、設計上の推奨事項に記載された推奨事項に沿わせてください。
  • 非機能要件に関するガイダンスを生成するには、以下のスキルを使用してください。
    • google-cloud-waf-security
    • google-cloud-waf-reliability
    • google-cloud-waf-cost-optimization
    • google-cloud-waf-operational-excellence
    • google-cloud-waf-performance-optimization
    • google-cloud-waf-sustainability

• ステップ 2：生成した推奨事項をユーザーに提示し、承認を得てください。タスク 2.4 に進む前に、ユーザーが「yes」または「I approve」と明示的に回答する必要があります。

  重要：ユーザーと設計上の推奨事項を確認するまでは、停止し、デプロイのガイダンスの生成に進まないでください。

タスク 2.4：デプロイのガイダンスを生成する

• ステップ 1：以下を含む、ソリューションのデプロイに関するガイダンスを生成します。

  • 拡張機能（google_ml_integration、alloydb_scan）、テーブル、B-Tree インデックス、ScaNN ベクトルインデックス、ハイブリッド検索 SQL、Gemini 検証 CTE 用の AlloyDB DDL および SQL セットアップスクリプト。
  • Cloud Run 上の MCP Toolbox デプロイ構成。
  • Python Cloud Run Function シムのデプロイコマンド。
  • アプリケーションのデプロイコマンド（gcloud run deploy {app_name}）。
  • 必要なインフラストラクチャを作成する Terraform コードまたは gcloud CLI コマンド。

  重要：生成するデプロイのガイダンスは、以下のリソースのガイダンスと整合している必要があります。

  • 関連ガイダンス
  • https://github.com/google/skills/tree/main/skills/cloud にある関連スキル

• ステップ 2：生成したデプロイのガイダンスをユーザーに提示し、承認を得てください。フェーズ 3 に進む前に、ユーザーが「yes」または「I approve」と明示的に回答する必要があります。

  重要：ユーザーとデプロイのガイダンスを確認するまでは、停止し、ソリューションの検証の生成に進まないでください。

フェーズ 3：ソリューションの検証

タスク 3.1：デプロイ前の検証

• ステップ 1：生成したソリューションを静的に検証し、稼働中のリソースをプロビジョニングせずにワークロードの要件を満たしていることを確認するための、デプロイ前計画を作成します。
  • デプロイのドライラン：ドライランコマンド（例：terraform plan または（サポートされている場合）gcloud ... --dry-run）を使用して、インフラストラクチャの構文を検証し、プロビジョニングされるリソースをプレビューします。
  • アーキテクチャとポリシーの分析：ネットワークルーティングトポロジ、ファイアウォールルール、IAM の適用について、ベストプラクティスに照らして静的検証を実施します。
• ステップ 2：静的検証計画をユーザーに提示して承認を得ます（ユーザーは「yes」または「I approve」と明示的に回答する必要があります）。その後、ドライランコマンドを実行します。
• ステップ 3：ドライランチェックで特定されたエラーやポリシーの不整合をトラブルシューティングして修正し、検証が成功するまで続けます。
• ステップ 4：タスク 3.2 に進みます

タスク 3.2：実行時の検証（デプロイ後）

• ステップ 1：インフラストラクチャを今すぐデプロイして実行時のライブ検証を行うか、フェーズ 4 に直接進むかをユーザーに尋ねます。
• ステップ 2：ユーザーがインフラストラクチャのデプロイを選択した場合：
  • ユーザーがインフラストラクチャをデプロイした後、実行時検証用コマンド（curl、ping、gcloud などのツールを使用）を作成してユーザーに提示し、ライブエンドポイントへの到達性、ネットワーク経路、ロードバランサーのルーティングをテストしてもらいます。
  • チェックに合格するまで、デプロイまたは実行時のルーティングに関する問題をトラブルシューティングします。
• ステップ 3：フェーズ 4 に進みます。

フェーズ 4：ソリューションのパッケージ化と提示

• ステップ 1：フェーズ 2 で作成した最終テキスト成果物を、出力テンプレートに基づいて、solution-architecture-guide.md という名前の単一の Markdown ファイルにまとめます。
• ステップ 2：ユーザーのワークスペースにコードファイルを書き込む許可を求めます。
• ステップ 3：ユーザーの許可を得た後、ユーザーのワークスペースに最終的なコードファイルを書き込みます。