Nesta página, descrevemos como criar e gerenciar o Gemini em endpoints de API conectados do Google Distributed Cloud.
Pré-requisitos
Esta seção descreve as etapas únicas que você precisa concluir antes de implantar o Gemini nos endpoints de API conectados do GDC. Conclua as etapas na máquina de ativação.
Conclua as etapas desta seção usando uma conta de administrador de TI com o papel de Leitor da zona de contêineres de borda. Depois de concluir as etapas desta seção, forneça as informações coletadas, incluindo o certificado de CA e o endereço IP do servidor DNS ao administrador do projeto Google Cloud , que implanta o endpoint conforme descrito em Implantar um endpoint de API conectado do Gemini no GDC.
Concluir a ativação do hardware
Antes de concluir as etapas nesta página, você precisa:
Implante o hardware certificado pelo Google conforme descrito em Requisitos de instalação.
Trabalhe com seu representante do Google para criar os clusters conectados do Distributed Cloud necessários.
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 os papéis listados 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 do Distributed Cloud de destino
Para saber o nome da zona conectada de destino do Distributed Cloud, faça o seguinte:
Receba o nome do ID da organização Google Cloud de destino:
gcloud organizations list
Liste as zonas conectadas do Distributed Cloud na sua organização Google Cloud :
gcloud alpha zone-management zones list \ --organization ORGANIZATION_ID \ --location REGION
Substitua:
ORGANIZATION_ID: o ID da Google Cloud organização de destino.REGION: a região do Google Cloud em que a zona conectada do Distributed Cloud de destino foi criada. Durante o Acesso antecipado, a única região compatível éus-west2.
Receba informações detalhadas sobre a zona de destino:
gcloud alpha zone-management zones describe ZONE \ --organization ORGANIZATION_ID \ --location REGION
Substitua:
ZONE: a zona de destino do Distributed Cloud Connected.ORGANIZATION_ID: o ID da Google Cloud organização de destino.REGION: a região do Google Cloud em que a zona conectada do Distributed Cloud de destino foi criada. Durante o Acesso antecipado, a única região compatível éus-west2.
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:
Liste as máquinas conectadas do Distributed Cloud na zona conectada de destino do Distributed Cloud, conforme descrito em Listar máquinas em uma zona.
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
Use uma conta de administrador de TI com a função Administrador do projeto zonal do contêiner de borda para concluir as etapas desta seção.
Ative o projeto Google Cloud de destino na zona conectada do Distributed Cloud de destino:
gcloud alpha zone-management projects enable PROJECT_ID \ --organization ORGANIZATION_ID \ --location REGION \ --zone 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 região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.ZONE: a zona de destino do Distributed Cloud Connected.
Ative o serviço do AI Platform no projeto Google Cloud de destino:
gcloud services enable aiplatform.googleapis.com --project PROJECT_ID
Substitua
PROJECT_IDpelo ID do projeto Google Cloud de destino.Ative o serviço da API Vertex AI na zona conectada do Distributed Cloud:
gcloud alpha zone-management services enable vertex --project PROJECT_ID \ --location REGION \ --zone ZONE
Substitua:
PROJECT_ID: o ID do projeto Google Cloud de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.ZONE: a zona de destino do Distributed Cloud Connected.
Configurar o endpoint para resolução de DNS
Receba o endereço DNS gerenciado, o domínio de nível superior (TLD) e o certificado da autoridade de certificação (CA) para a zona conectada do Distributed Cloud de destino.
gcloud alpha zone-management zones describe ZONE \ --organization ORGANIZATION_ID \ --location REGION \ --format="value(certificateAuthorities)" \ > CA_CERTIFICATE_FILE
Substitua:
ORGANIZATION_ID: o ID da Google Cloud organização de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.ZONE: a zona de destino do Distributed Cloud Connected.CA_CERTIFICATE_FILE: o arquivo em que a saída de payload do certificado do comando é salva. Você vai usar esse arquivo mais tarde para gerar a chave da conta de serviço.
O comando retorna uma saída semelhante à seguinte, que é armazenada no arquivo:
-----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
Crie a configuração de DNS para o endpoint da seguinte maneira usando o endereço IP do servidor DNS e o nome do domínio de nível superior (TLD) obtidos na etapa anterior. É necessário executar esse comando em uma máquina que esteja na mesma rede local que a máquina certificada pela 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
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 Gemini on GDC connected
Para implantar um endpoint de API Gemini on GDC connected, faça o seguinte usando uma conta de administrador do projeto Google Cloud :
Crie o endpoint:
gcloud beta ai endpoints create \ --project=PROJECT_ID \ --region=REGION \ --gdc-zone=ZONE \ --display-name=ENDPOINT_NAME \ --endpoint-id=ENDPOINT_ID
Substitua:
PROJECT_ID: o ID do projeto Google Cloud de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.ZONE: a zona de destino do Distributed Cloud Connected.ENDPOINT_NAME: um nome significativo para esse endpoint.ENDPOINT_ID: (opcional) um identificador exclusivo para este endpoint. Se for omitido, um identificador aleatório será gerado.
Implante o modelo:
gcloud beta ai endpoints deploy-model ENDPOINT_ID \ --display-name=ENDPOINT_NAME \ --model=MODEL_PUBLIC_ID \ --region=REGION
Substitua:
ENDPOINT_ID: o ID do endpoint de destino.ENDPOINT_NAME: o nome do endpoint de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.MODEL_PUBLIC_ID: o ID público do modelo. Para uma lista de modelos compatíveis, consulte Modelos compatíveis.
Liste os endpoints implantados:
gcloud beta ai endpoints list \ --project=PROJECT_ID \ --region=REGION
Substitua:
PROJECT_ID: o ID do projeto Google Cloud de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.
Anote o ID do endpoint de destino.
Receba o endereço do endpoint:
gcloud beta ai endpoints describe ENDPOINT_ID \ --project=PROJECT_ID \ --region=REGION
Substitua:
ENDPOINT_ID: o ID do endpoint de destino.PROJECT_ID: o ID do projeto Google Cloud de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.
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. O nome precisa conter apenas letras minúsculas, números, "-" ou ".", além de começar e terminar com um caractere alfanumérico. Letras maiúsculas não são permitidas.PROJECT_ID: o ID do projeto Google Cloud de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.ZONE: a zona de destino do Distributed Cloud Connected.
Receba a política do Identity and Access Management para a 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 região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.
Atribua o papel Desenvolvedor do AI Platform à conta de serviço:
gcloud alpha zone-management zones set-iam-policy POLICY_FILE \ --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 região do Google Cloud em que a zona de destino do Distributed Cloud conectado 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/PROJECT_ID/locations/REGION/serviceAccounts/SERVICE_ACCOUNT" ] } ] "etag": ""Confira um exemplo de política no formato YAML:
bindings: - role: roles/aiplatform.geminiDeveloper members: - serviceAccount: projects/PROJECT_ID/locations/REGION/serviceAccounts/SERVICE_ACCOUNT etag: ""
Substitua:
PROJECT_ID: o ID do projeto Google Cloud de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.SERVICE_ACCOUNT: um nome significativo que identifica exclusivamente essa conta de serviço.
Gere uma chave para a conta de serviço:
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
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 região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.CA_CERTIFICATE_FILE: o arquivo de certificado de CA criado anteriormente.
Receba o URL totalmente qualificado do endpoint:
gcloud beta ai endpoints describe ENDPOINT_ID \ --project=PROJECT_ID \ --region=REGION
Imprima o token de identidade da conta de serviço. Execute esse comando em uma máquina que esteja na mesma rede local que a máquina certificada da API Gemini on GDC connected.
gcloud alpha zone-management auth print-identity-token \ --cred-file=SA_KEY_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 totalmente qualificado do endpoint, incluindo o sufixo do TLD.
Listar endpoints implantados da API Gemini on GDC connected
Para listar os endpoints implantados da API Gemini on GDC connected, faça o seguinte:
gcloud beta ai endpoints list \
--project=PROJECT_ID \
--region=REGION \
--gdc-zone=ZONE
Substitua:
PROJECT_ID: o ID do projeto Google Cloud de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.ZONE: a zona de destino do Distributed Cloud Connected.
Receber informações sobre um endpoint de API Gemini on GDC connected
Para informações sobre um endpoint de API Gemini on GDC connected implantado, faça o seguinte:
gcloud beta ai endpoints describe ENDPOINT_ID \
--project=PROJECT_ID \
--region=REGION
Substitua:
ENDPOINT_ID: o ID do endpoint de destino.PROJECT_ID: o ID do projeto Google Cloud de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.
Interagir com um endpoint de API Gemini on Google Distributed Cloud connected
O endpoint de API Gemini on GDC connected oferece suporte à interação pelas APIs ChatCompletions e ListAvailableModels. Use essas APIs para interagir de forma programática com seu endpoint.
Confira um exemplo de solicitação pela API ChatCompletions. O token de autenticação gerado
nesta solicitação é válido por 12 horas.
Defina as seguintes variáveis no seu ambiente 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"Substitua:
MODEL_NAME: o nome do modelo de destino.PROJECT_ID: o ID do projeto Google Cloud de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.SA_KEY_FILE: o arquivo de chave da conta de serviço que você criou anteriormente.
Imprima o token do portador. Execute esse comando em uma máquina que esteja na mesma rede local que a máquina certificada da 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_TOKENCrie o payload:
REQUEST_BODY=$(cat <<EOF { "model": "${MODEL_NAME}", "messages": [ { "role": "system", "content": "Pizza for everyone!" }, { "role": "user", "content": "${USER_CONTENT}" } ], "stream": false } EOF )Envie a solicitação para o endpoint. Execute esse comando em uma máquina que esteja na mesma rede local que a máquina certificada da 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}"
Exemplo de solicitação de API multimodal ChatCompletions com um payload de imagem JPEG
Confira a seguir um exemplo de payload de solicitação de API ChatCompletions multimodal com uma imagem JPEG como entrada:
Crie o 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 )Envie a solicitação para o endpoint. Execute esse comando em uma máquina que esteja na mesma rede local que a máquina certificada da 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}"
Exemplo de solicitação de API multimodal ChatCompletions com um payload de documento PDF
Confira a seguir um exemplo de payload de solicitação de API ChatCompletions multimodal com um documento PDF como entrada:
Crie o payload:
BASE64_PDF=$(base64 -w 0 PDF_FILE) REQUEST_BODY=$(cat <<EOF { "model": "${MODEL_NAME}", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Please summarize this document." }, { "type": "input_document", "input_document": { "data": "data:application/pdf;base64,${BASE64_PDF}", "format": "pdf" } } ] } ] } EOF )Envie a solicitação para o endpoint. Execute esse comando em uma máquina que esteja na mesma rede local que a máquina certificada da 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}"
Exemplo de solicitação de API multimodal ChatCompletions com um payload de áudio
Confira a seguir um exemplo de payload de solicitação de API ChatCompletions multimodal com um arquivo de áudio como entrada:
Crie o payload:
BASE64_AUDIO=$(base64 -w 0 AUDIO_FILE) REQUEST_BODY=$(cat <<EOF { "model": "${MODEL_NAME}", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Transcribe this speech for me." }, { "type": "input_audio", "input_audio": { "data": "data:audio/mp3;base64,${BASE64_AUDIO}", "format": "mp3" } } ] } ] } EOF )Envie a solicitação para o endpoint. Execute esse comando em uma máquina que esteja na mesma rede local que a máquina certificada da 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}"
Exemplo de solicitação de API multimodal ChatCompletions com um payload de vídeo
Confira a seguir um exemplo de payload de solicitação de API ChatCompletions multimodal com um arquivo de vídeo como entrada:
Crie o payload:
BASE64_VIDEO=$(base64 -w 0 VIDEO_FILE) REQUEST_BODY=$(cat <<EOF { "model": "${MODEL_NAME}", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Could you summarize this video for me?" }, { "type": "input_video", "input_video": { "data": "data:video/wmv;base64,${BASE64_VIDEO}", "format": "wmv" } } ] } ] } EOF )Envie a solicitação para o endpoint. Execute esse comando em uma máquina que esteja na mesma rede local que a máquina certificada da 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}"
Exemplo de solicitação de API ListAllAvailableModels
Confira a seguir um exemplo de solicitação de 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
Excluir um endpoint de API Gemini on Google Distributed Cloud connected
Para excluir um endpoint de API Gemini on GDC connected, faça o seguinte:
Remova a implantação do modelo:
gcloud beta ai endpoints undeploy-model ENDPOINT_ID \ --region=REGION \ --gdc-zone=ZONE \ --model=MODEL_PUBLIC_ID
Substitua:
ENDPOINT_ID: o ID do endpoint de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado 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.
Exclua o endpoint:
gcloud beta ai endpoints delete ENDPOINT_ID \ --project=PROJECT_ID \ --region=REGION
Substitua:
ENDPOINT_ID: o ID do endpoint de destino.PROJECT_ID: o nome do endpoint de destino.REGION: a região do Google Cloud em que a zona de destino do Distributed Cloud conectado foi criada.
Resolver problemas de endpoints
Se um endpoint de API Gemini on GDC connected ficar inativo, entre em contato com seu representante do Google para resolver o problema.