Saltar al contenido principal

​
Requisitos previos

Antes de configurar Claude Code con Vertex AI, asegúrese de tener:
  • Una cuenta de Google Cloud Platform (GCP) con facturación habilitada
  • Un proyecto de GCP con la API de Vertex AI habilitada
  • Acceso a los modelos Claude deseados (por ejemplo, Claude Sonnet 4.6)
  • Google Cloud SDK (gcloud) instalado y configurado
  • Cuota asignada en la región de GCP deseada
Si está implementando Claude Code para varios usuarios, fije las versiones de su modelo para evitar problemas cuando Anthropic lance nuevos modelos.

​
Configuración de región

Claude Code se puede usar con puntos finales de Vertex AI globales y regionales.
Vertex AI puede no admitir los modelos predeterminados de Claude Code en todas las regiones o en puntos finales globales. Es posible que deba cambiar a una región compatible, usar un punto final regional o especificar un modelo compatible.

​
Configuración

​
1. Habilitar la API de Vertex AI

Habilite la API de Vertex AI en su proyecto de GCP: 
# Establezca su ID de proyecto
gcloud config set project YOUR-PROJECT-ID

# Habilitar la API de Vertex AI
gcloud services enable aiplatform.googleapis.com

​
2. Solicitar acceso al modelo

Solicite acceso a los modelos Claude en Vertex AI:
  1. Navegue al Vertex AI Model Garden
  2. Busque modelos “Claude”
  3. Solicite acceso a los modelos Claude deseados (por ejemplo, Claude Sonnet 4.6)
  4. Espere la aprobación (puede tomar 24-48 horas)

​
3. Configurar credenciales de GCP

Claude Code utiliza la autenticación estándar de Google Cloud. Para obtener más información, consulte la documentación de autenticación de Google Cloud.
Al autenticarse, Claude Code utilizará automáticamente el ID de proyecto de la variable de entorno ANTHROPIC_VERTEX_PROJECT_ID. Para anular esto, establezca una de estas variables de entorno: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT o GOOGLE_APPLICATION_CREDENTIALS.

​
4. Configurar Claude Code

Establezca las siguientes variables de entorno: 
# Habilitar la integración de Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Opcional: Anular la URL del punto final de Vertex para puntos finales personalizados o puertas de enlace
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# Opcional: Deshabilitar el almacenamiento en caché de indicaciones si es necesario
export DISABLE_PROMPT_CACHING=1

# Cuando CLOUD_ML_REGION=global, anule la región para modelos que no admiten puntos finales globales
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
Cada versión de modelo tiene su propia variable VERTEX_REGION_CLAUDE_*. Consulte la referencia de variables de entorno para obtener la lista completa. Verifique Vertex Model Garden para determinar qué modelos admiten puntos finales globales frente a solo regionales. Prompt caching se admite automáticamente cuando especifica la bandera efímera cache_control. Para deshabilitarlo, establezca DISABLE_PROMPT_CACHING=1. Para límites de velocidad elevados, póngase en contacto con el soporte de Google Cloud. Al usar Vertex AI, los comandos /login y /logout están deshabilitados ya que la autenticación se maneja a través de credenciales de Google Cloud.

​
5. Fijar versiones de modelo

Fije versiones de modelo específicas para cada implementación. Si utiliza alias de modelo (sonnet, opus, haiku) sin fijar, Claude Code puede intentar usar una versión de modelo más nueva que no esté habilitada en su proyecto de Vertex AI, lo que romperá los usuarios existentes cuando Anthropic lance actualizaciones.
Establezca estas variables de entorno en ID de modelo específicos de Vertex AI: 
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
Para los ID de modelo actuales y heredados, consulte Descripción general de modelos. Consulte Configuración de modelo para obtener la lista completa de variables de entorno. Claude Code utiliza estos modelos predeterminados cuando no se establecen variables de fijación:
Tipo de modeloValor predeterminado
Modelo principalclaude-sonnet-4-6
Modelo pequeño/rápidoclaude-haiku-4-5@20251001
Para personalizar aún más los modelos: 
export ANTHROPIC_MODEL='claude-opus-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

​
Configuración de IAM

Asigne los permisos de IAM requeridos: El rol roles/aiplatform.user incluye los permisos requeridos:
  • aiplatform.endpoints.predict - Requerido para la invocación de modelo y conteo de tokens
Para permisos más restrictivos, cree un rol personalizado con solo los permisos anteriores. Para obtener más detalles, consulte la documentación de IAM de Vertex.
Cree un proyecto de GCP dedicado para Claude Code para simplificar el seguimiento de costos y el control de acceso.

​
Ventana de contexto de 1M de tokens

Claude Opus 4.6, Sonnet 4.6, Sonnet 4.5 y Sonnet 4 admiten la ventana de contexto de 1M de tokens en Vertex AI. Claude Code habilita automáticamente la ventana de contexto extendida cuando selecciona una variante de modelo de 1M. Para habilitar la ventana de contexto de 1M para su modelo fijado, agregue [1m] al ID del modelo. Consulte Fijar modelos para implementaciones de terceros para obtener más detalles.

​
Solución de problemas

Si encuentra problemas de cuota:
  • Verifique las cuotas actuales o solicite un aumento de cuota a través de Cloud Console
Si encuentra errores “modelo no encontrado” 404:
  • Confirme que el modelo está habilitado en Model Garden
  • Verifique que tenga acceso a la región especificada
  • Si utiliza CLOUD_ML_REGION=global, verifique que sus modelos admitan puntos finales globales en Model Garden en “Características compatibles”. Para modelos que no admiten puntos finales globales, ya sea:
    • Especifique un modelo compatible a través de ANTHROPIC_MODEL o ANTHROPIC_DEFAULT_HAIKU_MODEL, o
    • Establezca un punto final regional usando variables de entorno VERTEX_REGION_<MODEL_NAME>
Si encuentra errores 429:
  • Para puntos finales regionales, asegúrese de que el modelo principal y el modelo pequeño/rápido sean compatibles en su región seleccionada
  • Considere cambiar a CLOUD_ML_REGION=global para una mejor disponibilidad

​
Recursos adicionales