https://caozuohua.github.io/tags/proxy/Recent content in Proxy on CAO ZUOHUAHugozh-cnThu, 25 Jun 2026 00:00:00 +0000https://caozuohua.github.io/posts/2026-06-25-google-genai-sdk-complete-guide/Thu, 25 Jun 2026 00:00:00 +0000https://caozuohua.github.io/posts/2026-06-25-google-genai-sdk-complete-guide/<h2 id="为什么要写这篇">为什么要写这篇？</h2> <p>最近在给 Hermes-lite 接入 Gemini 3.x 模型时，踩了不少 google-genai SDK 的坑——尤其是多轮 tool call 时 <code>thought_signature</code> 丢失导致 400、streaming 模式下 function_call args 是片段、<code>response.text</code> 莫名其妙打 stderr Warning 等问题。</p> <p>查了一圈官方文档和社区资料，发现这些坑分散在各处，所以整理了一篇一站式指南，把从安装到上线的完整路径、所有踩坑点都写清楚。</p> <hr> <h2 id="一sdk-概览">一、SDK 概览</h2> <p><strong>包名</strong>：<code>google-genai</code>（PyPI） <strong>仓库</strong>：googleapis/python-genai <strong>当前版本</strong>：v2.10.0（2026-06-24） <strong>Python</strong>：3.9+ <strong>License</strong>：Apache-2.0</p> <p>google-genai 统一封装了两条后端：</p> <ul> <li><strong>Gemini Developer API</strong>：<code>api_key</code> 认证，适合快速开发</li> <li><strong>Vertex AI</strong>：<code>project + location</code>，gcloud ADC 认证，VPC 上最方便</li> </ul> <p>通过 <code>Client</code> 的一个接口切换，代码几乎零改动。</p> <hr> <h2 id="二google-cloud-vps-上全流程配置">二、Google Cloud VPS 上全流程配置</h2> <h3 id="21-环境准备">2.1 环境准备</h3> <div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span><span style="color:#75715e"># 创建 venv（推荐 Python 3.12+）</span> </span></span><span style="display:flex;"><span>python3 -m venv /opt/genai-env </span></span><span style="display:flex;"><span>source /opt/genai-env/bin/activate </span></span><span style="display:flex;"><span> </span></span><span style="display:flex;"><span><span style="color:#75715e"># 安装 SDK</span> </span></span><span style="display:flex;"><span>pip install google-genai </span></span><span style="display:flex;"><span> </span></span><span style="display:flex;"><span><span style="color:#75715e"># 验证</span> </span></span><span style="display:flex;"><span>python3 -c <span style="color:#e6db74">&#34;from google import genai; print(&#39;OK&#39;, google.genai.__version__)&#34;</span> </span></span></code></pre></div><h3 id="22-认证vertex-ai-模式gcloud-adc">2.2 认证：Vertex AI 模式（gcloud ADC）</h3> <p>VPC 上最方便——<strong>Application Default Credentials</strong>，无需手动管理密钥。</p>