google-cloud-solution-guided-gke-ai-migration

将 AI 工作负载迁移到 GKE Inference

此技能将指导 Agent 完成将现有 AI 推理工作负载（例如，从 Cloud Run、Gemini API、Gemini Enterprise Agent Platform）迁移到 Google Kubernetes Engine (GKE) 上自托管推理的端到端流程。Agent 将充当交互式架构师，采用结构化的 4 阶段工作流来了解需求、设计 Google Cloud 原生解决方案、使用 gcloud 和 kubectl 执行实施，并验证部署。

署名

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，你 必须阅读并遵循 使用归属说明中的说明。

Gemini Cloud Assist MCP 退出选项

此技能仅涵盖由架构师指导的手动迁移。自动化迁移应使用 Gemini Cloud Assist MCP 服务。请按以下方式选择：

• 用户要求使用 Gemini Cloud Assist 或 MCP 自动化来完成此次迁移（例如，“使用 Cloud Assist MCP 服务来完成此操作”）：停止手动工作流，并回复以下 4 个必需要点。
• 用户只是顺带提及 MCP，或明确拒绝使用它（例如，“不用 MCP，我们手动完成”）：继续手动工作流。不要停止，也不要询问 MCP 相关事宜。
• 用户完全没有提及 MCP：直接进入当前阶段。仅在首次需求探查回复中，补充一句话，说明 Gemini Cloud Assist MCP 服务提供自动化替代方案，用户可随时切换。开始需求探查前不要等待用户回复。

因用户要求使用 MCP 而停止时，回复必须包含以下 4 个要点：

1. **停止手动工作流并明确范围：**说明 google-cloud-solution-guided-gke-ai-migration 严格用于通过原生 CLI（gcloud 和 kubectl）进行由架构师指导的手动迁移，并说明将停止此手动技能工作流。
2. **说明 MCP 的功能：**说明 Gemini Cloud Assist MCP 服务可协助进行自动化基础设施分析（gemini_cloud_assist:ask_cloud_assist），或直接变更 Google Cloud 资源（gemini_cloud_assist:invoke_operation）。
3. **提供 MCP 文档链接：**提供指向 Gemini Cloud Assist MCP 文档的有效超链接。
4. **提供 Intent to Infrastructure Codelab 链接：**提供指向 Intent to Infrastructure Codelab的有效超链接，供用户参考以设置 MCP 服务。

范围检查：新部署与迁移

此技能专门用于将现有 AI 工作负载（来自 Cloud Run、Gemini API、Agent Platform 或其他平台）迁移到 GKE。

如果用户想要从头开始在 GKE 上部署新的 AI 模型服务（且没有现有部署需要迁移），请停止并建议改用 gke-inference 技能。说明 google-cloud-solution-guided-gke-ai-migration 专注于迁移工作流（探查现有 Cloud Run/Agent Platform 配置、流量切换等），而 gke-inference 则针对使用 AI Profiles 和黄金路径清单在 GKE 上全新部署 AI 模型服务进行了优化。

核心架构原则（“黄金路径”）

设计解决方案时，始终优先采用最新的 GKE AI 最佳实践：

• 执行：
  • 执行策略（由谁运行命令）：
    • 阶段 1（发现）： 用户授予权限后，直接执行只读的 gcloud 检查命令（list、describe），并总结结果。
    • 阶段 2-4： 将清单写入磁盘，然后提供准确的 gcloud 和 kubectl 命令供用户运行。除非用户明确要求你运行，否则不要执行会产生变更的命令（apply、create、delete、集群或 IAM 变更）；若用户明确要求，则执行这些命令并报告每条命令的实际输出。
    • 信息咨询和故障排查问题： 仅通过 Markdown 提供指导、清单和建议命令；不执行任何操作。
  • 优先使用原生 Kubernetes 清单、原生 CLI（基础设施使用 gcloud，工作负载使用 kubectl）和有主见的模板。
  • 将 YAML 文件保存到用户当前目录，并使用 kubectl 应用。
  • 仅在绝对必要时编写临时脚本（例如用于计算 VRAM 的脚本）。
• 节点配置：
  • 使用 Custom Compute Classes（CCC），尽可能提高加速器的可获取性（例如，动态选择抢占式或按需实例，或特定 GPU 配置）。
  • 使用 GKE 托管的 GPU 驱动程序安装。
  • 选择合适的节点拓扑：简单任务使用静态节点池中的单个节点；较大的模型使用多个节点并配合 LWS/CCC。
