企业官网建设流程全解析

Google skills：基于 AlloyDB 的混合搜索解决方案架构模板全解——从需求到验证的 8 章节交付框架

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

在 google/skills 仓库中，google-cloud-solution-hybrid-search-alloydb这个 Agent Skill 用于指导 AI 助手完成“语义搜索 + 关键词/结构化过滤”混合搜索系统的架构设计、部署与验证。本文围绕该 Skill 的核心交付物模板 output-template.md 展开：它定义了最终架构文档solution-architecture-guide.md的 8 章节骨架、产品选型对比表、Mermaid 架构拓扑示例以及各支柱的配置基线。读完本文，你可以理解这套模板如何把一个混合搜索需求（向量检索 + SQL 过滤 + 语义重排）系统性地转化为一份可直接落地的 Google Cloud 架构方案，并掌握其中 ScaNN 索引调优、MCP Toolbox 抽象层与 Cloud Run 无服务器托管等关键技术要点。

一、模板的定位：Solution Architect Skill 的“最后一章”

该 Skill 的完整工作流定义在 SKILL.md 中，分为四个严格分阶段（phase）的流程：

1. Phase 1 需求发现：收集目录数据集规模、搜索模态、分面属性、六大类非功能需求（安全/可靠/成本/运维/性能/可持续）与依赖，要求用户显式批准后才进入下一阶段；
2. Phase 2 方案设计：产品选型（Task 2.1）、架构图表与描述（Task 2.2）、设计建议（Task 2.3）、部署指引（Task 2.4）；
3. Phase 3 方案验证：部署前静态干跑检查（terraform plan、gcloud ... --dry-run）与部署后运行时验证（curl/ping/gcloud探活）；
4. Phase 4 方案打包与呈现：把 Phase 2 产出整合为一份名为solution-architecture-guide.md的 Markdown 文档——这一步正是套用 output-template.md 模板，写入用户工作区。

模板开头的注释也点明了这一用途：“Use this template to compile the content that you generate based on the instructions inSKILL.md”。换言之，模板不是给人直接填写的空白表单，而是约束 Agent 输出文档结构的“契约”：每个章节对应工作流中的某个产出物，保证最终交付文档既完整（8 章不缺）、又与该 Skill 引用的两份参考资料 product-mapping.md 和 design-recommendations.md 保持事实一致。

该 Skill 的适用边界在 SKILL.md 元数据中写得很明确：面向“向量检索 + 结构化 SQL 过滤、分面属性、语义重排、库内 AI 质量校验、无服务器托管”的场景；不适用于纯关键词搜索，或必须使用独立非关系型向量数据库的场景。

二、8 章节骨架：模板逐节解析

2.1 第 1～2 章：执行摘要与需求基线

模板第 1 章要求用简短篇幅描述工作负载的业务目标与高层方案架构，是面向评审者的“电梯陈述”。

第 2 章是需求基线，把功能与非功能需求拆开固化，避免设计阶段出现“需求漂移”：

• 功能需求（2.1）：支持的业务流程、关键活动与用例——在混合搜索场景下即目录数据集（电商服饰、零售商品、专利库等）、搜索模态（自然语言、视觉搜索、属性过滤）与分面字段（category、sub_category、color、gender、price）；
• 非功能需求（2.2）：模板固定列出六个支柱条目——Security（合规、加密、访问控制）、Reliability（SLA、RTO/RPO、备份、冗余）、Cost、Operations（监控、日志、部署、维护）、Performance（时延、吞吐、扩展性）、Sustainability（碳足迹、资源优化）。这与 Phase 1 Step 2 强制询问的六大类一一对应；
• 现状（2.3）与依赖（2.4）：现有基础设施（本地/他云）、迁移动因，以及内外部依赖（库存数据库、ERP、运行时语言如 Java/Python）。

2.2 第 3 章：工作负载的技术分解

模板要求把应用拆成五个逻辑层，这是整份文档中把“业务语言”翻译为“技术语言”的关键一步：

这一分解直接决定了第 4 章产品映射表的行结构——每个逻辑层对应一行“推荐产品 + 选型理由 + 备选方案”的决策记录。

2.3 第 4 章：产品映射表与架构拓扑

