エンドポイントの作成と管理

プレビュー版

この機能は、サービス固有の規約の「一般サービス規約」セクションの「pre-GA サービス規約」の対象となります。 pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

このページでは、Gemini on Google Distributed Cloud 接続 API エンドポイントを作成して管理する方法について説明します。

このガイドは、インストール要件に記載されているように、Google 認定ハードウェアが正常にデプロイされていることを前提としています。

前提条件

このセクションでは、GDC 接続 API エンドポイントに Gemini をデプロイする前に完了する必要がある 1 回限りの手順について説明します。

必要な API を有効にする

ターゲットの Google Cloud プロジェクトで次の API を有効にする必要があります。

• aiplatform.googleapis.com
• anthos.googleapis.com
• anthosaudit.googleapis.com
• anthosgke.googleapis.com
• cloudresourcemanager.googleapis.com
• connectgateway.googleapis.com
• compute.googleapis.com
• container.googleapis.com
• edgecontainer.googleapis.com
• gdchardwaremanagement.googleapis.com
• gkeconnect.googleapis.com
• gkehub.googleapis.com
• gkeonprem.googleapis.com
• iam.googleapis.com
• iamcredentials.googleapis.com
• kubernetesmetadata.googleapis.com
• logging.googleapis.com
• monitoring.googleapis.com
• multiclustermetering.googleapis.com
• opsconfigmonitoring.googleapis.com
• oslogin.googleapis.com
• serviceusage.googleapis.com
• stackdriver.googleapis.com
• storage.googleapis.com
• sts.googleapis.com

API の有効化については、サービスの有効化をご覧ください。

必要なロールを付与する

次の必須ロールを構成する必要があります。

• Gemini on GDC 接続 API デプロイの管理に使用するアカウントには、Distributed Cloud Edge Container API のロールと権限に記載されているロールを付与します。

• GDC 接続 API エンドポイントで Gemini とのやり取りに使用されるアカウントには、Vertex AI API のロールと権限に記載されているロールを付与します。

ターゲットの Distributed Cloud コネクテッド ゾーンに関する情報を取得する

ターゲットの Distributed Cloud コネクテッド ゾーンの名前を取得するには、次の操作を行います。

1. ゾーンを一覧表示するの説明に沿って、 Google Cloud プロジェクト内の Distributed Cloud 接続ゾーンを一覧表示します。

2. ゾーンに関する情報を取得するの説明に沿って、ターゲット ゾーンに関する詳細情報を取得します。

Distributed Cloud コネクテッド ゾーン内の認定済みマシンに関する情報を取得する

Distributed Cloud コネクテッド ゾーンでターゲット認定マシンの名前を取得するには、次の操作を行います。

1. ゾーン内のマシンを一覧表示するの説明に沿って、ターゲットの Distributed Cloud コネクテッド ゾーンにある Distributed Cloud コネクテッド マシンを一覧表示します。

2. マシンの情報を取得するの説明に沿って、ターゲット マシンの詳細情報を取得します。

ローカルの AI Platform API サービスと Vertex AI API サービスを有効にする

1. ターゲットの Distributed Cloud 接続ゾーンでターゲットの Google Cloud プロジェクトを有効にします。

   gcloud zone-management projects enable PROJECT_ID \
      --organization ORGANIZATION_ID \
      --location REGION \
      --zones ZONE
   

   次のように置き換えます。

   • PROJECT_ID: ターゲット Google Cloud プロジェクトの ID。
   • ORGANIZATION_ID: ターゲット Google Cloud 組織の ID。
   • REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。
   • ZONE: ターゲットの Distributed Cloud 接続ゾーン。

2. ターゲットの Google Cloud プロジェクトで AI Platform サービスを有効にします。

   gcloud services enable aiplatform.googleapis.com --project PROJECT_ID
   

   PROJECT_ID は、ターゲット Google Cloud プロジェクトの ID に置き換えます。

