为 Gemini Enterprise Agent Platform 资源设置 Private Service Connect 接口

本指南介绍了如何为 Gemini Enterprise Agent Platform 资源设置 Private Service Connect 接口 。

您可以为 Gemini Enterprise Agent Platform 中的部分资源配置 Private Service Connect 接口连接，这些资源包括：

与 VPC 对等互连 连接不同，Private Service Connect 接口连接可以是 传递性的。这样一来，使用方 VPC 网络 中需要的 IP 地址更少。这样一来，您就可以更灵活地连接到 Google Cloud 项目和本地环境中的其他 VPC 网络。

本指南适用于已熟悉 Google Cloud 网络 概念的网络管理员。

目标

本指南包含以下任务：

  • 配置使用方 VPC 网络、子网和网络连接。
  • 向 Google Cloud 网络宿主项目添加防火墙规则。
  • 创建 Agent Platform 资源，指定要使用 Private Service Connect 接口的网络连接。

准备工作

按照以下说明创建或选择一个 Google Cloud 项目 ，并将其配置为与 Gemini Enterprise Agent Platform 和 Private Service Connect 搭配使用。

  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud的新用户， 请创建一个账号，以评估我们的产品在 实际场景中的表现。新客户还可获享 $300 赠金，用于 运行、测试和部署工作负载。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Gemini Enterprise Agent Platform, Compute Engine, and Cloud Storage APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  5. 安装 Google Cloud CLI。

  6. 如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

  7. 如需初始化 gcloud CLI，请运行以下命令： 

    gcloud init

  8. 初始化 gcloud CLI 后，对其进行更新并安装所需组件： 

    gcloud components update
gcloud components install beta

  9. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  10. Verify that billing is enabled for your Google Cloud project.

  11. Enable the Gemini Enterprise Agent Platform, Compute Engine, and Cloud Storage APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  12. 安装 Google Cloud CLI。

  13. 如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

  14. 如需初始化 gcloud CLI，请运行以下命令： 

    gcloud init

  15. 初始化 gcloud CLI 后，对其进行更新并安装所需组件： 

    gcloud components update
gcloud components install beta
  16. 如果您不是项目所有者，并且没有 Project IAM Admin (roles/resourcemanager.projectIamAdmin) 角色，请让项目所有者为您授予包含 compute.networkAttachments.update、 compute.networkAttachments.update 和 compute.regionOperations.get 权限的 IAM 角色（例如 Compute Network Admin (roles/compute.networkAdmin) 角色），以便您 管理网络资源。
  17. 向 AI Platform Service Agent 分配所需角色。 如需详细了解在不同场景中要授予哪些角色，请参阅本文档的 Gemini Enterprise Agent Platform 服务代理所需角色 部分。

设置 VPC 网络和子网

如果您没有现有网络，请按照相应配置步骤创建新的 VPC 网络。

  1. 创建 VPC 网络：

    gcloud compute networks create NETWORK \
    --subnet-mode=custom

    将 NETWORK 替换为 VPC 网络的名称。

  2. 创建子网：

    gcloud compute networks subnets create SUBNET_NAME \
    --network=NETWORK \
    --range=PRIMARY_RANGE \
    --region=REGION

    替换以下内容：

    • SUBNET_NAME：子网的名称。

    • PRIMARY_RANGE：新 子网的主要 IPv4 范围（采用 CIDR 表示法）。

      以下是 Agent Platform 的 IP 要求和限制：

      • Agent Platform 建议使用 /28 子网。
      • 网络连接的子网支持 RFC 1918 和非 RFC 1918 地址，但 100.64.0.0/20 和 240.0.0.0/4 这两个子网除外。
      • Agent Platform 只能连接到可从指定网络路由的 RFC 1918 IP 地址范围。

      • Agent Platform 无法访问私下使用的公共 IP 地址或以下非 RFC 1918 范围：

        • 100.64.0.0/20
        • 192.0.0.0/24
        • 192.0.2.0/24
        • 198.18.0.0/15
        • 198.51.100.0/24
        • 203.0.113.0/24
        • 240.0.0.0/4

      如需了解详情，请参阅 IPv4 子网范围。

    • REGION：您要在该 Google Cloud 区域创建新 子网。

