Membuat dan mengelola endpoint

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Halaman ini menjelaskan cara membuat dan mengelola endpoint API yang terhubung ke Gemini di Google Distributed Cloud.

Dokumen ini mengasumsikan bahwa Anda telah berhasil men-deploy hardware bersertifikasi Google seperti yang dijelaskan dalam Persyaratan penginstalan.

Prasyarat

Bagian ini menjelaskan langkah-langkah sekali saja yang harus Anda selesaikan sebelum dapat men-deploy Gemini di endpoint API yang terhubung ke GDC.

Berikan peran yang diperlukan

Anda harus mengonfigurasi peran wajib berikut:

• Untuk akun yang digunakan untuk mengelola deployment API yang terhubung dengan Gemini di GDC, berikan peran yang tercantum dalam Peran dan izin Distributed Cloud Edge Container API.

• Untuk akun yang digunakan untuk berinteraksi dengan Gemini di endpoint API yang terhubung ke GDC, berikan peran yang tercantum dalam Peran dan izin Vertex AI API.

Mendapatkan informasi tentang zona target Distributed Cloud terhubung

Untuk mendapatkan nama zona target yang terhubung ke Distributed Cloud, lakukan hal berikut:

1. Dapatkan nama ID organisasi target Google Cloud :

   gcloud organizations list
   

2. Mencantumkan zona yang terhubung ke Distributed Cloud di Google Cloud organisasi Anda:

   gcloud alpha zone-management zones list \
      --organization ORGANIZATION_ID \
      --location REGION
   

   Ganti kode berikut:

   • ORGANIZATION_ID: ID organisasi Google Cloud target.
   • REGION: region Google Cloud tempat zona Distributed Cloud terhubung target dibuat. Selama Pratinjau Publik, satu-satunya wilayah yang didukung adalah us-west2.

3. Dapatkan informasi mendetail tentang zona target:

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

   Ganti kode berikut:

   • ZONE: zona target Distributed Cloud Connected.
   • ORGANIZATION_ID: ID organisasi Google Cloud target.
   • REGION: region Google Cloud tempat zona Distributed Cloud terhubung target dibuat. Selama Pratinjau Publik, satu-satunya wilayah yang didukung adalah us-west2.

Mendapatkan informasi tentang mesin bersertifikasi di zona Distributed Cloud terhubung Anda

Untuk mendapatkan nama mesin bersertifikasi target di zona terhubung Distributed Cloud Anda, lakukan hal berikut:

1. Mencantumkan mesin yang terhubung ke Distributed Cloud di zona yang terhubung ke Distributed Cloud target seperti yang dijelaskan dalam Mencantumkan mesin dalam zona.

2. Dapatkan informasi mendetail tentang mesin target seperti yang dijelaskan dalam Mendapatkan informasi tentang mesin.

Aktifkan layanan AI Platform API dan Vertex AI API lokal

1. Aktifkan project Google Cloud target di zona yang terhubung dengan Distributed Cloud target Anda:

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

   Ganti kode berikut:

   • PROJECT_ID: ID project Google Cloud target.
   • ORGANIZATION_ID: ID organisasi Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
   • ZONE: zona target Distributed Cloud Connected.

2. Aktifkan layanan AI Platform di target Google Cloud project:

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

   Ganti PROJECT_ID dengan ID project Google Cloud target.

3. Aktifkan layanan Vertex AI API di zona yang terhubung dengan Distributed Cloud:

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

   Ganti kode berikut:

   • PROJECT_ID: ID project Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
   • ZONE: zona target Distributed Cloud Connected.

Mengonfigurasi endpoint untuk resolusi DNS

1. Dapatkan alamat DNS terkelola, domain level teratas (TLD), dan sertifikat Certificate Authority (CA) untuk target zona yang terhubung ke Distributed Cloud:

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

   Ganti kode berikut:

   • ORGANIZATION_ID: ID organisasi Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
   • ZONE: zona target Distributed Cloud Connected.

   Contoh berikut menggambarkan output perintah ini:

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

   Simpan sertifikat ke dalam file bernama CA_CERTIFICATE_FILE. Anda akan menggunakan file ini nanti untuk membuat kunci akun layanan.

