Crea y administra extremos

Vista previa

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “tal cual” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

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

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 implementar Gemini en los extremos de la API conectados a GDC.

Habilite las API necesarias

Debes habilitar las siguientes APIs en tu proyecto Google Cloud de destino:

• 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 obtener información sobre cómo habilitar las APIs, consulta Habilita servicios.

Otorga los roles necesarios

Debes configurar los siguientes roles obligatorios:

• Para las cuentas que se usan para administrar la implementación de la API conectada de Gemini on GDC, 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 Gemini en los extremos de la API conectados a GDC, 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:

1. Enumera las zonas conectadas de Distributed Cloud en tu proyecto Google Cloud como se describe en Enumera zonas.

2. Obtén información detallada sobre la zona objetivo, como se describe en Cómo obtener información sobre una zona.

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:

1. Enumera las máquinas conectadas de Distributed Cloud en la zona conectada de Distributed Cloud de destino, como se describe en Cómo enumerar máquinas en una zona.

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

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

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

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID del proyecto Google Cloud de destino.
   • ORGANIZATION_ID: Es el ID de la Google Cloud organizaciónORGANIZATION_IDobjetivo.
   • 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.

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

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

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

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

   gcloud zone-management services enable vertex --project PROJECT_ID \
      --location REGION \
      --zones 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

1. Obtén la dirección de DNS administrado, 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 Google Cloud organizaciónORGANIZATION_IDobjetivo.
   • 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_RUNNING
   

   Almacena el certificado en un archivo. Usarás este archivo en los próximos pasos.

2. 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: Es la dirección IP de tu servidor DNS.
   • TOP_LEVEL_DOMAIN: Es el dominio de nivel superior del extremo.

Implementa un extremo de API conectado a Gemini on GDC

Para implementar un extremo de API conectado a Gemini on GDC, haz lo siguiente:

1. Crea el extremo:

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

   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: Es un nombre significativo que identifica de forma única este extremo.

2. Implementa el modelo:

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

   Reemplaza lo siguiente:

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

3. Obtén la dirección del extremo:

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

   Reemplaza lo siguiente:

   • ENDPOINT_NAME: Es el nombre 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.

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

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

6. Asigna el rol de Desarrollador de AI Platform a la cuenta de servicio:

   gcloud alpha zone-management zones set-iam-policy  \
     --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/my-project/locations/my-region/serviceAccounts/my-service-account"
         ]
      }
   ],
   "etag": ""
   

   A continuación, se muestra un ejemplo de política en formato YAML:

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

7. Genera una clave para la cuenta de servicio:

   gcloud alpha zone-management service-accounts keys create  \
      --service-account  \
      --project  \
      --location  \
      --ca-cert-path 
   

   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.

8. Imprime el token de identidad de la cuenta de servicio:

   gcloud alpha zone-management auth print-identity-token \
     --cred-file=SA_CREDENTIAL_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 API conectados de Gemini en GDC implementados

Para enumerar los extremos de API conectados de Gemini on GDC que implementaste, haz lo siguiente:

gcloud 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 API de Gemini on GDC connected

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

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

Reemplaza lo siguiente:

• ENDPOINT_NAME: Es el nombre 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 on Google Distributed Cloud connected

Tu extremo de API de Gemini on GDC Connected 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.

A continuación, se muestra un ejemplo de una solicitud a través de la API de 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}"

A continuación, se muestra un ejemplo de una solicitud a la API de Chat Completions multimodal con un 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 es un ejemplo de una solicitud a la API de 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 obtener más información sobre las cargas de trabajo adecuadas para la API de Gemini en Google Distributed Cloud conectado, consulta la Descripción general de Gemini.

Borra un extremo de API de Gemini on Google Distributed Cloud connected

Para borrar un extremo de API conectado de Gemini on GDC, haz lo siguiente:

1. Anula la implementación del modelo:

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

   Reemplaza lo siguiente:

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

2. Borra el extremo:

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

   Reemplaza lo siguiente:

   • 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 se interrumpe el funcionamiento de un extremo de API conectado a Gemini en GDC, comunícate con tu representante de Google para solucionar el problema.