Gemini 3 Pro入门教程：从零开始学会使用最新gemini-3-pro-preview API接入

Gemini 3 是 Google 发布的新一代大型多模态模型（LLM），代表了其在 推理（reasoning）、多模态理解、agent 能力 和 编程协作 等方面的重要进展。官方将其称为 “最智能的模型家族”，特别为复杂任务（复杂推理、代理式工作流、跨模态任务）设计。 

Gemini 3 Pro（目前以 gemini-3-pro-preview 为主要标识）是该系列在开发者 API 中的首个模型。 

• 它拥有 超大上下文窗口：输入上下文可达 1 百万 token，输出上下文则上限为 64K token。 

• 它的知识截止点为 2025 年 1 月。

---

Gemini 3 的核心能力与特性

下面是 Gemini 3 的几个关键特性，以及这些特性为开发者或产品带来的潜在价值。

 推理 (“Thinking Level”)

• Gemini 3 引入了 thinking_level 参数，用以控制内部推理深度。 

  • low：最低推理深度，主打 低延迟 / 低成本，适用于简单指令处理或高吞吐应用。 

  • high（默认）：启用更深层次的思考，能生成更严谨、经过推理的回答，但首次 token 生成可能更慢。 

  • 文档中提到 medium 级别将在未来支持，但在初期版本尚未启用。 

这个设计使得开发者可以根据自己应用对响应速度、成本和推理质量之间做权衡。

多模态 (“Media Resolution”)

• 引入了 media_resolution 参数，可以对输入的图像、PDF、视频等进行分辨率控制，以平衡 质量 vs token 使用 vs 延迟。 

• 支持三个级别：media_resolution_low、_medium、_high，默认由系统根据媒体类型选取。 

• 推荐设置（官方建议）：

  • 图片（image）：用 high 来获得最高细节（token 上限 1120） 

  • PDF 文档：medium（token 上限 560）通常已足够 OCR 和理解多数文档结构 

  • 视频：

    • 常规动作识别 /描述场景：low（70 token / 帧）足够 

    • 对于帧中包含大量文字或细节（例如 OCR）：high（280 token / 帧）更合适 

这种分辨率控制对那些对视觉理解要求高（如文档分析、OCR、视频理解）的应用特别有意义。

Thought Signatures（思考签名）

• Gemini 3 使用 思考签名（thought signatures） 来在 API 调用中维持模型内在推理状态。 

• 这是模型内部“思考过程”的加密表示（signature），当你在下一轮对话中返回这个签名时，模型能更连贯地“记住”之前的推理链。 

• 在函数调用 (function calling) 场景中，这些签名是严格验证 (strict validation) 的：如果缺失会报 400 错误。 

• 在标准聊天或文本生成中，如果没有签名虽然不报错，但省略会降低推理质量。 

• 使用官方 SDK（Python / Node / Java）时，这些签名大多数时候自动管理，你不一定要手动处理。 

这个机制表明 Google 强调 持续的内部推理状态管理，使得 Gemini 3 在多轮交互中能够保持较强的一致性和深度。

温度 (Temperature)

• 官方建议 不要修改温度 (temperature)，保持默认值 1.0。 

• 原因是 Gemini 3 的推理能力是在默认温度下经过优化的：降低温度反而可能导致意外行为（例如重复、循环、推理质量下降）。 

这跟以前有些模型通过调温度来调整“创造性 vs 确定性”的做法不同：Gemini 3 更推荐用 thinking_level 来调节行为，而不是靠温度。

Structured Outputs & 工具调用 (Function Calling)

• Gemini 3 支持结构化输出 (structured output)，可以结合各种工具使用。 

• 支持 Google 自己的工具 (如 Google Search, URL Context, Code Execution) 以及自定义函数调用 (function calling)。 

• 通过这些能力，Gemini 3 可以以“agent”身份参与任务：既能理解上下文，也能执行外部操作 (搜索、执行代码等)。

迁移与兼容性

• 如果你之前在用 Gemini 2.5 Pro：官方建议把 thinking_budget（旧参数）迁移为新的 thinking_level 参数。 