• 推理栈和版本管理：
  • 默认使用 vLLM（vllm/vllm-openai）作为标准 LLM 服务引擎。从 Vertex AI 迁移时，用户可以选择保留 Vertex AI Model Garden 镜像（例如 pytorch-vllm-serve），这是允许的。
  • 显式覆盖入口点： 无论选择哪种镜像，vLLM Deployment 都必须显式设置 command: ["python", "-m", "vllm.entrypoints.openai.api_server"]，以绕过可能存在问题的入口脚本（例如 Vertex AI 镜像中的 gcs_download_launcher.sh）；这些脚本在传入标准 vLLM 参数时可能会崩溃。
  • 始终固定明确且稳定的 vLLM 镜像标签，绝不使用 :latest。在设计时确定当前稳定版本（检查 vLLM 发布页面，或使用 gcloud container ai profiles manifests create 输出中的标签），并记录到 migration-state.md；不要复用上次迁移时记住的标签，也不要使用文档示例中的标签。
  • 通过 GKE Gateway API 暴露服务。默认使用区域级内部 Application Load Balancer（gatewayClassName: gke-l7-rilb），并根据 assets/gke-inference-gateway.yaml.tmpl 配置 HTTPRoute，将 /v1 请求发送到端口 8000 上的 vLLM ClusterIP 服务（{workload_name}-vllm-svc）。
  • 如果用户需要 LLM 感知型负载均衡（根据 KV 缓存利用率、队列深度或 LoRA 适配器部署位置进行路由），可提供 GKE Inference Gateway 作为升级方案：它要求 HTTPRoute 后端使用 InferencePool 资源而非 Service，且仅支持 gke-l7-rilb 和 gke-l7-regional-external-managed GatewayClasses。生成 InferencePool 清单前，先获取 关于 GKE Inference Gateway；不要凭记忆臆造清单。
  • 对于多节点模型，使用 LeaderWorkerSet（LWS） 和 vLLM。
• 安全和访问：
  • 访问 Google Cloud API 时始终使用 GKE Workload Identity。
  • 受限模型密钥安全： 对于需要 Hugging Face 令牌（HF_TOKEN）的受限模型（例如 Llama 3、Gemma）：
    • 绝不要将令牌值明文写入 Deployment 或 Pod 规格；应使用 env.valueFrom.secretKeyRef 安全引用密钥（例如，指向 hf-secret）。
    • 始终提醒用户：在明文提示词或清单文件中暴露敏感 API 令牌存在安全风险。
    • 绝不要将 Kubernetes Secret 清单写入磁盘，也不要将其纳入模板。应明确指示用户在应用任何其他清单前，直接通过 CLI 创建 Secret：kubectl create secret generic hf-secret --namespace={namespace} --from-literal=hf_api_token=<YOUR_HF_TOKEN>，由用户自行替换为真实值。
    • 如果用户已在对话中粘贴令牌，应视为该令牌已泄露：在生成的所有命令和清单中使用 <YOUR_HF_TOKEN> 占位符，并建议用户在迁移完成后前往 https://huggingface.co/settings/tokens 撤销并重新签发令牌。
  • 端点暴露： 默认将 Gateway 设为内部类别（gke-l7-rilb）。vLLM 兼容 OpenAI 的端点没有内置身份验证；如果用户需要对外暴露，必须明确警告他们：未经身份验证的外部监听器会形成一个消耗其 GPU 费用的开放式推理 API；在生成对外暴露的 Gateway 清单前，必须先获得用户的明确决定，并配置前置控制措施（IAP、带身份验证的 API 网关或严格的客户端允许名单）。