模板第 4.1 节给定了一张五列决策表，要求每个组件都写清推荐产品、理由与引用、备选方案及其优缺点：

这张表必须与 product-mapping.md 中的推荐一致。该参考文件给出了各组件的首选与备选：

• 数据库与向量存储：首选AlloyDB for PostgreSQL（AlloyDB AI）——ScaNN 索引在高召回下比标准 HNSW/IVFFlat 快至 4 倍；库内向量化embedding('text-embedding-005', ...)、库内重排ai.rank、库内 LLM 调用ml_predict_row消除数据出库；内置evaluate_query_recall做库内精度测量；单条 SQL 即可把向量相似度排序与WHERE category = ANY(...)结构化过滤融合。备选一是BigQuery Vector Search（AI.SEARCH的mode => 'HYBRID'、VECTOR_SEARCH的lexical_search_columns、AI.GENERATE_EMBEDDING/AI.EMBED批量与自治向量化、CREATE VECTOR INDEX支持 ScaNNTREE_AH/IVF），适合 GB～PB 级分析型 RAG；备选二是Cloud SQL（MySQL 的VECTOR类型、ScaNNTREE_SQ、approx_distance/vector_distance，PostgreSQL 的pgvector），适合 1000 万行以下的中小负载，成本更低。
• 向量嵌入引擎：首选Gemini Enterprise Agent Platform 的文本嵌入模型（768 维稠密向量，可直接从 AlloyDB/BigQuery/Cloud SQL 的 SQL 中调用，多语言与零售领域语义准确度高，全托管免运维）；备选为 Cloud Run 或 Agent Platform 上自托管的开源/微调嵌入模型，换取完全的模型定制能力。
• 数据库抽象与 Agent 工具层：首选MCP Toolbox for Databases——把数据库执行与复杂混合搜索 SQL 从应用代码中解耦，向 Agent 暴露干净的 REST/MCP 工具端点，并可用自定义工具（如带租户隔离边界的lookup_active_order）替代开放式execute_sql；备选为 Google Cloud 托管远程 MCP 服务器（Agent Registry 管理、内置 IAM 与 Model Armor 扫描）或部署在 Cloud Run 上的自定义远程 MCP 服务器（TypeScript/Python/Go/FastMCP，streamable HTTP 或 SSE 传输，roles/run.invoker服务间认证）。
• Web 应用托管：首选Cloud Run——缩容到零、原生 Direct VPC Egress 私有直连 AlloyDB，兼容任意容器化框架。
• 网络与安全拓扑：首选Regional 外部应用负载均衡器 + Direct VPC Egress——Cloud Armor 提供 DDoS/WAF 防护，流量经区域型外部 ALB 进入配置了 Direct VPC Egress 的 Cloud Run 服务，数据库层保持严格的物理与网络隔离。

第 4.2 节则要求给出 Mermaid 架构拓扑图。模板内置了一个示例拓扑，展示经典的服务链路：

从该图与 SKILL.md 中 Task 2.2 的示例流程可以看出，架构图必须同时画出两条管线：

• 摄取管线：Catalog Data → AlloyDB 表（如apparels）→ 分面列 B-Tree 索引 →text-embedding-005文本嵌入 → ScaNN 向量索引；
• 服务管线：用户浏览器 → Cloud Run Web 应用 → MCP Toolbox for Databases → AlloyDB 单查询混合搜索（ScaNN 向量检索 + SQLWHERE过滤）→ai.rank重排器 → Gemini Proai.generate质量校验 → 校验后结果返回浏览器。

第 4.3 节要求把上述拓扑展开为文字描述，并强制区分Data flow与Tasks/control flow两条线索，避免“只画线不解释数据怎么动、控制怎么走”。

2.4 第 5 章：六支柱设计建议的“填空基线”

模板第 5 章按 Google Cloud Well-Architected Framework 六个支柱组织配置建议，每个条目都内置了混合搜索场景的默认最佳实践（与 design-recommendations.md 对齐）：

5.1 安全、隐私与合规