• 如果你的旧代码里设置了 temperature（特别是很低温度以求确定性输出）：建议删掉此项，恢复到默认 1.0，以避免一些复杂任务出现问题。 

• 文档理解 (如 PDF) 时，因为默认 OCR 分辨率变化，建议测试新的 media_resolution_high 是否对你有帮助。 

• 旧版本模型中一些图片分割 (image segmentation) 功能在 Gemini 3 Pro 里 不支持。对于需要像素级分割 (mask) 的任务，目前推荐继续使用 Gemini 2.5 Flash 或其他专门模型。 

---

Gemini3详细分析与对比​

Gemini-3主要特性与技术革新

• 原生多模态：支持文本、图片、代码、音频等多类型输入与理解，尤其在图像场景分析、视频内容推理、音频转文本等方面有重大提升。​

• 超长上下文窗口：可一次处理高达百万 Token 的数据，远超上一代 Gemini 2.5 Pro，提升了长文本和复杂代码的处理稳定性与完整性。​

• 代码生成能力：前端应用、SVG 结构性代码可一次性生成，支持动画和响应式设计，在实际开发测试中能够直接生成完整游戏和应用逻辑。​

• 智能体 AI Agent 能力：自动化任务编排、多工具串联、浏览器内容抓取、第三方 API 调用等，让 AI 能主动操作实现任务，不再只是被动问答。​

Gemini-3实测表现与性能分析

• 推理和规划能力有代际级飞跃，在 “Agent工具使用与长期任务” 基准测试中显著超越 GPT-5.1。​

• 多模态推理（MMMU-Pro 测试 81%，Video MMMU 87.6%）以及场景识别等 AI 评测项目都达到同类最佳。​

• 大幅优化 API 响应速度（延迟低于 1.8 秒），代码和文本处理更高效。​

Gemini-3局限性与注意事项

• Preview 处于预览阶段，稳定性和模型行为尚在快速迭代，暂不推荐关键生产环境落地。​

• 未来可能上线更大的窗口、更快推理、更深专业领域能力，加强与 Google 生态工具和行业定制版本的结合。​

Gemini-3与竞品对比

项目	Gemini 3 Pro Preview	GPT-5.1（OpenAI）	Claude 4.5 (Anthropic)
上下文窗口	百万级	百万级（部分版本）	百万级
多模态支持	原生（强）	多模态（强）	多模态（较强）
代码生成能力	前端与 SVG 极强	全栈代码生成	文档代码生成为主
Agent智能体能力	自动工具调配，长期任务领先	初步支持，可靠性较低	初步支持，任务串联较弱
性能评分（LMArena）	1501分（最高）	1432分	1375分

 

Gemini-3-Pro-Preview 以其百万上下文、多模态原生推理、卓越的代码与任务自动化能力，成为目前 Google 生态和全球 AI 领域的旗舰产品。特别适合需要复杂推理、跨模态分析和自动化工作的场景，但作为预览版，建议持续关注其稳定性和新功能进展。​

 

应用场景分析

基于上述能力，Gemini 3 在很多场景中展现出优势，同时也有需要注意或限制的地方。

优势场景

1. 复杂任务与长对话/长文档分析

   • 1 百万 token 的上下文窗口使其可以处理非常长的文本 (比如整本书、庞大的数据、复杂对话历史)。

   • 对于需要深入推理 (e.g. 战略规划、多步推理、法律 / 研究类任务)，“high thinking level” 能带来更准确、连贯的输出。

2. 多模态理解

   • 在图像、PDF 文档、视频等上有灵活控制的分辨率，适合图文混合、文档 OCR、视频内容分析等场景。

   • 例如文档自动化 (合同分析、报告解析)、图像理解 (产品照片、设计稿解读)、视频摘要 /分析，都可以利用 Gemini 3 的多模态处理能力。

3. Agent 驱动工作流

   • 结合 function calling 与工具 (Search, URL, code execution)，Gemini 3 可以作为“智能代理 (agent)”参与任务：自动查资料、执行代码、生成计划。

   • 这对于开发者工具 (IDE 自动生成代码、修复 bug)、自动化任务 (如日常办公自动化、数据处理) 非常有吸引力。