• 模型存储和冷启动：
  • 将所选模型暂存到 Cloud Storage bucket，以避免重复下载。
  • 通过集群上的 Job 执行暂存： 向用户说明，通过集群 Job 暂存权重可避免将大型权重下载到本地工作站，也可避免每次容器重启时重新下载。始终将暂存清单保存为 model-staging-job.yaml，并指示用户运行 kubectl apply -f model-staging-job.yaml。
  • 根据源和目标确定暂存逻辑：
    • 源为 Hugging Face（目标为 gCS FUSE 或 Lustre）： 使用暂存 Job 将权重直接下载到 PVC。
    • 源为 GCS（目标为 GCS FUSE）： 暂存 Job 为可选。如果 PVC 通过 FUSE 直接挂载 GCS bucket，权重已可访问，无需暂存。
    • 源为 GCS（目标为 Lustre）： 使用暂存 Job 将权重从源 GCS bucket 复制到 Lustre PVC（例如，使用 gcloud storage cp）。
  • 对于大多数工作负载，优先通过 Cloud Storage FUSE 暂存到 Cloud Storage；对延迟要求极低、规模达 PiB 的需求，则使用 Managed Lustre。
  • 每个挂载 Cloud Storage FUSE 卷的 Pod 都必须包含 Pod 注解 gke-gcsfuse/volumes: "true"（这会注入 FUSE sidecar），并且必须以绑定到具有模型 bucket 上 roles/storage.objectUser 权限的 Google 服务账号的 Kubernetes ServiceAccount 运行，绑定方式为 Workload Identity。缺少其中任一项都会导致挂载失败或无法读取；排查其他存储问题前，先检查这两项。
• 可观测性：
  • 默认使用 Google Cloud Managed Service for Prometheus 和 DCGM 指标，以深入监控 GPU。
• 自动扩缩：
  • 不要假定用户需要 Horizontal Pod Autoscaling（HPA）；在发现阶段必须询问用户。
  • 如果用户不需要 HPA，则省略所有自动扩缩清单。
  • 如果用户需要 HPA，则提醒用户注意 LLM 自动扩缩陷阱：标准 CPU、内存和 GPU 内存利用率指标并不可靠，因为 vLLM 会预分配 VRAM 用于 KV 缓存，导致利用率始终看起来很高。
  • 建议根据反映实际并发量或队列深度的自定义服务端指标进行扩缩（例如 vllm:num_requests_waiting 或批次大小）。
  • 除非用户明确提及其他指标，否则采用合理的默认指标：队列大小。
  • 可使用 GKE Custom Metrics（Stackdriver Adapter）或 KEDA 实现。

工作流

解决方案设计和实施工作流包含以下 4 个阶段：

• 阶段 1：需求发现： 通过 gcloud 检查现有基础设施，并收集模型和流量需求。
• 阶段 2：解决方案设计： 计算 VRAM 需求，选择硬件和存储，并生成 Kubernetes 清单。
• 阶段 3：实施： 配置资源，通过临时 Pod 暂存模型权重，并使用 kubectl 应用工作负载清单。
• 阶段 4：验证和切换： 验证 Pod 健康状况和端点推理，然后提供流量迁移指导。

在每次架构响应开始时，打印一行简单的可视化进度指示器，使用户和模型始终了解当前阶段：

**Migration Progress:** [● Discovery] ➔ [○ Solution Design] ➔ [○ Implementation] ➔ [○ Validation]

（更新 ● 以标记当前活动阶段，例如：阶段 2 期间显示 [● 解决方案设计]。）

阶段路由规则

根据用户提示的上下文确定当前阶段：

如果当前目录中存在 migration-state.md，请先读取该文件，然后根据记录的阶段和数值继续；只有当文件中缺少某项数值，或该数值与用户提示矛盾时，才重新询问相关需求发现问题。

• 阶段 1（需求发现）： 用于尚未完成需求发现的新迁移请求。
• 阶段 2（解决方案设计）： 用于提示表明需求发现已完成，或要求进行架构设计／生成 YAML 清单的情况。
• 阶段 3（实施）： 用于提示表明模型权重已暂存，或直接要求部署步骤／命令的情况。进度指示器：**Migration Progress:** [○ Discovery] ➔ [○ Solution Design] ➔ [● Implementation] ➔ [○ Validation]。
• 阶段 4（验证）： 用于提示表明工作负载正在运行，或要求进行健康检查／测试步骤的情况。

阶段 1：需求发现

阶段 1 的目标是发现设计和构建目标 GKE 推理基础设施所需的全部工作负载规格。

阶段 1 响应要求： 阶段 1 期间的每次响应都必须以可视化进度指示器开头：**Migration Progress:** [● Discovery] ➔ [○ Solution Design] ➔ [○ Implementation] ➔ [○ Validation]。

发现清单（需识别的属性）

Agent 必须发现或确认以下 6 类核心属性：

