Creare e gestire endpoint

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione 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 saperne di più, consulta le descrizioni della fase di lancio.

Questa pagina descrive come creare e gestire gli endpoint API connessi di Gemini su Google Distributed Cloud.

Presuppone che tu abbia eseguito il deployment dell'hardware certificato da Google come descritto in Requisiti di installazione.

Prerequisiti

Questa sezione descrive i passaggi da completare una sola volta prima di poter eseguire il deployment di Gemini sugli endpoint API connessi a GDC.

Abilita le API richieste

Devi abilitare le seguenti API nel progetto Google Cloud di destinazione:

• 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

Per informazioni sull'abilitazione delle API, vedi Abilitazione dei servizi.

Concedere i ruoli richiesti

Devi configurare i seguenti ruoli obbligatori:

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

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

Recupera informazioni sulla zona connessa a Distributed Cloud di destinazione

Per ottenere il nome della zona connessa a Distributed Cloud di destinazione:

1. Elenca le zone connesse a Distributed Cloud nel tuo progetto Google Cloud come descritto in Elenca zone.

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

Visualizza informazioni sulle macchine certificate nella tua zona connessa a Distributed Cloud

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

1. Elenca le macchine connesse a Distributed Cloud nella zona connessa a Distributed Cloud di destinazione come descritto in Elenca le macchine in una zona.

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

Abilita i servizi API AI Platform locale e API Vertex AI

1. Abilita il progetto Google Cloud di destinazione nella zona connessa a Distributed Cloud di destinazione:

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

   Sostituisci quanto segue:

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

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

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

   Sostituisci PROJECT_ID con l'ID del progetto Google Cloud di destinazione.

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

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

   Sostituisci quanto segue:

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

Configura 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 connessa Distributed Cloud di destinazione:

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

   Sostituisci quanto segue:

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

   L'esempio seguente illustra l'output di questo comando:

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

   Memorizza il certificato in un file. Utilizzerai questo file nei passaggi successivi.

2. Crea la configurazione DNS per l'endpoint nel seguente modo:

   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 tuo server DNS.
   • TOP_LEVEL_DOMAIN: il dominio di primo livello per l'endpoint.

Esegui il deployment di un endpoint API connesso a Gemini on GDC

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

1. Crea l'endpoint:

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

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID del progetto Google Cloud di destinazione.
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connessa di destinazione.
   • ZONE: la zona Distributed Cloud connessa di destinazione.
   • ENDPOINT_NAME: un nome significativo che identifichi in modo univoco questo endpoint.

2. Esegui il deployment del modello:

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

   Sostituisci quanto segue:

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

3. Ottieni l'indirizzo dell'endpoint:

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

   Sostituisci quanto segue:

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

4. Crea il account di servizio per l'endpoint nella zona connessa Distributed Cloud 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 identifichi in modo univoco questo account di servizio.
   • PROJECT_ID: l'ID del progetto Google Cloud di destinazione.
   • REGION: la Google Cloud regione in cui è stata creata la zona Distributed Cloud connessa di destinazione.
   • ZONE: la zona Distributed Cloud connessa di destinazione.

5. Recupera il criterio Identity and Access Management per la zona Distributed Cloud connessa di destinazione:

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

   Sostituisci quanto segue:

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

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

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

   Sostituisci quanto segue:

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

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

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

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

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

7. Genera una chiave per il account di servizio:

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

   Sostituisci quanto segue:

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

8. Stampa il token ID per il account di servizio:

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

   Sostituisci quanto segue:

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

Elenca gli endpoint API di Gemini di cui è stato eseguito il deployment su GDC Connected

Per elencare Gemini di cui è stato eseguito il deployment sugli endpoint API connessi a GDC:

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

Sostituisci quanto segue:

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

Ricevere informazioni su un endpoint API Gemini su GDC Connected

Per ottenere informazioni su un endpoint API Gemini on GDC Connected di cui è stato eseguito il deployment, procedi nel seguente modo:

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

Sostituisci quanto segue:

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

Interagisci con un endpoint API Gemini su Google Distributed Cloud connected

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

Ecco un esempio di richiesta tramite l'API Chat Completions:

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

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

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}"'"
                    }
                }
            ]
        }
    ]
}

Ecco un esempio di richiesta API ListAllAvailableModels:

# 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

Per ulteriori informazioni sui workload adatti a Gemini nell'API Google Distributed Cloud connesso, consulta Panoramica di Gemini.

Elimina un endpoint API Gemini on Google Distributed Cloud connected

Per eliminare un endpoint API connesso a Gemini on GDC, segui questi passaggi:

1. Annulla il deployment del modello:

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

   Sostituisci quanto segue:

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

2. Elimina l'endpoint:

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

   Sostituisci quanto segue:

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