Crie e faça a gestão de pontos finais

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Esta página descreve como criar e gerir o Gemini nos pontos finais da API connected do Google Distributed Cloud.

Parte do princípio de que implementou com êxito o hardware certificado pela Google, conforme descrito nos requisitos de instalação.

Pré-requisitos

Esta secção descreve os passos únicos que tem de concluir antes de poder implementar o Gemini nos pontos finais da API GDC connected.

Ative as APIs necessárias

Tem de ativar as seguintes APIs no seu projeto Google Cloud de destino:

• 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

Para obter informações sobre como ativar APIs, consulte a secção Ativar serviços.

Conceda as funções necessárias

Tem de configurar as seguintes funções obrigatórias:

• Para contas usadas para gerir a implementação da API Gemini on GDC connected, conceda as funções indicadas em Funções e autorizações da API Distributed Cloud Edge Container.

• Para contas usadas para interagir com o Gemini em pontos finais da API GDC ligados, conceda as funções indicadas em Funções e autorizações da API Vertex AI.

Obtenha informações sobre a zona ligada do Distributed Cloud de destino

Para obter o nome da zona ligada do Distributed Cloud de destino, faça o seguinte:

1. Liste as zonas ligadas do Distributed Cloud no seu Google Cloud projeto, conforme descrito em Listar zonas.

2. Obtenha informações detalhadas sobre a zona de destino, conforme descrito em Obtenha informações sobre uma zona.

Obtenha informações sobre as máquinas certificadas na sua zona ligada do Distributed Cloud

Para obter os nomes das máquinas certificadas de destino na sua zona ligada do Distributed Cloud, faça o seguinte:

1. Liste as máquinas ligadas ao Distributed Cloud na zona ligada ao Distributed Cloud de destino, conforme descrito em Liste máquinas numa zona.

2. Obtenha informações detalhadas sobre a máquina de destino, conforme descrito em Obtenha informações sobre uma máquina.

Ative os serviços da API AI Platform local e da API Vertex AI

1. Ative o projeto Google Cloud de destino na zona ligada do Distributed Cloud de destino:

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

   Substitua o seguinte:

   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • ORGANIZATION_ID: o ID da organização Google Cloud de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.
   • ZONE: a zona ligada do Distributed Cloud de destino.

2. Ative o serviço AI Platform no projeto Google Cloud de destino:

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

   Substitua PROJECT_ID pelo ID do projeto Google Cloud de destino.

3. Ative o serviço da API Vertex AI na zona ligada do Distributed Cloud:

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

   Substitua o seguinte:

   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.
   • ZONE: a zona ligada do Distributed Cloud de destino.

Configure o ponto final para a resolução de DNS

1. Obtenha o endereço DNS gerido, o domínio de nível superior (TLD) e o certificado da autoridade de certificação (AC) para a zona ligada do Distributed Cloud de destino:

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

   Substitua o seguinte:

   • ORGANIZATION_ID: o ID da organização Google Cloud de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.
   • ZONE: a zona ligada do Distributed Cloud de destino.

   O exemplo seguinte ilustra o resultado deste 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
   

   Armazene o certificado num ficheiro. Vai usar este ficheiro nos passos seguintes.

2. Crie a configuração de DNS para o ponto final da seguinte forma:

   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
   

   Substitua o seguinte:

   • DNS_SERVER_ADDRESS: o endereço IP do seu servidor DNS.
   • TOP_LEVEL_DOMAIN: o domínio de nível superior do ponto final.

Implemente um ponto final da API Gemini on GDC connected

Para implementar um ponto final da API associada do Gemini no GDC, faça o seguinte:

1. Crie o ponto final:

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

   Substitua o seguinte:

   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.
   • ZONE: a zona ligada do Distributed Cloud de destino.
   • ENDPOINT_NAME: um nome significativo que identifica exclusivamente este ponto final.

2. Implemente o modelo:

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

   Substitua o seguinte:

   • ENDPOINT_NAME: o nome do ponto final de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.
   • ZONE: a zona ligada do Distributed Cloud de destino.
   • MODEL_PUBLIC_ID: o ID público do modelo. Para ver uma lista dos modelos suportados, consulte o artigo Modelos suportados.

