GDC 连接的 Gemini on GDC API 公开预览版（当前版本）

如需了解版本信息，请参阅 GDC 连接的 Gemini on GDC API 版本说明。

可用版本：公开预览版

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

创建和管理端点

本页面介绍了如何创建和管理 Gemini on Google Distributed Cloud connected API 端点。

前提条件

本部分介绍了在部署 Gemini on GDC connected API 端点之前必须完成的一次性步骤。请在启动机器上完成这些步骤。

您必须使用具有 Edge Container Zone Viewer 角色的 IT 管理员账号完成本部分中的步骤。完成本部分中的步骤后，请将收集的信息（包括 CA 证书和 DNS 服务器 IP 地址）提供给 Google Cloud 项目管理员，以便其按照部署 Gemini on GDC connected API 端点中的说明部署端点。

完成硬件启动

在完成本页面上的步骤之前，您必须：

按照安装要求中的说明成功部署 Google 认证的硬件。
与您的 Google 代表合作，创建所需的 Distributed Cloud connected 集群。

授予所需角色

您必须配置以下必需角色：

对于用于管理 Gemini on GDC connected API 部署的账号，请授予 Distributed Cloud Edge Container API 角色和权限中列出的角色。
对于用于与 Gemini on GDC connected API 端点互动的账号，请授予 Vertex AI API 角色和权限中列出的角色。

获取有关目标 Distributed Cloud connected 可用区的信息

如需获取目标 Distributed Cloud connected 可用区的名称，请执行以下操作：

获取目标 Google Cloud 组织 ID 的名称：
```
gcloud organizations list
```
列出组织中的 Distributed Cloud connected 可用区： Google Cloud
```
gcloud alpha zone-management zones list \
   --organization ORGANIZATION_ID \
   --location REGION
```
替换以下内容：
- ORGANIZATION_ID：目标 Google Cloud 组织的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。在公开预览版期间，唯一受支持的区域是 us-west2。
获取有关目标可用区的详细信息：
```
gcloud alpha zone-management zones describe ZONE \
   --organization ORGANIZATION_ID \
   --location REGION
```
替换以下内容：
- ZONE：目标 Distributed Cloud connected 可用区。
- ORGANIZATION_ID：目标 Google Cloud 组织的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。在公开预览版期间，唯一受支持的区域是 us-west2。

获取有关 Distributed Cloud connected 可用区中经过认证的机器的信息

如需获取 Distributed Cloud connected 可用区中经过认证的目标机器的名称，请执行以下操作：

按照列出可用区中的机器中的说明，列出目标 Distributed Cloud connected 可用区中的 Distributed Cloud connected 机器。
按照获取有关机器的信息中的说明，获取有关目标机器的详细信息。

启用本地 AI Platform API 和 Vertex AI API 服务

请使用具有 Edge Container Zonal Project Admin 角色的 IT 管理员账号完成本部分中的步骤。

在目标 Google Cloud 项目中启用目标 Distributed Cloud connected 可用区：
```
gcloud alpha zone-management projects enable PROJECT_ID \
   --organization ORGANIZATION_ID \
   --location REGION \
   --zone ZONE
```
替换以下内容：
- PROJECT_ID：目标 Google Cloud 项目的 ID。
- ORGANIZATION_ID：目标 Google Cloud 组织的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
- ZONE：目标 Distributed Cloud connected 可用区。
在目标 Google Cloud 项目上启用 AI Platform 服务：
```
gcloud services enable aiplatform.googleapis.com --project PROJECT_ID
```
将 PROJECT_ID 替换为目标 Google Cloud 项目的 ID。
在 Distributed Cloud connected 可用区中启用 Vertex AI API 服务：
```
gcloud alpha zone-management services enable vertex --project PROJECT_ID \
   --location REGION \
   --zone ZONE
```
替换以下内容：
- PROJECT_ID：目标 Google Cloud 项目的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
- ZONE：目标 Distributed Cloud connected 可用区。

为 DNS 解析配置端点

获取目标 Distributed Cloud connected 可用区的受管 DNS 地址、顶级网域 (TLD) 和证书授权机构 (CA) 证书。

gcloud alpha zone-management zones describe ZONE \
  --organization ORGANIZATION_ID \
  --location REGION \
  --format="value(certificateAuthorities)" \
  > CA_CERTIFICATE_FILE

替换以下内容：

