Acesso antecipado público do Gemini na API GDC conectada à GDC (atual)

Para informações sobre a versão, consulte as notas da versão do Gemini na API GDC no GDC Connected.

Versões disponíveis: Acesso antecipado

Esta página foi traduzida pela API Cloud Translation.

Criar e gerenciar endpoints

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 do GDC.

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:

Receba o nome do ID da organização Google Cloud de destino:
```
gcloud organizations list
```
Liste as zonas conectadas do Distributed Cloud na sua Google Cloud organização:
```
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.
Confira 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 público, 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 das API AI Platform e Vertex AI

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

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.

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 chamado CA_CERTIFICATE_FILE. Você vai usar esse arquivo mais tarde para gerar a chave da conta de serviço.

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 ao Gemini no GDC, faça o seguinte:

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 do Distributed Cloud de destino:
```
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 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 a seguir 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 da 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:
```
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 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 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 conectada do Gemini no GDC

Para receber informações sobre um endpoint de API conectado do Gemini no GDC 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 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 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="gemini-2.0-flash-001"
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:
- 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:

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

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

curl -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 da API multimodal `ChatCompletions`

Confira a seguir um exemplo de payload de solicitação de API ChatCompletions multimodal com um documento 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:

curl -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 da API `ListAllAvailableModels`

Confira a seguir um exemplo de solicitação da 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 conectada do Gemini no Google Distributed Cloud

Para excluir um endpoint de API conectada do Gemini no GDC, 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 conectada do Gemini no GDC ficar inativo, entre em contato com seu representante do Google para resolver o problema.

Criar e gerenciar endpoints Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Pré-requisitos

Conceder os papéis necessários

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

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

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

Configurar o endpoint para resolução de DNS

Implantar um endpoint de API conectado ao Gemini no GDC

Listar os endpoints de API conectados do Gemini implantados no GDC

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

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

Exemplo de solicitação da API multimodal ChatCompletions

Exemplo de solicitação da API ListAllAvailableModels

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

Resolver problemas de endpoints

Criar e gerenciar endpoints

Exemplo de solicitação da API multimodal `ChatCompletions`

Exemplo de solicitação da API `ListAllAvailableModels`