Posts

google-genai SDK 全流程指南：Vertex AI + Gemini API 实战

为什么要写这篇？

最近在给 Hermes-lite 接入 Gemini 3.x 模型时，踩了不少 google-genai SDK 的坑——尤其是多轮 tool call 时 thought_signature 丢失导致 400、streaming 模式下 function_call args 是片段、response.text 莫名其妙打 stderr Warning 等问题。

查了一圈官方文档和社区资料，发现这些坑分散在各处，所以整理了一篇一站式指南，把从安装到上线的完整路径、所有踩坑点都写清楚。

一、SDK 概览

包名：google-genai（PyPI） 仓库：googleapis/python-genai 当前版本：v2.10.0（2026-06-24） Python：3.9+ License：Apache-2.0

google-genai 统一封装了两条后端：

  • Gemini Developer API：api_key 认证，适合快速开发
  • Vertex AI：project + location，gcloud ADC 认证，VPC 上最方便

通过 Client 的一个接口切换，代码几乎零改动。

二、Google Cloud VPS 上全流程配置

2.1 环境准备

# 创建 venv（推荐 Python 3.12+）
python3 -m venv /opt/genai-env
source /opt/genai-env/bin/activate

# 安装 SDK
pip install google-genai

# 验证
python3 -c "from google import genai; print('OK', google.genai.__version__)"

2.2 认证：Vertex AI 模式（gcloud ADC）

VPC 上最方便——Application Default Credentials，无需手动管理密钥。

read more