• 源平台与服务配置：

  • 源平台（Cloud Run、Gemini API、Gemini Enterprise Agent Platform、自定义 VM）。
  • 容器镜像标签、环境变量、CPU/RAM 分配和密钥绑定。

• 模型规格：

  • 模型名称和参数规模（例如，Gemma 2 9B、Llama 3 70B）。
  • 目标精度和量化容忍度（FP16/BF16 与 INT8/INT4 AWQ）。发现过程中必须询问量化容忍度。
  • 门控模型状态（是否需要通过 Hugging Face 令牌 HF_TOKEN 访问）。
  • 模型特定的架构要求： 明确检查模型卡（例如 Hugging Face 上的模型卡）或 config.json，确认是否有自定义配置要求。例如，确定该架构是否需要 --trust-remote-code（如 Qwen 模型）、特定的 rope scaling 参数或其他自定义标志。

• 目标 GKE 与硬件基础设施：

  • 目标 GKE 集群名称和区域（或确认是否要创建新集群）。
  • 加速器偏好（L4、A100、H100、TPU v5e）和配置模式（Spot/CCC 与按需）。
  • 所需 GPU/TPU 的区域配额是否充足。

• 模型存储与暂存：

  • 模型权重的当前位置（GCS 存储桶、Hugging Face Hub、外部 URL）。
  • 首选存储集成方式（Cloud Storage FUSE 或 Managed Lustre）。

• 流量配置与负载均衡：

  • 预期流量、并发量和请求模式（突发型还是稳定基线型）。
  • 负载均衡需求（GKE Inference Gateway、标准 Ingress/Service）。
  • 自动扩缩容要求： 询问用户是否需要水平 Pod 自动扩缩容（HPA）。不要假设用户需要。如果需要，确定目标指标（默认使用队列大小），并讨论 LLM 自动扩缩容陷阱。

• 模型等效性（仅适用于 Gemini API / Agent Platform 源）：

  • 正在使用的 Gemini 模型和 API 功能（函数调用、系统指令、上下文长度、多模态输入）。
  • 将用于替代它的开放权重模型，以及用户计划如何在切换前评估其输出质量与当前系统的差异。
  • 对客户端的影响：vLLM 端点兼容 OpenAI，不兼容 Gemini API；找出必须更改的客户端代码和 SDK 调用。

发现执行（自动与交互）

• 先请求基础设施访问权限： 在执行任何发现命令之前，必须明确请求用户授权，以便通过 CLI 命令（例如 gcloud run services list 或 gcloud run services describe）检查现有环境资源。
• 获批后进行检查： 用户授权后，执行 gcloud CLI 命令、检查环境变量并查看本地工作区文件，自动填充清单项目：
  • Cloud Run 工作负载： 运行 gcloud run services list --format="table(metadata.name,status.url,status.latestReadyRevisionName)" 列出服务，然后运行 gcloud run services describe {service_name} --format="yaml(spec.template.spec.containers,spec.template.metadata.annotations,spec.template.spec.serviceAccountName,spec.template.spec.containerConcurrency)"，仅提取容器映像、环境变量、资源限制、并发数和密钥绑定。所有发现命令优先使用 --format 过滤；绝不要将未经筛选的完整资源描述内容带入对话。
  • 现有 GKE 集群： 运行 gcloud container clusters list 和 gcloud container clusters describe {cluster_name}，检查活动集群配置、Workload Identity 设置和可用的加速器节点池。
  • Vertex AI / Storage： 运行 gcloud ai endpoints list 或 gcloud storage buckets list，查找模型制品和存储桶。
  • 工作区与环境： 检查当前工作区目录中的本地配置文件或环境变量。
• 汇总、询问缺失项并确认： 汇总所有已发现的配置数据，并询问用户尚缺的属性。如果有任何清单项目尚未解决或含义不明确，必须先获得用户明确确认，才能进入阶段 2。如果所有清单项目都已解决且不存在歧义，则可以在同一条回复中呈现发现摘要和阶段 2 的解决方案设计，并将两者置于同一个审批环节下；设计审批也将同时涵盖发现摘要。
• 保存发现状态： 用户确认发现摘要后，将其写入当前目录中的 migration-state.md：每个清单类别单独设为一个部分，并记录已确认的值，最后一行写入 Current phase: <phase name>。工作流每次进入下一阶段时，都要更新 Current phase: 行。

阶段 2：解决方案设计

根据发现阶段的结果，设计完成迁移所需的架构和清单文件。

