← 返回 Blog
UseAIAPIAI API2min

GOOGLE_GENAI_API_KEY放哪最安全？google-genai 的 Client() 鉴权链解析：AI Studio key vs Vertex 服务账号别混用

将 API 密钥硬编码至代码后提交至公开代码仓库，是开发新手最易出现的经典错误，也是极易被爬虫批量窃取的安全漏洞。即便知晓应使用环境变量配置密钥，不少开发者仍会面临诸多细节困惑：应设置 GOOGLE_API_KEY 还是 GEMINI_API_KEY？AI Studio 密钥与 Vertex AI 服务账号能否通用？新版 SDK 客户端初始化背后的认证逻辑究竟如何运行？

Gemini新版 Gemini SDK 密钥配置指南

新版 Gemini SDK 密钥配置指南：厘清认证体系 规避常见配置误区

将 API 密钥硬编码至代码后提交至公开代码仓库，是开发新手最易出现的经典错误，也是极易被爬虫批量窃取的安全漏洞。即便知晓应使用环境变量配置密钥，不少开发者仍会面临诸多细节困惑：应设置 GOOGLE_API_KEY 还是 GEMINI_API_KEY？AI Studio 密钥与 Vertex AI 服务账号能否通用？新版 SDK 客户端初始化背后的认证逻辑究竟如何运行？

随着 google-genai 新版 SDK 的全面推广，这些看似基础的配置问题，实际复杂度远超预期。厘清认证体系差异、掌握优先级规则、规范密钥存储方式，是开发者顺利完成 SDK 迁移、保障调用安全的核心前提。

一、双服务路线并行 两套身份体系不可混用

目前 Google 生成式 AI 服务分为两条完全独立的服务路线，对应不同的身份凭证、适用场景与认证方式，二者不可交叉混用。

Gemini Developer API 即 AI Studio 路线，面向个人开发者与原型验证场景，凭证为 AI Studio 发放的 API 密钥，绑定个人 Google 账号与调用配额，无需关联 Google Cloud 项目，配置轻量化。Vertex AI 即 Google Cloud 企业级路线，面向生产环境部署，凭证为服务账号，依托云项目实现 IAM 权限管控、VPC 网络隔离与审计追溯，具备完整的企业级 SLA 保障。

对应到新版 SDK 的客户端初始化，两条路线有着完全不同的代码写法。

路线 A：Gemini Developer API（AI Studio 密钥）

python

运行

from google import genai
client = genai.Client(api_key="你的_AI_STUDIO_KEY")

路线 B：Vertex AI（服务账号 ADC 认证）

python

运行

from google import genai
client = genai.Client(
    vertexai=True,
    project="your-project-id",
    location="us-central1"
)

该模式无需传入 API 密钥，SDK 将自动通过应用默认凭据（ADC）完成认证，支持 gcloud 命令行配置或服务账号 JSON 文件两种方式。

需要特别注意的是，AI Studio 密钥无法用于开启 vertexai 参数的客户端，Vertex AI 采用 OAuth2/ADC 认证体系，不支持 API 密钥方式；反之，服务账号凭证也无法用于 AI Studio 模式的客户端。

官方虽提供了 Vertex AI 快速模式作为例外，允许通过 API 密钥访问 Vertex AI 服务，无需配置服务账号，适合临时验证场景，但功能存在限制，不推荐用于生产环境。对应环境变量配置方式如下：

bash

运行

export GOOGLE_API_KEY="your-express-mode-key"
export GOOGLE_GENAI_USE_VERTEXAI=true

二、双环境变量存在优先级 同时配置易引发异常

新版 SDK 支持通过 GOOGLE_API_KEY 与 GEMINI_API_KEY 两个环境变量传入 API 密钥，但二者并非平权关系，存在明确的优先级差异。

官方文档明确说明：建议仅设置其中一个变量；若同时设置两个变量，GOOGLE_API_KEY 将被优先读取。SDK 内部的读取逻辑可简化为：优先读取 GOOGLE_API_KEY，若该变量为空，再读取 GEMINI_API_KEY。

这一规则极易引发排查困难的配置异常：若开发者在环境配置文件中同时设置了两个变量，即便修改了 GEMINI_API_KEY 的值，SDK 仍会静默使用 GOOGLE_API_KEY，导致配置修改看似 “不生效”。Go 版本 SDK 会输出警告日志提示冲突，Python 版本则无明显提示，排查难度更高。

