Gemini 3.5准入机制与企业级调用实战指南

1. 这不是“注册即用”的玩具：Gemini 3.5 的真实能力边界与准入逻辑

“Gemini 3.5 使用教程：从注册到精通一篇全搞定”——这个标题本身就是一个需要被拆解的信号。它暗示着一种普遍存在的认知偏差：把 Gemini 3.5 当作一个和 ChatGPT、Claude 一样，打开网页、点几下鼠标就能立刻上手的“通用聊天机器人”。但现实远比这复杂。我从去年底开始系统性地接入 Gemini 系列模型，从最初的 Gemini 1.5 Pro 到现在的 3.5 Flash 和 3.1 Pro，踩过的坑、填过的坑、绕过的坑，摞起来能当办公椅坐垫。这篇内容，就是我把所有这些经验，浓缩成一份真正能让你少走半年弯路的实操指南。

首先必须明确一个核心事实：Gemini 3.5 并非一个单一产品，而是一个由多个独立服务层构成的“能力矩阵”。你在 Chrome 浏览器地址栏里看到的那个“问问 Gemini”图标，只是最表层的、面向普通消费者的免费入口；而你在 Google Cloud Console 里配置的 Vertex AI Agent Platform，才是支撑企业级应用的底层引擎；至于那些在 GitHub 上疯传的“免翻墙使用 Gemini”脚本，它们调用的，往往是早已被 Google 官方弃用或严格限流的旧版 API 接口。这三者之间，存在着巨大的技术代差、权限壁垒和功能鸿沟。网络热词里反复出现的your current account is not eligible for gemini、chrome gemini has disappeared、api error: 400 thinking options type cannot be disabled，本质上都是用户在不同服务层之间“迷路”后触发的系统级报错。

为什么会出现这种割裂？答案藏在 Google 的商业逻辑里。Gemini 的核心价值，从来就不是做一个“更好用的 Siri”，而是成为 Google Cloud 生态中，驱动企业级 AI 应用的“智能引擎”。它被设计成一个需要被“集成”、被“编排”、被“治理”的基础设施组件，而不是一个开箱即用的消费级 App。所以，当你在搜索“Gemini 下载教程”时，你其实是在寻找一个根本不存在的东西——Gemini 没有客户端可下载，它只存在于云端 API 的调用请求里。那些教你“如何让 Chrome 显示 Gemini 图标”的教程，其本质是教你如何将一个已有的 Google 账号，绑定到 Google 的消费者 AI 服务白名单上，这个过程完全不涉及任何代码或 SDK，但它却是绝大多数人卡住的第一道关。

我见过太多开发者，在没搞清这个前提的情况下，一头扎进google-generativeaiSDK 的文档里，写了一堆 Python 代码，结果运行时抛出402 insufficient balance或400 the model has reached its context window limit，然后开始怀疑人生。其实问题根本不在于代码，而在于他们连“自己有没有资格调用这个模型”这个最基本的前提都没确认。真正的“从注册到精通”，第一步不是写代码，而是完成一次精准的“身份定位”：你是想做一个个人知识管理工具（Consumer Tier），还是想为公司开发一个客服对话机器人（Enterprise Tier）？前者需要的是 Gmail 账号的白名单认证，后者需要的是 Google Cloud 项目的配额与计费设置。混淆这两者，就像拿着一张地铁票去坐高铁，方向错了，再快的车也到不了目的地。

因此，本篇教程的起点，不是pip install google-genai，而是带你亲手拨开层层迷雾，看清 Gemini 3.5 的真实架构。我会用一张表格，清晰地列出你在网络热词中看到的所有关键词，它们究竟对应着哪一层服务、需要哪种认证方式、以及最常见的失败原因。这不是枯燥的理论，而是我每天都在调试、验证、并最终沉淀下来的“故障树”。

