Ejecución de Claude en Google Cloud Vertex AI: Cuotas y Cuentas de Servicio

Google Cloud Vertex AI pone Claude detrás de tu proyecto GCP existente: una cuenta de servicio autentica las llamadas, la cuota del proyecto limita cuánto tráfico puedes enviar y un punto de conexión regional decide dónde se ejecuta realmente la inferencia.

Resumen

Vertex AI se autentica de manera diferente a la API directa de Anthropic y a Amazon Bedrock: no hay ninguna clave API, solo las Credenciales Predeterminadas de Aplicación de Google resueltas a través de una cuenta de servicio.

Tres cosas deben existir antes de que una llamada tenga éxito: una cuenta de servicio con el rol IAM correcto, la API de Vertex AI habilitada con suficiente cuota en el proyecto y una elección deliberada de región en lugar de un valor predeterminado asumido.

La falta de cualquiera de esas tres produce un error de permiso o cuota que parece un error del SDK, pero en realidad es una brecha de aprovisionamiento, la misma forma de fallo que una cuenta de Bedrock no aprovisionada.

Esta página cubre la configuración de la cuenta de servicio, la solicitud y el monitoreo de cuotas, y la elección entre una región específica y el enrutamiento global de Vertex AI, luego muestra la forma de solicitud que el código de aplicación realmente utiliza.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

from anthropic import AnthropicVertex
 
client = AnthropicVertex(project_id="mi-proyecto-gcp", region="us-east5")
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Resume este ticket en una frase."}],
)
print(response.content[0].text)

Cuándo usar esto:

Tu organización ya ejecuta cargas de trabajo de producción en Google Cloud y quiere que el uso de Claude fluya a través de la gestión de identidades y accesos (IAM) y la facturación existentes.
Necesitas que el tráfico de Claude permanezca dentro de una red administrada por GCP y un límite de cumplimiento.
Quieres que el gasto de Claude cuente contra un descuento por uso comprometido existente de Google Cloud.
Estás integrando Claude en un servicio que ya autentica otras APIs de GCP a través de una cuenta de servicio.

Ejemplo de Trabajo

import os
from anthropic import AnthropicVertex
import anthropic
 
# project_id y region son ambos requeridos - no hay proyecto ni región predeterminados.
client = AnthropicVertex(
    project_id=os.environ["GCP_PROJECT_ID"],
    region=os.environ.get("GCP_REGION", "us-east5"),
)
 
 
def summarize_ticket(ticket_text: str) -> str:
    """Llama a Claude en Vertex AI y devuelve un resumen de una frase.
 
    Asume que las Credenciales Predeterminadas de Aplicación se resuelven a una cuenta de servicio
    con el rol de Usuario de Vertex AI, y que el proyecto tiene cuota para
    claude-sonnet-5 en la región de destino.
    """
    try:
        response = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=200,
            messages=[
                {
                    "role": "user",
                    "content": f"Resume este ticket de soporte en una frase:\n\n{ticket_text}",
                }
            ],
        )
        return response.content[0].text
    except anthropic.PermissionDeniedError:
        raise RuntimeError(
            "La cuenta de servicio carece del rol de Usuario de Vertex AI, o la API de Vertex AI "
            "no está habilitada en este proyecto."
        )
    except anthropic.RateLimitError:
        raise RuntimeError(
            "Cuota del proyecto excedida para este modelo y región - solicita un "
            "aumento de cuota en la consola de Google Cloud."
        )
 
 
if __name__ == "__main__":
    ticket = "El cliente informa que la página de inicio de sesión devuelve un error 500 después del último despliegue."
    print(summarize_ticket(ticket))

Lo que esto demuestra:

AnthropicVertex toma project_id y region como argumentos de constructor requeridos; ninguno tiene un valor predeterminado, a diferencia del cliente de la API directa que no tiene argumentos.
La autenticación es completamente a través de Credenciales Predeterminadas de Aplicación; no hay ninguna clave API de Anthropic en ningún lugar de este código.
Capturar PermissionDeniedError y RateLimitError por separado convierte los dos fallos más comunes al desplegar por primera vez (rol IAM faltante, cuota agotada) en un mensaje procesable.

Inmersión Profunda

Cómo Funciona

Cada solicitud de Vertex AI se autentica como una cuenta de servicio a través de la cadena de Credenciales Predeterminadas de Aplicación de Google: localmente se resuelve a través de gcloud auth application-default login, y en producción se resuelve a través de la cuenta de servicio adjunta al entorno de cómputo (una instancia de GCE, un servicio de Cloud Run o una vinculación de identidad de carga de trabajo de GKE).
La cuenta de servicio necesita el rol IAM Usuario de Vertex AI (o un rol personalizado equivalente con los permisos correspondientes) vinculado a nivel de proyecto o de recurso antes de que cualquier llamada tenga éxito.
Habilitar la API de Vertex AI en el proyecto es un paso separado de la vinculación IAM: una cuenta de servicio con el rol correcto aún falla si la API en sí nunca se habilitó para ese proyecto.
La cuota se rastrea por proyecto, por modelo y por región: un proyecto con cuota generosa en us-east5 puede no tener ninguna en europe-west1 hasta que se solicite un aumento separado allí.
La selección de Región determina dónde se ejecuta realmente la inferencia: una región específica fija el procesamiento en esa ubicación, un valor multirregional abarca una geografía y "global" permite a Anthropic enrutar a la región que tenga capacidad.

