仅限 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，以实现纵深防御——当该标志为真值时，系统永远不会查询它们，但移除它们可以完全消除残余路径。

3. 配置应用默认凭据

Vertex 路径使用 ADC 进行身份验证，而不是使用 API 密钥：

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

或者通过伞形 crate 上的提供程序自动检测：

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 的出站流量。当该标志为真值且功能已编译时，没有任何代码路径会构造 Studio 客户端，因此该阻止机制不会对 ADK 流量生效。

故障排除