规范的配置原则为：仅设置一个环境变量，避免二者同时存在。个人开发项目推荐使用 GEMINI_API_KEY，语义指向更明确；企业级 Vertex AI 体系推荐使用 GOOGLE_API_KEY，与云平台生态命名保持一致。

三、密钥存储分层规范 生产环境需强化安全防护

官方安全规范明确要求，禁止在客户端代码中明文暴露 API 密钥。“不硬编码” 只是最基础的安全要求，根据使用场景不同，密钥存储可分为三个层级。

第一层：环境变量存储（基础要求）

将密钥写入独立的环境配置文件，并将该文件加入版本控制忽略列表，避免密钥随代码提交至仓库。SDK 初始化时不传任何参数，自动从环境变量读取密钥，这是安全配置的及格线。

python

运行

from google import genai
client = genai.Client()

第二层：显式传参（仅限临时测试）

在客户端初始化时直接传入密钥参数，适合临时脚本与快速验证场景。需注意：显式传入的密钥参数优先级高于环境变量。该方式严禁提交至代码仓库，仅可用于本地临时调试。

python

运行

client = genai.Client(api_key="你的Key")

第三层：专用密钥管理服务（生产环境标准）

环境变量仅实现了 “密钥与代码分离”，但在系统中仍以明文形式存在。生产环境应采用专用密钥管理服务，运行时动态拉取密钥，而非静态存储于系统环境。主流方案包括 Google Cloud 的 Secret Manager、AWS 的 Secrets Manager，以及通用方案 HashiCorp Vault。

此外，环境隔离是不可突破的安全底线：开发、测试、生产环境必须使用不同的密钥，禁止单密钥通用于全环境。

四、隐藏优先级规则：项目地域参数优先级高于密钥

这是新版 SDK 中隐蔽性极强、踩坑后排查难度极高的一条规则：若客户端初始化时同时传入了项目 ID 与地域参数（即 Vertex AI 模式）和 API 密钥，前者优先级更高，密钥参数将被静默忽略。

python

运行

# 错误示例：此处传入的api_key不会生效
client = genai.Client(
    vertexai=True,
    project="my-project",
    location="us-central1",
    api_key="你的KEY"
)

上述代码中，SDK 将默认走 ADC 认证流程，传入的密钥不会被使用。Go 版本 SDK 会直接抛出参数互斥错误，Python 版本则不会明确报错，仅会因认证权限不足导致请求失败，极易误导开发者反复排查密钥本身。

五、核心配置要点总结

梳理新版 SDK 的密钥配置规则，核心可归纳为四项原则：

第一，双路线认证体系相互独立，AI Studio 密钥不可用于 Vertex AI 模式，避免交叉混用；

第二，环境变量存在优先级差异，GOOGLE_API_KEY 优先级高于 GEMINI_API_KEY，仅配置其一即可；

第三，密钥禁止硬编码，基础场景使用环境变量，生产环境必须采用专业密钥管理服务；

第四，Vertex AI 模式以项目地域参数为准，传入该参数后密钥将自动失效，无需重复配置。

随着旧版 google-generativeai SDK 全面进入弃用周期，新版 Client 模式已成为标准配置。认证逻辑封装更规范的同时，也要求开发者明确自身使用的服务路线，遵循对应配置规则，才能规避不必要的调用异常与安全风险。

对于需要同时对接多款大模型的企业与开发团队而言，逐一适配各家厂商的认证体系、密钥管理与 SDK 更新，往往会耗费大量技术精力。UseAIAPI 一站式 AI 接口服务平台，整合了 Gemini、Claude、ChatGPT、DeepSeek 等全球主流最新 AI 大模型，通过统一标准接口即可实现多模型调用，无需分别适配不同厂商的认证规则与 SDK 版本，大幅降低技术对接与维护成本。

平台同步提供全流程企业级定制化服务，可根据业务规模、安全合规要求定制专属接入方案，全程配备专业技术支撑，保障服务稳定可靠。在使用成本上，平台全线模型调用折扣低至官方定价的 50%，无论是日常高频次调用，还是大规模批量处理任务，都能有效压缩 AI 能力落地的成本开支，让不同规模的市场主体都能以高性价比畅享全球前沿 AI 技术能力。