2. Buat konfigurasi DNS untuk endpoint sebagai berikut:

   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
   

   Ganti kode berikut:

   • DNS_SERVER_ADDRESS: alamat IP server DNS Anda.
   • TOP_LEVEL_DOMAIN: domain level teratas untuk endpoint.

Men-deploy endpoint API yang terhubung dengan Gemini di GDC

Untuk men-deploy endpoint API yang terhubung dengan Gemini di GDC, lakukan hal berikut:

1. Buat endpoint:

   gcloud beta ai endpoints create \
      --project=PROJECT_ID \
      --region=REGION \
      --gdc-zone=ZONE \
      --display-name=ENDPOINT_NAME \
      --endpoint-id=ENDPOINT_ID
   

   Ganti kode berikut:

   • PROJECT_ID: ID project Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
   • ZONE: zona target Distributed Cloud Connected.
   • ENDPOINT_NAME: nama yang bermakna untuk endpoint ini.
   • ENDPOINT_ID: (opsional) ID unik untuk endpoint ini. Jika tidak ada, ID acak akan dibuat.

2. Deploy model:

   gcloud beta ai endpoints deploy-model ENDPOINT_ID \
     --display-name=ENDPOINT_NAME \
     --model=MODEL_PUBLIC_ID \
     --region=REGION
   

   Ganti kode berikut:

   • ENDPOINT_ID: ID endpoint target.
   • ENDPOINT_NAME: nama endpoint target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
   • MODEL_PUBLIC_ID: ID model yang ditampilkan secara publik. Untuk mengetahui daftar model yang didukung, lihat Model yang didukung.

3. Mencantumkan endpoint yang di-deploy:

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

   Ganti kode berikut:

   • PROJECT_ID: ID project Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.

   Catat ID endpoint target.

4. Dapatkan alamat endpoint:

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

   Ganti kode berikut:

   • ENDPOINT_ID: ID endpoint target.
   • PROJECT_ID: ID project Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.

5. Buat akun layanan untuk endpoint di zona yang terhubung Distributed Cloud target:

   gcloud alpha zone-management service-accounts create SERVICE_ACCOUNT \
     --project PROJECT_ID \
     --location REGION \
     --zone ZONE
   

   Ganti kode berikut:

   • SERVICE_ACCOUNT: nama yang bermakna yang mengidentifikasi akun layanan ini secara unik.
   • PROJECT_ID: ID project Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
   • ZONE: zona target Distributed Cloud Connected.

6. Dapatkan kebijakan Identity and Access Management untuk zona target yang terhubung ke Distributed Cloud:

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

   Ganti kode berikut:

   • ZONE: zona target Distributed Cloud Connected.
   • PROJECT_ID: ID project Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.

7. Tetapkan peran AI Platform Developer ke akun layanan:

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

   Ganti kode berikut:

   • POLICY_FILE: File JSON atau YAML yang berisi kebijakan penetapan peran.
   • PROJECT_ID: ID project Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
   • ZONE: zona target Distributed Cloud Connected.

   Berikut adalah contoh kebijakan dalam format JSON:

   "bindings": [
      {
         "role": "roles/aiplatform.geminiDeveloper",
         "members": [
         "serviceAccount": "projects/PROJECT_ID/locations/REGION/serviceAccounts/SERVICE_ACCOUNT"
         ]
      }
   ]
   "etag": ""
   

   Berikut adalah contoh kebijakan dalam format YAML:

   bindings:
   - role: roles/aiplatform.geminiDeveloper
   members:
   - serviceAccount: projects/PROJECT_ID/locations/REGION/serviceAccounts/SERVICE_ACCOUNT
   etag: ""
   

   Ganti kode berikut:

   • PROJECT_ID: ID project Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
   • SERVICE_ACCOUNT: nama yang bermakna yang mengidentifikasi akun layanan ini secara unik.

8. Buat kunci untuk akun layanan:

   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
   

   Ganti kode berikut:

   • SA_KEY_FILE: file tempat menyimpan kunci akun layanan yang dibuat.
   • PROJECT_ID: ID project Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
   • CA_CERTIFICATE_FILE: file sertifikat CA yang Anda buat sebelumnya.

9. Dapatkan URL endpoint yang sepenuhnya memenuhi syarat:

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

10. Mencetak token identitas untuk akun layanan:

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

    Ganti kode berikut:

    • SA_KEY_FILE: file kunci akun layanan yang Anda buat sebelumnya.
    • ENDPOINT_URL: URL endpoint yang sepenuhnya memenuhi syarat, termasuk akhiran TLD.

Mencantumkan endpoint API yang terhubung ke GDC dengan Gemini yang di-deploy

Untuk mencantumkan endpoint API yang terhubung ke Gemini yang di-deploy di GDC, lakukan hal berikut:

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

Ganti kode berikut:

• PROJECT_ID: ID project Google Cloud target.
• REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
• ZONE: zona target Distributed Cloud Connected.

Mendapatkan informasi tentang endpoint API Gemini di GDC terhubung

Untuk mendapatkan informasi tentang endpoint API yang terhubung dengan Gemini yang di-deploy di GDC, lakukan hal berikut:

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

Ganti kode berikut:

• ENDPOINT_ID: ID endpoint target.
• PROJECT_ID: ID project Google Cloud target.
• REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.

Berinteraksi dengan endpoint API Gemini di Google Distributed Cloud terhubung

Endpoint API Gemini di GDC yang terhubung mendukung interaksi melalui API ChatCompletions dan API ListAvailableModels. Gunakan API ini untuk berinteraksi dengan endpoint Anda secara terprogram.

Berikut adalah contoh permintaan melalui ChatCompletions API. Token pembawa yang dibuat dalam permintaan ini valid selama 12 jam.

1. Tetapkan variabel berikut di lingkungan shell Anda:

   MODEL_NAME="gemini-2.0-flash-001"
   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"
   

   Ganti kode berikut:

   • PROJECT_ID: ID project Google Cloud target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
   • SA_KEY_FILE: file kunci akun layanan yang Anda buat sebelumnya.

2. Cetak token pemilik:

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

3. Buat payload:

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

4. Kirim permintaan ke endpoint:

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

Contoh permintaan API ChatCompletions multimodal

Berikut adalah contoh payload permintaan API ChatCompletions multimodal dengan dokumen sebagai input:

1. Buat payload:

   BASE64_IMAGE=$(base64 -w 0 JPEG_FILE)
   REQUEST_BODY=$(cat <<EOF
   {
   "model": "${MODEL_NAME}",
   "messages": [
      {
         "role": "user",
         "content": [
               {
                  "type": "text",
                  "text": "What is this image?"
               },
               {
                  "type": "image_url",
                  "image_url": {
                     "url": "data:image/jpeg;base64,${BASE64_IMAGE}"
                  }
               }
         ]
      }
   ]
   }
   EOF
   
   )
   

2. Kirim permintaan ke endpoint:

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

Contoh permintaan API ListAllAvailableModels

Berikut adalah contoh permintaan API ListAllAvailableModels:

BEARER_TOKEN=$(gcloud alpha zone-management auth print-identity-token --cred-file="${CRED_FILE}" --audience="https://${IG_FQDN}")
# The request body -d parameter is intentionally omitted.
grpcurl -insecure \
  -H "Authorization: Bearer ${BEARER_TOKEN}" \
  -H "x-goog-user-project: projects/${PROJECT}" \
  "${IG_FQDN}" \
  cloud.gdc.ai.inference.inferencegateway.GeminiMetadataService.ListAvailableModels

Menghapus endpoint API Gemini on Google Distributed Cloud terhubung

Untuk menghapus endpoint API yang terhubung ke Gemini di GDC, lakukan hal berikut:

1. Batalkan deployment model:

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

   Ganti kode berikut:

   • ENDPOINT_ID: ID endpoint target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.
   • ZONE: zona target Distributed Cloud Connected.
   • MODEL_PUBLIC_ID: ID model yang ditampilkan secara publik. Untuk mengetahui daftar model yang didukung, lihat Model yang didukung.

2. Hapus endpoint:

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

   Ganti kode berikut:

   • ENDPOINT_ID: ID endpoint target.
   • PROJECT_ID: nama endpoint target.
   • REGION: Google Cloud region tempat zona Distributed Cloud terhubung target dibuat.

Memecahkan masalah endpoint

Jika endpoint API Gemini di GDC yang terhubung tidak berfungsi, hubungi perwakilan Google Anda untuk memecahkan masalah tersebut.