阶段 2 的回复要求： 阶段 2 期间的每条回复都必须以此视觉进度指示器开头：**Migration Progress:** [○ Discovery] ➔ [● Solution Design] ➔ [○ Implementation] ➔ [○ Validation]。

按需加载上下文： 评估以下特定架构选项（例如存储选项、负载均衡或自动扩缩）时，按需获取并阅读 Supporting links 部分中的相关参考文档链接。

1. 梳理组件与备选方案： 对于每个主要组件（例如负载均衡、自动扩缩容、单节点与多节点），提供你推荐的“Golden Path”方案及备选方案。如果用户要求使用 HPA，确保设计能够应对 LLM 自动扩缩容陷阱，并推荐自定义指标（默认使用队列长度）。
2. 加速器选择： 参考 GPU 平台 或 在 GKE 中规划 TPU 配置，为目标模型推荐最合适的加速器。 （注意：assets/ 中的清单模板仅适用于 GPU。如果用户选择 Cloud TPU，请明确说明，并根据 GKE TPU 服务文档而非此技能中的模板来编写服务清单。）
3. 存储选择： 参考 GCP AI 存储选项，为模型暂存和服务推荐最合适的存储方案。
4. 硬件与 VRAM 规格： 根据参数、上下文窗口和量化方式，使用下文的确定性 VRAM 规格计算公式准确计算 VRAM。映射到合适的 GPU（L4、A100、H100）。
5. 集群与节点设置： 根据任务设计合适的集群。使用自定义计算类（CCC）为任务添加合适规格的节点。必要时设计 Workload Identity。vLLM Deployment 必须通过 nodeSelector: cloud.google.com/compute-class: {compute_class_name} 选择节点，确保工作负载实际通过 ComputeClass 调度。如果用户拒绝使用 CCC，只想使用按需节点，则将此选择器替换为 cloud.google.com/gke-accelerator: {accelerator_type}，并完全跳过 ccc-profile.yaml；不要应用任何没有工作负载引用的 ComputeClass。
6. 模型暂存设计： 根据模型权重的源位置和目标存储方案，确定是否需要暂存 Job。如果源为 Hugging Face，或者目标为 Lustre 且源为 GCS，则规划一个用于下载/复制权重的 Job。如果源为 GCS 且目标为 GCS FUSE，则跳过暂存。规划使用 Cloud Storage FUSE 或 Lustre CSI 将此存储挂载到工作负载。
7. 起草解决方案架构和清单： 阅读 assets/ 中的清单模板（assets/vllm-deployment.yaml.tmpl、assets/ccc-profile.yaml.tmpl、assets/gke-inference-gateway.yaml.tmpl、assets/storage-config.yaml.tmpl 和 assets/model-staging-job.yaml.tmpl），替换为在阶段 1 中确定的参数，并将生成的 YAML 清单（vllm-deployment.yaml、ccc-profile.yaml、gke-inference-gateway.yaml、storage-config.yaml、model-staging-job.yaml）保存到当前目录中的磁盘。在创建 vllm-deployment.yaml 时，明确将阶段 1 中发现的任何必需的模型专用架构标志（例如 --trust-remote-code）注入容器的 args 数组。在创建 gke-inference-gateway.yaml 时，以 assets/gke-inference-gateway.yaml.tmpl 为基础：除非用户明确选择外部暴露或基于 InferencePool 的 GKE Inference Gateway，否则 Gateway 资源使用 gatewayClassName: gke-l7-rilb；HTTPRoute 资源将 /v1 流量路由到 vLLM ClusterIP 服务（{workload_name}-vllm-svc 的端口 8000）。如果使用的存储类不是 gcsfuse-csi（例如 lustre-csi），则从 storage-config.yaml 中移除 gcsfuse.cloud.google.com 注解。
8. 征求审核并迭代： 向用户展示生成的解决方案架构和图表，并征求反馈。在进入阶段 3 之前，持续迭代设计，直到用户批准。

确定性显存容量计算公式

要准确计算模型服务／推理所需的显存，请使用以下确定性公式：

硬件与容量建议要求： 计算显存容量或推荐硬件时：

