Crear y gestionar endpoints

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

En esta página se describe cómo crear y gestionar endpoints de API conectados de Gemini en Google Distributed Cloud.

Se presupone que has implementado correctamente el hardware certificado por Google, tal como se describe en los requisitos de instalación.

Requisitos previos

En esta sección se describen los pasos que debes completar una sola vez antes de poder implementar Gemini en los endpoints de la API conectada de GDC.

Asigna los roles necesarios

Debes configurar los siguientes roles obligatorios:

• En las cuentas que se usan para gestionar tu implementación de la API conectada de Gemini en GDC, otorga los roles que se indican en Roles y permisos de la API de contenedor de Distributed Cloud Edge.

• En las cuentas que se usen para interactuar con Gemini en los endpoints de API conectados a GDC, concede los roles que se indican en Roles y permisos de la API de Vertex AI.

Obtener información sobre la zona de Distributed Cloud conectada de destino

Para obtener el nombre de tu zona conectada de Distributed Cloud de destino, haz lo siguiente:

1. Obtén el nombre del ID de la organización de destino: Google Cloud

   gcloud organizations list
   

2. Lista las zonas conectadas de Distributed Cloud de tu Google Cloud organización:

   gcloud alpha zone-management zones list \
      --organization ORGANIZATION_ID \
      --location REGION
   

   Haz los cambios siguientes:

   • ORGANIZATION_ID: el ID de la organización de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino. Durante la Vista Previa Pública, la única región admitida es us-west2.

3. Obtén información detallada sobre la zona de destino:

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

   Haz los cambios siguientes:

   • ZONE: la zona de Distributed Cloud conectada de destino.
   • ORGANIZATION_ID: el ID de la organización de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino. Durante la Vista Previa Pública, la única región admitida es us-west2.

Obtener información sobre las máquinas certificadas de tu zona de Distributed Cloud conectada

Para obtener los nombres de las máquinas certificadas de destino en tu zona conectada de Distributed Cloud, haz lo siguiente:

1. Enumera las máquinas conectadas de Distributed Cloud en la zona conectada de Distributed Cloud de destino, tal como se describe en Listar máquinas de una zona.

2. Obtén información detallada sobre el equipo de destino, tal como se describe en Obtener información sobre un equipo.

Habilita los servicios de las APIs de AI Platform y Vertex AI locales

1. Habilita el proyecto de destino Google Cloud en tu zona de Distributed Cloud conectada de destino:

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

   Haz los cambios siguientes:

   • PROJECT_ID: el ID del proyecto de destino. Google Cloud
   • ORGANIZATION_ID: el ID de la organización de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
   • ZONE: la zona de Distributed Cloud conectada de destino.

2. Habilita el servicio AI Platform en el proyecto de destino: Google Cloud

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

   Sustituye PROJECT_ID por el ID del proyecto de destino. Google Cloud

3. Habilita el servicio de la API Vertex AI en la zona conectada de Distributed Cloud:

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

   Haz los cambios siguientes:

   • PROJECT_ID: el ID del proyecto de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
   • ZONE: la zona de Distributed Cloud conectada de destino.

Configurar el endpoint para la resolución de DNS

1. Obtén la dirección DNS gestionada, el dominio de nivel superior (TLD) y el certificado de la autoridad de certificación (CA) de la zona conectada de Distributed Cloud de destino:

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

   Haz los cambios siguientes:

   • ORGANIZATION_ID: el ID de la organización de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
   • ZONE: la zona de Distributed Cloud conectada de destino.

   En el siguiente ejemplo se muestra 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_RUNNING
   

   Guarda 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.

2. Crea la configuración de DNS del endpoint 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
   

   Haz los cambios siguientes:

   • DNS_SERVER_ADDRESS: la dirección IP de tu servidor DNS.
   • TOP_LEVEL_DOMAIN: el dominio de nivel superior del endpoint.

Desplegar una API de Gemini en un endpoint de API conectado a GDC

Para implementar un endpoint de API conectado a Gemini en GDC, haz lo siguiente:

1. Crea el endpoint:

   gcloud beta ai endpoints create \
      --project=PROJECT_ID \
      --region=REGION \
      --gdc-zone=ZONE \
      --display-name=ENDPOINT_NAME \
      --endpoint-id=ENDPOINT_ID
   

   Haz los cambios siguientes:

   • PROJECT_ID: el ID del proyecto de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
   • ZONE: la zona de Distributed Cloud conectada de destino.
   • ENDPOINT_NAME: un nombre significativo para este endpoint.
   • ENDPOINT_ID: (opcional) identificador único de este endpoint. Si se omite, se genera un identificador aleatorio.

2. Despliega el modelo:

   gcloud beta ai endpoints deploy-model ENDPOINT_ID \
     --display-name=ENDPOINT_NAME \
     --model=MODEL_PUBLIC_ID \
     --region=REGION
   

   Haz los cambios siguientes:

   • ENDPOINT_ID: el ID del endpoint de destino.
   • ENDPOINT_NAME: el nombre del endpoint de destino.
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
   • MODEL_PUBLIC_ID: el ID público del modelo. Para ver una lista de los modelos compatibles, consulta Modelos compatibles.

3. Lista los endpoints implementados:

   gcloud beta ai endpoints list \
     --project=PROJECT_ID \
     --region=REGION
   

   Haz los cambios siguientes:

   • PROJECT_ID: el ID del proyecto de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.

   Anota el ID del endpoint de destino.