这张表，是我过去半年里，帮超过 30 个不同背景的团队排查问题后总结出的“黄金对照表”。它不讲虚的，每一个条目，都对应着一个我亲手复现、定位并解决的真实案例。接下来的内容，将围绕这张表展开，带你一步步，从最底层的身份认证，走到最高阶的多模态协同推理。这不是一篇“保姆级教程”，而是一份“防坑地图”。因为真正的精通，不在于你会多少命令，而在于你知道哪些路根本不能走。

2. 身份认证：一场关于“你是谁”的精密校验

在开始任何一行代码之前，你必须完成一场严肃的“身份认证”。这不是一个简单的登录动作，而是一次跨越 Google 两大生态系统的、精密的权限校验。它决定了你后续能走哪条路，能用哪些模型，甚至能花多少钱。网络热词里高频出现的your current account is not eligible for gemini code assist for individuals，其根源，就深埋在这场认证的每一个环节里。

2.1 Consumer Tier：你的 Gmail 账号，是一张“社会信用分”通行证

对于绝大多数个人用户和小团队来说，“Gemini 3.5”的第一站，是 Chrome 浏览器里的那个小图标。它的背后，是 Google 的 Consumer AI 服务。这里的认证逻辑，与我们习惯的“用户名+密码”完全不同。它更像是一套基于行为的“社会信用分”系统。

Google 并不会在你点击“Sign In”按钮的瞬间，就给你一个明确的“通过”或“拒绝”。它会综合评估你的账号历史：你的 Gmail 账号注册了多久？你是否长期、稳定地使用 Google Drive、Google Photos、YouTube 等核心服务？你的登录设备是否经常变更？你的 IP 地址是否来自一个高风险的代理网络？所有这些数据，都会被实时计算，生成一个动态的“可信度评分”。只有当这个评分超过某个阈值，你的账号才会被加入 Gemini Consumer 的白名单。

这就是为什么，一个刚注册的 Gmail 账号，无论你多么努力地刷新页面、清除缓存、甚至重装 Chrome，那个“问问 Gemini”的图标都不会出现。这不是 Bug，而是 Google 主动设置的风控闸门。我曾用一个注册仅 3 天的新账号，尝试了所有网上能找到的“激活教程”，包括修改 Chrome 的启动参数、手动导入证书、甚至模拟不同地区的 DNS 解析，全部失败。直到第 32 天，当我早上打开 Chrome，那个图标毫无征兆地出现在了地址栏右侧。那一刻我才真正理解，耐心，是 Consumer Tier 认证的第一道，也是最重要的一道门槛。

提示：如果你急需一个可用的 Consumer 环境进行测试，最稳妥的方案是借用一个“老账号”。这个账号不需要是你的主账号，但必须满足：注册时间 > 6 个月，且近 3 个月内有活跃的 Google 服务使用记录（比如上传过照片、编辑过文档）。切记，不要用这个账号去尝试任何可疑的“加速激活”脚本，那只会降低它的可信分，得不偿失。

2.2 Enterprise Tier：Google Cloud 项目，是你在云端的“数字身份证”

当你不再满足于和 Gemini “聊聊天”，而是想把它集成进你的 SaaS 产品、内部知识库或自动化工作流时，你就必须进入 Enterprise Tier——也就是 Google Cloud 的 Vertex AI 平台。这里的认证，是一场彻头彻尾的“企业级”流程，它要求你拥有一张在 Google Cloud 生态中被广泛认可的“数字身份证”：一个配置完备的 Google Cloud 项目。

这个过程，远比 Consumer Tier 复杂，但也更加透明和可控。它由四个环环相扣的步骤组成，缺一不可：

1. 项目创建与 Billing 绑定：这是整个大厦的地基。你必须登录 Google Cloud Console ，创建一个全新的项目（强烈建议不要用你的个人主项目，以防误操作影响其他服务），然后为其绑定一个有效的 Billing 账户。这里有一个极易被忽略的细节：Billing 账户的“状态”必须是Active，而不仅仅是“已关联”。我曾遇到一个客户，他的 Billing 账户因为信用卡过期被 Google 自动暂停了 24 小时，导致所有 API 调用都返回402 insufficient balance，而控制台的提示却非常模糊，花了整整一天才定位到这个根源。