Configuración de la Cuenta de Servicio

# Crea una cuenta de servicio dedicada para las llamadas a la API de Claude.
gcloud iam service-accounts create claude-api-caller \
  --display-name="Llamador de API de Claude"
 
# Otorga el rol de Usuario de Vertex AI, limitado al proyecto.
gcloud projects add-iam-policy-binding mi-proyecto-gcp \
  --member="serviceAccount:claude-api-caller@mi-proyecto-gcp.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
 
# Habilita la API de Vertex AI si aún no lo está.
gcloud services enable aiplatform.googleapis.com --project=mi-proyecto-gcp

Crear una cuenta de servicio dedicada para el tráfico de Claude, en lugar de reutilizar una cuenta general amplia, mantiene la auditoría IAM sencilla y limita el radio de explosión si las credenciales se ven comprometidas alguna vez.
roles/aiplatform.user es el rol predefinido estándar para invocar modelos de Vertex AI; un rol personalizado más específico vale la pena crearlo una vez que tus necesidades de permisos estén bien entendidas.
Habilitar la API es idempotente: ejecutarla nuevamente en un proyecto ya habilitado no tiene ningún efecto, por lo que es seguro incluirla en los scripts de configuración.

Opciones de Región y Punto de Conexión

Valor de Región	Comportamiento	Mejor ajuste
Región específica (ej. `us-east5`)	La inferencia se fija en esa ubicación exacta.	Requisitos de residencia de datos o latencia que exigen una ubicación fija.
Multirregional (ej. `us`, `eu`)	Enruta dentro de una geografía, no de un único centro de datos.	Cargas de trabajo sensibles a la latencia con un requisito de residencia amplio pero limitado.
`"global"`	Anthropic enruta a la región disponible con mejor capacidad.	Opción predeterminada cuando no hay restricciones de residencia: maximiza la disponibilidad durante los límites de capacidad regionales.

Los aumentos de cuota están limitados a la región, por lo que cambiar una carga de trabajo de una región específica a "global" (o viceversa) más tarde puede requerir una nueva conversación sobre cuotas, no solo un cambio de código.
Una carga de trabajo regulada que debe mantener el procesamiento dentro de una jurisdicción nombrada debe fijar una región específica en lugar de usar "global", aunque "global" sea la opción predeterminada más resiliente para todo lo demás.

Notas de Python

from anthropic import AnthropicVertex
 
# El streaming funciona de manera idéntica a la API directa: solo la clase del cliente difiere.
client = AnthropicVertex(project_id="mi-proyecto-gcp", region="us-east5")
 
with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "Redacta una nota de lanzamiento corta."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

AnthropicVertex expone los mismos métodos messages.create y messages.stream que los clientes de la API directa y Bedrock: el código escrito contra la API directa solo necesita un cambio en la construcción del cliente para ejecutarse en Vertex AI.
Instalar el SDK con el extra vertex (pip install "anthropic[vertex]") instala las bibliotecas de autenticación de Google que el cliente necesita; el paquete anthropic simple no es suficiente.

Parámetros y Valores de Retorno

Parámetro	Tipo	Descripción
`project_id`	`str`	Argumento de constructor requerido. El proyecto GCP que posee la cuota y la facturación para estas llamadas.
`region`	`str`	Argumento de constructor requerido. Una región específica, un valor multirregional o `"global"`.
`model`	`str`	Los IDs de los modelos Claude de generación actual en Vertex AI no tienen prefijo, coincidiendo con la cadena de modelo desnuda de la API directa.

Errores Comunes

Asumir que el patrón de cliente sin argumentos de la API directa funciona aquí. AnthropicVertex() sin argumentos falla inmediatamente: tanto project_id como region son requeridos. Solución: siempre pásalos explícitamente, típicamente obtenidos de la configuración del entorno.
La cuenta de servicio tiene el rol IAM pero la API de Vertex AI nunca se habilitó. La vinculación del rol se completa silenciosamente, pero las llamadas aún fallan. Solución: confirma que aiplatform.googleapis.com está habilitado en el proyecto, no solo que existe el rol IAM.
Solicitar cuota en la región incorrecta. La cuota se otorga por región, por lo que un aumento de cuota aprobado para us-east5 no hace nada para un cliente configurado con region="europe-west1". Solución: haz coincidir la región de la solicitud de cuota exactamente con la región configurada del cliente.
Tratar "global" como la opción más segura siempre. Para una carga de trabajo regulada con un requisito de residencia de datos, "global" puede enrutar la inferencia a una región fuera de la jurisdicción requerida. Solución: fija una región específica siempre que la residencia sea un requisito estricto, y usa "global" solo cuando no exista tal restricción.
Olvidar el extra vertex al instalar el SDK. Una simple pip install anthropic no incluye las dependencias de autenticación de Google que AnthropicVertex necesita. Solución: instala con pip install "anthropic[vertex]".
Reutilizar una cuenta de servicio amplia y preexistente en lugar de una con ámbito. Esto dificulta mucho la auditoría IAM para el tráfico específico de Claude más adelante. Solución: crea una cuenta de servicio dedicada para las llamadas a la API de Claude con solo los roles que necesita.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
API Directa de Anthropic	Quieres el camino más rápido a los modelos y características más recientes, sin dependencia de GCP.	Tu organización requiere que el tráfico permanezca dentro de los límites de gobernanza de IAM y red administrados por GCP.
Amazon Bedrock	Tu organización está estandarizada en AWS en lugar de GCP.	No tienes presencia en AWS y solo incorporarías un nuevo proveedor de nube para esto.
Una puerta de enlace autoalojada delante de Vertex AI	Quieres añadir caché, limitación de velocidad centralizada o respaldo a otro proveedor sin tocar el código de la aplicación.	Tienes una única carga de trabajo simple donde la infraestructura añadida no vale el costo operativo.

