En esta página, se describe cómo crear y administrar extremos de la API de Gemini en Google Distributed Cloud conectado.
Se supone que implementaste correctamente el hardware certificado por Google, como se describe en los requisitos de instalación.
Requisitos previos
En esta sección, se describen los pasos únicos que debes completar antes de poder implementar los extremos de la API de Gemini en GDC conectado.
Otorga los roles necesarios
Debes configurar los siguientes roles obligatorios:
Para las cuentas que se usan para administrar tu implementación de la API de Gemini en GDC conectado, otorga los roles que se indican en Roles y permisos de la API de Distributed Cloud Edge Container.
Para las cuentas que se usan para interactuar con los extremos de la API de Gemini en GDC conectado, otorga los roles que se indican en Roles y permisos de la API de Vertex AI.
Obtén información sobre la zona conectada de Distributed Cloud de destino
Para obtener el nombre de la zona conectada de Distributed Cloud de destino, haz lo siguiente:
Obtén el nombre del ID de la organización Google Cloud objetivo:
gcloud organizations list
Enumera las zonas conectadas de Distributed Cloud en tu Google Cloud organización:
gcloud alpha zone-management zones list \ --organization ORGANIZATION_ID \ --location REGION
Reemplaza lo siguiente:
ORGANIZATION_ID: Es el ID de la organización Google Cloud objetivo.REGION: Es la Google Cloud región en la que se creó la zona conectada de Distributed Cloud de destino. Durante la versión preliminar pública, la única región admitida esus-west2.
Obtén información detallada sobre la zona objetivo:
gcloud alpha zone-management zones describe ZONE \ --organization ORGANIZATION_ID \ --location REGION
Reemplaza lo siguiente:
ZONE: Es la zona de Distributed Cloud conectada de destino.ORGANIZATION_ID: Es el ID de la organización Google Cloud objetivo.REGION: Es la Google Cloud región en la que se creó la zona conectada de Distributed Cloud de destino. Durante la versión preliminar pública, la única región admitida esus-west2.
Obtén información sobre las máquinas certificadas en tu zona conectada de Distributed Cloud
Para obtener los nombres de las máquinas certificadas de destino en tu zona conectada de Distributed Cloud, haz lo siguiente:
Enumera las máquinas conectadas de Distributed Cloud en la zona conectada de Distributed Cloud de destino, como se describe en Enumera las máquinas en una zona.
Obtén información detallada sobre la máquina de destino, como se describe en Cómo obtener información sobre una máquina.
Habilita los servicios locales de las API de AI Platform y Vertex AI
Habilita el proyecto Google Cloud de destino en tu zona conectada de Distributed Cloud de destino:
gcloud alpha zone-management projects enable PROJECT_ID \ --organization ORGANIZATION_ID \ --location REGION \ --zone ZONE
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto Google Cloud de destino.ORGANIZATION_ID: Es el ID de la organización Google Cloud objetivo.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.ZONE: Es la zona de Distributed Cloud conectada de destino.
Habilita el servicio de AI Platform en el proyecto Google Cloud de destino:
gcloud services enable aiplatform.googleapis.com --project PROJECT_ID
Reemplaza
PROJECT_IDpor el ID del proyecto Google Cloud de destino.Habilita el servicio de la API de Vertex AI en la zona conectada de Distributed Cloud:
gcloud alpha zone-management services enable vertex --project PROJECT_ID \ --location REGION \ --zone ZONE
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.ZONE: Es la zona de Distributed Cloud conectada de destino.
Configura el extremo para la resolución de DNS
Obtén la dirección DNS administrada, el dominio de nivel superior (TLD) y el certificado de la autoridad certificadora (CA) para la zona conectada de Distributed Cloud de destino:
gcloud alpha zone-management zones describe ZONE \ --organization ORGANIZATION_ID \ --location REGION
Reemplaza lo siguiente:
ORGANIZATION_ID: Es el ID de la organización Google Cloud objetivo.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.ZONE: Es la zona de Distributed Cloud conectada de destino.
En el siguiente ejemplo, se ilustra el resultado de este 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_RUNNINGAlmacena el certificado en un archivo llamado
CA_CERTIFICATE_FILE. Usarás este archivo más adelante para generar la clave de la cuenta de servicio.Crea la configuración de DNS para el extremo de la siguiente manera:
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
Reemplaza lo siguiente:
DNS_SERVER_ADDRESS: La dirección IP de tu servidor DNS.TOP_LEVEL_DOMAIN: Es el dominio de nivel superior del extremo.
Implementa un extremo de Gemini en la API de GDC conectado
Para implementar un extremo de Gemini en la API de GDC conectado, haz lo siguiente:
Crea el extremo:
gcloud beta ai endpoints create \ --project=PROJECT_ID \ --region=REGION \ --gdc-zone=ZONE \ --display-name=ENDPOINT_NAME \ --endpoint-id=ENDPOINT_ID
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.ZONE: Es la zona de Distributed Cloud conectada de destino.ENDPOINT_NAME: Un nombre significativo para este extremo.ENDPOINT_ID: (opcional) Es un identificador único para este extremo. Si se omite, se genera un identificador aleatorio.
Implementa el modelo:
gcloud beta ai endpoints deploy-model ENDPOINT_ID \ --display-name=ENDPOINT_NAME \ --model=MODEL_PUBLIC_ID \ --region=REGION
Reemplaza lo siguiente:
ENDPOINT_ID: Es el ID del extremo de destino.ENDPOINT_NAME: Es el nombre del extremo de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.MODEL_PUBLIC_ID: Es el ID público del modelo. Para obtener una lista de los modelos compatibles, consulta Modelos compatibles.
Enumera los extremos implementados:
gcloud beta ai endpoints list \ --project=PROJECT_ID \ --region=REGION
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.
Toma nota del ID del extremo de destino.
Obtén la dirección del extremo:
gcloud beta ai endpoints describe ENDPOINT_ID \ --project=PROJECT_ID \ --region=REGION
Reemplaza lo siguiente:
ENDPOINT_ID: Es el ID del extremo de destino.PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.
Crea la cuenta de servicio para el extremo en la zona conectada de Distributed Cloud de destino:
gcloud alpha zone-management service-accounts create SERVICE_ACCOUNT \ --project PROJECT_ID \ --location REGION \ --zone ZONE
Reemplaza lo siguiente:
SERVICE_ACCOUNT: Es un nombre significativo que identifica de forma única a esta cuenta de servicio.PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.ZONE: Es la zona de Distributed Cloud conectada de destino.
Obtén la política de Identity and Access Management para la zona conectada de Distributed Cloud de destino:
gcloud alpha zone-management zones get-iam-policy ZONE \ --project PROJECT_ID \ --location REGION
Reemplaza lo siguiente:
ZONE: Es la zona de Distributed Cloud conectada de destino.PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.
Asigna el rol de Desarrollador de AI Platform a la cuenta de servicio:
gcloud alpha zone-management zones set-iam-policy POLICY_FILE \ --project PROJECT_ID \ --location REGION \ --zone ZONE
Reemplaza lo siguiente:
POLICY_FILE: Archivo JSON o YAML que contiene la política de asignación de roles.PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.ZONE: Es la zona de Distributed Cloud conectada de destino.
A continuación, se muestra un ejemplo de política en formato JSON:
"bindings": [ { "role": "roles/aiplatform.geminiDeveloper", "members": [ "serviceAccount": "projects/PROJECT_ID/locations/REGION/serviceAccounts/SERVICE_ACCOUNT" ] } ] "etag": ""A continuación, se muestra un ejemplo de política en formato YAML:
bindings: - role: roles/aiplatform.geminiDeveloper members: - serviceAccount: projects/PROJECT_ID/locations/REGION/serviceAccounts/SERVICE_ACCOUNT etag: ""
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.SERVICE_ACCOUNT: Es un nombre significativo que identifica de forma única esta cuenta de servicio.
Genera una clave para la cuenta de servicio:
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
Reemplaza lo siguiente:
SA_KEY_FILE: Es el archivo en el que se almacenará la clave de la cuenta de servicio generada.PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.CA_CERTIFICATE_FILE: Es el archivo de certificado de CA que creaste antes.
Obtén la URL completamente calificada del extremo:
gcloud beta ai endpoints describe ENDPOINT_ID \ --project=PROJECT_ID \ --region=REGION
Imprime el token de identidad de la cuenta de servicio:
gcloud alpha zone-management auth print-identity-token \ --cred-file=SA_KEY_FILE \ --audience=ENDPOINT_URL
Reemplaza lo siguiente:
SA_KEY_FILE: Es el archivo de claves de la cuenta de servicio que creaste antes.ENDPOINT_URL: Es la URL completamente calificada del extremo, incluido el sufijo del TLD.
Enumera los extremos de Gemini en la API de GDC conectado implementados
Para enumerar los extremos de la API de Gemini en GDC conectado que implementaste, haz lo siguiente:
gcloud beta ai endpoints list \
--project=PROJECT_ID \
--region=REGION \
--gdc-zone=ZONE
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.ZONE: Es la zona de Distributed Cloud conectada de destino.
Obtén información sobre un extremo de Gemini en la API de GDC conectado
Para obtener información sobre un extremo de Gemini en la API de GDC conectado implementado, haz lo siguiente:
gcloud beta ai endpoints describe ENDPOINT_ID \
--project=PROJECT_ID \
--region=REGION
Reemplaza lo siguiente:
ENDPOINT_ID: Es el ID del extremo de destino.PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.
Interactúa con un extremo de API de Gemini en Google Distributed Cloud conectado
Tu extremo de API de Gemini conectado a GDC admite la interacción a través de las APIs de ChatCompletions y ListAvailableModels. Usa estas APIs para interactuar de forma programática con tu extremo.
Este es un ejemplo de una solicitud a través de la API de ChatCompletions. El token de portador generado en esta solicitud es válido durante 12 horas.
Establece las siguientes variables en tu entorno de 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"Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto Google Cloud de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.SA_KEY_FILE: Es el archivo de claves de la cuenta de servicio que creaste antes.
Imprime el token del portador:
BEARER_TOKEN=$(gcloud alpha zone-management auth print-identity-token --cred-file="${CRED_FILE}" --audience="https://${IG_FQDN}") echo $BEARER_TOKENCompila la carga útil:
REQUEST_BODY=$(cat <<EOF { "model": "${MODEL_NAME}", "messages": [ { "role": "system", "content": "Pizza for everyone!" }, { "role": "user", "content": "${USER_CONTENT}" } ], "stream": false } EOF )Envía la solicitud al extremo:
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}"
Ejemplo de solicitud a la API de ChatCompletions multimodal
A continuación, se muestra un ejemplo de una carga útil de solicitud a la API de ChatCompletions multimodal con un documento como entrada:
Compila la carga útil:
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 )Envía la solicitud al extremo:
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}"
Ejemplo de solicitud a la API de ListAllAvailableModels
A continuación, se muestra un ejemplo de una solicitud a la API de 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
Borra un extremo de API de Gemini en Google Distributed Cloud conectado
Para borrar un extremo de API de Gemini en GDC conectado, haz lo siguiente:
Anula la implementación del modelo:
gcloud beta ai endpoints undeploy-model ENDPOINT_ID \ --region=REGION \ --gdc-zone=ZONE \ --model=MODEL_PUBLIC_ID
Reemplaza lo siguiente:
ENDPOINT_ID: Es el ID del extremo de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.ZONE: Es la zona de Distributed Cloud conectada de destino.MODEL_PUBLIC_ID: Es el ID público del modelo. Para obtener una lista de los modelos compatibles, consulta Modelos compatibles.
Borra el extremo:
gcloud beta ai endpoints delete ENDPOINT_ID \ --project=PROJECT_ID \ --region=REGION
Reemplaza lo siguiente:
ENDPOINT_ID: Es el ID del extremo de destino.PROJECT_ID: Es el nombre del extremo de destino.REGION: Es la Google Cloud región en la que se creó la zona de Distributed Cloud conectada de destino.
Soluciona problemas relacionados con los extremos
Si tu extremo de API de Gemini en GDC conectado deja de funcionar, comunícate con tu representante de Google para solucionar el problema.