2. API 启用：地基打好后，你需要为这个项目“安装”Gemini 的能力模块。在 Console 的左侧导航栏，进入APIs & Services > Library，搜索Vertex AI API，并点击启用。注意，这里启用的是Vertex AI API，而不是Generative Language API（后者是旧版，已逐步淘汰）。启用后，系统会自动为你创建一个名为vertex-ai的服务账号，这是后续所有操作的执行主体。

3. IAM 权限授予：这是最关键的一步，也是权限错误的高发区。仅仅启用了 API，你的个人账号依然无法调用它。你必须进入IAM & Admin > IAM页面，找到你自己的邮箱地址（即你登录 Console 的那个 Gmail），然后点击右侧的铅笔图标进行编辑。在“角色”下拉菜单中，必须添加Vertex AI User(roles/aiplatform.user) 这个预定义角色。很多教程会告诉你添加Owner或Editor，这是极其危险的。Owner权限过大，一旦你的 API Key 泄露，攻击者可以删除你的整个云项目；而Editor权限又不足以调用 Gemini 的高级功能（如 Code Execution）。Vertex AI User是 Google 官方推荐的、最小权限原则下的最佳实践。

4. 服务账号密钥（可选但推荐）：对于本地开发或 CI/CD 流水线，你可能需要一个长期有效的凭证。这时，你应该回到IAM & Admin > Service Accounts页面，找到刚才创建的vertex-ai@your-project-id.iam.gserviceaccount.com服务账号，为其创建一个新的JSON密钥文件。切记，这个文件必须像你的银行密码一样被严格保管。我的个人习惯是，将它存放在一个加密的密码管理器中，并在.gitignore文件里永久屏蔽*.json和*.p12文件，绝不在任何代码仓库中提交。

完成这四步之后，你的 Google Cloud 项目才真正具备了调用 Gemini 3.5 的“合法身份”。此时，你就可以放心地执行gcloud auth application-default login来配置 Application Default Credentials (ADC)，或者将服务账号密钥文件路径设置为GOOGLE_APPLICATION_CREDENTIALS环境变量。这才是 SDK 能够正常工作的前提。

2.3 为什么google-generativeaiSDK 会“突然失效”？

google-generativeai是目前最主流的 Python SDK，但它的稳定性，高度依赖于上述认证流程的完整性。我观察到，大约 70% 的 SDK 报错，其根源并非 SDK 本身，而是认证环节的“慢性失血”。

最常见的“慢性失血”场景是：ADC 凭据的自动过期与静默失效。gcloud auth application-default login生成的 ADC 凭据，默认有效期为 1 小时。当它过期后，SDK 不会抛出一个清晰的TokenExpiredError，而是会返回一个语义模糊的401 Unauthorized或403 Forbidden。如果你的代码里没有完善的错误日志，你可能会以为是网络问题，或是模型 ID 写错了，从而陷入无休止的排查循环。

我的解决方案是，在每次调用 Gemini API 之前，增加一个轻量级的健康检查：

from google.auth import default from google.auth.transport.requests import Request def check_adc_health(): """检查 Application Default Credentials 是否有效且未过期""" try: # 尝试获取凭据 credentials, _ = default() # 尝试刷新令牌（如果已过期，此操作会触发刷新） if credentials.expired or not credentials.valid: Request().refresh(credentials) return True, "ADC is valid and fresh" except Exception as e: return False, f"ADC health check failed: {str(e)}" # 在你的主函数开头调用 is_healthy, msg = check_adc_health() if not is_healthy: print(f"⚠️ ADC Health Check Failed: {msg}") print("💡 Please run: gcloud auth application-default login") exit(1)

这段代码，是我所有生产环境脚本的标配。它能在问题发生前，就给你一个明确的、可操作的修复指引。真正的“精通”，不在于写出多么炫酷的 Prompt，而在于构建一套健壮、自检、可运维的基础设施。

3. SDK 实战：从pip install到生产级调用的完整链路

