Gemini 3 開發人員指南
发布于 2025-11-22 23:07:52（微信公众号导出记录）。
本文来自公众号后台的“导出文章内容”功能。博客正文由导出长图进行本地 OCR 转写，并保留原始排版图用于逐段核对。
原文链接：查看原文
OCR 转写有效文字约 5971 字；代码、流程图和版式以文末原始排版图为准。
正文（本地 OCR 转写）
original wex7ce EI V1ajero 2025年11月22日 23:08 中国香港 这是一份根摊官方文件整理的Gemini3完整开發指南,本指南涵蒸了模型介绍、核心新功能 (如思考層级、思维签章)、Python/Node.js/REST API的完整調用箱例,以及遵移與最 佳實晚。 Genini 3是Google目前显强大的模型系列,專為进腐推理、代理工作流程[Agentic Workflows)和褪離的多模感任移而設計。
1.模型概舆定價
Genin13目前提供雨個主要预質版模型。 输入俱格(每百 输出俱格(每百 知撒截止 模型ID(model) 通用場景 Token) 高Token) 12(<=200k) 2(<=200k) gemini-3-pro-p 2025年 推理、编 review 碼、多模舰分析 1月 4 (>280k) 18 (>208k) gemini-3-pro-i 2025年 图像生成奥编 $0.134/張 $2(文字输入) mage-preview 租、文字科图像 1月 (图片输出) 基本规格:
-
Context Window(服窗口):109萬Token(输入)/64kToken(输出)。
-
API版本:建使用VlaLpha或vlbeta以携取显新参数支援
2.核心新功能解
Genini3引l入了三图厢键的新参数,这與善版模型(如Gemini1.5/2.5)有很大不同。 A.思考層级(thinking_level) 控制模型在回愿前的推理深度:。注意:請勿奥蓄版thinking_budget混用。
-
ow:速度快、成本低。遗合篇单指令、聊天或高春吐量度用。
-
high(预段):深度推理。模型會花更多時“思考:以產出高品置结果。
B.媒體解析度(media_resolution) 控制输入医片或影片的虐理精组度。运窄影署Token用量與磁别细前的能力。
-
medla_resolution_Low:適合—般影片助作罐剧。
-
medla_resolution_nediun:適合一般文件理解(PDF)。
-
media_resolution_high:適合密集文字(OCR)或需要滋别片微小细即的场景。
-
Token 用量:图片显高1120 tokens(High),影片每帕最亮 286tokens。
C.温度(temperature) 量要建:保持预設值1.0。Gemini3的推理能力已针封预设值優化,降低运度(例如设 为0.1)可能會導致模型陷入退图或推理能力下降。 D.思維签章(thoughtSignature) 遍是一個加密的字申,代表模型的内部思考透程。
-
用途:在多输到活、函式呼叫(FunctionCalLing)或像端辑中维持上下文。
-
规则:你必须将徙API收到的thoughtSignature原封不勤地在下一次請求中儒回给
模型,否则會报錯(HTTP 4BG)或幕致智力下降。
- SDK 自動虚理:如果使用官方 Python/Noce.js SDK 排癌 Chat History,SDK
會自動虚理。RESTAPI需手肋虚理。
3.基確文字生成與推理例
以下展示如何調用Gemini3逾行程式碼分析或推理任務。 Python (google-genai SDK) Teu5 1uodut #166 uo fron google.genai inport types client = genai.Cllent (api_key=YoUR _API_KEY) response - client.nodels.generate_content( ',mataud-od-c-Tuusb,=lapou contents="找出温段 C++程式码中的RaceCandition:[在此贴上程式码]", config=types.Generatecontentconfig( 段定思考雁级(预股為high) thinking_level="high, 保持湿度码1.0 temperature=1.0
print (response.text)
JavaScript / Node.js (@google/genai SDK)
inport { GoogleGenAI } fron *egoogle/genai°;
const ai = neM GoogleGenAI{{ apiKey: "YOuR API KEY- });
async function run(} {
const response = await ai.models.generateContent({
conteats:“解耀量子病的源理。就曾霞是五小孩一檬。。
}:u
thinkingLevel:“low,//需單任務使用lov以额省感本
},
}1;
console.log(response.text);
run () ;
REST API (cURL)
curl "https://generativelanguage-googleapis.con/vlbeta/models/genin1-3
,uos/uotne3T1dde :ad-1uauo. H-
X P05T\
- d
"contents*:[{ “parts":【(“text":“适段Python 代码有什磨谱在的資安风险?"}] }1, "generationconfig": { "thinkingLevel": "HIGH"
4.多模態:圆片理解與解析度控制
使用media_resolution来控制如何端取图片。 Python fron google inport genai fron google.genal Inport types inport base64
假超你有 inage_data (bytes) 顾取图片通辑 response = client.nodels.generate_content( nodel="genini-3-pro-preview*, contents=[ types.Content( parts=[ types.Part{text=值摄片的票金额是多少?), types. Part( Inline_data=types Blob( mime_type="inage/jpeg*, data=base64.b64decode(YOUR_BA5E64_STRING), ), 段定高解析度以造行精殖OCR nedia_resolution-{"level*: *nedia_resolution_high"
1se , text)
REST API
curl "https://gencrativelanguage-googlcapis.con/vlalpha/modcls/gcnini-
1,uos /uotet1dde :ad1-uaqu0, H-
- X POST \
).p 1:,s1ua100 "parts#: [ {“tcxt”:“描述这强国片的细”}, { "inlineData": { "nincType": "inage/ipeg", "data*: "BASE64_ENCODED_IMAGE_STRING* }。 "nediaRcsolution':{ "level': "media_resolution_high"
5.结構化输出(JSONMode)與工具使用
Gen1n1 3 支援透遥 Schena 定羲格的 JSoN 输出,亚结合 Google Search 工具。 Python (Pydantic 整合) fron google 1mport gena1 from pydantic inport BaseNodel, Field fron typing inport List 定兼输出的资料结情 class MatchResult(BeseModel): winner: str = Fleld(description="者名辑") scorers:List[str]= Field(description==得分球具名单*) client = genai.Client (api_key=YoUR API KEY) response = client.nodels.generate_content( nodel="genini-3-pro-preview, contents="强导最新的欧洲杯法薇结果。“, conf1g={ 款用Google搜导工具 "toals*: [{"google_search: 0}], 播定赖出格式J50N整定Schema "response _nime_type': application/json, "response_json_schema*: MatchResult.nodel_json_schema(),
睡频益臀换结果 result = MatchResult.model_val.idate_son(response. text) print (result) JavaScript (Zod 整合) Teuab/abooa, wo { Ivuagoboo ] lodut inport {z } fron *zod"; iszuayos-us[-ui-paz, uo ruauosuosoipoz ] rradu const a1 = new GoogleGenAI{f apiKey: "YouR_API_KEY- }): const matchschena - z.object({ score: z.string(), async function run(){ const responsc = await ai.models.gencratecontent({ ',naTAeud-oud-E-Tutuab, :lapou config:{ tools: [< googlesearch: {} }1. responseMineType: "application/jsun", responseJsonschema : zodToJson5chcma (natchschena), }, }1; console. Log(response.text) ; run () ;
6.圆像生成(Gemini 3Image)
使用gemini-3-pro-image-previev模型。支援原生4K、生成文字(如招牌、国表),亚 可适過GoogleSearch確保生成内容符合事贰(例如:即時天氯圈)。 CURRENTWEATHERINTOKYO,JAPAN WEDNESDAY,NOVEMBER19,2025-8:49PMJST 19, 2025 - 8:49 PMJST
CURRENTLY:CLEAR 46°F 8C FEELS LIKE 8°C FEELS LIKE 46°F PRECIPITATIONCHANCE:10% HUMIDITY:66% WIND:CALM 3-DAYFORECAST FRIDAY (NOV 21) ( TOMORROW(NOV20) 13°C/55F High: 14°C/57°F High: 17°C/63°F 4°C/39°F 5°C/41°F 6°C/43°F Low: Chance of Rain:10% 公hceRa Chance of Rain:20% Python例 from google.genai import types client = genai.Client (api_key="YoUR_API_KEY") response = client.models.generate_content( contents="生成一张目前束京天氣的祝觉化資訊国表,包含温度數握。" config=types.GenerateContentConfig( 使用搜导工具取真實数據 tools=[{"google_search": {}}], image_config=types.ImageConfig( aspect_ratio="16:9", 13 image_size="4K"#原生4K支援
1. 4
.5 16 )) #存圆片 for part in response.candidates[θ].content.parts: if part.inline_data: import base64 2 1 img_data = base64.b64decode(part.inline_data.data) with open("tokyo_weather.png", "wb") as f: f.write (img_data)
7.進:手動處理思維章(ThoughtSignature)
注意:如果你使用RESTAPI或自定義的對話管理,你必须手動傅退thoughtSignatur e。 流程説明: L.Request1:使用者發送提示。
2.Response 1:模型回傅text以及thoughtSignature(通常在candidate 的内
容中)。
3.Request2:使用者發送新提示,必须在contents的歷史訊息中包含上一次模型回傅
的thoughtSignature。 退移提示:如果你要將蓄模型(如Gemini1.5)的歷史記錄逻移到Gemini3,由於蓄模型 没有章,你可以使用以下占位符来续過验證: "thoughtsignature":"context_engineeri ng_is_the_way_to_go"
8.移指南與最佳實(MigrationGuide)
Gemini1.5或2.5升级時請注意: L.簡化提示(Prompt Simplification): 技巧。
-
Gemini3已經會自動進行深度推理。過度指導反而會降低效果。
-
做法:直接下達清晰、簡漯的指令。
2.重置温度:
調低温度。
3.PDF 奥OCR:
- Gemini3的PDF處理预設解析度可能與蓄版不同。如果發現讀取文件效果不佳,請
顯式投定media_resolution:“media_resolution_high"。
- 注意:這會增加Token消耗。
1.語氣調整:
- Gemini3预設倾向於簡潔、直接的回答。如果你需要它變得「健谈或「親切」,請
在SystemInstruction或Prompt中明確要求(例如:「請以親切且健的語氣 回覆:)。 (FAQ) 常見問题
-
有免費?API目前没有免費層,但在GoogleAIStudio中試用是免費的。
-
支援BatchAPI?支援,可用於大量非即時處理以節省成本。
-
支援ContextCaching?支援,當输入Token超過2,048時可用快取。
這份指南涵菱了開始使用Gemini3所需的關鍵知識。建先 thinking_level="hig h"開始體验其推理能力,再根據需求調整至Low優化成本。
原始排版图
