GCP Vertex AI

---

概述

GCP Vertex AI： 一项完全托管的服务，通过 Google Cloud 提供主流生成式 AI 模型（如 Anthropic Claude 3.5 Sonnet v2）。了解更多 GCP Vertex AI。

本指南面向已建立 GCP 环境的企业（利用 IAM 角色、服务账号及资源管理最佳实践），确保安全合规使用。

---

步骤 1：准备 GCP 环境

1.1 创建或使用 GCP 项目

• 登录 GCP 控制台： Google Cloud Console
• 选择或新建项目： 可使用现有项目，或为 Vertex AI 新建专用项目。

1.2 配置 IAM 权限与服务账号

• 分配所需角色：

  • 为你的用户（或服务账号）分配 Vertex AI User 角色（roles/aiplatform.user）。
  • 服务账号还需附加 Vertex AI Service Agent 角色（roles/aiplatform.serviceAgent），以支持部分操作。
  • 可根据需要附加其他预定义角色：
    • Vertex AI Platform Express Admin
    • Vertex AI Platform Express User
    • Vertex AI Migration Service User

• 跨项目资源访问：

  • 若需访问其他项目的 BigQuery 表，分配 BigQuery Data Viewer 角色。
  • 若需访问其他项目的 Cloud Storage 存储桶，分配 Storage Object Viewer 角色。
  • 访问外部数据源请参考 GCP Vertex AI 访问控制文档。

---

步骤 2：验证区域与模型访问

2.1 选择并确认区域

Vertex AI 支持八大区域。请选择符合延迟、合规和容量需求的区域，例如：

• us-east5（俄亥俄州哥伦布）
• us-east1（南卡罗来纳州）
• us-east4（弗吉尼亚北部）
• us-central1（爱荷华州）
• us-west1（俄勒冈州达尔斯）
• us-west4（内华达州拉斯维加斯）
• europe-west1（比利时）
• asia-southeast1（新加坡）

2.2 启用 Claude 3.5 Sonnet v2 模型

• 打开 Vertex AI Model Garden： 在 Cloud Console 导航至 Vertex AI → Model Garden。
• 启用 Claude 3.5 Sonnet v2： 找到该模型卡片，点击 Enable 启用。

---

步骤 3：配置 Cline VS Code 扩展

3.1 安装并打开 Cline

• 下载 VS Code： 官方下载
• 安装 Cline 扩展：
  • 打开 VS Code
  • 进入扩展市场（Ctrl+Shift+X 或 Cmd+Shift+X）
  • 搜索 Cline 并安装

3.2 配置 Cline 设置

• 打开 Cline 设置： 在 Cline 扩展内点击设置 ⚙️ 图标
• 设置 API Provider： 在下拉菜单中选择 GCP Vertex AI
• 输入 Google Cloud 项目 ID： 填写前面准备好的项目 ID
• 选择区域： 选择支持的区域（如 us-east5）
• 选择模型： 从可用列表中选择 Claude 3.5 Sonnet v2
• 保存并测试： 保存设置后，发送简单提示测试（如“生成一个判断数字是否为质数的 Python 函数”）

---

步骤 4：认证与凭证设置

方案 A：使用 Google 账号（用户凭证）

1. 安装 Google Cloud CLI： 参考 安装指南
2. 初始化并认证：

   gcloud init
   gcloud auth application-default login

   • 这会用你的 Google 账号设置 Application Default Credentials (ADC)
3. 重启 VS Code： 确保 VS Code 重启后，Cline 扩展能读取新凭证

方案 B：使用服务账号（JSON 密钥）

1. 创建服务账号：
   • 在 GCP 控制台导航至 IAM 与管理 > 服务账号
   • 新建服务账号（如“vertex-ai-client”）
2. 分配角色：
   • 附加 Vertex AI User（roles/aiplatform.user）
   • 附加 Vertex AI Service Agent（roles/aiplatform.serviceAgent）
   • 可按需添加其他角色
3. 生成 JSON 密钥：
   • 在服务账号管理页面生成并下载 JSON 密钥
4. 设置环境变量：

   export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

   • 这样 Google Cloud 客户端库（及 Cline）会使用该密钥
5. 重启 VS Code： 从设置了 GOOGLE_APPLICATION_CREDENTIALS 的终端启动 VS Code

---

步骤 5：安全、监控与最佳实践

5.1 最小权限原则

• 最小权限原则： 只授予必要权限。自定义角色可比预定义角色更细粒度控制。
• 最佳实践： 参考 GCP IAM 最佳实践

5.2 管理资源访问

• 项目级与资源级访问： 可在两个层级管理访问。注意资源级权限会叠加而非覆盖项目级策略。

5.3 监控用量与配额

• 模型可观测性仪表盘：
  • 在 Vertex AI 控制台进入 Model Observability 仪表盘
  • 监控请求吞吐量、延迟、错误率（包括 429 配额错误）等指标
• 配额管理：
  • 如遇 429 错误，请检查 IAM 与管理 > 配额 页面
  • 必要时申请配额提升。了解 GCP Vertex AI 配额

5.4 服务代理与跨项目访问

• 服务代理： 注意不同类型的服务代理账号：
  • Vertex AI Service Agent
  • Vertex AI RAG Data Service Agent
  • Vertex AI Custom Code Service Agent
  • Vertex AI Extension Service Agent
• 跨项目访问： 访问其他项目资源（如 BigQuery、Cloud Storage）时，需分配相应角色（BigQuery Data Viewer、Storage Object Viewer）

---

总结

按照上述步骤，你的企业团队可安全地将 GCP Vertex AI 集成到 Cline VS Code 扩展中，充分利用 Claude 3.5 Sonnet v2 的强大能力：

• 准备 GCP 环境： 创建/使用项目，按最小权限配置 IAM，确保附加所需角色（包括 Vertex AI Service Agent）
• 验证区域与模型访问： 确认所选区域支持 Claude 3.5 Sonnet v2 并已启用
• 在 VS Code 配置 Cline： 安装 Cline，填写项目 ID，选择区域和模型
• 设置认证方式： 可用用户凭证（gcloud auth application-default login）或服务账号 JSON 密钥
• 实施安全与监控： 遵循 IAM 最佳实践，细致管理资源访问，并用模型可观测性仪表盘监控用量

如需更多细节，请查阅 GCP Vertex AI 官方文档 及企业内部安全政策。祝你编码愉快！

本指南会随着 GCP Vertex AI 和 Cline 的发展持续更新。请始终参考最新官方文档和最佳实践。