• 访问控制：IAM 最小权限角色（roles/alloydb.client、roles/aiplatform.user）叠加 PostgreSQL 原生CREATE ROLE细粒度授权，防止DROP TABLE/TRUNCATE等破坏性命令；通过ALTER ROLE user_name SET search_path = pg_catalog, pg_temp;防搜索路径劫持；
• 数据保护：CMEK 静态加密、mTLS 传输加密（AlloyDB Auth Proxy/Language Connector，TLS 1.3）、DLP 去标识化模板；
• 网络安全：Direct VPC Egress、PSC（Private Services Access）、Cloud Armor WAF 规则（sqli-v33-stable与 XSS 防护）、禁用 Cloud Run 默认run.app入口 URL；
• Agent 安全：用带租户过滤的自定义工具替代开放式execute_sql防多租户提示注入泄露；硬编码 Action-Selector 或双 LLM 护栏前置筛查 + 工具白名单防工具链滥用；对 AI 端点启用 Model Armor 并配置model_armor_config.json的 DLP 模板脱敏 PII；对 MCP 工具与 AlloyDB 开启数据访问审计日志（记录原始 LLM SQL、工具参数、用户/会话 ID）以检测数据外泄。

5.2 可靠性

• AlloyDB 主实例多可用区 HA 自动故障切换 + 微秒级 PITR 持续备份（可从 Agent 误操作/恶意破坏中恢复）；
• Cloud Run 服务与 shim 跨多可用区部署；
• 区域型/双区域型 Cloud Storage + Pub/Sub 流控与重试策略承接摄取尖峰。

5.3 运维卓越

• ScaNN 索引开启自动维护以降低召回退化；
• AlloyDB Query Insights / System Insights 面板监控查询时延、复制延迟、峰值连接数；
• 应用日志结构化 JSON 入 Cloud Logging，Cloud Trace 打通跨服务端到端链路。

5.4 成本优化

• AlloyDB 计算负载用 CUD（承诺使用折扣），非生产环境用 basic 实例；
• Cloud Run 空闲缩容到零；
• Cloud Storage 对象生命周期管理归档/删除临时摄取数据；
• Cloud Logging 排除过滤器丢弃非关键调试日志。

5.5 性能效率（ScaNN 调优核心）

模板在此处给出了可直接引用的索引参数基线，这也是整份模板信息密度最高的部分：

• 多级树参数（按数据集规模与树深选择）：
  • 两级树：num_leaves = sqrt(rows)（构建速度均衡）或rows/100（质量最优）；
  • 三级树：max_num_levels = 2，num_leaves = power(rows, 2/3)（均衡）或rows/100（质量）；
  • 四级树：scann.max_allowed_num_levels = 3、max_num_levels = 3、num_leaves = power(rows, 3/4)；
• 高选择性过滤场景：scann.satisfy_limit = 'relaxed_order'（流式叶搜索）配合scann.max_pct_leaves_to_search = 15限制分区搜索数量以提升召回；
• 高维嵌入（≥ 500 维）：调优scann.pre_reordering_num_neighbors（默认50 * K）精修重排精度；
• 分面列建 B-Tree 索引；
• 数据更新侧：自动化嵌入生成 + ScaNN 索引自维护（MODE='AUTO'）；
• 网络侧：Cloud Run 挂 Direct VPC Egress 建立到 AlloyDB 的低时延私有 IP 路径，无公网跳板。

5.6 可持续性

• 无服务器计算（Cloud Run 及其 functions）空闲自动缩容降低能耗；
• 向量距离计算、全文排序、嵌入生成全部在 AlloyDB 库内执行，避免跨服务网络出口与重复计算。

2.5 第 6 章：部署指引

模板把部署拆成“前置条件”与“分步操作”两部分，并内置了默认项：

• 6.1 前置条件：例如启用 API（alloydb.googleapis.com、aiplatform.googleapis.com、run.googleapis.com）、安装工具链（gcloud、Terraform、psql）；
• 6.2 分步操作：认证并设置项目环境 →terraform init && terraform apply应用基础设施 → 部署容器化应用与 MCP 工具到 Cloud Run。

