Estructura de objeto de Anthropic Vertex AI

LibreChat admite la ejecución de modelos Anthropic Claude a través de Google Cloud Vertex AI. Esto le permite utilizar modelos Claude con su infraestructura, facturación y credenciales de Google Cloud existentes.

Para una configuración rápida usando variables de entorno, consulta la guía de configuración de Anthropic

Beneficios

• Facturación unificada: Utilice su cuenta de facturación de Google Cloud existente
• Características empresariales: Acceda a las funciones de seguridad y cumplimiento empresarial de Google Cloud
• Cumplimiento regional: Implemente en regiones específicas para cumplir con los requisitos de residencia de datos
• Infraestructura existente: Aproveche sus cuentas de servicio y políticas de IAM de GCP actuales

Requisitos previos

Antes de configurar Anthropic Vertex AI, asegúrese de tener:

1. Google Cloud Project con la API de Vertex AI habilitada
2. Service Account con el rol Vertex AI User (roles/aiplatform.user)
3. Modelos Claude habilitados en tu Vertex AI Model Garden
4. Service Account Key (archivo JSON) descargada y accesible para LibreChat

Ejemplo de configuración

endpoints:
  anthropic:
    streamRate: 20
    titleModel: "claude-3.5-haiku"  # Use the visible model name (key from models config)

    vertex:
      region: "us-east5"
      # serviceKeyFile: "/path/to/service-account.json"  # Optional, defaults to api/data/auth.json
      # projectId: "${VERTEX_PROJECT_ID}"  # Optional, auto-detected from service key

      # Model mapping: visible name -> Vertex AI deployment name
      models:
        claude-opus-4.5:
          deploymentName: claude-opus-4-5@20251101
        claude-sonnet-4:
          deploymentName: claude-sonnet-4-20250514
        claude-3.7-sonnet:
          deploymentName: claude-3-7-sonnet-20250219
        claude-3.5-sonnet:
          deploymentName: claude-3-5-sonnet-v2@20241022
        claude-3.5-haiku:
          deploymentName: claude-3-5-haiku@20241022

Nota: El endpoint de Anthropic admite todos los Shared Endpoint Settings, incluidos streamRate, titleModel, titleMethod, titlePrompt, titlePromptTemplate y titleEndpoint.

vertex

El objeto vertex contiene todas las opciones de configuración específicas de Vertex AI.

region

Clave:

Predeterminado: us-east5

Regiones disponibles:

• global (recomendado para la mayoría de los casos de uso)
• us-east5
• us-central1
• europe-west1
• europe-west4
• asia-southeast1

Consejo: Se recomienda la región global, ya que proporciona enrutamiento automático a la región disponible más cercana. Utilice regiones específicas solo si tiene requisitos de residencia de datos.

Ejemplo:

region: "global"

projectId

Clave:

Predeterminado: Detectado automáticamente desde el archivo de clave de servicio

Ejemplo:

projectId: "${GOOGLE_PROJECT_ID}"

serviceKeyFile

Clave:

Predeterminado: api/data/auth.json (o la variable de entorno GOOGLE_SERVICE_KEY_FILE)

Ejemplo:

serviceKeyFile: "/etc/secrets/gcp-service-account.json"

models

El campo models define los modelos de Claude disponibles y asigna nombres fáciles de usar a los IDs de despliegue de Vertex AI. Esto funciona de manera similar al mapeo de modelos de Azure OpenAI.

Opciones de formato

Puedes configurar modelos de tres maneras:

Opción 1: Matriz simple

Utilice los IDs de modelo reales de Vertex AI directamente. Estos se mostrarán tal cual en la interfaz de usuario:

models:
  - "claude-sonnet-4-20250514"
  - "claude-3-7-sonnet-20250219"
  - "claude-3-5-haiku@20241022"

Opción 2: Objeto con nombres personalizados (Recomendado)

Asigne nombres fáciles de usar a los nombres de despliegue de Vertex AI:

models:
  claude-opus-4.5:           # Visible in UI
    deploymentName: claude-opus-4-5@20251101  # Actual Vertex AI model ID
  claude-sonnet-4:
    deploymentName: claude-sonnet-4-20250514
  claude-3.5-haiku:
    deploymentName: claude-3-5-haiku@20241022

Opción 3: Formato mixto con predeterminado

Establezca un nombre de despliegue predeterminado y utilice valores booleanos para los modelos que lo hereden:

deploymentName: claude-sonnet-4-20250514  # Default deployment
models:
  claude-sonnet-4: true  # Uses default deploymentName
  claude-3.5-haiku:
    deploymentName: claude-3-5-haiku@20241022  # Override for this model

Propiedades del objeto Model

Ejemplo:

models:
  claude-sonnet-4:
    deploymentName: claude-sonnet-4-20250514

Alternativa de variable de entorno

Para configuraciones más sencillas, puede configurar Vertex AI usando variables de entorno en lugar de YAML:

# Enable Vertex AI mode
ANTHROPIC_USE_VERTEX=true

# Vertex AI region (optional, defaults to us-east5)
ANTHROPIC_VERTEX_REGION=global

# Path to service account key (optional, defaults to api/data/auth.json)
GOOGLE_SERVICE_KEY_FILE=/path/to/service-account.json

Nota: Al utilizar variables de entorno, el mapeo de modelos no está disponible. Todos los modelos de Claude conocidos se incluirán automáticamente.

Ejemplos completos

Configuración básica

Configuración mínima usando los valores predeterminados (Vertex AI se habilita mediante la presencia de la sección vertex):

endpoints:
  anthropic:
    vertex:
      region: us-east5

Esto utiliza:

• Región: us-east5
• Clave de servicio: api/data/auth.json (o variable de entorno GOOGLE_SERVICE_KEY_FILE)
• ID del proyecto: Detectado automáticamente desde la clave de servicio
• Modelos: Todos los modelos Claude conocidos

Configuración de producción con Model Mapping

Configuración completa con nombres de modelo y títulos personalizados:

endpoints:
  anthropic:
    streamRate: 20
    titleModel: "haiku"
    titleMethod: "completion"

    vertex:
      region: "global"
      serviceKeyFile: "${GOOGLE_SERVICE_KEY_FILE}"

      models:
        opus:
          deploymentName: claude-opus-4-5@20251101
        sonnet:
          deploymentName: claude-sonnet-4-20250514
        haiku:
          deploymentName: claude-3-5-haiku@20241022

Configuración multirregional

Solo puede configurar una región por despliegue. Para necesidades multirregionales, considere utilizar instancias de LibreChat separadas o endpoints personalizados.

Solución de problemas

Errores comunes

"No se pudieron cargar las credenciales predeterminadas"

• Asegúrese de que el archivo de clave de la cuenta de servicio exista en la ruta especificada
• Compruebe los permisos de archivo (deben ser legibles por el proceso de LibreChat)
• Verifique que el archivo JSON sea válido y no esté dañado

"Permission denied" o "403 Forbidden"

• Verifique que la cuenta de servicio tenga el rol Vertex AI User
• Asegúrate de que los modelos Claude estén habilitados en tu Vertex AI Model Garden
• Compruebe que la cuenta de servicio pertenece al proyecto correcto

"Modelo no encontrado"

• Comprueba que el ID del modelo en deploymentName sea correcto
• Verifique que el modelo esté disponible en la región seleccionada
• Asegúrese de que el modelo esté habilitado en su Vertex AI Model Garden

Problemas de región

"Región no válida" o "Región no admitida"

• Utilice una de las regiones compatibles enumeradas anteriormente
• Prueba a usar la región global, la cual proporciona enrutamiento automático
• Consulta la documentación de Google Cloud para obtener la lista más reciente de regiones donde Claude está disponible.

"Modelo no disponible en la región"

• No todos los modelos de Claude están disponibles en todas las regiones
• Intenta cambiar a la región global para el enrutamiento automático a una región disponible
• Consulta el Vertex AI Model Garden para ver qué modelos están disponibles en tu región
• Considere usar una región diferente que tenga una mayor disponibilidad de modelos (por ejemplo, us-east5)

Problemas de latencia

• Si experimentas una latencia alta, intenta utilizar una región geográficamente más cercana a tus usuarios.
• La región global se enruta automáticamente a la región disponible más cercana
• Para cargas de trabajo en producción con requisitos de latencia estrictos, pruebe diferentes regiones y elija la que ofrezca el mejor rendimiento para su caso de uso.

Verificando la configuración

1. Asegúrese de que su clave de cuenta de servicio sea válida:

   gcloud auth activate-service-account --key-file=/path/to/key.json
   gcloud auth list

2. Probar el acceso a Vertex AI:

   gcloud ai models list --region=us-east5

3. Verificar el acceso al modelo Claude:

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://us-east5-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/us-east5/publishers/anthropic/models/claude-3-5-haiku@20241022:rawPredict" \
     -d '{"anthropic_version": "vertex-2023-10-16", "max_tokens": 100, "messages": [{"role": "user", "content": "Hello"}]}'

Notas

• Vertex AI y la API directa de Anthropic son mutuamente excluyentes. Cuando una sección de configuración vertex está presente, la variable de entorno ANTHROPIC_API_KEY se ignora.
• La funcionalidad de búsqueda web es totalmente compatible con Vertex AI.
• El almacenamiento en caché de prompts (Prompt caching) es compatible mediante el filtrado automático de encabezados para la compatibilidad con Vertex AI.
• La llamada a funciones (function calling) y el uso de herramientas funcionan igual que con la API directa de Anthropic.