完成了身份认证，现在终于可以进入代码的世界了。但请注意，pip install google-genai只是万里长征的第一步。真正的挑战，在于如何将这个 SDK，从一个能跑通 Hello World 的玩具，变成一个稳定、高效、可监控的生产级组件。网络热词中反复出现的api error: 400 thinking options type cannot be disabled when reasoning_effor，正是 SDK 配置不当的典型症状。

3.1 环境变量：隐藏在幕后的“指挥官”

google-genaiSDK 的行为，很大程度上由一组环境变量所控制。这些变量就像藏在幕后的指挥官，默默决定着 SDK 是该走 Google Cloud 的 Vertex AI 通道，还是走 Consumer 的公共 API 通道。忽略它们，是导致400错误的最常见原因。

最关键的三个环境变量是：

• GOOGLE_CLOUD_PROJECT: 这是你 Google Cloud 项目的 ID，格式为my-awesome-project-123456。它告诉 SDK：“我要调用的资源，属于这个项目。” 如果你没有设置它，SDK 会默认尝试使用 Consumer API，而这往往会导致权限错误。
• GOOGLE_CLOUD_LOCATION: 这是你的 Vertex AI 资源所在的地理区域。对于全球通用的模型（如gemini-3.5-flash），你可以安全地设置为global。但对于一些特定区域部署的模型（如us-central1），你必须精确匹配。
• GOOGLE_GENAI_USE_ENTERPRISE: 这是一个布尔值开关。必须将其设置为True。这是 SDK 的“企业模式”开关。当它为True时，SDK 会强制使用 Vertex AI 的端点（https://us-central1-aiplatform.googleapis.com）；当它为False或未设置时，SDK 会回退到 Consumer 的端点（https://generativelanguage.googleapis.com），而后者对gemini-3.5-flash等新模型的支持是不完整且不稳定的。

一个典型的、安全的初始化脚本如下：

# 在你的终端中执行（Linux/macOS） export GOOGLE_CLOUD_PROJECT="your-project-id-123456" export GOOGLE_CLOUD_LOCATION="global" export GOOGLE_GENAI_USE_ENTERPRISE="True" # 然后运行你的 Python 脚本 python my_gemini_app.py

注意：在 Windows 的 PowerShell 中，语法略有不同：

$env:GOOGLE_CLOUD_PROJECT="your-project-id-123456" $env:GOOGLE_CLOUD_LOCATION="global" $env:GOOGLE_GENAI_USE_ENTERPRISE="True"

3.2 模型选择：不是“越新越好”，而是“恰到好处”

Gemini 3.5 系列提供了多个模型，它们不是简单的“升级版”，而是针对不同任务进行了深度优化的“特种兵”。盲目选择“最新”的模型，往往会适得其反。

• gemini-3.5-flash: 这是目前的“速度之王”。它的上下文窗口高达 1048576 tokens，推理速度极快，成本最低。但它牺牲了一部分“深度思考”能力。适用场景：实时对话、长文档摘要、批量内容生成、代码补全。不适用场景：需要多步逻辑推演、复杂数学证明、或对输出格式有严苛要求的任务。
• gemini-3.1-pro: 这是目前的“全能冠军”。它在速度、深度、多模态能力上取得了最佳平衡。它的上下文窗口同样巨大，且在代码执行（Code Execution）、结构化输出（Structured Output）、函数调用（Function Calling）等高级特性上，支持最为完善。适用场景：构建 AI Agent、自动化工作流、需要代码解释与执行的分析任务。不适用场景：对延迟极度敏感的毫秒级响应（此时flash更优）。
• gemini-3.5-flash-image: 这是专为图像生成而生的模型。它能根据文本 Prompt 生成高质量图片，并支持TEXT和IMAGE双模态输出。关键限制：它不支持纯文本输出。如果你的response_modalities只设置了["TEXT"]，API 会直接报错400。你必须显式地同时声明["TEXT", "IMAGE"]。

下面是一个完整的、生产就绪的 Python 示例，它展示了如何安全地调用gemini-3.1-pro，并处理常见的错误：

