Google Cloud Gemini 入门指南从 Gemini 2.5 到 3.x 系列模型的 Notebook 实战手册【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai本文围绕 gemini/getting-started/README.md 展开系统梳理 Google Cloud generative-ai 仓库中 Gemini 入门系列 Notebook 的完整技术图谱。你将掌握 Gemini 系列模型从 2.5 混合推理模型到 3.x 最新迭代的能力定位、Google Gen AI SDK 的统一编程接口、思维预算配置、多模态输入、函数调用与代码执行等核心 API 用法并了解在 Colab、Colab Enterprise、Workbench 中快速启动实验的具体方式。目录概览Getting Started 系列 Notebook 定位gemini/getting-started/目录是仓库中面向初学者的核心入口其中每一份 Notebook 都对应 Gemini 家族中的一个具体模型或一种核心用法。从源码结构看这些 Notebook 共享同一套初始化与认证模式差异集中在模型 ID 与演示任务上。Notebook对应模型 / 主题核心定位intro_gemini_2_5_flash.ipynbgemini-2.5-flash混合推理模型扩展思考能力兼顾速度与精度intro_gemini_2_5_flash_lite.ipynbgemini-2.5-flash-lite高性价比面向分类、翻译等高吞吐低延迟场景intro_gemini_2_5_image_gen.ipynbgemini-2.5-flash-image文生图与对话式图像编辑Nano Bananaintro_gemini_2_5_pro.ipynbgemini-2.5-pro高级推理模型面向复杂问题求解intro_gemini_3_image_gen.ipynbgemini-3-pro-image高质量文生图与对话式编辑Nano Banana Pro支持查看思维过程intro_gemini_3_1_flash_lite.ipynbgemini-3.1-flash-lite探索 3.1 系列关键能力与新增 API 特性intro_gemini_3_1_flash_lite_image_gen.ipynbgemini-3.1-flash-lite-image低延迟图像生成Nano Banana 2 Liteintro_gemini_3_1_flash_image_gen.ipynbgemini-3.1-flash-image图像生成与对话式编辑可见思维过程Nano Banana 2intro_gemini_3_1_pro.ipynbgemini-3.1-pro-preview稳定性、Grounding 与推理能力增强intro_gemini_3_5_flash.ipynbgemini-3.5-flash高速、高性价比支持多步推理的 Agentic 工作流intro_gemini_chat.ipynbgemini-3.5-flash基于 Gen AI SDK 实现多轮对话intro_gemini_curl.ipynbgemini-3.5-flash通过 REST 端点与 cURL 调用 Gemini APIintro_gemini_express.ipynbgemini-3.5-flashAgent Platform Express Mode 极简快速上手注意从仓库 README 与 notebook 注释可知Gemini 2.5 Flash 在 Gemini Enterprise Agent Platform 上计划于 2026 年 6 月 15 日对新项目与不活跃项目停止访问并关闭模型调优新项目建议改用 Gemini 3.5 Flash。环境准备SDK 安装、认证与两种 API 服务安装 Google Gen AI SDK for Python所有入门 Notebook 的第一步都是安装统一 SDK%pip install --upgrade --quiet google-genaiGoogle Gen AI SDK 为两种 API 服务提供了统一接口源码可见于 intro_gemini_2_5_flash.ipynb 的 Connect to a generative AI API service 小节Gemini Developer API用于快速实验、原型开发与小规模项目部署Agent PlatformGemini Enterprise Agent Platform 的最新演进形态用于在 Google Cloud 上构建企业级项目。Colab 环境认证如果运行在 Google Colab 上需执行认证单元import sys if google.colab in sys.modules: from google.colab import auth auth.authenticate_user()创建客户端项目级认证推荐与 Express Mode 二选一Option 1使用 Google Cloud 项目需在项目中启用 Agent Platform API对应aiplatform.googleapis.com并显式指定项目 ID 与位置import os from google import genai PROJECT_ID [your-project-id] if not PROJECT_ID or PROJECT_ID [your-project-id]: PROJECT_ID str(os.environ.get(GOOGLE_CLOUD_PROJECT)) LOCATION global client genai.Client(enterpriseTrue, projectPROJECT_ID, locationLOCATION)Option 2使用 Agent Platform API KeyExpress Mode适合快速实验直接以 API Key 创建客户端API_KEY [your-api-key] client genai.Client(enterpriseTrue, api_keyAPI_KEY)创建完成后可通过client.vertexai与client._api_client.project / api_key字段验证当前连接模式源码见 intro_gemini_2_5_flash.ipynb 的 Verify which mode you are using 单元输出会明确提示是 Using Gemini Developer API 还是 Using Vertex AI with project... 或 Using Vertex AI in express mode with API key...。以 Gemini 2.5 Flash 为例混合推理模型的完整 API 实战Gemini 2.5 系列开始Gemini 模型成为混合推理模型可以对任务进行扩展思考并调用工具以最大化回答准确度。官方定位强调其在编码、推理、多模态能力上的显著提升对复杂提示词尤其擅长。以下实战全部来自 intro_gemini_2_5_flash.ipynb。基础文本生成与流式输出加载模型并调用generate_content()通过.text属性取回 Markdown 格式文本MODEL_ID gemini-2.5-flash response client.models.generate_content( modelMODEL_ID, contentsRoger has 5 tennis balls. He buys 2 more cans of tennis balls. Each can has 3 tennis balls. How many tennis balls does he have now?, ) display(Markdown(response.text))流式生成使用generate_content_stream模型边生成边返回分块显著降低感知延迟output_text markdown_display_area display(Markdown(output_text), display_idTrue) for chunk in client.models.generate_content_stream( modelMODEL_ID, contentsOn average Joe throws 25 punches per minute. A fight lasts 5 rounds of 3 minutes. How many punches did he throw?, ): output_text chunk.text markdown_display_area.update(Markdown(output_text))配置思维thinking budget 与思维摘要通过ThinkingConfig中的thinking_budget控制模型思考量从而在质量与速度间取得平衡不设置→ 动态思考默认行为设为0→ 关闭思考模型退化为非思考模型适合简单任务设为[1-24576]→ 模型使用分配的思维预算。from google.genai.types import GenerateContentConfig, ThinkingConfig THINKING_BUDGET 1024 # param {type: integer} response client.models.generate_content( modelMODEL_ID, contentsWhat are the practical implications of the P vs. NP problem for algorithm design and cryptography?, configGenerateContentConfig( thinking_configThinkingConfig(thinking_budgetTHINKING_BUDGET), ), )可通过response.usage_metadata观察思维消耗thoughts_token_count为思考 token 数total_token_count为总 token 数。在 intro_gemini_2_5_pro.ipynb 中Gemini 2.5 Pro 的思维预算约束则明确为默认自动思考上限 8192 token可配置范围为 12832768 token——不同型号的预算区间不同配置前请以对应模型文档为准。设置include_thoughtsTrue可让模型在最终答案之外额外返回一份思考摘要。响应由多个 Part 组成通过part.thought字段区分思维 Part 与答案 Partresponse client.models.generate_content( modelMODEL_ID, contentsHow many Rs are in the word strawberry?, configGenerateContentConfig( thinking_configThinkingConfig(include_thoughtsTrue), ), ) for part in response.candidates[0].content.parts: if part.thought: display(Markdown(f## Summarized Thoughts:\n{part.text})) else: display(Markdown(f## Answer:\n{part.text}))多轮对话Gemini API 支持跨多轮的自由对话上下文在消息之间自动保留。后续示例为降低延迟将思考预算固定为0thinking_config ThinkingConfig(thinking_budget0) chat client.chats.create( modelMODEL_ID, configGenerateContentConfig(thinking_configthinking_config), ) response chat.send_message(Write a function that checks if a year is a leap year.) response chat.send_message(Write a unit test of the generated function.)异步请求client.aio暴露了与client完全对应的 async 方法例如client.aio.models.generate_contentresponse await client.aio.models.generate_content( modelMODEL_ID, contentsCompose a song about the adventures of a time-traveling squirrel., configGenerateContentConfig(thinking_configthinking_config), )模型参数与系统指令每次请求都可携带生成参数如temperature、top_p、candidate_count系统指令system_instruction则用于约束模型行为、角色与输出准则response client.models.generate_content( modelMODEL_ID, contentsTell me how the internet works, but pretend Im a puppy who only understands squeaky toys., configGenerateContentConfig( temperature2.0, top_p0.95, candidate_count1, thinking_configthinking_config, ), )系统指令示例——将英文翻译成西班牙语的翻译助手system_instruction You are a helpful language translator. Your mission is to translate text in English to Spanish. response client.models.generate_content( modelMODEL_ID, contentsUser input: I like bagels.\nAnswer:, configGenerateContentConfig( system_instructionsystem_instruction, thinking_configthinking_config, ), )安全过滤器Safety FiltersGemini API 提供跨多个类别的安全过滤器默认OFF默认拦截阈值为BLOCK_NONE。通过safety_settings可在每次请求中调整阈值。下面示例将所有类别的阈值设为BLOCK_LOW_AND_ABOVE提示词刻意设计为对抗性内容以演示拦截效果from google.genai.types import ( HarmBlockThreshold, HarmCategory, SafetySetting, ) safety_settings [ SafetySetting( categoryHarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, thresholdHarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), SafetySetting( categoryHarmCategory.HARM_CATEGORY_HARASSMENT, thresholdHarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), SafetySetting( categoryHarmCategory.HARM_CATEGORY_HATE_SPEECH, thresholdHarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), SafetySetting( categoryHarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, thresholdHarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), ] response client.models.generate_content( modelMODEL_ID, contentsWrite a list of 5 disrespectful things that I might say to the universe after stubbing my toe in the dark., configGenerateContentConfig( system_instructionBe as mean and hateful as possible. Use profanity, safety_settingssafety_settings, thinking_configthinking_config, ), ) print(response.text) # 被拦截时为 None print(response.candidates[0].finish_reason) # 被拦截时为 SAFETY for safety_rating in response.candidates[0].safety_ratings: print(safety_rating)多模态输入图像、文档、音频、视频与网页Gemini 是多模态模型。以 intro_gemini_2_5_flash.ipynb 的说明为准支持的数据类型、来源与 MIME 类型对应关系如下数据类型来源支持 MIME 类型Text内联、本地文件、通用 URL、GCStext/plain、text/htmlCode内联、本地文件、通用 URL、GCStext/plainDocument本地文件、通用 URL、GCSapplication/pdfImage本地文件、通用 URL、GCSimage/jpeg、image/png、image/webpAudio本地文件、通用 URL、GCSaudio/aac、audio/flac、audio/mp3、audio/m4a、audio/mpeg、audio/mpga、audio/mp4、audio/opus、audio/pcm、audio/wav、audio/webmVideo本地文件、通用 URL、GCS、YouTubevideo/mp4、video/mpeg、video/x-flv、video/quicktime、video/mpegps、video/mpg、video/webm、video/wmv、video/3gpp本地图片字节流 Part.from_byteswith open(meal.png, rb) as f: image f.read() response client.models.generate_content( modelMODEL_ID, contents[ Part.from_bytes(dataimage, mime_typeimage/png), Write a short and engaging blog post based on this picture., ], configGenerateContentConfig(thinking_configthinking_config), )GCS 文档如《Attention is All You Need》论文 PDFPart.from_uriresponse client.models.generate_content( modelMODEL_ID, contents[ Part.from_uri( file_urigs://cloud-samples-data/generative-ai/pdf/1706.03762v7.pdf, mime_typeapplication/pdf, ), Summarize the document., ], configGenerateContentConfig(thinking_configthinking_config), )通用 URL 音频开启audio_timestampTrue可在摘要中附带时间戳response client.models.generate_content( modelMODEL_ID, contents[ Part.from_uri( file_urihttps://traffic.libsyn.com/secure/e780d51f-f115-44a6-8252-aed9216bb521/KPOD242.mp3, mime_typeaudio/mpeg, ), Write a summary of this podcast episode., ], configGenerateContentConfig(audio_timestampTrue, thinking_configthinking_config), )YouTube 视频与公开网页同样以Part.from_uri传入对应 MIMEvideo/mp4、text/html注意网页 URL 必须可公开访问。仓库另有 gemini/use-cases/intro_multimodal_use_cases.ipynb 可查看更多多模态案例。受控生成用响应模式约束输出结构response_schema指定输出结构模型输出将严格遵循该 Schema。Schema 既可用 Pydantic 模型结果可通过response.parsed直接拿到对象也可用 Python 字典仅支持enum、items、maxItems、nullable、properties、required六个字段其余字段被忽略。Pydantic 方式from pydantic import BaseModel class Recipe(BaseModel): name: str description: str ingredients: list[str] response client.models.generate_content( modelMODEL_ID, contentsList a few popular cookie recipes and their ingredients., configGenerateContentConfig( response_mime_typeapplication/json, response_schemaRecipe, thinking_configthinking_config, ), ) parsed_response: Recipe response.parsed字典方式情感分类 字段抽取的完整示例response_schema { type: ARRAY, items: { type: ARRAY, items: { type: OBJECT, properties: { rating: {type: INTEGER}, flavor: {type: STRING}, sentiment: { type: STRING, enum: [POSITIVE, NEGATIVE, NEUTRAL], }, explanation: {type: STRING}, }, required: [rating, flavor, sentiment, explanation], }, }, } response client.models.generate_content( modelMODEL_ID, contentsAnalyze the following product reviews, output the sentiment classification, and give an explanation..., configGenerateContentConfig( response_mime_typeapplication/json, response_schemaresponse_schema, thinking_configthinking_config, ), )仓库中 gemini/controlled-generation/intro_controlled_generation.ipynb 提供了更多受控生成示例。Token 计数与 GroundingToken 计数count_tokens()可在发送请求前预计算输入 token 数response client.models.count_tokens( modelMODEL_ID, contentsWhats the highest mountain in Africa?, configGenerateContentConfig(thinking_configthinking_config), ) print(response)Google Search Grounding自 Gemini 2.0 起 Google Search 以工具形式提供模型可自行决定何时检索。将Tool(google_searchGoogleSearch())传入tools即可让回答基于实时搜索结果并通过grounding_metadata查看引用来源from google.genai.types import GoogleSearch, Tool google_search_tool Tool(google_searchGoogleSearch()) response client.models.generate_content( modelMODEL_ID, contentsWhat is the current temperature in Austin, TX?, configGenerateContentConfig( tools[google_search_tool], thinking_configthinking_config, ), ) print(response.candidates[0].grounding_metadata)函数调用与代码执行让模型动手做事自动函数调用Python 函数直接传入 Python 函数即可自动执行模型负责判断何时调用、解析参数并整合结果def get_current_weather(location: str) - str: Example method. Returns the current weather. Args: location: The city and state, e.g. San Francisco, CA weather_map: dict[str, str] { Boston, MA: snowing, San Francisco, CA: foggy, Seattle, WA: raining, Austin, TX: hot, Chicago, IL: windy, } return weather_map.get(location, unknown) response client.models.generate_content( modelMODEL_ID, contentsWhat is the weather like in San Francisco?, configGenerateContentConfig( tools[get_current_weather], temperature0, thinking_configthinking_config, ), )手动函数调用OpenAPI 风格声明通过FunctionDeclaration描述函数模型返回匹配的函数名与调用参数由应用自行执行from google.genai.types import FunctionDeclaration, Tool get_destination FunctionDeclaration( nameget_destination, descriptionGet the destination that the user wants to go to, parameters{ type: OBJECT, properties: { destination: { type: STRING, description: Destination that the user wants to go to, }, }, }, ) destination_tool Tool(function_declarations[get_destination]) response client.models.generate_content( modelMODEL_ID, contentsId like to travel to Paris., configGenerateContentConfig( tools[destination_tool], temperature0, thinking_configthinking_config, ), ) print(response.function_calls[0])代码执行工具代码执行让模型生成并运行 Python 代码、根据运行结果迭代学习直至得到最终输出。模型同样自主决定何时启用from google.genai.types import ToolCodeExecution code_execution_tool Tool(code_executionToolCodeExecution()) response client.models.generate_content( modelMODEL_ID, contentsCalculate 20th fibonacci number. Then find the nearest palindrome to it., configGenerateContentConfig( tools[code_execution_tool], temperature0, thinking_configthinking_config, ), ) # response.executable_code 与 response.code_execution_result 分别给出代码与运行结果更深入的示例见 gemini/code-execution/intro_code_execution.ipynb 与 gemini/function-calling/intro_function_calling.ipynb。思维模型的综合示例Notebook 末尾给出了三类需要多轮策略与迭代求解的复杂任务示例代码生成单行提示词生成完整的 p5.js 无尽跑酷小游戏像素恐龙主题含屏幕操作提示多模态几何推理基于geometry.png图片计算重叠区域面积数学脑筋急转弯基于台球图片回答如何用三个球凑成 30模型会在思考中识别出数学上无解并给出跳出框架的解法。多轮对话专项从有状态会话到预置历史intro_gemini_chat.ipynb 以gemini-3.5-flash为例展示完整的有状态会话能力创建会话时可通过GenerateContentConfig注入系统指令如你是一位熟悉太阳系的天文学家chat.get_history()可随时取回对话历史代码场景下可在同一会话内先要求编写闰年判断函数再追加为生成的函数编写单元测试验证上下文在轮次间保持。更进阶的用法是预置对话历史以UserContent与ModelContent交替构造history参数系统消息放在首条消息的第一部分让模型带着既有人设与记忆开始新会话from google.genai.types import ModelContent, UserContent chat2 client.chats.create( modelMODEL_ID, history[ UserContent(My name is Ned. You are my personal assistant. ... Who do you work for?), ModelContent(I work for Ned.), UserContent(What do I like?), ModelContent(Ned likes watching movies.), ], ) response chat2.send_message(Are my favorite movies based on a book series?)不依赖 SDK用 cURL 直连 REST 端点intro_gemini_curl.ipynb 展示了绕过 SDK、直接以标准 REST 方式调用 Gemini API 的做法。关键一步是构造端点LOCATION为global时使用aiplatform.googleapis.com否则使用location-aiplatform.googleapis.comMODEL_IDgemini-3.5-flash LOCATIONglobal api_hostaiplatform.googleapis.com if [ $LOCATION ! global ]; then api_host${LOCATION}-aiplatform.googleapis.com fi API_ENDPOINT${api_host}/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}普通生成generateContentcurl -X POST \ -H Authorization: Bearer $(gcloud auth print-access-token) \ -H Content-Type: application/json \ https://${API_ENDPOINT}:generateContent \ -d { contents: { role: USER, parts: { text: Why is the sky blue? }, }, generation_config: { response_modalities: TEXT, }, } 2/dev/null response.json jq -r .candidates[].content.parts[].text response.json流式生成streamGenerateContent返回分块结果用jq逐条提取即可。参数控制则在generation_config中设置temperature、top_p、top_k、max_output_tokens、candidate_count、stop_sequences并在safety_settings中配置类别与阈值如HARM_CATEGORY_SEXUALLY_EXPLICITBLOCK_LOW_AND_ABOVE。多轮对话场景下contents中每条消息需要显式指定role取值为user或model。Express Mode 与图像生成快速上手Express Mode 极简启动intro_gemini_express.ipynb 面向最小化配置快速体验无需预建 GCP 项目基础设施仅用 API Key 创建客户端即可调用gemini-3.5-flash覆盖文本生成、流式输出、多轮对话与基础参数配置适合验证想法与 Demo 演示。Nano Banana 系列图像生成图像生成 Notebook 沿用了同一套 SDK 编程模型仅切换模型 IDgemini-2.5-flash-imageintro_gemini_2_5_image_gen.ipynb文生图与对话式图像编辑gemini-3-pro-imageintro_gemini_3_image_gen.ipynb高质量文生图、对话式编辑且可查看模型的思维过程Nano Banana Progemini-3.1-flash-imageintro_gemini_3_1_flash_image_gen.ipynb图像生成与对话式编辑可见思维过程Nano Banana 2gemini-3.1-flash-lite-imageintro_gemini_3_1_flash_lite_image_gen.ipynb面向高吞吐图像生成与编辑的低延迟模型Nano Banana 2 Lite。运行方式与后续学习路径所有 Notebook 均可直接通过Open in Colab / Open in Colab Enterprise / Open in Workbench按钮导入运行Notebook 内部自带的按钮区域或克隆本仓库后在本地 Jupyter 环境执行。在 setup-env/README.md 中可找到 Google Cloud、Gen AI Python SDK 与 Notebook 环境的完整搭建说明。读完入门系列后可按需深入仓库其他专题目录gemini/prompts/intro_prompt_design.ipynb提示工程基础gemini/function-calling/intro_function_calling.ipynb函数调用深入gemini/code-execution/intro_code_execution.ipynb代码执行进阶gemini/grounding/intro-grounding-gemini.ipynbGrounding 与检索增强gemini/use-cases/intro_multimodal_use_cases.ipynb多模态业务场景gemini/responsible-ai/gemini_safety_ratings.ipynb安全评分与过滤器机制gemini/controlled-generation/intro_controlled_generation.ipynb结构化输出进阶。一言以蔽之本目录是理解 Google Cloud Gemini 全家族模型能力的最小完备起点——从选定合适的模型 ID到掌握统一的 Gen AI SDK 编程范式再到多模态、工具调用与结构化输出的进阶组合均可在这 13 份 Notebook 中完成闭环演练。【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考