4. 编程协作

   • 在 “agent-first” 编码平台中 (例如 Google Antigravity) 使用 Gemini 3，可以让 agent 自主地在编辑器、终端、浏览器间工作，为开发者构建、调试、计划任务等。 

   • 对开发者来说，这可以大幅提升效率，同时保持对最终结果 (计划、代码) 的可审查性。

5. 空间/视觉推理

   • Gemini 3 强化了空间推理能力 (spatial reasoning)，支持复杂的实体、运动轨迹、任务进展判断。 

   • 对于机器人 (robotics)、虚拟现实 (XR)、智能屏幕理解 (如分析桌面 / 移动屏幕上的布局和用户操作) 等应用尤为适合。

6. 视频理解

   • Gemini 3 Pro 对高速场景 (fast actions) 的视频理解能力增强，并能在长视频中回忆上下文 (长上下文回顾)，适合视频摘要、监控分析、行为识别。 

可能的挑战 / 限制

1. 成本与延迟

   • 虽然 thinking_level 可调，但如果使用高思考 (high)，首次响应可能较慢且成本较高。

   • 高频使用大上下文 /高媒体分辨率可能带来较高的 token 成本。

2. 签名 (Thought Signature) 管理

   • 虽然 SDK 会自动处理大多数情况，但如果你自己管理对话逻辑 (尤其是函数调用、工具调用)，还要注意正确传递和验证签名，否则可能影响推理质量或出错。

3. 温度灵活性受限

   • 推荐锁定 temperature = 1.0，意味着创造性调节 (更保守或更随机) 空间可能受限。

4. 特定任务模型适配

   • 虽然 Gemini 3 在很多方面表现强，但某些专用任务 (如像素级图像分割) 可能不如专门模型 (例如某些专用视觉 /分割模型) 高效。

5. 文档迁移成本

   • 从旧版本 (如 Gemini 2.5) 迁移可能需要调整 prompt 逻辑 (思考层级、温度、媒体分辨率等)。

   • 开发者需要重新测试对话质量、多模态输入、工具调用等。

6. 用户可用性 /权限

   • 有用户反映 Gemini 3 Pro 的接入受限 (例如在某些客户端或订阅级别才可用)。比如有用户说在 Gemini CLI 里需要 Ultra 计划。 

   • 文档、SDK 等对初学者可能有一定学习成本。

---

结合生态：Gemini 3 在 Google 生态中的作用

• Gemini App：Google 在 Gemini App 中引入了 Gemini 3，带来更智能的对话、更强的多模态理解、新界面 (如视觉布局、动态视图) 以及实验 agent。 

• Google Antigravity：一种以 agent 为核心的开发平台，使用 Gemini 3 Pro 支持多智能体 (agents) 在编辑器、终端、浏览器之间协作。 

• Vertex AI：Gemini 3 API 可通过 Google Cloud (Vertex AI) 调用。文档中有快速上手步骤，包括安装 GenAI SDK、设定环境等。 

• 工具整合：通过 function calling，Gemini 3 可以和 Google 自己的工具 (Google Search, URL 上下文等) 紧密集成，为开发者构建智能 agent 或 RAG (retrieval-augmented generation) 系统提供基础。

---

如何快速接入Gemini3 API

常见的调用大型语言模型（LLM）API 方式主要包括：

直接对接官方 API

例如：

• Google Gemini 官方 API

• OpenAI 官方 API

• Anthropic Claude 官方 API

这种方式优点是最原生，但缺点是 成本高、速度不稳定、还可能存在地区访问问题。

---

使用第三方中转 / 代理 API（推荐）

第三方中转服务通常提供：

• 统一的 API 协议（兼容 OpenAI 格式）

• 支持多种模型（Gemini 系列、GPT 系列、Claude 系列、本地模型等）

• 更便宜、更快、稳定可靠

➡️ 神马中转 API 就属于这一类，可以把多家模型统一成 /v1/chat/completions 格式。

无论你使用什么模型，只需要换：

"model": "模型名称"

即可切换。

如何对接「神马中转 API」