from google import genai from google.genai.types import ( GenerateContentConfig, SafetySetting, HarmCategory, HarmBlockThreshold, Tool, ToolCodeExecution, ) import logging # 配置日志 logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) def create_safe_client(): """创建一个带有安全配置的 Gemini 客户端""" # 初始化客户端，SDK 会自动读取环境变量 client = genai.Client() return client def call_gemini_with_safety( client, model_id: str, prompt: str, temperature: float = 0.2, max_output_tokens: int = 8192, ): """ 安全、鲁棒地调用 Gemini API Args: client: 已初始化的 genai.Client model_id: 模型ID，如 "gemini-3.1-pro" prompt: 用户输入的 Prompt temperature: 温度参数，控制输出随机性 max_output_tokens: 最大输出 token 数 Returns: str: 模型的响应文本，或错误信息 """ try: # 构建安全配置：降低有害内容风险 safety_settings = [ SafetySetting( category=HarmCategory.HARM_CATEGORY_HARASSMENT, threshold=HarmBlockThreshold.BLOCK_ONLY_HIGH, ), SafetySetting( category=HarmCategory.HARM_CATEGORY_HATE_SPEECH, threshold=HarmBlockThreshold.BLOCK_ONLY_HIGH, ), SafetySetting( category=HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, threshold=HarmBlockThreshold.BLOCK_ONLY_HIGH, ), SafetySetting( category=HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, threshold=HarmBlockThreshold.BLOCK_ONLY_HIGH, ), ] # 构建生成配置 config = GenerateContentConfig( temperature=temperature, max_output_tokens=max_output_tokens, safety_settings=safety_settings, ) # 对于需要代码执行的复杂任务，启用 Code Execution 工具 # tools = [Tool(code_execution=ToolCodeExecution())] # 发起请求 response = client.models.generate_content( model=model_id, contents=prompt, config=config, # tools=tools, # 取消注释以启用代码执行 ) # 检查响应状态 if not response.candidates or len(response.candidates) == 0: logger.error("No candidates returned from Gemini.") return "Gemini returned no response." candidate = response.candidates[0] if candidate.finish_reason != "STOP": logger.warning(f"Gemini finished with reason: {candidate.finish_reason}") return candidate.content.text except Exception as e: logger.error(f"Gemini API call failed: {e}") # 根据不同的异常类型，提供更具体的错误信息 if "400" in str(e): return "❌ API Error 400: 请求参数错误。请检查模型ID、Prompt格式或环境变量设置。" elif "401" in str(e) or "403" in str(e): return "❌ API Error 401/403: 认证失败。请检查 Google Cloud 项目权限和 ADC 凭据。" elif "402" in str(e): return "❌ API Error 402: 账户余额不足。请检查 Billing 设置。" else: return f"❌ 未知错误: {str(e)}" # 使用示例 if __name__ == "__main__": client = create_safe_client() # 测试一个简单的问答 result = call_gemini_with_safety( client, model_id="gemini-3.1-pro", prompt="请用中文，用不超过100字，解释什么是量子纠缠。", ) print("✅ 响应:", result) # 测试一个需要代码执行的复杂任务（取消注释 tools 行后启用） # result = call_gemini_with_safety( # client, # model_id="gemini-3.1-pro", # prompt="计算斐波那契数列的第 30 项，并找出小于它的最大质数。", # tools=[Tool(code_execution=ToolCodeExecution())], # ) # print("✅ 响应:", result)

这段代码的价值，不在于它实现了什么功能，而在于它体现了生产环境的思维：

1. 防御性编程：对response.candidates进行空值检查，对finish_reason进行日志记录。
2. 错误分类：将模糊的Exception，映射为用户可理解的、可操作的错误信息（如❌ API Error 400）。
3. 安全优先：默认启用了SafetySetting，防止模型输出有害内容。
4. 配置化：将temperature、max_output_tokens等关键参数暴露为函数参数，便于在不同场景下灵活调整。

3.3api error: 400 thinking options type cannot be disabled when reasoning_effor的真相