3. Distributed Cloud 接続ゾーンで Vertex AI API サービスを有効にします。

   gcloud zone-management services enable vertex --project PROJECT_ID \
      --location REGION \
      --zones ZONE
   

   次のように置き換えます。

   • PROJECT_ID: ターゲット Google Cloud プロジェクトの ID。
   • REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。
   • ZONE: ターゲットの Distributed Cloud 接続ゾーン。

DNS 解決のエンドポイントを構成する

1. ターゲットの Distributed Cloud 接続ゾーンのマネージド DNS アドレス、トップレベル ドメイン（TLD）、認証局（CA）証明書を取得します。

   gcloud alpha zone-management zones describe ZONE \
     --organization ORGANIZATION_ID \
     --location REGION
   

   次のように置き換えます。

   • ORGANIZATION_ID: ターゲット Google Cloud 組織の ID。
   • REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。
   • ZONE: ターゲットの Distributed Cloud 接続ゾーン。

   次の例は、このコマンドの出力例を示しています。

   -----BEGIN CERTIFICATE-----
   MIIDATCCAemgAwIBAgIRAOsIG15loHwPBpjQe9FZYUAwDQYJKoZIhvcNAQELBQAw
   GjEYMBYGA1UEAxMPZ2RjZS1jbHVzdGVyLWNhMB4XDTI1MDcyOTEyMTAwNloXDTQ5
   MDcyMzEyMTAwNlowGjEYMBYGA1UEAxMPZ2RjZS1jbHVzdGVyLWNhMIIBIjANBgkq
   hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3YdoASubyzHdgZ0vIU5g1dxdFRT1T4wc
   o9FaRXftSTDfiNVNKj/vC+De9EZokpyLZkdZNep6p0TLJAsPZYq+yiTCiaJ6Ihwy
   3LBn8j2PessSIte2LUhkft1yCQqfkgpYfKcjM3IauIXETS961m0uJb4sntgLJ4nM
   Scb5vpW1f70D1V27bqnEsE7+rbxzeFTosHC+DGBcLqIE0ptdionm/4xoltH7yv2O
   qKfcc/46TyPwGRzxifEdNzjKZ1kRdTThESfW+L7TQNv6VF5TC4FPksYX/ID/X7Fz
   G9BRey0mikvc4J7qQIeyMRlpIKqRh/1FCdRDC9vVEQipT2Ls0MwwTwIDAQABo0Iw
   QDAOBgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUmES2
   pyMLOnnsKug8amFmenOaTr8wDQYJKoZIhvcNAQELBQADggEBADn71zo7cNFZ0kQE
   C2lS6b0DLz4Nd1yCz5fGDvxzcTRdOT60wyq/TAx1YlYse33cGk/cQ7RkVsM56UX1
   T8RMvi09UcEQG3wFrYuU62ZjXF1a3RrOnHxyvVdyvbUYAO5gvzBQrj4tMZYX9kL3
   6H/9FwXuHVyqWAm0xpWvZfszwJjY4C1VxoDwmRiZPYzTrWI6/rY0QmORgcZXLnPL
   OVufbAX30aRGdTRnVXxE0fKmXwzbtbSHilU5hJT7EQWMvV5hJfyNqdXG0gbrhrsk
   sB0yRjk5PHQd9pOMcXcYIgfNnUEcQl4qeSll3g5cZ+cRrcTO1USFLRo8dcbQpJ6Y
   6ykzvKs=
   -----END CERTIFICATE-----
   createTime: '2025-08-25T20:46:50.269384028Z'
   dnsServers:
   - ipAddress: 10.200.1.10
   tld: my-tld.google.private.goog
   name: organizations/my-organization/locations/my-region/zones/my-zone
   state: STATE_RUNNING
   

   証明書をファイルに保存します。このファイルは次の手順で使用します。

2. エンドポイントの DNS 構成を次のように作成します。

   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 接続 API エンドポイントをデプロイする

Gemini on GDC 接続 API エンドポイントをデプロイする手順は次のとおりです。

