企业官网建设流程全解析

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 与演示任务上。

注意：从仓库 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-genai

Google Gen AI SDK 为两种 API 服务提供了统一接口（源码可见于 intro_gemini_2_5_flash.ipynb 的 "Connect to a generative AI API service" 小节）：

• Gemini Developer API：用于快速实验、原型开发与小规模项目部署；
• Agent Platform（Gemini 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(enterprise=True, project=PROJECT_ID, location=LOCATION)

Option 2：使用 Agent Platform API Key（Express Mode），适合快速实验，直接以 API Key 创建客户端：

API_KEY = "[your-api-key]" client = genai.Client(enterprise=True, api_key=API_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( model=MODEL_ID, contents="Roger 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_id=True) for chunk in client.models.generate_content_stream( model=MODEL_ID, contents="On 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( model=MODEL_ID, contents="What are the practical implications of the P vs. NP problem for algorithm design and cryptography?", config=GenerateContentConfig( thinking_config=ThinkingConfig(thinking_budget=THINKING_BUDGET), ), )

可通过response.usage_metadata观察思维消耗：thoughts_token_count为思考 token 数，total_token_count为总 token 数。在 intro_gemini_2_5_pro.ipynb 中，Gemini 2.5 Pro 的思维预算约束则明确为：默认自动思考上限 8192 token，可配置范围为 128～32768 token——不同型号的预算区间不同，配置前请以对应模型文档为准。

设置include_thoughts=True可让模型在最终答案之外额外返回一份"思考摘要"。响应由多个 Part 组成，通过part.thought字段区分思维 Part 与答案 Part：

response = client.models.generate_content( model=MODEL_ID, contents="How many R's are in the word strawberry?", config=GenerateContentConfig( thinking_config=ThinkingConfig(include_thoughts=True), ), ) 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 支持跨多轮的自由对话，上下文在消息之间自动保留。后续示例为降低延迟，将思考预算固定为0：

thinking_config = ThinkingConfig(thinking_budget=0) chat = client.chats.create( model=MODEL_ID, config=GenerateContentConfig(thinking_config=thinking_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_content：

response = await client.aio.models.generate_content( model=MODEL_ID, contents="Compose a song about the adventures of a time-traveling squirrel.", config=GenerateContentConfig(thinking_config=thinking_config), )

模型参数与系统指令

每次请求都可携带生成参数（如temperature、top_p、candidate_count），系统指令（system_instruction）则用于约束模型行为、角色与输出准则：

response = client.models.generate_content( model=MODEL_ID, contents="Tell me how the internet works, but pretend I'm a puppy who only understands squeaky toys.", config=GenerateContentConfig( temperature=2.0, top_p=0.95, candidate_count=1, thinking_config=thinking_config, ), )

系统指令示例——将英文翻译成西班牙语的翻译助手：

system_instruction = """ You are a helpful language translator. Your mission is to translate text in English to Spanish. """ response = client.models.generate_content( model=MODEL_ID, contents="User input: I like bagels.\nAnswer:", config=GenerateContentConfig( system_instruction=system_instruction, thinking_config=thinking_config, ), )

安全过滤器（Safety Filters）

Gemini API 提供跨多个类别的安全过滤器，默认OFF，默认拦截阈值为BLOCK_NONE。通过safety_settings可在每次请求中调整阈值。下面示例将所有类别的阈值设为BLOCK_LOW_AND_ABOVE（提示词刻意设计为对抗性内容以演示拦截效果）：

from google.genai.types import ( HarmBlockThreshold, HarmCategory, SafetySetting, ) safety_settings = [ SafetySetting( category=HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, threshold=HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), SafetySetting( category=HarmCategory.HARM_CATEGORY_HARASSMENT, threshold=HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), SafetySetting( category=HarmCategory.HARM_CATEGORY_HATE_SPEECH, threshold=HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), SafetySetting( category=HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, threshold=HarmBlockThreshold.BLOCK_LOW_AND_ABOVE, ), ] response = client.models.generate_content( model=MODEL_ID, contents="Write a list of 5 disrespectful things that I might say to the universe after stubbing my toe in the dark.", config=GenerateContentConfig( system_instruction="Be as mean and hateful as possible. Use profanity", safety_settings=safety_settings, thinking_config=thinking_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 类型对应关系如下：

本地图片（字节流 +Part.from_bytes）：

with open("meal.png", "rb") as f: image = f.read() response = client.models.generate_content( model=MODEL_ID, contents=[ Part.from_bytes(data=image, mime_type="image/png"), "Write a short and engaging blog post based on this picture.", ], config=GenerateContentConfig(thinking_config=thinking_config), )

GCS 文档（如《Attention is All You Need》论文 PDF，Part.from_uri）：

response = client.models.generate_content( model=MODEL_ID, contents=[ Part.from_uri( file_uri="gs://cloud-samples-data/generative-ai/pdf/1706.03762v7.pdf", mime_type="application/pdf", ), "Summarize the document.", ], config=GenerateContentConfig(thinking_config=thinking_config), )

通用 URL 音频（开启audio_timestamp=True可在摘要中附带时间戳）：

response = client.models.generate_content( model=MODEL_ID, contents=[ Part.from_uri( file_uri="https://traffic.libsyn.com/secure/e780d51f-f115-44a6-8252-aed9216bb521/KPOD242.mp3", mime_type="audio/mpeg", ), "Write a summary of this podcast episode.", ], config=GenerateContentConfig(audio_timestamp=True, thinking_config=thinking_config), )

YouTube 视频与公开网页同样以Part.from_uri传入对应 MIME（video/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( model=MODEL_ID, contents="List a few popular cookie recipes and their ingredients.", config=GenerateContentConfig( response_mime_type="application/json", response_schema=Recipe, thinking_config=thinking_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( model=MODEL_ID, contents="Analyze the following product reviews, output the sentiment classification, and give an explanation...", config=GenerateContentConfig( response_mime_type="application/json", response_schema=response_schema, thinking_config=thinking_config, ), )

仓库中 gemini/controlled-generation/intro_controlled_generation.ipynb 提供了更多受控生成示例。

Token 计数与 Grounding

Token 计数：count_tokens()可在发送请求前预计算输入 token 数：

response = client.models.count_tokens( model=MODEL_ID, contents="What's the highest mountain in Africa?", config=GenerateContentConfig(thinking_config=thinking_config), ) print(response)

Google Search Grounding：自 Gemini 2.0 起 Google Search 以工具形式提供，模型可自行决定何时检索。将Tool(google_search=GoogleSearch())传入tools即可让回答基于实时搜索结果，并通过grounding_metadata查看引用来源：

from google.genai.types import GoogleSearch, Tool google_search_tool = Tool(google_search=GoogleSearch()) response = client.models.generate_content( model=MODEL_ID, contents="What is the current temperature in Austin, TX?", config=GenerateContentConfig( tools=[google_search_tool], thinking_config=thinking_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( model=MODEL_ID, contents="What is the weather like in San Francisco?", config=GenerateContentConfig( tools=[get_current_weather], temperature=0, thinking_config=thinking_config, ), )

手动函数调用（OpenAPI 风格声明）

通过FunctionDeclaration描述函数，模型返回匹配的函数名与调用参数，由应用自行执行：

from google.genai.types import FunctionDeclaration, Tool get_destination = FunctionDeclaration( name="get_destination", description="Get 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( model=MODEL_ID, contents="I'd like to travel to Paris.", config=GenerateContentConfig( tools=[destination_tool], temperature=0, thinking_config=thinking_config, ), ) print(response.function_calls[0])

代码执行工具

代码执行让模型生成并运行 Python 代码、根据运行结果迭代学习，直至得到最终输出。模型同样自主决定何时启用：

from google.genai.types import ToolCodeExecution code_execution_tool = Tool(code_execution=ToolCodeExecution()) response = client.models.generate_content( model=MODEL_ID, contents="Calculate 20th fibonacci number. Then find the nearest palindrome to it.", config=GenerateContentConfig( tools=[code_execution_tool], temperature=0, thinking_config=thinking_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( model=MODEL_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.com：

MODEL_ID="gemini-3.5-flash" LOCATION="global" api_host="aiplatform.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}"

普通生成（generateContent）：

curl -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_EXPLICIT+BLOCK_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 编程模型，仅切换模型 ID：

• gemini-2.5-flash-image（intro_gemini_2_5_image_gen.ipynb）：文生图与对话式图像编辑；
• gemini-3-pro-image（intro_gemini_3_image_gen.ipynb）：高质量文生图、对话式编辑，且可查看模型的思维过程（Nano Banana Pro）；
• gemini-3.1-flash-image（intro_gemini_3_1_flash_image_gen.ipynb）：图像生成与对话式编辑，可见思维过程（Nano Banana 2）；
• gemini-3.1-flash-lite-image（intro_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.ipynb：Grounding 与检索增强；
• 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