4. Obtén la dirección del endpoint:

   gcloud beta ai endpoints describe ENDPOINT_ID \
     --project=PROJECT_ID \
     --region=REGION
   

   Haz los cambios siguientes:

   • ENDPOINT_ID: el ID del endpoint de destino.
   • PROJECT_ID: el ID del proyecto de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.

5. Crea la cuenta de servicio del endpoint 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
   

   Haz los cambios siguientes:

   • SERVICE_ACCOUNT: un nombre significativo que identifique de forma única a esta cuenta de servicio.
   • PROJECT_ID: el ID del proyecto de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
   • ZONE: la zona de Distributed Cloud conectada de destino.

6. Obtén la política de Gestión de Identidades y Accesos de la zona conectada de Distributed Cloud de destino:

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

   Haz los cambios siguientes:

   • ZONE: la zona de Distributed Cloud conectada de destino.
   • PROJECT_ID: el ID del proyecto de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.

7. Asigna el rol 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
   

   Haz los cambios siguientes:

   • POLICY_FILE: archivo JSON o YAML que contiene la política de asignación de roles.
   • PROJECT_ID: el ID del proyecto de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
   • ZONE: 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: ""
   

   Haz los cambios siguientes:

   • PROJECT_ID: el ID del proyecto de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
   • SERVICE_ACCOUNT: un nombre significativo que identifique de forma única a esta cuenta de servicio.

8. 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
   

   Haz los cambios siguientes:

   • SA_KEY_FILE: archivo en el que se almacenará la clave de la cuenta de servicio generada.
   • PROJECT_ID: el ID del proyecto de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
   • CA_CERTIFICATE_FILE: el archivo de certificado de AC que has creado antes.

9. Obtén la URL completa del endpoint:

   gcloud beta ai endpoints describe ENDPOINT_ID \
     --project=PROJECT_ID \
     --region=REGION
   

10. 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
    

    Haz los cambios siguientes:

    • SA_KEY_FILE: el archivo de clave de cuenta de servicio que has creado anteriormente.
    • ENDPOINT_URL: la URL completa del endpoint, incluido el sufijo de TLD.

Listar los modelos de Gemini implementados en los endpoints de API conectados de GDC

Para mostrar tu Gemini implementado en los endpoints de API conectados a GDC, haz lo siguiente:

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

Haz los cambios siguientes:

• PROJECT_ID: el ID del proyecto de destino. Google Cloud
• REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
• ZONE: la zona de Distributed Cloud conectada de destino.

Obtener información sobre un endpoint de API de Gemini en GDC conectado

Para obtener información sobre un endpoint de API de Gemini implementado en GDC conectado, haz lo siguiente:

gcloud beta ai endpoints describe ENDPOINT_ID \
    --project=PROJECT_ID \
    --region=REGION
   

Haz los cambios siguientes:

• ENDPOINT_ID: el ID del endpoint de destino.
• PROJECT_ID: el ID del proyecto de destino. Google Cloud
• REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.

Interactuar con un endpoint de API de Gemini en Google Distributed Cloud conectado

Tu endpoint de API conectado de Gemini en GDC admite la interacción a través de la API ChatCompletions y la API ListAvailableModels. Usa estas APIs para interactuar de forma programática con tu endpoint.

A continuación, se muestra un ejemplo de una solicitud a través de la API ChatCompletions. El token de portador generado en esta solicitud es válido durante 12 horas.

1. Define 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"
   

   Haz los cambios siguientes:

   • PROJECT_ID: el ID del proyecto de destino. Google Cloud
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
   • SA_KEY_FILE: el archivo de clave de cuenta de servicio que has creado anteriormente.

2. Imprime el token de portador:

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

3. Crea 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
   )
   

4. Envía la solicitud al 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}"
   

Ejemplo de solicitud a la API ChatCompletions multimodal

A continuación se muestra un ejemplo de una carga útil de solicitud de la API ChatCompletions multimodal con un documento como entrada:

1. Crea 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
   
   )
   

2. Envía la solicitud al 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}"
   

Ejemplo de solicitud a la API ListAllAvailableModels

A continuación, se muestra un ejemplo de solicitud de la 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

Eliminar un endpoint de API de Gemini en Google Distributed Cloud connected

Para eliminar un Gemini en un endpoint de API conectado a GDC, sigue estos pasos:

1. Anula el despliegue del modelo:

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

   Haz los cambios siguientes:

   • ENDPOINT_ID: el ID del endpoint de destino.
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.
   • ZONE: la zona de Distributed Cloud conectada de destino.
   • MODEL_PUBLIC_ID: el ID público del modelo. Para ver una lista de los modelos compatibles, consulta Modelos compatibles.

2. Elimina el endpoint:

   gcloud beta ai endpoints delete ENDPOINT_ID \
      --project=PROJECT_ID \
      --region=REGION
   

   Haz los cambios siguientes:

   • ENDPOINT_ID: el ID del endpoint de destino.
   • PROJECT_ID: el nombre del endpoint de destino.
   • REGION: la Google Cloud región en la que se ha creado la zona de Distributed Cloud conectada de destino.

Solucionar problemas con los endpoints

Si se produce una interrupción en el endpoint de la API conectada de Gemini en GDC, ponte en contacto con tu representante de Google para solucionar el problema.