这个错误信息，是 SDK 用户的噩梦。它的字面意思是“当启用reasoning_effort时，thinking options type不能被禁用”。但它的实际含义，是 SDK 版本与模型能力之间的不兼容。

reasoning_effort是 Gemini 3.1 Pro 引入的一个新参数，用于精细控制模型的“思考深度”。而thinking options type则是旧版 API 中的一个遗留字段。当你使用一个较老版本的google-genaiSDK（例如 0.4.x）去调用gemini-3.1-pro时，SDK 会尝试发送一个包含了reasoning_effort但又禁用了thinking options的请求体，这违反了 API 的契约，于是服务器就返回了这个令人费解的400。

解决方案只有一个：永远使用最新稳定版的 SDK。在撰写本文时，google-genai的最新版本是0.7.0。你必须执行：

pip install --upgrade google-genai

并且，在升级后，务必检查你的requirements.txt文件，将版本号锁定：

google-genai==0.7.0

这能确保你的生产环境与开发环境使用完全一致的 SDK 版本，避免因版本漂移导致的线上事故。记住，AI SDK 的迭代速度，远超传统 Web 框架。昨天还“完美”的代码，今天就可能因为一个 SDK 更新而崩溃。保持更新，不是一种选择，而是一种生存必需。

4. 多模态协同：超越文本的 Gemini 3.5 真实力量

当人们谈论 Gemini 3.5 时，焦点往往集中在它的“文本能力”上：写文章、编代码、做翻译。但这只是冰山一角。Gemini 3.5 的真正革命性，在于它将文本、图像、音频、视频、甚至代码执行，整合进了一个统一的、可协同的推理框架中。网络热词中出现的deepseek api如何调用、codex配置第三方api，恰恰反映了开发者们正在从单模态的“调用 API”时代，迈向多模态的“编排智能”时代。

4.1 图像理解：从“看图说话”到“视觉推理”

Gemini 3.5 的图像理解能力，已经远超简单的“图像描述”。它能进行跨模态的深度推理。例如，你可以给它一张复杂的财务报表截图，然后问：“请指出其中同比增长率最高的三个项目，并计算它们的总和。”

要实现这一点，关键在于Part.from_uri()的正确使用。你不能直接把本地图片路径传给 SDK，而必须先将图片上传到 Google Cloud Storage (GCS)，然后使用 GCS 的gs://URI。

from google import genai from google.genai.types import Part def analyze_image_from_gcs(client, gcs_uri: str, prompt: str): """ 分析存储在 Google Cloud Storage 中的图像 Args: client: genai.Client gcs_uri: GCS URI, e.g., "gs://my-bucket/images/report.png" prompt: 文本 Prompt Returns: str: 模型的分析结果 """ # 创建一个包含图像 URI 的 Part image_part = Part.from_uri( file_uri=gcs_uri, mime_type="image/png", # 必须与实际文件类型匹配 ) # 将文本 Prompt 和图像 Part 组合成一个消息 contents = [ prompt, image_part, ] response = client.models.generate_content( model="gemini-3.1-pro", contents=contents, ) return response.text # 使用示例 # result = analyze_image_from_gcs( # client, # gcs_uri="gs://my-company-data/reports/q1-financial.png", # prompt="请分析这张财报截图，指出同比增长率最高的三个项目，并计算它们的总和。" # ) # print(result)

提示：上传图片到 GCS 的命令非常简单：

gsutil cp /path/to/local/image.png gs://my-bucket-name/images/

请确保你的 Google Cloud 项目对这个 GCS 存储桶拥有storage.objects.get权限。

4.2 图像生成：告别“黑盒”，拥抱“可控创作”

gemini-3.5-flash-image模型的出现，标志着图像生成进入了“可控”时代。它不再是一个只能接受模糊 Prompt 的黑盒，而是一个可以被精确引导的创作伙伴。你可以要求它生成一张图片，然后立即对这张图片进行编辑，比如“将图中人物的衬衫颜色改为蓝色”，或者“在画面右下角添加一个半透明的公司 Logo”。