3. Obtenha o endereço do ponto final:

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

   Substitua o seguinte:

   • ENDPOINT_NAME: o nome do ponto final de destino.
   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.

4. Crie a conta de serviço para o ponto final na zona ligada do Distributed Cloud de destino:

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

   Substitua o seguinte:

   • SERVICE_ACCOUNT: um nome significativo que identifica exclusivamente esta conta de serviço.
   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.
   • ZONE: a zona ligada do Distributed Cloud de destino.

5. Obtenha a política de gestão de identidade e de acesso para a zona ligada do Distributed Cloud de destino:

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

   Substitua o seguinte:

   • ZONE: a zona ligada do Distributed Cloud de destino.
   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.

6. Atribua a função AI Platform Developer à conta de serviço:

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

   Substitua o seguinte:

   • POLICY_FILE: ficheiro JSON ou YAML que contém a política de atribuição de funções.
   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.
   • ZONE: a zona ligada do Distributed Cloud de destino.

   Segue-se um exemplo de uma política no formato JSON:

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

   Segue-se um exemplo de uma política no formato YAML:

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

7. Gere uma chave para a conta de serviço:

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

   Substitua o seguinte:

   • SA_KEY_FILE: ficheiro no qual armazenar a chave da conta de serviço gerada.
   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.
   • CA_CERTIFICATE_FILE: o ficheiro de certificado da AC que criou anteriormente.

8. Imprima o token de identidade para a conta de serviço:

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

   Substitua o seguinte:

   • SA_KEY_FILE: o ficheiro de chave da conta de serviço que criou anteriormente.
   • ENDPOINT_URL: o URL totalmente qualificado do ponto final, incluindo o sufixo do TLD.

Liste os pontos finais da API Gemini on GDC associados implementados

Para listar o Gemini implementado nos pontos finais da API ligada do GDC, faça o seguinte:

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

Substitua o seguinte:

• PROJECT_ID: o ID do projeto Google Cloud de destino.
• REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.
• ZONE: a zona ligada do Distributed Cloud de destino.

Obtenha informações sobre um ponto final da API Gemini on GDC associado

Para obter informações sobre um ponto final da API Gemini on GDC connected implementado, faça o seguinte:

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

Substitua o seguinte:

• ENDPOINT_NAME: o nome do ponto final de destino.
• PROJECT_ID: o ID do projeto Google Cloud de destino.
• REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.

Interaja com um Gemini num ponto final da API do Google Distributed Cloud connected

O seu ponto final da API Gemini on GDC ligado suporta a interação através da API ChatCompletions e da API ListAvailableModels. Use estas APIs para interagir programaticamente com o seu ponto final.

Segue-se um exemplo de um pedido através da 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}"

Segue-se um exemplo de um pedido da API Chat Completions multimodal com um documento como entrada:

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

Este é um exemplo de um pedido da 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

Para mais informações sobre as cargas de trabalho adequadas para o Gemini na API Google Distributed Cloud connected, consulte a vista geral do Gemini.

Elimine um ponto final da API Gemini on Google Distributed Cloud connected

Para eliminar um ponto final da API Gemini on GDC connected, faça o seguinte:

1. Anule a implementação do modelo:

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

   Substitua o seguinte:

   • ENDPOINT_NAME: o nome do ponto final de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.
   • ZONE: a zona ligada do Distributed Cloud de destino.
   • MODEL_PUBLIC_ID: o ID público do modelo. Para ver uma lista dos modelos suportados, consulte o artigo Modelos suportados.

2. Elimine o ponto final:

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

   Substitua o seguinte:

   • PROJECT_ID: o nome do ponto final de destino.
   • REGION: a Google Cloud região na qual a zona conectada do Distributed Cloud de destino foi criada.

Resolva problemas de pontos finais

Se um ponto final da API do Gemini on GDC ligado ficar inativo, contacte o seu representante da Google para resolver o problema.