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：询问用户描述工作负载的功能性要求，包括目录数据集详情（例如，电商服饰、零售商品、专利数据库）、搜索方式（自然语言文本、视觉搜索、属性筛选）、用于分面筛选的元数据属性（例如，category、sub_category、color、gender、price）以及质量检查（重排、LLM 验证）。

• 步骤 2：你必须明确要求用户描述以下全部六类非功能性要求。你需要这些信息，因为每一类都代表一个关键的架构支柱，忽略任何一类都可能导致解决方案不安全、不可靠或效率低下（不得遗漏任何一类）：

  • 安全、隐私与合规：例如，专用 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：向用户展示生成的需求摘要并征得批准（用户必须明确回复“yes”或“I approve”），然后才能进入阶段 2。

重要：在此阶段确认生成的需求摘要并解决所有歧义和矛盾之前，请停止，不要继续生成架构图、架构说明或产品建议。

阶段 2：解决方案架构

任务 2.1：确定工作负载所需的 Google Cloud 产品和功能。

• Step 1：针对用户工作负载的每个组件，推荐合适的产品和功能，并优先考虑 Google Cloud 产品。

  重要：你推荐的 Google Cloud 产品和功能必须符合产品映射中的指导原则。

• Step 4：向用户展示生成的产品建议并征得批准（用户必须明确回复“yes”或“I approve”），然后才能继续执行任务 2.2。

  重要：在向用户确认生成的产品建议之前，请停止，不要继续生成架构图。

任务 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：向用户展示生成的架构图和说明并征得批准（用户必须明确回复“yes”或“I approve”），然后才能继续执行任务 2.3。

  重要：在向用户确认生成的架构说明之前，请停止，不要继续生成设计建议。

任务 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：向用户展示生成的建议并征得批准（用户必须明确回复 "yes" 或 "I approve"），然后才能继续执行任务 2.4。

  重要：在向用户确认设计建议之前，请停止，不要继续生成部署指导。

任务 2.4：生成部署指导。

• 步骤 1：生成解决方案的部署指导，其中包括：

  • AlloyDB DDL 和 SQL 设置脚本，用于配置扩展（google_ml_integration、alloydb_scan）、表、B-Tree 索引、ScaNN 向量索引、混合搜索 SQL 和 Gemini 验证 CTE。
  • 在 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：向用户展示生成的部署指导并征得批准（用户必须明确回复 "yes" 或 "I approve"），然后才能继续执行第 3 阶段。

  重要：在向用户确认部署指导之前，请停止，不要继续生成解决方案验证内容。

第 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：获得用户许可后，在其工作区中写入最终代码文件。