这背后的技术，是response_modalities参数的精妙运用。正如前面提到的，flash-image模型必须同时返回TEXT和IMAGE。TEXT部分会包含模型对 Prompt 的理解和生成逻辑的解释，而IMAGE部分则是最终的图片数据。

from google import genai from google.genai.types import GenerateContentConfig, Modality from io import BytesIO from PIL import Image import os def generate_and_explain_image(client, prompt: str, output_dir: str = "output"): """ 生成图像并获取其生成逻辑的解释 Args: client: genai.Client prompt: 图像生成 Prompt output_dir: 输出图片的目录 Returns: tuple: (解释文本, 图片文件路径) """ # 确保输出目录存在 os.makedirs(output_dir, exist_ok=True) # 构建配置，明确指定需要 TEXT 和 IMAGE 两种模态 config = GenerateContentConfig( response_modalities=[Modality.TEXT, Modality.IMAGE], # 可以设置更高的 candidate_count 来获得多个备选 candidate_count=1, ) response = client.models.generate_content( model="gemini-3.5-flash-image", contents=prompt, config=config, ) # 解析响应 text_explanation = "" image_data = None for part in response.candidates[0].content.parts: if part.text: text_explanation = part.text elif part.inline_data: image_data = part.inline_data.data # 保存图片 if image_data: image = Image.open(BytesIO(image_data)) # 生成一个安全的文件名 safe_prompt = "".join(c for c in prompt[:50] if c.isalnum() or c in (' ', '-', '_')).rstrip() filename = f"{output_dir}/{safe_prompt.replace(' ', '_')}.png" image.save(filename) return text_explanation, filename else: return text_explanation, None # 使用示例 explanation, img_path = generate_and_explain_image( client, prompt="A photorealistic portrait of a wise old owl wearing glasses, sitting on a stack of ancient books, in a cozy library with warm lighting.", output_dir="generated_images" ) print("📝 生成逻辑解释:", explanation) print("🖼️ 图片已保存至:", img_path)

这段代码的精妙之处在于，它不仅生成了图片，还为你提供了一份“创作说明书”。这份说明书，是调试 Prompt、优化生成效果的金钥匙。当你发现生成的图片不符合预期时，你首先应该看的，不是图片本身，而是这份text_explanation。它会告诉你模型是如何理解你的 Prompt 的，哪里出现了歧义，从而指导你进行下一轮的 Prompt 迭代。

4.3 代码执行：让 Gemini 成为你最聪明的“协作者”

Code Execution是 Gemini 3.1 Pro 的王牌功能。它让模型不仅能“说”代码，更能“写”代码、“跑”代码、“看”结果，然后基于结果进行下一步推理。这彻底改变了我们与 AI 协作的方式。

想象一下这个场景：你需要分析一个 CSV 文件中的销售数据，找出销售额最高的五个城市，并绘制柱状图。过去，你需要自己写 Python 脚本，加载数据，写 Pandas 代码，再用 Matplotlib 绘图。现在，你只需要告诉 Gemini：

“请分析附件中的sales_data.csv，找出销售额最高的五个城市，并用 matplotlib 绘制一个柱状图。”

Gemini 会自动生成一段完整的、可执行的 Python 代码，然后在它自己的沙箱环境中运行这段代码，最后将运行结果（包括图表）作为响应的一部分返回给你。

要启用这个功能，你只需要在GenerateContentConfig中添加一个Tool：

from google.genai.types import Tool, ToolCodeExecution # 在你的 config 构建中加入 config = GenerateContentConfig( tools=[Tool(code_execution=ToolCodeExecution())], temperature=0.0, # 为了确定性，温度设为 0 ) response = client.models.generate_content( model="gemini-3.1-pro", contents="请分析附件中的 sales_data.csv，找出销售额最高的五个城市，并用 matplotlib 绘制一个柱状图。", config=config, ) # 获取执行结果 if response.executable_code: print("💻 生成的代码:") print(response.executable_code) if response.code