Creare e gestire endpoint

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Avviso: durante il periodo di anteprima, puoi utilizzare Gemini sull'API GDC connected solo per scopi di valutazione e test. Non puoi utilizzare la release di anteprima dell'API Gemini on GDC connected per scopi commerciali o di produzione né divulgare l'output generato a terze parti.

Questa pagina descrive come creare e gestire gli endpoint dell'API Gemini on Google Distributed Cloud connected.

Prerequisiti

Questa sezione descrive i passaggi da completare una sola volta prima di poter eseguire il deployment degli endpoint dell'API Gemini on GDC connected. Completa i passaggi sulla macchina di attivazione.

Completare l'attivazione dell'hardware

Prima di completare i passaggi descritti in questa pagina, devi:

• Eseguire il deployment dell'hardware certificato da Google come descritto in Requisiti di installazione.

• Collaborare con il tuo rappresentante di Google per creare i cluster Distributed Cloud connected richiesti.

Concedere i ruoli richiesti

Devi configurare i seguenti ruoli obbligatori:

• Per gli account utilizzati per gestire il deployment dell'API Gemini on GDC connected, concedi i ruoli elencati in Ruoli e autorizzazioni dell'API Distributed Cloud Edge Container.

• Per gli account utilizzati per interagire con gli endpoint dell'API Gemini on GDC connected, concedi i ruoli elencati in Ruoli e autorizzazioni dell'API Vertex AI.

Ottenere informazioni sulla zona Distributed Cloud connected di destinazione

Per ottenere il nome della zona Distributed Cloud connected di destinazione:

1. Ottieni il nome dell'ID dell'organizzazione di destinazione: Google Cloud

   gcloud organizations list
   

2. Elenca le zone Distributed Cloud connected nella tua Google Cloud organizzazione:

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

   Sostituisci quanto segue:

   • ORGANIZATION_ID: l'ID dell'organizzazione di destinazione. Google Cloud
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione. Durante l'anteprima pubblica, l'unica regione supportata è us-west2.

3. Ottieni informazioni dettagliate sulla zona di destinazione:

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

   Sostituisci quanto segue:

   • ZONE: la zona Distributed Cloud connected di destinazione.
   • ORGANIZATION_ID: l'ID dell'organizzazione di destinazione. Google Cloud
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione. Durante l'anteprima pubblica, l'unica regione supportata è us-west2.

Ottenere informazioni sulle macchine certificate nella zona Distributed Cloud connected

Per ottenere i nomi delle macchine certificate di destinazione nella zona Distributed Cloud connected:

1. Elenca le macchine Distributed Cloud connected nella zona Distributed Cloud connected di destinazione come descritto in Elencare le macchine in una zona.

2. Ottieni informazioni dettagliate sulla macchina di destinazione come descritto in Ottenere informazioni su una macchina.

Abilitare i servizi API AI Platform locale e API Vertex AI

1. Abilita ilprogetto di destinazione nella zona Distributed Cloud connected di destinazione: Google Cloud

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

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
   • ORGANIZATION_ID: l'ID dell'organizzazione di destinazione. Google Cloud
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
   • ZONE: la zona Distributed Cloud connected di destinazione.

2. Abilita il servizio AI Platform nel progetto di destinazione Google Cloud :

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

   Sostituisci PROJECT_ID con l'ID delprogetto di destinazione. Google Cloud

3. Abilita il servizio API Vertex AI nella zona Distributed Cloud connected:

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

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
   • ZONE: la zona Distributed Cloud connected di destinazione.

Configurare l'endpoint per la risoluzione DNS

1. Ottieni l'indirizzo DNS gestito, il dominio di primo livello (TLD) e il certificato dell'autorità di certificazione (CA) per la zona Distributed Cloud connected di destinazione.

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

   Sostituisci quanto segue:

   • ORGANIZATION_ID: l'ID dell'organizzazione di destinazione. Google Cloud
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
   • ZONE: la zona Distributed Cloud connected di destinazione.
   • CA_CERTIFICATE_FILE: il file in cui viene salvato il payload del certificato generato dal comando. Utilizzerai questo file in un secondo momento per generare la chiave del account di servizio.

   Il comando restituisce un output simile al seguente, memorizzato nel file:

   -----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: DNS_SERVER_ADDRESS
   tld: TOP_LEVEL_DOMAIN
   name: organizations/ORGANIZATION_ID/locations/REGION/zones/ZONE
   state: STATE_RUNNING
   

2. Crea la configurazione DNS per l'endpoint come segue utilizzando l'indirizzo IP del server DNS e il nome del dominio di primo livello (TLD) ottenuti nel passaggio precedente. Devi eseguire questo comando da una macchina che si trova sulla stessa rete locale della macchina certificata dell'API Gemini on GDC connected.

   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
   

   Sostituisci quanto segue:

   • DNS_SERVER_ADDRESS: l'indirizzo IP del server DNS.
   • TOP_LEVEL_DOMAIN: il dominio di primo livello per l'endpoint.

Eseguire il deployment di un endpoint API Gemini on GDC connected

Per eseguire il deployment di un endpoint API Gemini on GDC connected:

1. Crea l'endpoint:

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

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
   • ZONE: la zona Distributed Cloud connected di destinazione.
   • ENDPOINT_NAME: un nome significativo per questo endpoint.
   • ENDPOINT_ID: (facoltativo) un identificatore univoco per questo endpoint. Se omesso, viene generato un identificatore casuale.

2. Esegui il deployment del modello:

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

   Sostituisci quanto segue:

   • ENDPOINT_ID: l'ID dell'endpoint di destinazione.
   • ENDPOINT_NAME: il nome dell'endpoint di destinazione.
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
   • MODEL_PUBLIC_ID: l'ID pubblico del modello. Per un elenco dei modelli supportati, consulta Modelli supportati.