1. エンドポイントを作成します。

   gcloud ai endpoints create \
      --project=PROJECT_ID \
      --region=REGION \
      --gdc-zone=ZONE \
      --display_name=ENDPOINT_NAME
   

   次のように置き換えます。

   • PROJECT_ID: ターゲット Google Cloud プロジェクトの ID。
   • REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。
   • ZONE: ターゲットの Distributed Cloud 接続ゾーン。
   • ENDPOINT_NAME: このエンドポイントを一意に識別する意味のある名前。

2. モデルをデプロイします。

   gcloud ai endpoints deploy-model ENDPOINT_NAME \
     --region=REGION \
     --gdc-zone=ZONE \
     --model=MODEL_PUBLIC_ID
   

   次のように置き換えます。

   • ENDPOINT_NAME: ターゲット エンドポイントの名前。
   • REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。
   • ZONE: ターゲットの Distributed Cloud 接続ゾーン。
   • MODEL_PUBLIC_ID: モデルの一般公開 ID。サポートされているモデルの一覧については、サポートされているモデルをご覧ください。

3. エンドポイント アドレスを取得します。

   gcloud ai endpoints describe ENDPOINT_NAME \
     --project=PROJECT_ID \
     --region=REGION
   

   次のように置き換えます。

   • ENDPOINT_NAME: ターゲット エンドポイントの名前。
   • PROJECT_ID: ターゲット Google Cloud プロジェクトの ID。
   • REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。

4. ターゲットの Distributed Cloud 接続ゾーンにエンドポイントのサービス アカウントを作成します。

   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 コネクテッド ゾーンが作成された Google Cloud リージョン。
   • ZONE: ターゲットの Distributed Cloud 接続ゾーン。

5. ターゲットの Distributed Cloud 接続ゾーンの Identity and Access Management ポリシーを取得します。

   gcloud alpha zone-management zones get-iam-policy ZONE \
     --project PROJECT_ID \ 
     --location REGION
   

   次のように置き換えます。

   • ZONE: ターゲットの Distributed Cloud 接続ゾーン。
   • PROJECT_ID: ターゲット Google Cloud プロジェクトの ID。
   • REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。

6. サービス アカウントに AI Platform デベロッパー ロールを割り当てます。

   gcloud alpha zone-management zones set-iam-policy  \
     --project PROJECT_ID \
     --location REGION \
     --zone ZONE
   

   次のように置き換えます。

   • POLICY_FILE: ロール割り当てポリシーを含む JSON または YAML ファイル。
   • PROJECT_ID: ターゲット Google Cloud プロジェクトの ID。
   • REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。
   • ZONE: ターゲットの Distributed Cloud 接続ゾーン。

   JSON 形式のポリシーの例を次に示します。

   "bindings": [
      {
         "role": "roles/aiplatform.geminiDeveloper",
         "members": [
         "serviceAccount": "projects/my-project/locations/my-region/serviceAccounts/my-service-account"
         ]
      }
   ],
   "etag": ""
   

   YAML 形式のポリシーの例を次に示します。

   bindings:
   - role: roles/aiplatform.geminiDeveloper
   members:
   - serviceAccount: projects/my-project/locations/my-region/serviceAccounts/my-service-account
   etag: ""
   

7. サービス アカウントのキーを生成します。

   gcloud alpha zone-management service-accounts keys create  \
      --service-account  \
      --project  \
      --location  \
      --ca-cert-path 
   

   次のように置き換えます。

   • SA_KEY_FILE: 生成されたサービス アカウント キーを保存するファイル。
   • PROJECT_ID: ターゲット Google Cloud プロジェクトの ID。
   • REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。
   • CA_CERTIFICATE_FILE: 前に作成した CA 証明書ファイル。

8. サービス アカウントの ID トークンを出力します。

   gcloud alpha zone-management auth print-identity-token \
     --cred-file=SA_CREDENTIAL_FILE \
     --audience=ENDPOINT_URL
   

   次のように置き換えます。

   • SA_KEY_FILE: 先ほど作成したサービス アカウント キーファイル。
   • ENDPOINT_URL: エンドポイントの完全修飾 URL（TLD サフィックスを含む）。

