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 キーよりも前に、2 つの環境フラグを参照します。フラグは、その値が 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 の設定を解除します。フラグが真である場合、これらが参照されることはありませんが、削除することで残存経路を完全に排除できます。

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

または、アンブレラクレートでプロバイダーの自動検出を使用します。

use adk_rust::provider_from_env;

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

Studio トラフィックがないことの確認

ビルド時 — フラグは暗黙にフォールバックせず、エラーになります。

• 真のフラグを指定し、gemini-vertex 機能を指定しない GeminiModel::from_env は、機能名を示すエラーを返します。
• GOOGLE_CLOUD_PROJECT または GOOGLE_CLOUD_LOCATION がない状態で真のフラグを指定すると、不足している変数名を示すエラーが返されます。

実行時 — ガードレール警告を監視します。Vertex フラグが真である一方、gemini-vertex 機能がコンパイルされておらず、検出処理が API キーにフォールスルーするたびに、provider_from_env がこの警告を出力します。

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 のトラフィックに対してブロックが発生することはありません。

トラブルシューティング