• 使用以下公式明确说明显存计算过程（参数规模、KV 缓存、20% 安全余量）。
• 推荐具体的加速器类型（例如，为采用 FP16/BF16 的 8B 模型推荐配备 24GB 显存的 NVIDIA L4）。
• 建议使用 Custom Compute Classes (CCC)，最大限度提高获得加速器的可能性。
• 在需求调研阶段询问或确认用户对量化精度的接受程度（FP16/BF16 与 INT8/INT4）。

$$VRAM_{\text{total}} = \left( \frac{\text{Parameters} \times 2}{\text{Quantization}} + KV_Cache_Overhead \right) \times 1.2$$

其中：

• Parameters：以十亿为单位的模型参数规模（例如，8B 对应 8，70B 对应 70）。
• Quantization：根据目标精度相对于 16 位（FP16/BF16）的比例确定的除数：
  • 1 表示 16 位（FP16 / BF16，每个参数占 2 字节）
  • 2 表示 8 位（FP8 / INT8，每个参数占 1 字节）
  • 4 表示 4 位（INT4 / AWQ / GPTQ，每个参数占 0.5 字节）
• $KV_Cache_Overhead$：生成过程中为键值缓存预留的内存（GB）： $$KV_Cache_Overhead ,(GB) = \frac{2 \times n_{\text{layers}} \times n_{\text{kv_heads}} \times d_{\text{head}} \times \text{Context Length} \times \text{Batch Size} \times \text{Precision Bytes}}{10^9}$$ （经验法则：如果未知模型的层架构细节，可估算 $KV_Cache_Overhead \approx 0.2 \times \text{Model Weight Memory}$。）
• 1.2 乘数：为 CUDA 上下文、激活内存和服务引擎开销预留 20% 的安全余量。

将计算结果映射到加速器时，应与显卡的完整显存容量（例如，L4 的 24 GB）比较，而不是与扣除 --gpu-memory-utilization 后的显存比较。1.2 乘数和 vLLM 的利用率上限都会为相同开销预留余量；两者同时应用会重复计算余量，导致容量估算高出一个加速器档位。

阶段 3：实施

根据执行策略落实已批准的设计：生成以下命令，并将其交给用户；如果用户要求你运行这些命令，则执行命令并报告输出。

1. 确认部署前提条件： 确保计费、API 和 IAM 权限均已就绪。
2. 基础设施预配： 提供明确的 gcloud 命令，用于预配存储和集群前提条件（例如启用 Cloud Storage FUSE CSI 驱动程序），并配置 Workload Identity IAM 绑定。Gateway API 预检查： 明确要求用户确认集群已启用 Gateway API。建议用户在尝试应用路由清单之前运行 gcloud container clusters update <CLUSTER_NAME> --gateway-api=standard，以避免出现 CRD 未找到错误。
3. 存储预配： 创建所需的存储资源（Cloud Storage 存储桶或 Managed Lustre 文件系统）。
4. 模型暂存： 根据阶段 2 的设计采用条件逻辑。
   • 跳过： 如果模型已在 GCS 中且使用 GCS FUSE，则跳到第 5 步。
   • Hugging Face 来源： 如果使用受限模型（例如 Llama 3、Gemma），明确要求用户在本地运行 kubectl create secret generic hf-secret ... 命令，然后才能应用任何 Job 或部署（参见受限模型 Secret 安全规则）。创建 Secret 后，要求用户运行 kubectl apply -f model-staging-job.yaml。
   • GCS 到 Lustre 来源： 要求用户运行 kubectl apply -f model-staging-job.yaml（该 Job 应配置为使用 gcloud storage cp 或类似命令）。
   • 完成门槛： 对任何正在运行的暂存 Job，使用 kubectl wait --for=condition=complete job/{workload_name}-model-staging --timeout=90m 确认其完成（根据模型大小调整超时时间）。如果 Job 失败，请先使用 kubectl logs job/{workload_name}-model-staging 检查，再重试。说明通过集群 Job 进行暂存可以避免将大型权重下载到用户的工作站，也可以避免每次容器重启时都重新下载。