神马中转 API 提供一个 OpenAI 协议兼容的接口：

POST https://api.whatai.cc/v1/chat/completions

这意味着：

👉 你可以直接把 OpenAI 的代码粘过去就能跑

👉 只需要改两个地方：域名 + 模型名

通用 Python 调用方式（用于对接神马中转 API）

下面基于你提供的代码，做了针对“神马中转 API”的完整示例。

只需要填写你的中转接口域名和 key。

通用 Python 代码（适用于所有模型，包括 Gemini 3）

import http.client
import json

# 1. 修改为你的神马中转 API 域名，例如：
#https://api.whatai.cc/
conn = http.client.HTTPSConnection("你的中转API域名")

payload = json.dumps({
    "model": "gemini-3-pro-preview",  # 只需要在这里切换模型名
    "messages": [
        {
            "role": "user",
            "content": "你好，请介绍一下 Gemini 3"
        }
    ],
    "temperature": 1,
    "top_p": 1,
    "stream": False,
    "max_tokens": 2048
})

headers = {
    'Accept': 'application/json',
    'Authorization': 'Bearer 你的API_KEY',
    'Content-Type': 'application/json'
}

conn.request("POST", "/v1/chat/completions", payload, headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

---

🔄 如何切换不同模型（只改 model 参数）

示例：

模型类型	model 示例
Gemini 3	"gemini-3-pro"
Gemini 2.0 / 1.5	"gemini-2.0-pro" / "gemini-1.5-flash"
GPT 系列	"gpt-4o-mini" / "gpt-4.1"
Claude 系列	"claude-3-5-sonnet"
DeepSeek 系列	"deepseek-chat" / "deepseek-reasoner"
本地模型/自由模型	"qwen2-72b" / "llama3.1-70b"

🌟 只换 model 名即可，无需改代码。

兼容性总结

内容	支持
OpenAI API 兼容	✔
/v1/chat/completions	✔
流式返回（SSE）	✔
多模型切换	✔
多模态（图像、文件、PDF）	取决于中转服务是否启用

也可以在首页-操练场可视化试用

Gemini 3 Pro常见问题解答

Gemini 3 Pro 的知识截止日期是什么？Gemini 3 的知识截止日期为 2025 年 1 月。如需了解最新信息，请使用搜索基础工具。

上下文窗口有哪些限制？Gemini 3 Pro 支持 100 万个 token 的输入上下文窗口，输出最多可达 6.4 万个 token。

Gemini 3 Pro 是否有免费层级？您可以在 Google AI Studio 中免费试用该模型，但目前 Gemini API 中没有 gemini-3-pro-preview 的免费层级。

我的旧 thinking_budget 代码是否仍然有效？可以，为了实现向后兼容性，我们仍支持 thinking_budget，但建议您迁移到 thinking_level 以获得更可预测的性能。请勿在同一请求中同时使用这两个参数。

Gemini 3 是否支持 Batch API？可以，Gemini 3 支持批量 API。

是否支持上下文缓存？可以，Gemini 3 支持上下文缓存。启动缓存所需的最低 token 数为 2,048 个。

Gemini 3 支持哪些工具？Gemini 3 支持Google 搜索、文件搜索、代码执行和网址上下文。它还支持标准函数调用，以便您使用自己的自定义工具。请注意，Google 地图和电脑使用目前不受支持。

 

总结：Gemini 3 是 Google 在其 LLM 产品线上的一次重大升级。它将更深层次推理、多模态理解 (图像、视频、文档)、agent 能力 (自动执行任务)、以及高容量上下文 (百万级 token) 融合在一起，面向复杂、高级应用场景。

潜力：对于开发者而言，它提供了构建 “智能代理 + 自动化系统 + 高级分析工具” 的能力。对用户而言，它能带来更自然、智能、多样化的交互。

挑战：成本、签名管理、迁移门槛、访问权限等仍是需要考虑的问题。

未来方向：随着更多用户和开发者使用 Gemini 3，我们可能会看到更多创新型 agent 工具 (尤其在编码、研究、自动化领域)，以及更深入整合 Google 云服务 (搜索、数据、计算) 的产品。