デプロイされた Gemini on GDC 接続 API エンドポイントを一覧表示する

デプロイされた Gemini on GDC 接続 API エンドポイントを一覧表示するには、次の操作を行います。

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

次のように置き換えます。

• PROJECT_ID: ターゲット Google Cloud プロジェクトの ID。
• REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。
• ZONE: ターゲットの Distributed Cloud 接続ゾーン。

Gemini on GDC 接続 API エンドポイントに関する情報を取得する

デプロイされた Gemini on GDC 接続 API エンドポイントに関する情報を取得する手順は次のとおりです。

gcloud ai endpoints describe ENDPOINT_NAME \
    --project=PROJECT_ID \
    --region=REGION
   

次のように置き換えます。

• ENDPOINT_NAME: ターゲット エンドポイントの名前。
• PROJECT_ID: ターゲット Google Cloud プロジェクトの ID。
• REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。

Gemini on Google Distributed Cloud コネクテッド API エンドポイントを操作する

Gemini on GDC 接続 API エンドポイントは、ChatCompletions API と ListAvailableModels API を介したインタラクションをサポートしています。これらの API を使用して、エンドポイントをプログラムで操作します。

Chat Completions API を介したリクエストの例を次に示します。

API_ENDPOINT="https://${IG_FQDN}/v1/projects/${PROJECT}/locations/${LOCATION}/chat/completions"

FLOW_ID="gemini-2.0-flash-001"

REQUEST_BODY='{
>   "model": "'${FLOW_ID}'",
>   "messages": [
>     {
>       "role": "system",
>       "content": "You are a helpful assistant."
>     },
>     {
>       "role": "user",
>       "content": "Hello!"
>     }
>   ],
}'

curl -X POST -vv -k \
  "${API_ENDPOINT}" \
  -d "${REQUEST_BODY}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${BEARER_TOKEN}" \
  -H "x-goog-user-project: projects/${PROJECT}"

次に、ドキュメントを入力として使用するマルチモーダル Chat Completions API リクエストの例を示します。

BASE64_IMAGE=$(base64 -w 0 sample-image.jpg)

{
    "model": "gemini-1.5-flash-002",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is this image?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "data:image/jpeg;base64,'"${BASE64_IMAGE}"'"
                    }
                }
            ]
        }
    ]
}

ListAllAvailableModels API リクエストの例を次に示します。

# The request body -d parameter is intentionally omitted.
grpcurl -insecure \
  -H "Authorization: Bearer ${BEARER_TOKEN}" \
  -H "x-goog-user-project: projects/${PROJECT}" \
  "${IG_FQDN}:443" \
  cloud.gdc.ai.inference.inferencegateway.GeminiMetadataService.ListAvailableModels

Gemini on Google Distributed Cloud 接続 API に適したワークロードの詳細については、Gemini の概要をご覧ください。

Gemini on Google Distributed Cloud connected API エンドポイントを削除する

Gemini on GDC 接続 API エンドポイントを削除するには、次の操作を行います。

1. モデルのデプロイを解除します。

   gcloud ai endpoints undeploy-model ENDPOINT_NAME \
     --region=REGION \
     --gdc-zone=ZONE \
     --model=MODEL_PUBLIC_ID
   

   次のように置き換えます。

   • ENDPOINT_NAME: ターゲット エンドポイントの名前。
   • REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。
   • ZONE: ターゲットの Distributed Cloud 接続ゾーン。
   • MODEL_PUBLIC_ID: モデルの一般公開 ID。サポートされているモデルの一覧については、サポートされているモデルをご覧ください。

2. エンドポイントを削除します。

   gcloud ai endpoints delete ENDPOINT_NAME \
      --project=PROJECT_ID \
      --region=REGION
   

   次のように置き換えます。

   • PROJECT_ID: ターゲット エンドポイントの名前。
   • REGION: ターゲットの Distributed Cloud コネクテッド ゾーンが作成された Google Cloud リージョン。