概要

Gemini 3.1 Pro是Google DeepMind于2026年2月推出的旗舰级多模态大语言模型。ARC-AGI-2得分77.1%，SWE-Bench Verified 80.6%，GPQA Diamond 94.3%，在推理能力和代码生成上相比前代有明显提升。本文面向开发者，从零开始讲解Gemini 3.1 Pro的代码接入方式，覆盖Python SDK安装、基础调用、多模态输入、流式输出、参数调优、错误处理六个模块，每个模块附带可运行的代码示例。想一站体验Gemini 3.1 Pro等主流AI模型的，可以去AI聚合平台上看看，一个页面就能找到多个模型的调用入口。

---

整体架构流程

Gemini 3.1 Pro的代码调用架构分为四层。

第一层：认证层。 通过API Key完成身份验证。每次请求在Header或SDK配置中携带密钥，Google通过密钥鉴权和计费。

第二层：请求构建层。 构造请求体，包含模型标识符、提示词内容、生成参数（温度、输出长度、安全阈值等）。支持文本、图像、音频、视频等多种输入模态。

第三层：模型推理层。 请求发送到Google的推理服务器，Gemini 3.1 Pro的MoE架构根据输入复杂度动态激活专家模块。支持低/中/高三级思考模式，复杂推理任务使用"高"模式可获得更深度的分析。

第四层：响应解析层。 模型返回JSON格式的响应，包含生成文本、token消耗、安全过滤结果等。开发者提取所需字段后集成到应用中。

---

技术名词解释

API Key： 调用Gemini API的身份凭证。在Google Cloud Console的APIs & Services页面创建。注意限制Key的调用范围和来源IP，不要提交到公开仓库。

google-generativeai： Google官方提供的Python SDK包。封装了HTTP请求细节，开发者用几行代码就能完成Gemini API调用。通过pip install google-generativeai安装。

generate_content： SDK中的核心方法。接收提示词和配置参数，返回模型的生成结果。支持文本输入、多模态输入和流式输出。

temperature： 输出随机性控制参数，值域0到2。代码生成建议0.2到0.4保证确定性，创意任务可调到0.7到0.85。超过1.5容易出现语义断裂。

max_output_tokens： 单次输出的最大token数。代码生成场景建议4096，避免长代码被截断。输入token越多，可用输出token会被动态压缩。

system_instruction： 全局角色设定。在模型实例化时注入，作用于该实例的所有后续调用。比如"你是资深后端工程师，输出代码风格遵循PEP8"。

safety_settings： 安全过滤器配置。默认过滤较严格，技术文档和代码场景中某些术语可能被误拦截。建议根据业务场景调低相关类别的阈值。

thinking_mode： Gemini 3.1 Pro的三层思考机制。"低"模式适合简单格式转换，"中"模式适合常规代码生成，"高"模式适合复杂架构设计和多步调试。模式越高消耗token越多。

Stream（流式输出）： 模型边生成边返回结果，不需要等全部生成完毕。适合需要实时显示生成过程的交互场景。SDK中通过stream=True参数开启。

---

技术细节

一、环境准备与SDK安装

首先确保Python版本3.9以上。推荐在虚拟环境中安装，避免依赖冲突。

安装SDK只需一行命令：pip install google-generativeai。安装完成后在代码中import即可。

配置API Key有两种方式。推荐方式是设置环境变量export GOOGLE_API_KEY="你的密钥"，SDK会自动读取。也可以在代码中通过genai.configure(api_key="...")直接配置，但泄露风险较高。

验证安装是否成功：导入包后执行genai.list_models()，如果返回模型列表说明环境配置正确。

二、基础文本生成

最基本的调用方式：创建模型实例→调用generate_content方法→打印结果。

模型标识符指定为gemini-3.1-pro。不要写成gemini-2.5-pro或其他版本号，写错会返回404。

generate_content方法接收一个字符串参数，就是你的提示词。返回值的.text属性包含模型的文本输出。

首次调用建议用简单提示词测试，比如"用Python写一个快速排序"。验证密钥有效、网络通畅、模型可达三件事。

三、配置生成参数

通过GenerationConfig对象配置参数，传入generate_content方法的generation_config参数中。

temperature控制输出随机性。代码生成建议0.3，确保输出稳定可复现。

max_output_tokens控制输出长度。简单函数设1024够用，完整类或模块建议4096。设太小会截断，设太大增加成本。

top_p和top_k控制采样范围。一般不需要手动调整，用默认值即可。对输出多样性有特殊需求时可以微调。

stop_sequences指定停止生成的标记。比如设置stop_sequences=["```"]可以让模型在代码块结束后停止，避免生成多余的解释文字。

四、系统指令注入

在创建模型实例时通过system_instruction参数注入全局角色设定。

一个代码场景的实用设定："你是一位资深全栈工程师。输出代码风格遵循对应语言的最佳实践。每个函数附带docstring。复杂逻辑附带行内注释。只输出代码，不输出解释文字。"

注入后该实例的所有后续调用都会遵循这个设定。不需要每次提示词中重复写要求。

注意长度不超过2048字符。过长的system_instruction会压缩可用的输入空间。

五、多模态输入

Gemini 3.1 Pro支持图像输入，可以直接上传截图让模型分析。

用PIL库打开图片，传入generate_content方法的参数列表中。提示词和图片作为同一个参数列表的两个元素传入。

实用场景：上传UI设计稿截图，让模型生成对应的前端代码。上传数据库ER图，让模型生成建表SQL。上传手写算法草稿，让模型转成可执行代码。

图像输入支持JPEG、PNG、GIF、WebP格式。单张图片建议控制在5MB以内。Base64编码后传递，SDK会自动处理。

六、流式输出

通过stream=True参数开启流式输出。generate_content方法返回一个迭代器，逐块输出生成结果。

在for循环中遍历迭代器，每个chunk的.text属性包含当前块的文本。实时打印即可实现打字机效果。

流式输出在两个场景下特别有用。一是交互式代码生成，用户可以边看边决定是否需要中断。二是长代码生成，避免等待时间过长导致请求超时。

七、多轮对话

通过ChatSession实现多轮对话。模型会自动维护对话历史，保持上下文连贯。

创建ChatSession后，用send_message方法发送消息。每次发送时模型会参考之前的对话历史生成回复。

多轮对话在代码调试场景下很实用。第一轮让模型生成代码，第二轮让它修复Bug，第三轮让它优化性能。模型会记住之前的代码上下文，不需要每次重新描述。

注意对话历史会持续消耗token。超过一定轮次后总token数可能接近上下文窗口上限。建议超过10轮后开启自动截断或手动清理早期对话。

八、错误处理

API调用需要处理几类常见异常。

APIError：密钥无效或服务未启用。检查API Key和Generative Language API是否已启用。

ResourceExhausted：触发速率限制。建议做指数退避重试——第一次等1秒，第二次等2秒，第三次等4秒，最多重试5次。

InvalidArgument：请求参数格式错误。检查模型标识符、token限制、输入格式是否正确。

安全过滤拦截：输出不完整且包含安全警告。通过safety_settings调低相关类别的阈值。

建议在生产环境中用try-except包裹所有API调用，记录完整的错误信息到日志中，方便排查。

---

小结

Gemini 3.1 Pro的代码接入并不复杂。核心流程就是：安装SDK→配置密钥→创建模型实例→调用generate_content→解析结果。

几个关键提醒。第一，模型标识符写gemini-3.1-pro。第二，代码场景temperature建议0.2到0.4。第三，system_instruction注入角色设定能显著提升输出质量。第四，流式输出和多轮对话在交互场景下体验更好。第五，错误处理必须做，尤其是速率限制和安全过滤。

100万token的上下文窗口是Gemini 3.1 Pro的结构性优势。可以一次性输入整个项目的多个文件，理解文件之间的依赖关系。这对代码审查、重构、文档生成等需要全局视角的任务来说很重要。

定价方面，每百万输入token仅需2美元。对需要频繁调用API的开发工作流来说成本可控。

如果不想折腾Google Cloud注册和API Key管理，也可以通过AI聚合平台一个入口直接体验多个模型。对比不同模型在同一个任务上的表现，找到最适合自己场景的方案，再决定要不要走官方API接入。

建议从你手头正在开发的项目中挑一个小模块，用Gemini 3.1 Pro做一次完整的代码生成或审查。跑通了再接入日常开发流程。适合自己技术栈的才是值得投入的。

---

以上为个人实测经验总结，具体代码和参数可能因SDK版本更新而有变化。