3. Elenca gli endpoint di cui è stato eseguito il deployment:

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

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.

   Prendi nota dell'ID dell'endpoint di destinazione.

4. Ottieni l'indirizzo dell'endpoint:

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

   Sostituisci quanto segue:

   • ENDPOINT_ID: l'ID dell'endpoint di destinazione.
   • PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.

5. Crea il account di servizio per l'endpoint nella zona Distributed Cloud connected di destinazione:

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

   Sostituisci quanto segue:

   • SERVICE_ACCOUNT: un nome significativo che identifica in modo univoco questo account di servizio. Questo nome deve contenere solo lettere minuscole, numeri, "-" o "." e deve iniziare e terminare con un carattere alfanumerico. Non sono consentite lettere maiuscole.
   • PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
   • ZONE: la zona Distributed Cloud connected di destinazione.

6. Ottieni la policy Identity and Access Management per la zona Distributed Cloud connected di destinazione:

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

   Sostituisci quanto segue:

   • ZONE: la zona Distributed Cloud connected di destinazione.
   • PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.

7. Assegna il ruolo Sviluppatore AI Platform al account di servizio:

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

   Sostituisci quanto segue:

   • POLICY_FILE: file JSON o YAML contenente la policy di assegnazione dei ruoli.
   • PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
   • ZONE: la zona Distributed Cloud connected di destinazione.

   Di seguito è riportato un esempio di policy in formato JSON:

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

   Di seguito è riportato un esempio di policy in formato YAML:

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

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
   • SERVICE_ACCOUNT: un nome significativo che identifica in modo univoco questo account di servizio.

8. Genera una chiave per il account di servizio:

   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
   

   Sostituisci quanto segue:

   • SA_KEY_FILE: file in cui memorizzare la chiave del account di servizio generata.
   • PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
   • CA_CERTIFICATE_FILE: il file del certificato CA creato in precedenza.

9. Ottieni l'URL completo dell'endpoint:

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

10. Stampa il token ID per il account di servizio. Devi eseguire questo comando da una macchina che si trova sulla stessa rete locale della macchina certificata dell'API Gemini on GDC connected.

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

    Sostituisci quanto segue:

    • SA_KEY_FILE: il file della chiave del account di servizio creato in precedenza.
    • ENDPOINT_URL: l'URL completo dell'endpoint, incluso il suffisso TLD.

Elencare gli endpoint dell'API Gemini on GDC connected di cui è stato eseguito il deployment

Per elencare gli endpoint dell'API Gemini on GDC connected di cui è stato eseguito il deployment:

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

Sostituisci quanto segue:

• PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
• REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
• ZONE: la zona Distributed Cloud connected di destinazione.

Ottenere informazioni su un endpoint API Gemini on GDC connected

Per ottenere informazioni su un endpoint API Gemini on GDC connected di cui è stato eseguito il deployment:

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

Sostituisci quanto segue:

• ENDPOINT_ID: l'ID dell'endpoint di destinazione.
• PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
• REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.

Interagire con un endpoint API Gemini on Google Distributed Cloud connected

L'endpoint API Gemini on GDC connected supporta l'interazione tramite l'API ChatCompletions e l'API ListAvailableModels. Utilizza queste API per interagire in modo programmatico con l'endpoint.

Di seguito è riportato un esempio di richiesta tramite l'API ChatCompletions. Il token di autenticazione generato in questa richiesta è valido per 12 ore.

1. Imposta le seguenti variabili nell'ambiente della 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"
   

   Sostituisci quanto segue:

   • MODEL_NAME: il nome del modello di destinazione.
   • PROJECT_ID: l'ID delprogetto di destinazione Google Cloud .
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
   • SA_KEY_FILE: il file della chiave del account di servizio creato in precedenza.

2. Stampa il token di autenticazione. Devi eseguire questo comando da una macchina che si trova sulla stessa rete locale della macchina certificata dell'API Gemini on GDC connected.

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

3. Crea il payload:

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

4. Invia la richiesta all'endpoint. Devi eseguire questo comando da una macchina che si trova sulla stessa rete locale della macchina certificata dell'API Gemini on GDC connected.

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

Esempio di richiesta dell'API ChatCompletions multimodale

Di seguito è riportato un esempio di payload di richiesta dell'API ChatCompletions multimodale con un documento come input:

1. Crea il 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. Invia la richiesta all'endpoint. Devi eseguire questo comando da una macchina che si trova sulla stessa rete locale della macchina certificata dell'API Gemini on GDC connected.

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

Esempio di richiesta dell'API ListAllAvailableModels

Di seguito è riportato un esempio di richiesta dell'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

Eliminare un endpoint API Gemini on Google Distributed Cloud connected

Per eliminare un endpoint API Gemini on GDC connected:

1. Annulla il deployment del modello:

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

   Sostituisci quanto segue:

   • ENDPOINT_ID: l'ID dell'endpoint di destinazione.
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.
   • ZONE: la zona Distributed Cloud connected di destinazione.
   • MODEL_PUBLIC_ID: l'ID pubblico del modello. Per un elenco dei modelli supportati, consulta Modelli supportati.

2. Elimina l'endpoint:

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

   Sostituisci quanto segue:

   • ENDPOINT_ID: l'ID dell'endpoint di destinazione.
   • PROJECT_ID: il nome dell'endpoint di destinazione.
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connected di destinazione.

Risolvere i problemi relativi agli endpoint

Se un endpoint API Gemini on GDC connected non funziona, contatta il tuo rappresentante di Google per risolvere il problema.