Criar e gerenciar endpoints

Prévia

Este recurso está sujeito aos "Termos das Soluções Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições das fases de lançamento.

Nesta página, descrevemos como criar e gerenciar endpoints de API conectados do Gemini no Google Distributed Cloud.

Ele pressupõe que você implantou o hardware certificado pelo Google conforme descrito em Requisitos de instalação.

Pré-requisitos

Esta seção descreve as etapas únicas que você precisa concluir antes de implantar o Gemini nos endpoints de API conectados ao GDC.

Ative as APIs necessárias

Ative as seguintes APIs no projeto de destino Google Cloud :

• 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 informações sobre como ativar APIs, consulte Como ativar serviços.

Conceder os papéis necessários

Você precisa configurar os seguintes papéis obrigatórios:

• Para contas usadas no gerenciamento da implantação da API conectada do Gemini no GDC, conceda as funções listadas em Funções e permissões da API Distributed Cloud Edge Container.

• Para contas usadas para interagir com o Gemini em endpoints de API conectados ao GDC, conceda os papéis listados em Papéis e permissões da API Vertex AI.

Receber informações sobre a zona conectada de destino do Distributed Cloud

Para saber o nome da zona conectada de destino da nuvem distribuída, faça o seguinte:

1. Liste as zonas conectadas da nuvem distribuída no projeto Google Cloud , conforme descrito em Listar zonas.

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

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

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

1. Liste as máquinas conectadas da nuvem distribuída na zona conectada de destino da nuvem distribuída, conforme descrito em Listar máquinas em uma zona.

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

Ativar os serviços locais da API AI Platform e da API Vertex AI

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

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

   Substitua:

   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • ORGANIZATION_ID: o ID da Google Cloud organização de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.
   • ZONE: a zona de destino do Distributed Cloud Connected.

2. Ative o serviço do 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 conectada do Distributed Cloud:

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

   Substitua:

   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.
   • ZONE: a zona de destino do Distributed Cloud Connected.

Configurar o endpoint para resolução de DNS

1. Receba o endereço DNS gerenciado, o domínio de nível superior (TLD) e o certificado da autoridade certificadora (CA) para a zona conectada do Distributed Cloud de destino:

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

   Substitua:

   • ORGANIZATION_ID: o ID da Google Cloud organização de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.
   • ZONE: a zona de destino do Distributed Cloud Connected.

   O exemplo a seguir ilustra a saída desse 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 em um arquivo. Você vai usar esse arquivo nas próximas etapas.

2. Crie a configuração de DNS para o endpoint da seguinte maneira:

   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:

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

Implantar um endpoint de API conectado ao Gemini no GDC

Para implantar um endpoint de API conectado do Gemini no GDC, faça o seguinte:

1. Crie o endpoint:

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

   Substitua:

   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.
   • ZONE: a zona de destino do Distributed Cloud Connected.
   • ENDPOINT_NAME: um nome significativo que identifica exclusivamente esse endpoint.

2. Implante o modelo:

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

   Substitua:

   • ENDPOINT_NAME: o nome do endpoint de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.
   • ZONE: a zona de destino do Distributed Cloud Connected.
   • MODEL_PUBLIC_ID: o ID público do modelo. Para uma lista de modelos compatíveis, consulte Modelos compatíveis.

3. Receba o endereço do endpoint:

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

   Substitua:

   • ENDPOINT_NAME: o nome do endpoint de destino.
   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.

4. Crie a conta de serviço para o endpoint na zona conectada de destino do Distributed Cloud:

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

   Substitua:

   • SERVICE_ACCOUNT: um nome significativo que identifica exclusivamente essa conta de serviço.
   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.
   • ZONE: a zona de destino do Distributed Cloud Connected.

5. Receba a política do Identity and Access Management da zona conectada do Distributed Cloud de destino:

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

   Substitua:

   • ZONE: a zona de destino do Distributed Cloud Connected.
   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.

6. Atribua o papel Desenvolvedor do AI Platform à conta de serviço:

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

   Substitua:

   • POLICY_FILE: arquivo JSON ou YAML que contém a política de atribuição de função.
   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.
   • ZONE: a zona de destino do Distributed Cloud Connected.

   Confira a seguir um exemplo de política no formato JSON:

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

   Confira a seguir um exemplo de 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:

   • SA_KEY_FILE: arquivo em que a chave da conta de serviço gerada será armazenada.
   • PROJECT_ID: o ID do projeto Google Cloud de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.
   • CA_CERTIFICATE_FILE: o arquivo de certificado da CA criado anteriormente.

8. Imprima o token de identidade da conta de serviço:

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

   Substitua:

   • SA_KEY_FILE: o arquivo de chave da conta de serviço que você criou anteriormente.
   • ENDPOINT_URL: o URL completo do endpoint, incluindo o sufixo do TLD.

Listar os endpoints de API conectados do Gemini implantados no GDC

Para listar os endpoints de API conectados do Gemini implantados no GDC, faça o seguinte:

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

Substitua:

• PROJECT_ID: o ID do projeto Google Cloud de destino.
• REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.
• ZONE: a zona de destino do Distributed Cloud Connected.

Receber informações sobre um endpoint de API Gemini no GDC conectado

Para informações sobre um endpoint de API conectada do Gemini no GDC implantado, faça o seguinte:

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

Substitua:

• ENDPOINT_NAME: o nome do endpoint de destino.
• PROJECT_ID: o ID do projeto Google Cloud de destino.
• REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.

Interagir com um Gemini em um endpoint de API do Google Distributed Cloud Connected

Endpoint de API conectada do Gemini no GDC é compatível com a interação pelas APIs ChatCompletions e ListAvailableModels. Use essas APIs para interagir de maneira programática com seu endpoint.

Confira um exemplo de solicitação usando a 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}"

Confira um exemplo de solicitação 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 solicitação 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 conectada do Google Distributed Cloud, consulte Visão geral do Gemini.

Excluir um endpoint de API conectada do Gemini no Google Distributed Cloud

Para excluir um endpoint de API conectada do Gemini no GDC, faça o seguinte:

1. Remova a implantação do modelo:

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

   Substitua:

   • ENDPOINT_NAME: o nome do endpoint de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.
   • ZONE: a zona de destino do Distributed Cloud Connected.
   • MODEL_PUBLIC_ID: o ID público do modelo. Para uma lista de modelos compatíveis, consulte Modelos compatíveis.

2. Exclua o endpoint:

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

   Substitua:

   • PROJECT_ID: o nome do endpoint de destino.
   • REGION: a Google Cloud região em que a zona de destino do Distributed Cloud Connected foi criada.

Resolver problemas de endpoints

Se um endpoint de API conectada do Gemini no GDC ficar inativo, entre em contato com seu representante do Google para resolver o problema.