与 SKILL.md Task 2.4 的要求对照，部署指引还必须包含五类具体工件：AlloyDB DDL/SQL 脚本（google_ml_integration、alloydb_scan扩展，表、B-Tree 索引、ScaNN 向量索引、混合搜索 SQL、Gemini 校验 CTE）、Cloud Run 上的 MCP Toolbox 部署配置、Python Cloud Run Function shim 的部署命令、应用部署命令gcloud run deploy {app_name}，以及创建所需基础设施的 Terraform 代码或gcloudCLI。参考文档 related-guidance.md 进一步列出了该方案依赖的官方资料主题：MCP Toolbox 的 Agent 安全交互、基于 Agent Platform 与 AlloyDB 的 RAG 参考架构、AlloyDB ScaNN 调优最佳实践（num_leaves、num_leaves_to_search、pre_reordering_num_neighbors）、AlloyDB 连接方式选型（Auth Proxy / PSC / VPC 对等）、AlloyDB 安全最佳实践，以及 Cloud Run 上的混合搜索 Codelab、AlloyDB 混合向量相似搜索、AI 算子语义查询评估（ml_predict_row与ai.rank）和 Cloud Run Direct VPC Egress 配置。

2.6 第 7～8 章：验证计划与参考资料

第 7 章要求给出“部署前静态干跑 + 部署后运行时验证”两层计划。静态侧包括terraform plan/gcloud ... --dry-run校验语法与资源预览，以及网络路由、防火墙、IAM 策略的静态核验；运行时侧（用户选择实际部署时）包括curl/ping/gcloud探活命令测试端点可达性、网络路径与负载均衡路由。模板还点名了混合搜索特有的验证手段：用evaluate_query_recall测量 ScaNN 向量查询召回率，以及端点健康检查——这与 Phase 3 的 Task 3.1/3.2 严格对应。

第 8 章要求列出方案引用的官方文档清单（如 MCP Toolbox 安全交互、RAG 参考架构、ScaNN 调优最佳实践、AlloyDB 连接方式、AlloyDB 安全最佳实践等主题），保证架构结论可溯源。

三、把模板当“质检清单”用：与 WAF Skill 体系的衔接

值得注意的细节是：SKILL.md 在 Task 2.3（生成设计建议）中明确要求，针对非功能需求要调用六个 Well-Architected Framework 支柱 Skill——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（例如 google-cloud-waf-security 采用“评估问题清单 → 差距分析 → 建议形成 → 建议解释”的四步工作流）。模板第 5 章的六个 5.x 小节与这六个支柱 Skill 一一对应，因此可以推断：模板第 5 章的每个小节就是对应 WAF Skill 输出的落位处，这样设计保证了混合搜索方案的安全/可靠/成本等建议不是自由发挥，而是由仓库内已沉淀的支柱级方法论支撑。

同时 SKILL.md 还要求生成内容时先查阅 product-mapping.md 与 design-recommendations.md，信息不足时再通过 Google Developer Knowledge MCP 服务器等渠道取证，避免架构承诺先于需求澄清、避免幻觉式选型。

四、模板中的产品命名与兼容性说明

SKILL.md 专门给出一张命名映射表，模板产出物必须遵守：旧名Vertex AI对应新名Gemini Enterprise Agent Platform（首次出现后可简称 Agent Platform）；Vertex AI Embedding对应 Agent Platform 上的文本嵌入模型；Vertex AI Matching Engine对应Vector Search。需要注意的是，底层 API、Terraform 资源与 IAM 角色可能仍保留旧标识符——这正是模板第 4.1 章“Justification and citations”列要求引用官方文档的原因：产品名在变，证据链必须跟最新文档对齐。

五、在仓库中定位这套材料

六、总结

output-template.md 表面上是一份 8 章节的 Markdown 模板，实质上是 google/skills 仓库中“Agentic 架构师”工作流的输出契约：它把需求基线（第 2 章）、五层技术分解（第 3 章）、带决策记录的产品映射与 Mermaid 拓扑（第 4 章）、WAF 六支柱配置基线（第 5 章）、部署工件清单（第 6 章）、双层验证计划（第 7 章）与可溯源引用（第 8 章）固化下来，并让 Agent 在填充每一章时必须回溯 product-mapping.md 与 design-recommendations.md 中的事实基线。对使用者而言，理解这份模板就是理解如何把“AlloyDB + ScaNN + 库内 AI 算子 + MCP Toolbox + Cloud Run”这套混合搜索参考架构，转化为一份可评审、可部署、可验证的完整方案文档。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills