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 的真实架构。我会用一张表格清晰地列出你在网络热词中看到的所有关键词它们究竟对应着哪一层服务、需要哪种认证方式、以及最常见的失败原因。这不是枯燥的理论而是我每天都在调试、验证、并最终沉淀下来的“故障树”。网络热词/错误信息对应的服务层核心准入条件常见失败原因我的实操建议failed to sign in. message: your current account is not eligible for geminiConsumer Web (Chrome 内置)Gmail 账号需在 Google 的 Gemini Consumer 白名单内通常要求账号注册时间 6 个月且无异常登录行为新注册的 Gmail 账号、使用临时邮箱注册的账号、或近期频繁切换登录设备的账号几乎 100% 被拒不要重试立即停止操作。新账号请至少等待 30 天并确保日常使用 Gmail、Google Drive 等服务建立“可信用户”画像。这是 Google 的风控策略没有捷径。gemini api 付费层级/api error: 402 insufficient balanceVertex AI (Google Cloud)必须创建 Google Cloud 项目启用 Billing并为该项目分配 Gemini API 的配额项目未开启计费、Billing 账户余额不足、或未在 IAM 中为当前用户授予aiplatform.user角色这是最容易被忽略的一步。在 Google Cloud Console 中Billing页面和API Services Library页面是两个独立的开关必须都打开。我建议新项目直接启用PayGo计费模式避免Provisioned Throughput的复杂配置。api error: the model has reached its context window limit.Vertex AI / Gemini Enterprise Agent Platform模型自身的上下文长度限制如 Gemini 3.5 Flash 为 1,048,576 tokens提交的 Prompt 历史对话 文件内容总 token 数超限或未正确使用streaming模式处理长文本不要试图“硬塞”。我的方案是对长文档先用gemini-3.5-flash进行摘要提取再将摘要喂给gemini-3.1-pro进行深度分析。这是一种成本与效果的平衡术。chrome gemini没有显示/为什么chrome浏览器内置gemini消失Consumer Web (Chrome 内置)Chrome 浏览器版本需 ≥ 124且设备地区需在 Google 开放服务的国家/地区列表内使用了非官方渠道下载的 Chrome、或系统区域设置为不支持的地区如某些亚洲国家最简单的验证方法在 Chrome 地址栏输入chrome://settings/search#gemini如果页面存在且开关可操作说明基础环境OK。否则请卸载所有非官方 Chrome从官网下载最新版。api error: 400 this models maximum context length is 1048565 tokens. however...Vertex AI REST APIREST API 请求体格式错误特别是contents字段的嵌套结构将contents直接设为字符串如Hello而非符合规范的{role: user, parts: [{text: Hello}]}数组结构这是新手最常犯的错误。REST API 的contents是一个数组每个元素代表一个“消息片段”必须包含role和parts。SDK 会自动帮你封装但如果你手写 curl就必须严格遵循 JSON Schema。这张表是我过去半年里帮超过 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 TierGoogle Cloud 项目是你在云端的“数字身份证”当你不再满足于和 Gemini “聊聊天”而是想把它集成进你的 SaaS 产品、内部知识库或自动化工作流时你就必须进入 Enterprise Tier——也就是 Google Cloud 的 Vertex AI 平台。这里的认证是一场彻头彻尾的“企业级”流程它要求你拥有一张在 Google Cloud 生态中被广泛认可的“数字身份证”一个配置完备的 Google Cloud 项目。这个过程远比 Consumer Tier 复杂但也更加透明和可控。它由四个环环相扣的步骤组成缺一不可项目创建与 Billing 绑定这是整个大厦的地基。你必须登录 Google Cloud Console 创建一个全新的项目强烈建议不要用你的个人主项目以防误操作影响其他服务然后为其绑定一个有效的 Billing 账户。这里有一个极易被忽略的细节Billing 账户的“状态”必须是Active而不仅仅是“已关联”。我曾遇到一个客户他的 Billing 账户因为信用卡过期被 Google 自动暂停了 24 小时导致所有 API 调用都返回402 insufficient balance而控制台的提示却非常模糊花了整整一天才定位到这个根源。API 启用地基打好后你需要为这个项目“安装”Gemini 的能力模块。在 Console 的左侧导航栏进入APIs Services Library搜索Vertex AI API并点击启用。注意这里启用的是Vertex AI API而不是Generative Language API后者是旧版已逐步淘汰。启用后系统会自动为你创建一个名为vertex-ai的服务账号这是后续所有操作的执行主体。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 官方推荐的、最小权限原则下的最佳实践。服务账号密钥可选但推荐对于本地开发或 CI/CD 流水线你可能需要一个长期有效的凭证。这时你应该回到IAM Admin Service Accounts页面找到刚才创建的vertex-aiyour-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, fADC 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_PROJECTyour-project-id-123456 export GOOGLE_CLOUD_LOCATIONglobal export GOOGLE_GENAI_USE_ENTERPRISETrue # 然后运行你的 Python 脚本 python my_gemini_app.py注意在 Windows 的 PowerShell 中语法略有不同$env:GOOGLE_CLOUD_PROJECTyour-project-id-123456 $env:GOOGLE_CLOUD_LOCATIONglobal $env:GOOGLE_GENAI_USE_ENTERPRISETrue3.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(levellogging.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( categoryHarmCategory.HARM_CATEGORY_HARASSMENT, thresholdHarmBlockThreshold.BLOCK_ONLY_HIGH, ), SafetySetting( categoryHarmCategory.HARM_CATEGORY_HATE_SPEECH, thresholdHarmBlockThreshold.BLOCK_ONLY_HIGH, ), SafetySetting( categoryHarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, thresholdHarmBlockThreshold.BLOCK_ONLY_HIGH, ), SafetySetting( categoryHarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, thresholdHarmBlockThreshold.BLOCK_ONLY_HIGH, ), ] # 构建生成配置 config GenerateContentConfig( temperaturetemperature, max_output_tokensmax_output_tokens, safety_settingssafety_settings, ) # 对于需要代码执行的复杂任务启用 Code Execution 工具 # tools [Tool(code_executionToolCodeExecution())] # 发起请求 response client.models.generate_content( modelmodel_id, contentsprompt, configconfig, # toolstools, # 取消注释以启用代码执行 ) # 检查响应状态 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(fGemini finished with reason: {candidate.finish_reason}) return candidate.content.text except Exception as e: logger.error(fGemini 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_idgemini-3.1-pro, prompt请用中文用不超过100字解释什么是量子纠缠。, ) print(✅ 响应:, result) # 测试一个需要代码执行的复杂任务取消注释 tools 行后启用 # result call_gemini_with_safety( # client, # model_idgemini-3.1-pro, # prompt计算斐波那契数列的第 30 项并找出小于它的最大质数。, # tools[Tool(code_executionToolCodeExecution())], # ) # print(✅ 响应:, result)这段代码的价值不在于它实现了什么功能而在于它体现了生产环境的思维防御性编程对response.candidates进行空值检查对finish_reason进行日志记录。错误分类将模糊的Exception映射为用户可理解的、可操作的错误信息如❌ API Error 400。安全优先默认启用了SafetySetting防止模型输出有害内容。配置化将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-genai0.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_urigcs_uri, mime_typeimage/png, # 必须与实际文件类型匹配 ) # 将文本 Prompt 和图像 Part 组合成一个消息 contents [ prompt, image_part, ] response client.models.generate_content( modelgemini-3.1-pro, contentscontents, ) return response.text # 使用示例 # result analyze_image_from_gcs( # client, # gcs_urigs://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_okTrue) # 构建配置明确指定需要 TEXT 和 IMAGE 两种模态 config GenerateContentConfig( response_modalities[Modality.TEXT, Modality.IMAGE], # 可以设置更高的 candidate_count 来获得多个备选 candidate_count1, ) response client.models.generate_content( modelgemini-3.5-flash-image, contentsprompt, configconfig, ) # 解析响应 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, promptA photorealistic portrait of a wise old owl wearing glasses, sitting on a stack of ancient books, in a cozy library with warm lighting., output_dirgenerated_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中添加一个Toolfrom google.genai.types import Tool, ToolCodeExecution # 在你的 config 构建中加入 config GenerateContentConfig( tools[Tool(code_executionToolCodeExecution())], temperature0.0, # 为了确定性温度设为 0 ) response client.models.generate_content( modelgemini-3.1-pro, contents请分析附件中的 sales_data.csv找出销售额最高的五个城市并用 matplotlib 绘制一个柱状图。, configconfig, ) # 获取执行结果 if response.executable_code: print( 生成的代码:) print(response.executable_code) if response.code