Preguntas Frecuentes

¿Necesito una clave API de Anthropic para usar Claude en Vertex AI?

No. La autenticación se realiza completamente a través de las Credenciales Predeterminadas de Aplicación de Google, resueltas a una cuenta de servicio; no hay una clave API separada emitida por Anthropic involucrada.

¿Por qué `AnthropicVertex()` genera un error sin argumentos?

Tanto project_id como region son argumentos de constructor requeridos sin valores predeterminados, a diferencia del cliente de la API directa que se puede construir sin argumentos leyendo una variable de entorno.

¿Qué rol IAM necesita la cuenta de servicio?

El rol predefinido roles/aiplatform.user, o un rol personalizado equivalente con permisos coincidentes.
La API de Vertex AI en sí misma habilitada en el proyecto, que es un paso separado de la vinculación IAM.

¿Cómo se delimita la cuota en Vertex AI?

Por proyecto, por modelo y por región. Un aumento de cuota aprobado para una región no se aplica a una región diferente configurada en el cliente.

¿Cuál es la diferencia entre una región específica, un valor multirregional y "global"?

Una región específica fija la inferencia en una ubicación; un valor multirregional enruta dentro de una geografía; "global" permite a Anthropic enrutar a la región que tenga capacidad, que es el valor predeterminado más resiliente en ausencia de un requisito de residencia.

¿Debería una carga de trabajo regulada usar `region="global"`?

Generalmente no. Un requisito estricto de residencia de datos exige fijar una región específica, ya que "global" puede enrutar la inferencia fuera de una jurisdicción requerida.

¿Puede el mismo código de aplicación ejecutarse tanto contra la API directa como contra Vertex AI?

En su mayor parte, sí. Ambos clientes exponen los mismos métodos messages.create y messages.stream; las diferencias son la construcción del cliente (clave API vs. proyecto y región) y, para modelos más antiguos con instantáneas fechadas, el formato del ID del modelo.

¿Los IDs de los modelos Claude actuales necesitan un prefijo en Vertex AI?

No, para los modelos de generación actual, el ID coincide con la cadena de modelo desnuda de la API directa. Los modelos con instantáneas fechadas usan un separador de versión @ en lugar de un prefijo.

¿Qué extra de paquete necesito instalar para el soporte de Vertex AI?

pip install "anthropic[vertex]" - el paquete anthropic simple no incluye las dependencias de autenticación de Google que AnthropicVertex requiere.

¿El streaming funciona de la misma manera en Vertex AI que en la API directa?

Sí. client.messages.stream(...) se comporta de manera idéntica, incluido el iterador de conveniencia text_stream.

¿Habilitar la API de Vertex AI es lo mismo que otorgar acceso IAM?

No, son pasos separados. Una cuenta de servicio puede tener el rol IAM correcto mientras la API en sí todavía está deshabilitada en el proyecto, y cualquiera de las brechas por sí sola hace que las llamadas fallen.

¿Por qué un equipo podría elegir Vertex AI sobre la API directa aunque requiera más configuración?

Para mantener el tráfico de Claude dentro de la gobernanza IAM y de red existente de GCP, y para que el gasto cuente contra un acuerdo de facturación o descuento existente de Google Cloud en lugar de una nueva relación con un proveedor.

Relacionado

Elegir entre la API Directa, Bedrock y Vertex AI para Claude - decide si Vertex AI es la plataforma adecuada antes de aprovisionarla.
Conceptos Básicos de Despliegue Empresarial - la primera llamada mínima en las tres plataformas, incluida Vertex AI.
Despliegue de Claude en Amazon Bedrock: IAM, Aprovisionamiento e Inferencia entre Regiones - los pasos de aprovisionamiento equivalentes en AWS.
Lista de Verificación de Residencia de Datos y Fijación de Regiones para Cargas de Trabajo Reguladas - cómo la elección de la región en Vertex AI interactúa con los requisitos de cumplimiento.
Comparación de Bedrock, Vertex AI y Acceso Directo a la API de Anthropic - compromisos entre las tres plataformas en una tabla.

Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de modelos, precios y versiones del SDK cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.