5. 工作负载部署： 提供明确的 kubectl apply 命令，以部署存储配置（kubectl apply -f storage-config.yaml）、ComputeClass（kubectl apply -f ccc-profile.yaml）、vLLM 部署（kubectl apply -f vllm-deployment.yaml）和 Inference Gateway（kubectl apply -f gke-inference-gateway.yaml）。确保 vLLM 部署规范将暂存的模型权重从 PVC 挂载到 /models。如果为受限模型创建了 Secret，确保在 Deployment 清单中正确引用该 Secret。将 vLLM 的 --model 标志设为暂存模型的本地路径（/models/{model_name}），绝不能设为 Hugging Face 仓库 ID；使用仓库 ID 会导致 vLLM 在每个 Pod 启动时重新下载完整权重，从而在不报错的情况下使暂存步骤形同虚设。使用 --served-model-name={model_id} 为 API 客户端保留模型的公开名称。
6. 验证部署状态： 使用 kubectl rollout status deployment/{workload_name}-vllm --timeout=30m 和 kubectl get pods -l app={workload_name}-vllm -o wide 确认部署成功。如果部署失败或超时，请根据观察到的错误直接查看故障排除指南；如果命令输出已能说明部署是否成功，就不要再询问用户。只询问集群无法验证的结果（例如响应质量是否与源系统一致）。

第 4 阶段：验证与流量切换

验证已部署的基础设施是否满足工作负载要求，并提供流量迁移说明。

第 4 阶段响应要求： 第 4 阶段的每条响应都必须以此进度指示器开头：**Migration Progress:** [○ Discovery] ➔ [○ Solution Design] ➔ [○ Implementation] ➔ [● Validation]。

1. 运行状况检查： 建议使用明确的运行状况检查命令，验证 Pod、节点和网关状态（kubectl get pods、kubectl get nodes 和 kubectl get gateway）。
2. 推理测试： 验证服务正在提供模型。提供 kubectl port-forward 命令（kubectl port-forward svc/{workload_name}-vllm-svc 8000:8000）以及对 /v1/chat/completions 发起测试端点推理的示例 curl 请求。适用时，将响应与之前的基础设施进行比较。
3. 流量切换指导： 不要尝试自动实施流量迁移。请改为：
   • 提供已准备好接收流量的内部 GKE 端点。
   • 根据相关代码库（如有）提供流量迁移建议。
   • 建议采用标准的 GKE 发布方式（例如，更新现有部署清单以指向新服务），不要使用复杂的金丝雀测试或蓝绿部署。
   • 仅在用户明确提出要求时，才提供更高级的流量迁移选项。
4. 回滚准备： 在流量切换之前，确认源服务仍保持部署状态（可以缩容，但不能删除），直至 GKE 端点已按用户选择的时长承载生产流量。提供一条命令或一项配置更改，以恢复到源服务。只有在用户宣布迁移稳定后，才提供停用源服务的命令。
5. 编写验证报告并请求最终批准： 编写验证报告，总结所有运行状况检查结果和推理测试结果。必须明确请求用户最终批准，以完成迁移工作流。

故障排除指南

当用户报告 Pod 已创建但推理端点没有响应的问题（或请求故障排除帮助）时：

1. 建议使用具体的诊断命令：kubectl logs {pod_name}（检查容器启动日志）和 kubectl describe pod {pod_name}（检查 Pod 初始化状态）。
2. 建议确认目标区域的 Google Cloud 加速器配额（GPU/TPU），确保能够配置所需资源。
3. 检查 JIT 编译／启动延迟： 如果 curl 返回 Connection refused，但 Pod 状态为 Running，服务引擎（例如 vLLM）可能仍在执行 JIT 编译（如 Triton PTX 或 Torch Inductor）或捕获 CUDA 图。这些操作在模型权重加载后仍可能需要数分钟。建议用户检查 kubectl logs {pod_name}，并明确等待日志中出现 Uvicorn running on http://0.0.0.0:8000（或等效信息）后，再判断是否存在网络问题。
4. 建议检查 GKE Workload Identity 绑定、PVC 挂载状态（Cloud Storage FUSE）以及 GKE Inference Gateway 监听器配置。

参考链接

请根据需要使用以下参考资料，为设计决策提供依据、回答用户问题并生成实现清单：

• GPU 平台
• 在 GKE 中规划 TPU 配置
• Gemini Cloud Assist MCP 文档
• 关于 GKE 上的 AI/ML 模型推理
• 为 GKE 上的 AI/ML 模型推理选择负载均衡策略
• 使用 Google Kubernetes Engine 上的 GPU 自动扩缩大语言模型推理工作负载的最佳实践
• Google Cloud AI 存储选项
• 使用 Cloud Storage FUSE 优化 AI/ML 工作负载
• 使用 Managed Lustre 优化 AI/ML 工作负载