Conectar Theus a Google Vertex AI (BYOK)
Ejecuta Theus contra modelos alojados en tu propio proyecto de Google Cloud, usando tus credenciales de Google Cloud (BYOK).
Vertex AI es la vía BYOK ("trae tu propia cuenta") para clientes que ya operan en Google Cloud. En vez de una API key literal, Theus se autentica con las credenciales de tu entorno de Google Cloud y enruta las peticiones a tu proyecto y región. Es el equivalente en GCP a la ruta de Bedrock en AWS.
/providers (ese asistente cubre endpoints OpenAI-compatibles y BYOK con API key). Exporta las variables antes de lanzar theus.Requisitos previos
- Un proyecto de Google Cloud con la API de Vertex AI habilitada y acceso concedido a los modelos Theus en tu región.
- Credenciales de aplicación de Google Cloud disponibles en la máquina (por ejemplo, las credenciales por defecto de la aplicación, referenciadas con
GOOGLE_APPLICATION_CREDENTIALS). - El identificador de tu proyecto y la región donde tienes habilitados los modelos.
Activación
Enciende la ruta de Vertex y apunta Theus a tu proyecto y región con estas variables:
# Activa la ruta Vertex
export THEUS_CODE_USE_VERTEX=1
# Tu proyecto de Google Cloud
export THEUS_VERTEX_PROJECT_ID="mi-proyecto-gcp"
# Región por defecto (si se omite, Theus usa us-east5)
export CLOUD_ML_REGION="us-east5"
# Credenciales de Google Cloud (ruta al JSON de la cuenta de servicio)
export GOOGLE_APPLICATION_CREDENTIALS="/ruta/a/credenciales.json"
theus
Variables reconocidas
| Variable | Rol |
|---|---|
THEUS_CODE_USE_VERTEX | Activa la ruta Vertex (valor "truthy": 1, true). |
THEUS_VERTEX_PROJECT_ID | Identificador del proyecto de Google Cloud que atiende las peticiones. |
CLOUD_ML_REGION | Región por defecto para los modelos. Sin valor, Theus usa us-east5. |
THEUS_VERTEX_BASE_URL | Endpoint de Vertex a usar, si necesitas sobrescribir el predeterminado. |
GOOGLE_APPLICATION_CREDENTIALS | Ruta al archivo de credenciales de Google Cloud que Theus propaga al autenticarse. |
THEUS_CODE_SKIP_VERTEX_AUTH | Omite el paso de autenticación de GCP (para entornos donde las credenciales ya se inyectan por otra vía). |
VERTEX_REGION_THEUS_* | Sobrescribe la región por modelo (ver abajo). |
Región por modelo
Algunos modelos solo están disponibles en ciertas regiones. Puedes fijar la región de un modelo concreto sin cambiar la región global con las variables VERTEX_REGION_THEUS_*. Por ejemplo:
export VERTEX_REGION_THEUS_4_5_SONNET="us-east5"
export VERTEX_REGION_THEUS_HAIKU_4_5="us-central1"
Estas variables se resuelven por prefijo de modelo, de modo que cada modelo enruta a la región que le corresponde. Si un modelo no tiene override, se usa CLOUD_ML_REGION (o us-east5 por defecto).
global de Vertex no ofrece todos los modelos pequeños; en ese caso Theus recurre automáticamente a un modelo mayor para operaciones auxiliares como el conteo de tokens. Prefiere una región regional (por ejemplo us-east5) si necesitas el modelo rápido pequeño.Verificar la conexión
Al arrancar, el panel de estado de Theus muestra el proveedor activo, el proyecto de GCP y la región por defecto detectados. Comprueba que aparezcan tus valores:
THEUS_NO_OPEN_DASHBOARD=1 theus
# En la sesión, revisa el estado del proveedor:
/status
Deberías ver el proyecto (THEUS_VERTEX_PROJECT_ID), la región por defecto y, si lo definiste, el endpoint de Vertex. Si THEUS_CODE_SKIP_VERTEX_AUTH está activo, el estado lo indica explícitamente.
Notas
- Con Vertex activo, los identificadores de modelo siguen el formato de Vertex; ajústalos con
THEUS_MODELy las variables de modelo por defecto (THEUS_DEFAULT_SONNET_MODEL,THEUS_DEFAULT_HAIKU_MODEL,THEUS_DEFAULT_OPUS_MODEL,THEUS_SMALL_FAST_MODEL) si tu proyecto expone IDs específicos. - Vertex es una ruta opcional: Theus nunca exige un servicio remoto para arrancar. Si no defines
THEUS_CODE_USE_VERTEX, se usa la configuración de proveedores habitual (local, OpenAI-compatible o BYOK). - Las credenciales de Google Cloud viven en tu entorno; Theus no las copia a su almacén de proveedores.