创建网络连接

在共享 VPC 部署中，在宿主项目中创建用于网络连接的子网，然后在服务项目中创建 Private Service Connect 网络连接。

以下示例展示了如何创建可自动接受连接的网络连接。

   gcloud compute network-attachments create NETWORK_ATTACHMENT_NAME \
       --region=REGION \
       --connection-preference=ACCEPT_AUTOMATIC \
       --subnets=SUBNET_NAME

将 NETWORK_ATTACHMENT_NAME 替换为网络 连接的名称。

如果网络连接是在与服务项目不同的项目中创建的，则在调用 Gemini Enterprise 时，您需要传递完整的网络连接路径。

Gemini Enterprise Agent Platform 服务代理所需角色

在您创建网络连接的项目中，向同一项目的 Gemini Enterprise Agent Platform 服务代理 授予 compute.networkAdmin 角色。如果此项目与您使用 Agent Platform 的服务项目不同，请提前在此项目中启用 Agent Platform API。

如果您指定 共享 VPC 网络供 Agent Platform 使用 并在服务项目中创建网络连接，请向您使用 Agent Platform 的服务项目中的 Agent Platform 服务代理授予 VPC 宿主项目的 compute.networkUser 角色。

配置防火墙规则

系统会在使用方 VPC 中应用入站防火墙规则，以便从计算端点和本地端点与 Private Service Connect 接口网络连接子网进行通信。

配置防火墙规则是可选操作。不过，我们建议您设置常用的防火墙规则，如以下示例所示。

  1. 创建一条允许通过 TCP 端口 22 进行 SSH 访问的防火墙规则：

    gcloud compute firewall-rules create NETWORK-firewall1 \
    --network NETWORK \
    --allow tcp:22

  2. 创建一条允许 TCP 端口 443 上的 HTTPS 流量的防火墙规则：

    gcloud compute firewall-rules create NETWORK-firewall2 \
    --network NETWORK \
    --allow tcp:443

  3. 创建一条允许 ICMP 流量（例如 ping 请求）的防火墙规则：

    gcloud compute firewall-rules create NETWORK-firewall3 \
    --network NETWORK \
    --allow icmp

设置专用 DNS 对等互连

为了使配置了 PSC-I 的 Vertex AI Training 作业或 Agent Runtime 代理能够解析客户管理的 Cloud DNS 区域中的专用 DNS 记录，Agent Platform API 提供了一种用户可配置的机制，用于指定要与 Google 内部资源进行对等互连的 DNS 网域。进行以下额外配置：

  1. 将 DNS Peer(roles/dns.peer) 角色分配给您在其中使用 Vertex AI Training 或 Agent Runtime 服务的项目的 AI Platform Service Agent 账号。如果您指定Gemini Enterprise Agent Platform 要使用的共享 VPC 网络，并在服务项目中创建网络连接，请向您使用 Agent Platform 的服务项目中的 AI Platform Service Agent 授予 VPC 宿主项目中的 DNS Peer(roles/dns.peer) 角色。

  2. 创建一条允许所有 ICMP、TCP 和 UDP 流量的防火墙规则（可选）：

    gcloud compute firewall-rules create NETWORK-firewall4 \
    --network NETWORK
    --allow tcp:0-65535,udp:0-65535,icmp
    --source-ranges IP_RANGES

  3. 设置专用 DNS 区域，以解析 DNS 并路由流量。如需将 DNS 记录添加到专用 DNS 区域，请参阅添加资源记录集。

问题排查

本部分介绍了为 Gemini Enterprise Agent Platform 配置 Private Service Connect 时的一些常见问题。

为 Agent Platform 配置共享 VPC 时，请在您使用 Agent Platform 的服务项目中创建网络连接。 这种方法有助于防止出现某些错误消息，例如：

_Please make sure that the Agent Platform API is enabled for the
project_, by ensuring the
necessary permissions and APIs are enabled in the correct project.

后续步骤