Google Vertex AI 使用教程：从启用 API 到 Python 调用与排错
调用 Google Vertex AI 前，需要先确认你使用的是 Google Cloud 项目而不是个人 Google 账号，并完成结算账号绑定和 Vertex AI API 启用。
本文按“准备环境、生成凭据、调用模型、验证结果、排错”的顺序展开，适合第一次接触 Vertex AI 的开发者照着操作。
先确认项目与 API 是否就绪
Vertex AI 的调用权限绑定在 Google Cloud 项目上，因此第一步不是写代码，而是把项目基础配置做对。
- 登录 Google Cloud 控制台，在顶部项目选择器中确认当前项目 ID。
- 进入“API 和服务” > “库”，搜索
Vertex AI API，点击启用。如果项目未绑定结算账号，控制台会提示先完成结算设置。 - 在“IAM 和管理” > “服务账号”中创建一个服务账号，名称可按用途填写，例如
vertex-ai-caller。 - 给该服务账号授予
Vertex AI User角色，这是调用模型所需的最小常用权限。 - 进入该服务账号的“密钥”页，创建 JSON 格式密钥并下载到本地。
下载的 JSON 文件包含私钥信息，不要提交到 Git 仓库，也不要放进前端代码。
建议保存为 ~/keys/vertex-sa.json，并在服务器上设置权限：
chmod 600 ~/keys/vertex-sa.json安装 SDK 并设置认证环境变量
Python 调用 Vertex AI 使用 google-cloud-aiplatform 包。
建议在虚拟环境中安装，避免污染系统 Python。
python3 -m venv venv
source venv/bin/activate
pip install --upgrade google-cloud-aiplatform设置凭据路径和项目 ID，命令中的值替换成你自己的：
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/keys/vertex-sa.json"
export GOOGLE_CLOUD_PROJECT="你的项目ID"
export GOOGLE_CLOUD_REGION="us-central1"GOOGLE_APPLICATION_CREDENTIALS 是 Google 客户端库默认读取的凭据变量，设置后不需要在代码里硬编码密钥路径。
用 Python 调用 Gemini 模型
下面是一个最小调用示例，使用 gemini-2.0-flash 模型。
模型名称和可用区域可能随项目权限变化，如果返回 404，优先检查模型是否在当前区域可用。
import os
import vertexai
from vertexai.generative_models import GenerativeModel
project = os.environ["GOOGLE_CLOUD_PROJECT"]
location = os.environ.get("GOOGLE_CLOUD_REGION", "us-central1")
vertexai.init(project=project, location=location)
model = GenerativeModel("gemini-2.0-flash")
response = model.generate_content("用一句话解释什么是对象存储")
print(response.text)保存为 test_vertex.py 后执行：
python test_vertex.py预期输出是一段中文回答。
如果返回空字符串，先检查提示词是否被安全策略拦截，再查看完整响应对象。
常见报错怎么排查
403 PermissionDenied：多为服务账号角色不足或 API 未启用。
回到 IAM 页面确认该服务账号拥有 Vertex AI User，并在 API 库确认 Vertex AI API 状态为已启用。
404 NotFound：常见原因是模型名称拼写错误，或当前区域不支持该模型。
把 location 改为 us-central1 再试，同时核对模型 ID 是否与官方文档一致。
凭据文件读取失败：检查 GOOGLE_APPLICATION_CREDENTIALS 是否指向绝对路径，以及运行用户是否有读权限。
用 python -c "import os; print(os.environ.get('GOOGLE_APPLICATION_CREDENTIALS'))" 确认变量已生效。
结算相关错误：Vertex AI 调用会产生费用，项目没有有效结算账号时通常无法正常调用。
控制台“结算”页面可以确认绑定状态。
验证与上线前检查
调用成功后，建议记录三件事：项目 ID、区域、模型名称。
上线前把凭据改为通过服务器环境变量或密钥管理服务注入，不要写死在代码里。
如果要在多台服务器上运行，统一使用同一个服务账号并限制其角色范围，比复制密钥文件更容易管理。
最后，在控制台“Vertex AI” > “在线预测”或日志中确认请求确实到达对应项目，避免把本地缓存或错误配置误判为调用成功。