ORGANIZATION_ID：目标 Google Cloud 组织的 ID。
REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
ZONE：目标 Distributed Cloud connected 可用区。
CA_CERTIFICATE_FILE：用于保存命令输出的证书载荷的文件。您稍后将使用此文件生成服务帐号密钥。

该命令返回的输出类似于以下内容，并存储在文件中：

使用在上一步中获得的 DNS 服务器 IP 地址和顶级网域 (TLD) 名称，为端点创建 DNS 配置，如下所示。您必须从与 Gemini on GDC connected API 认证机器位于同一本地网络中的机器运行此命令。
```
mkdir /etc/systemd/resolved.conf.d
echo '[Resolve]
DNS=DNS_SERVER_ADDRESS
Domains=~TOP_LEVEL_DOMAIN' > /etc/systemd/resolved.conf.d/dns.conf
sudo systemctl restart systemd-resolved
```
替换以下内容：
- DNS_SERVER_ADDRESS：DNS 服务器的 IP 地址。
- TOP_LEVEL_DOMAIN：端点的顶级网域。

部署 Gemini on GDC connected API 端点

如需部署 Gemini on GDC connected API 端点，请使用 Google Cloud 项目管理员账号执行以下操作：

创建端点：
```
gcloud beta ai endpoints create \
   --project=PROJECT_ID \
   --region=REGION \
   --gdc-zone=ZONE \
   --display-name=ENDPOINT_NAME \
   --endpoint-id=ENDPOINT_ID
```
替换以下内容：
- PROJECT_ID：目标 Google Cloud 项目的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
- ZONE：目标 Distributed Cloud connected 可用区。
- ENDPOINT_NAME：此端点的有意义的名称。
- ENDPOINT_ID：（可选）此端点的唯一标识符。如果省略，系统会生成随机标识符。
部署模型：
```
gcloud beta ai endpoints deploy-model ENDPOINT_ID \
  --display-name=ENDPOINT_NAME \
  --model=MODEL_PUBLIC_ID \
  --region=REGION
```
替换以下内容：
- ENDPOINT_ID：目标端点的 ID。
- ENDPOINT_NAME：目标端点的名称。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
- MODEL_PUBLIC_ID：模型的公开 ID。如需查看受支持的模型列表，请参阅支持的模型。
列出已部署的端点：
```
gcloud beta ai endpoints list \
  --project=PROJECT_ID \
  --region=REGION
```
替换以下内容：
- PROJECT_ID：目标 Google Cloud 项目的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
记下目标端点的 ID。
获取端点地址：
```
gcloud beta ai endpoints describe ENDPOINT_ID \
  --project=PROJECT_ID \
  --region=REGION
```
替换以下内容：
- ENDPOINT_ID：目标端点的 ID。
- PROJECT_ID：目标 Google Cloud 项目的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
在目标 Distributed Cloud connected 可用区中为端点创建服务帐号：
```
gcloud alpha zone-management service-accounts create SERVICE_ACCOUNT \
  --project PROJECT_ID \
  --location REGION \
  --zone ZONE
```
替换以下内容：
- SERVICE_ACCOUNT：用于唯一标识此服务帐号的有意义的名称。此名称只能包含小写字母、数字、“-”或“.”，并且必须以字母数字字符开头和结尾。不允许使用大写字母。
- PROJECT_ID：目标 Google Cloud 项目的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
- ZONE：目标 Distributed Cloud connected 可用区。
获取目标 Distributed Cloud connected 可用区的 Identity and Access Management 政策：
```
gcloud alpha zone-management zones get-iam-policy ZONE \
  --project PROJECT_ID \
  --location REGION
```
替换以下内容：
- ZONE：目标 Distributed Cloud connected 可用区。
- PROJECT_ID：目标 Google Cloud 项目的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
将 AI Platform Developer 角色分配给服务帐号：
```
gcloud alpha zone-management zones set-iam-policy POLICY_FILE \
  --project PROJECT_ID \
  --location REGION \
  --zone ZONE
```
替换以下内容：
- POLICY_FILE：包含角色分配政策的 JSON 或 YAML 文件。
- PROJECT_ID：目标 Google Cloud 项目的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
- ZONE：目标 Distributed Cloud connected 可用区。
以下是 JSON 格式的政策示例：
```
"bindings": [
   {
      "role": "roles/aiplatform.geminiDeveloper",
      "members": [
      "serviceAccount": "projects/PROJECT_ID/locations/REGION/serviceAccounts/SERVICE_ACCOUNT"
      ]
   }
]
"etag": ""
```
以下是 YAML 格式的政策示例：
```
bindings:
- role: roles/aiplatform.geminiDeveloper
members:
- serviceAccount: projects/PROJECT_ID/locations/REGION/serviceAccounts/SERVICE_ACCOUNT
etag: ""
```
替换以下内容：
- PROJECT_ID：目标 Google Cloud 项目的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
- SERVICE_ACCOUNT：用于唯一标识此服务帐号的有意义的名称。
为服务帐号生成密钥：
```
gcloud alpha zone-management service-accounts keys create SA_KEY_FILE \
  --service-account SERVICE_ACCOUNT \
  --project PROJECT_ID \
  --location REGION \
  --ca-cert-path CA_CERTIFICATE_FILE
```
替换以下内容：
- SA_KEY_FILE：用于存储生成的服务帐号密钥的文件。
- PROJECT_ID：目标 Google Cloud 项目的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
- CA_CERTIFICATE_FILE：您之前创建的 CA 证书文件。

