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
Posts

从零到一：基于 Gemini 和 Claude 的智能体开发实战（集成 Vertex AI）

构建一个真正能用的 AI Agent，不是调 API 写段对话就完事。你需要的是：能接工具、能记忆、能扩展、能上线的完整系统。

技术选型

模型选择

模型优势适用场景
Gemini 3.5 Flash1M 上下文、多模态、性价比高长文档分析、多轮对话
Claude 3.5 Sonnet代码能力强、指令遵循严格代码生成、复杂推理
Gemini + Claude 双模型互补优势主模型决策 + 辅助验证

部署平台

Vertex AI（推荐 GCP 用户）：

  • 统一接口管理多个模型
  • VPC 内调用，安全可控
  • ADC 认证，无需手动管理 key

Gemini Developer API（快速原型）：

  • 免费额度够日常用
  • API Key 简单直接
  • 适合单机开发阶段

核心架构

用户输入
    ↓
主控制器（LLM 决策）
    ├── 工具调用 → Shell / File / Web / API
    ├── 记忆读写 → 持久化存储
    └── 子代理 → 并行任务
    ↓
输出生成

1. 工具层

基础工具集：

read more