Implementaciones exclusivas en Vertex

Garantiza que el tráfico de Gemini llegue únicamente a Vertex AI ({location}-aiplatform.googleapis.com) y nunca al endpoint de Gemini API Studio (generativelanguage.googleapis.com). Las cargas de trabajo reguladas —HIPAA, residencia de datos, VPC Service Controls— lo requieren: el endpoint de Studio no está cubierto por un BAA de Google Cloud, mientras que Vertex AI sí.

Decisión del endpoint

GeminiModel::from_env y provider_from_env consultan dos indicadores de entorno antes de cualquier clave API. Un indicador es verdadero cuando su valor es 1 o un true sin distinción entre mayúsculas y minúsculas.

Importante: las banderas tienen prioridad sobre cada clave API, incluidas ANTHROPIC_API_KEY y OPENAI_API_KEY en provider_from_env. Una clave API aislada no puede desviar una implementación fijada a Vertex hacia Studio.

Configuración

1. Habilitar la característica gemini-vertex

Compile el backend de Vertex en — sin ella, la bandera no se puede aplicar:

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "gemini-vertex"] }

O use el ajuste preestablecido de la plataforma, que la incluye:

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "gemini-agent-platform"] }

2. Establecer las banderas de entorno

export GOOGLE_GENAI_USE_ENTERPRISE=true
export GOOGLE_CLOUD_PROJECT=my-project
export GOOGLE_CLOUD_LOCATION=us-central1

Elimine GOOGLE_API_KEY y GEMINI_API_KEY del entorno de implementación como defensa en profundidad — cuando la bandera es verdadera, nunca se consultan, pero eliminarlas suprime por completo la ruta residual.

3. Configurar las credenciales predeterminadas de la aplicación

La ruta de Vertex se autentica con ADC, no con una clave API:

# Local development
gcloud auth application-default login

# Service accounts (CI, containers)
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

En GKE y Cloud Run, Workload Identity proporciona ADC sin un archivo de claves.

4. Construir el modelo a partir del entorno

use adk_model::gemini::GeminiModel;

// The Vertex path builds Application Default Credentials, which requires a
// current Tokio runtime.
#[tokio::main]
async fn main() -> adk_core::Result<()> {
    // Vertex AI when a flag is truthy; errors instead of falling back to
    // Studio when the Vertex configuration is incomplete.
    let model = GeminiModel::from_env("gemini-3.7-flash")?;
    Ok(())
}

O mediante la detección automática del proveedor en el crate general:

use adk_rust::provider_from_env;

#[tokio::main]
async fn main() -> adk_rust::Result<()> {
    let model = provider_from_env()?;
    Ok(())
}

Verificar que no haya tráfico de Studio

En tiempo de compilación — la bandera devuelve un error en lugar de degradarse silenciosamente:

• GeminiModel::from_env con una bandera verdadera y sin la característica gemini-vertex devuelve un error que indica el nombre de la característica.
• Una bandera verdadera con GOOGLE_CLOUD_PROJECT o GOOGLE_CLOUD_LOCATION ausente devuelve un error que indica el nombre de la variable faltante.

En tiempo de ejecución — busque la advertencia de protección. provider_from_env la emite siempre que una bandera de Vertex sea verdadera, pero la característica gemini-vertex no esté compilada y la detección continúe hasta las claves API:

WARN vertex backend requested via environment but the gemini-vertex feature is not compiled; api-key detection may select the gemini studio endpoint (generativelanguage.googleapis.com)

Una implementación exclusiva de Vertex debe tratar esta advertencia como un error de implementación: significa que el binario se compiló sin la característica gemini-vertex. Configure una alerta para ella en la agregación de registros.

Red — para los perímetros de VPC Service Controls, bloquea la salida a generativelanguage.googleapis.com. Con la marca establecida como verdadera y la función compilada, ninguna ruta de código construye un cliente de Studio, por lo que el bloqueo nunca se activa para el tráfico de ADK.

Solución de problemas