获取端点的完全限定网址：

gcloud beta ai endpoints describe ENDPOINT_ID \
  --project=PROJECT_ID \
  --region=REGION

输出服务帐号的身份令牌。您必须从与 Gemini on GDC connected API 认证机器位于同一本地网络中的机器运行此命令。
```
gcloud alpha zone-management auth print-identity-token \
  --cred-file=SA_KEY_FILE \
  --audience=ENDPOINT_URL
```
替换以下内容：
- SA_KEY_FILE：您之前创建的服务帐号密钥文件。
- ENDPOINT_URL：端点的完全限定网址，包括 TLD 后缀。

列出已部署的 Gemini on GDC connected API 端点

如需列出已部署的 Gemini on GDC connected API 端点，请执行以下操作：

gcloud beta ai endpoints list \
    --project=PROJECT_ID \
    --region=REGION \
    --gdc-zone=ZONE

替换以下内容：

PROJECT_ID：目标 Google Cloud 项目的 ID。
REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
ZONE：目标 Distributed Cloud connected 可用区。

获取有关 Gemini on GDC connected API 端点的信息

如需获取有关已部署的 Gemini on GDC connected API 端点的信息，请执行以下操作：

gcloud beta ai endpoints describe ENDPOINT_ID \
    --project=PROJECT_ID \
    --region=REGION

替换以下内容：

ENDPOINT_ID：目标端点的 ID。
PROJECT_ID：目标 Google Cloud 项目的 ID。
REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。

与 Gemini on Google Distributed Cloud connected API 端点互动

您的 Gemini on GDC connected API 端点支持通过 ChatCompletions API 和 ListAvailableModels API 进行互动。您可以使用这些 API 以编程方式与端点互动。

以下是通过 ChatCompletions API 发出的请求的示例。在此请求中生成的不记名令牌的有效期为 12 小时。

在 Shell 环境中设置以下变量：
```
MODEL_NAME="MODEL_NAME"
USER_CONTENT="Who invented the light bulb?"
PROJECT="PROJECT_ID"
LOCATION="REGION"
IG_FQDN="inference-gateway.vai.ZONE.google.private.goog"
CRED_FILE="SA_KEY_FILE"
API_ENDPOINT="https://${IG_FQDN}/v1/projects/${PROJECT}/locations/${LOCATION}/chat/completions"
```
替换以下内容：
- MODEL_PROMPT_ID：目标模型的提示 ID，即用于与端点互动的 ID。在此版本中，唯一受支持的值是 gemini-2.5-flash-ggc。这与模型的公开 ID 不同。
- PROJECT_ID：目标 Google Cloud 项目的 ID。
- REGION：在其中创建目标 Distributed Cloud connected 可用区的 Google Cloud 区域。
- SA_KEY_FILE：您之前创建的服务帐号密钥文件。

输出不记名令牌。您必须从与 Gemini on GDC connected API 认证机器位于同一本地网络中的机器运行此命令。

BEARER_TOKEN=$(gcloud alpha zone-management auth print-identity-token --cred-file="${CRED_FILE}" --audience="https://${IG_FQDN}")
echo $BEARER_TOKEN

构建载荷：

REQUEST_BODY=$(cat <<EOF
{
"model": "${MODEL_NAME}",
"messages": [
   {
      "role": "system",
      "content": "Pizza for everyone!"
   },
   {
      "role": "user",
      "content": "${USER_CONTENT}"
   }
],
"stream": false
}
EOF
)