为 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. 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

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

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

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  4. 安装 Google Cloud CLI。

  5. 配置 gcloud CLI 以使用您的联合身份。

    如需了解详情，请参阅使用联合身份登录 gcloud CLI。

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

    gcloud init

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

    gcloud components update
gcloud components install beta
  8. 如果您不是项目所有者，并且没有 Project IAM Admin (roles/resourcemanager.projectIamAdmin) 角色，请让项目所有者为您授予包含 compute.networkAttachments.update、 compute.networkAttachments.update 和 compute.regionOperations.get 权限的 IAM 角色（例如 Compute Network Admin (roles/compute.networkAdmin) 角色），以便您 管理网络资源。
  9. 向 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 服务代理 (AI Platform Service Agent) 需要特定的 IAM 角色来管理网络资源并促进 Private Service Connect (Private Service Connect) 接口连接。

根据您的网络配置，向服务代理 (service-PROJECT_NUMBER@gcp-sa-aiplatform.) 授予以下角色：

  1. Compute Network Admin (roles/compute.networkAdmin)

    在您创建网络连接的项目中，您必须向服务代理授予 roles/compute.networkAdmin 角色。

  2. Compute Network User (roles/compute.networkUser)

    如果您使用的是共享 VPC，并且在服务项目中创建了网络连接，请向服务代理（位于服务项目中）授予 VPC 宿主项目中的 roles/compute.networkUser 角色。

  3. DNS Peer (roles/dns.peer)

    如需让 Agent Platform Managed Training 或 Agent Runtime 等资源解析专用 DNS 记录，请向服务代理授予 roles/dns.peer 角色。在您使用服务的项目中授予此角色。如果使用共享 VPC，您还必须在 VPC 宿主项目中向服务代理授予 roles/dns.peer 角色。

配置防火墙规则

系统会在使用方 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 对等互连

如需让配置了 Private Service Connect 接口的 Agent Platform Managed Training 作业或 Agent Runtime 代理解析客户管理的 Cloud DNS 区域中的专用 DNS 记录，您可以在配置或部署资源时指定网络连接并创建专用 DNS 对等互连。

您可以通过在 psc_interface_config 下的 dns_peering_configs 字段中指定目标网络和网域后缀来配置 DNS 对等互连：

  • dns_peering_configs：DNS 对等互连配置的列表：
    • domain：专用 Cloud DNS 区域的 DNS 名称。
    • target_project：托管 VPC 网络的项目。它可以不同于您在其中创建网络连接的项目。
    • target_network：在目标项目中建立 DNS 对等互连的 VPC 网络名称。

例如，在 Python 中创建资源时，您可以按如下方式配置专用 DNS 对等互连：

psc_interface_config = {
    "network_attachment": "NETWORK_ATTACHMENT",
    "dns_peering_configs": [
        {
            "domain": "DOMAIN_SUFFIX",
            "target_project": "TARGET_PROJECT",
            "target_network": "TARGET_NETWORK",
        },
    ],
}

替换以下内容：

  • NETWORK_ATTACHMENT：网络连接的名称或完整路径。例如，projects/SERVICE_PROJECT/regions/REGION/networkAttachments/NETWORK_ATTACHMENT_NAME。如果您在与您使用 Agent Platform 的服务项目不同的项目中创建网络连接，则必须传递网络连接的完整路径。
  • DOMAIN_SUFFIX：专用 Cloud DNS 区域的 DNS 名称（例如 example.com.）。
  • TARGET_PROJECT：托管 VPC 网络的项目。它可以不同于您在其中创建网络连接的项目。
  • TARGET_NETWORK：在目标项目中建立 DNS 对等互连的 VPC 网络名称。

问题排查

本部分介绍了为 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.

后续步骤