Vertex 전용 배포

Gemini 트래픽이 Vertex AI({location}-aiplatform.googleapis.com)에만 도달하고 Gemini API Studio 엔드포인트(generativelanguage.googleapis.com)에는 절대 도달하지 않도록 보장합니다. 규제를 받는 워크로드 — HIPAA, 데이터 레지던시, VPC Service Controls — 에는 이것이 필수입니다. Studio 엔드포인트는 Google Cloud BAA의 적용을 받지 않지만 Vertex AI는 적용을 받기 때문입니다.

엔드포인트 결정

GeminiModel::from_env 및 provider_from_env은 모든 API 키보다 먼저 두 개의 환경 플래그를 확인합니다. 플래그 값이 1이거나 대소문자를 구분하지 않는 true이면 참으로 간주됩니다.

중요: 플래그는 API의 모든 키보다 우선하며, provider_from_env의 ANTHROPIC_API_KEY 및 OPENAI_API_KEY도 포함됩니다. 남아 있는 API 키로 인해 Vertex로 고정된 배포가 Studio로 우회될 수 없습니다.

설정

1. gemini-vertex 기능 활성화

Vertex 백엔드를 포함하여 컴파일해야 합니다. 그렇지 않으면 플래그가 적용되지 않습니다.

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

또는 해당 기능이 포함된 플랫폼 사전 설정을 사용합니다.

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

2. 환경 플래그 설정

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

방어 심층화를 위해 배포 환경에서 GOOGLE_API_KEY 및 GEMINI_API_KEY의 설정을 해제합니다. 플래그가 truthy이면 해당 값은 절대 참조되지 않지만, 제거하면 남아 있는 경로를 완전히 없앨 수 있습니다.

3. Application Default Credentials 구성

Vertex 경로는 API 키가 아닌 ADC로 인증합니다.

# Local development
gcloud auth application-default login

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

GKE 및 Cloud Run에서는 Workload Identity가 키 파일 없이 ADC를 제공합니다.

4. 환경에서 모델 구성

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(())
}

또는 umbrella crate에서 provider 자동 감지를 사용합니다.

use adk_rust::provider_from_env;

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

Studio 트래픽이 없는지 확인

빌드 시 — 플래그는 자동으로 조용히 성능을 저하하는 대신 오류를 발생시킵니다.

• truthy 플래그가 설정되어 있고 gemini-vertex 기능이 없으면 GeminiModel::from_env가 기능 이름을 포함한 오류를 반환합니다.
• GOOGLE_CLOUD_PROJECT 또는 GOOGLE_CLOUD_LOCATION가 누락된 상태에서 truthy 플래그를 사용하면 누락된 변수 이름을 포함한 오류가 반환됩니다.

런타임 — 보호 경고를 확인합니다. provider_from_env는 Vertex 플래그가 truthy이지만 gemini-vertex 기능이 컴파일되지 않았고 감지가 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)

Vertex 전용 배포에서는 이 경고를 배포 오류로 처리해야 합니다. 이는 바이너리가 gemini-vertex 기능 없이 빌드되었다는 의미입니다. 로그 집계 시스템에서 이에 대한 알림을 설정하세요.

네트워크 — VPC Service Controls 경계의 경우 generativelanguage.googleapis.com로의 송신을 차단합니다. 플래그가 truthy이고 기능이 컴파일된 상태에서는 어떤 코드 경로도 Studio 클라이언트를 생성하지 않으므로 ADK 트래픽에 대해 차단이 발생하지 않습니다.

문제 해결