GSP1209

概览

Google Gen AI SDK 提供了访问 Google 生成式 AI API 服务的统一接口。该 SDK 简化了将生成式 AI 功能集成到应用和服务中的过程，使开发者能够利用 Google 的先进 AI 模型处理各种任务。在本实验中，您将探索 Google Gen AI SDK，学习如何连接到 AI 服务、发送各种提示，以及对 Gemini 的回答进行微调。您还将动手练习更高级的技巧，为在自己的项目中利用生成式 AI 的强大功能做好准备。

目标

在本实验中，您将学习如何使用 Google Gen AI SDK for Python 来与 Google 的生成式 AI 服务和模型（包括 Gemini）进行交互。具体活动包括：

• 安装 Gen AI SDK。
• 连接到 API 服务。
• 发送文本提示和多模态提示。
• 设置系统指令。
• 配置模型参数和安全过滤器。
• 管理模型交互（多轮聊天、内容流式传输、异步请求）。
• 使用高级功能（token 计数、上下文缓存、函数调用、批量预测、文本嵌入）。

前提条件

在开始本实验之前，您应该先熟悉：

• Python 编程基础知识。
• API 的一般性概念。
• 在 Vertex AI Workbench 上的 Jupyter 笔记本中运行 Python 代码

设置和要求

点击“开始实验”按钮前的注意事项

请阅读以下说明。实验是计时的，并且您无法暂停实验。计时器在您点击开始实验后即开始计时，显示 Google Cloud 资源可供您使用多长时间。

此实操实验可让您在真实的云环境中开展实验活动，免受模拟或演示环境的局限。为此，我们会向您提供新的临时凭据，您可以在该实验的规定时间内通过此凭据登录和访问 Google Cloud。

为完成此实验，您需要：

• 能够使用标准的互联网浏览器（建议使用 Chrome 浏览器）。

注意：请使用无痕模式（推荐）或无痕浏览器窗口运行此实验。这可以避免您的个人账号与学生账号之间发生冲突，这种冲突可能导致您的个人账号产生额外费用。

• 完成实验的时间 - 请注意，实验开始后无法暂停。

注意：请仅使用学生账号完成本实验。如果您使用其他 Google Cloud 账号，则可能会向该账号收取费用。

如何开始实验并登录 Google Cloud 控制台

1. 点击开始实验按钮。如果该实验需要付费，系统会打开一个对话框供您选择支付方式。左侧是“实验详细信息”窗格，其中包含以下各项：

   • “打开 Google Cloud 控制台”按钮
   • 剩余时间
   • 进行该实验时必须使用的临时凭据
   • 帮助您逐步完成本实验所需的其他信息（如果需要）

2. 点击打开 Google Cloud 控制台（如果您使用的是 Chrome 浏览器，请右键点击并选择在无痕式窗口中打开链接）。

   该实验会启动资源并打开另一个标签页，显示“登录”页面。

   提示：将这些标签页安排在不同的窗口中，并排显示。

   注意：如果您看见选择账号对话框，请点击使用其他账号。

3. 如有必要，请复制下方的用户名，然后将其粘贴到登录对话框中。

   {{{user_0.username | "<用户名>"}}}

   您也可以在“实验详细信息”窗格中找到“用户名”。

4. 点击下一步。

5. 复制下面的密码，然后将其粘贴到欢迎对话框中。

   {{{user_0.password | "<密码>"}}}

   您也可以在“实验详细信息”窗格中找到“密码”。

6. 点击下一步。

   重要提示：您必须使用实验提供的凭据。请勿使用您的 Google Cloud 账号凭据。 注意：在本实验中使用您自己的 Google Cloud 账号可能会产生额外费用。

7. 继续在后续页面中点击以完成相应操作：

   • 接受条款及条件。
   • 由于这是临时账号，请勿添加账号恢复选项或双重验证。
   • 请勿注册免费试用。

片刻之后，系统会在此标签页中打开 Google Cloud 控制台。

注意：如需访问 Google Cloud 产品和服务，请点击导航菜单，或在搜索字段中输入服务或产品的名称。

任务 1. 在 Vertex AI Workbench 中打开笔记本

1. 在 Google Cloud 控制台的导航菜单 () 中依次点击 Vertex AI > Workbench。

2. 找到 实例，然后点击打开 JupyterLab 按钮。

Workbench 实例的 JupyterLab 界面会在新浏览器标签页中打开。

任务 2. 设置笔记本

打开笔记本文件，导入库，然后选择模型。

1. 打开 文件。

2. 在选择内核对话框中，从可用内核列表中选择 Python 3。

3. 运行笔记本的以下部分：

   • 开始使用
   • 使用 Google Gen AI SDK
   • 连接到生成式 AI API 服务

对于项目 ID，请使用 ；对于位置，使用 。

注意：请跳过任何标为“仅限 Colab”的笔记本单元。如有笔记本单元在执行时遇到 429 响应，请等待 1 分钟，然后再次运行该单元以继续操作。

点击检查我的进度以验证是否完成了以下目标： 导入库并设置笔记本

任务 3. 与模型交互

如需详细了解 Vertex AI 上的所有 AI 模型和 API，请参阅 Google 模型和 Model Garden。

选择模型

• 运行笔记本的选择模型部分。

发送文本提示

使用 generate_content 方法生成对提示的回答。您可以将文本传递给 generate_content，并使用 .text 属性获取回答的文本内容。

• 运行笔记本的发送文本提示部分。

发送多模态提示

您可以在提示请求中包含文本、PDF 文档、图片、音频和视频，并获取文本或代码形式的回答。

您还可以直接在请求中通过 Part.from_uri 将文件网址传递给模型。

• 运行笔记本的发送多模态提示部分。

设置系统指令

系统指令可用于控制模型行为。设置系统指令可以为模型提供更多背景信息，以便其理解任务、提供更具个性化的回答，并在与用户交互的过程中遵循相关准则。

• 运行笔记本的设置系统指令部分。

点击检查我的进度以验证是否完成了以下目标： 与模型交互

任务 4. 配置和控制模型

配置模型参数

您可以在发送给模型的每个调用中包含参数值，以控制模型如何生成回答。如需了解详情，请参阅使用参数值进行实验。

• 运行笔记本的配置模型参数部分。

配置安全过滤器

Gemini API 提供了安全过滤器，您可以在多个过滤器类别中进行调整，以限制或允许某些类型的内容。您可以使用这些过滤器，针对您的应用场景进行适当的调整。如需了解详情，请参阅配置安全过滤器页面。

向模型发出请求时，系统会对内容进行分析并进行安全评级。您可以输出模型的回答，以检查所生成内容的安全评级，如以下示例所示：

• 运行笔记本的配置安全过滤器部分。

开始多轮聊天

Gemini API 可以实现多轮自由对话。

• 运行笔记本的开始多轮聊天部分。

控制生成的输出

借助 Gemini API 中的受控生成功能，您可以将模型输出限制为结构化格式。您可以将架构作为 Pydantic 模型或 JSON 字符串提供。

您还可以在 Python 字典中定义回答架构。您只能使用以下字段。系统会忽略所有其他字段。

• enum
• items
• maxItems
• nullable
• properties
• required

在本例中，您将指示模型分析商品评价数据、提取关键实体、执行情感分类（选择题）、提供附加说明，并以 JSON 格式输出结果。

• 运行笔记本的控制生成的输出部分。

点击检查我的进度以验证是否完成了以下目标： 配置和控制模型

任务 5. 管理模型交互

生成内容流

默认情况下，模型会在完成整个生成过程后返回回答。您也可以使用 generate_content_stream 方法，在生成回答的同时对其进行流式传输，这样，模型在生成一部分回答后便立即返回这部分回答。

• 运行笔记本的生成内容流部分。

发送异步请求

您可以使用 client.aio 模块发送异步请求。该模块公开了 client 上提供的所有类似的异步方法。

例如，client.aio.models.generate_content 是 client.models.generate_content 的异步版本。

• 运行笔记本的发送异步请求部分。

统计并计算 token 数量

您可以使用 count_tokens 方法计算输入 token 的数量，然后再向 Gemini API 发送请求。如需了解详情，请参阅列出并统计 token 数量页面。

统计 token 数量

• 运行笔记本的统计 token 数量部分。

计算 token 数量

• 运行笔记本的计算 token 数量部分。

点击检查我的进度以验证是否完成了以下目标： 管理模型交互

任务 6. 高级功能

函数调用

借助函数调用功能，您可以提供一组工具，让模型使用这些工具来回答用户的提示。您需要在代码中创建函数的说明，然后通过请求将说明传递给语言模型。模型的响应包括与说明匹配的函数名称以及用于调用该函数的参数。

如需查看更多函数调用示例，请参阅此笔记本。

• 运行笔记本的函数调用部分。

点击检查我的进度以验证是否完成了以下目标： 函数调用

使用上下文缓存

借助上下文缓存功能，您可以将常用的输入 token 存储在专用缓存中，并在后续请求中引用这些 token，从而无需将同一组 token 反复传递给模型。

注意：上下文缓存仅适用于具有固定版本号（例如 gemini-2.0-flash-001）的稳定模型。版本号必须包含版本后缀（例如 -001）。

创建缓存

• 运行笔记本的创建缓存部分。

使用缓存

• 运行笔记本的使用缓存部分。

删除缓存

• 运行笔记本的删除缓存部分。

点击检查我的进度以验证是否完成了以下目标： 使用上下文缓存

批量预测

获取在线（同步）回答时，一次只能发送一个输入请求。但在 Vertex AI 中使用 Gemini API 执行批量预测时，您可以在单个批量请求中向 Gemini 发送大量请求。然后，模型回答会异步填充到 Cloud Storage 或 BigQuery 中的存储空间输出位置。

在处理对延迟不敏感的大量输入时，批量预测通常比在线预测更高效，也更具成本效益。

准备批量输入

批量请求的输入指定要发送到模型进行预测的内容。

对 Gemini 的批量请求适用的输入来源包括 BigQuery 存储空间和 Cloud Storage。您可以访问批量文本生成页面，详细了解批量输入的格式。

本实验以 Cloud Storage 为例。Cloud Storage 输入需遵循以下要求：

• 文件格式：JSON Lines (JSONL)
• 位于 us-central1 区域
• 为服务账号配置适当的读取权限

向模型发送的每个请求都可以包含参数，利用这些参数来控制模型如何生成回答。如需详细了解 Gemini 参数，请参阅使用参数值进行实验页面。

以下是 JSONL 输入文件 batch_requests_for_multimodal_input_2.jsonl 中的一个示例请求：

{"request":{"contents": [{"role": "user", "parts": [{"text": "List objects in this image."}, {"file_data": {"file_uri": "gs://cloud-samples-data/generative-ai/image/office-desk.jpeg", "mime_type": "image/jpeg"}}]}],"generationConfig":{"temperature": 0.4}}}

• 运行笔记本的准备批量输入部分。

准备批量输出位置

批量预测任务完成后，系统会将输出存储在您的请求中指定的位置。

• 位置信息的格式为 Cloud Storage 或 BigQuery URI 前缀，例如： gs://path/to/output/data 或 bq://projectId.bqDatasetId。

• 如果未指定输出位置，则在来源为 Cloud Storage 时使用 gs://STAGING_BUCKET/gen-ai-batch-prediction，来源为 BigQuery 时使用 bq://PROJECT_ID.gen_ai_batch_prediction.predictions_TIMESTAMP。

本实验使用一个 Cloud Storage 存储桶作为输出位置的示例。

您可以在 BUCKET_URI 中指定 Cloud Storage 存储桶的 URI；如果未指定，系统会为您创建一个新的 Cloud Storage 存储桶，格式为 gs://PROJECT_ID-TIMESTAMP。

• 运行笔记本的准备批量输出位置部分。

发送批量预测请求

如需发送批量预测请求，请指定来源模型 ID、输入来源，以及 Vertex AI 用于存储批量预测结果的输出位置。

如需了解详情，请参阅批量预测 API 页面。您还可以在控制台 (https://console.cloud.google.com/vertex-ai/batch-predictions) 中查看状态。

• 运行笔记本的发送批量预测请求部分。

注意：批量预测可能需要几分钟才能完成。

检索批量预测结果

批量预测任务完成后，其输出会存储在请求中指定的位置。此外，批量预测结果还会存储在 batch_job.dest.bigquery_uri 或 batch_job.dest.gcs_uri 中。

输出示例：

{"status": "", "processed_time": "2024-11-13T14:04:28.376+00:00", "request": {"contents": [{"parts": [{"file_data": null, "text": "List objects in this image."}, {"file_data": {"file_uri": "gs://cloud-samples-data/generative-ai/image/gardening-tools.jpeg", "mime_type": "image/jpeg"}, "text": null}], "role": "user"}], "generationConfig": {"temperature": 0.4}}, "response": {"candidates": [{"avgLogprobs": -0.10394711927934126, "content": {"parts": [{"text": "Here's a list of the objects in the image:\n\n* **Watering can:** A green plastic watering can with a white rose head.\n* **Plant:** A small plant (possibly oregano) in a terracotta pot.\n* **Terracotta pots:** Two terracotta pots, one containing the plant and another empty, stacked on top of each other.\n* **Gardening gloves:** A pair of striped gardening gloves.\n* **Gardening tools:** A small trowel and a hand cultivator (hoe). Both are green with black handles."}], "role": "model"}, "finishReason": "STOP"}], "modelVersion": "gemini-2.0-flash-001@default", "usageMetadata": {"candidatesTokenCount": 110, "promptTokenCount": 264, "totalTokenCount": 374}}}

• 运行笔记本的检索批量预测结果部分。

点击检查我的进度以验证是否完成了以下目标： 检索批量预测结果

获取文本嵌入

您可以使用 embed_content 方法获取一段文本的文本嵌入。默认情况下，所有模型都会生成具有 768 个维度的输出。不过，有些模型可让用户选择 1 到 768 之间的输出维数。如需了解详情，请参阅 Vertex AI 文本嵌入 API。

• 运行笔记本的获取文本嵌入部分。

点击检查我的进度以验证是否完成了以下目标： 获取文本嵌入

恭喜！

恭喜！您已成功探索 Google Gen AI SDK，了解了如何连接到 AI 服务、发送各种提示，以及对 Gemini 模型的回答进行微调。您还获得了更高级技巧的实践经验，包括管理交互、使用上下文缓存，甚至使用嵌入功能！现在，您已经做好准备，可以在自己的项目中利用生成式 AI 的强大功能了。

后续步骤/了解详情

请参阅以下资源，详细了解 Gemini：

• Gemini 概览
• 有关 Vertex AI 上生成式 AI 的文档
• YouTube 上有关生成式 AI 的视频
• 探索 Vertex AI 实战宝典，了解精心挑选的生成式 AI 笔记，还可以在笔记本库中搜索内容。
• 探索 Google Cloud 生成式 AI 仓库中的其他笔记本和示例。

Google Cloud 培训和认证

…可帮助您充分利用 Google Cloud 技术。我们的课程会讲解各项技能与最佳实践，可帮助您迅速上手使用并继续学习更深入的知识。我们提供从基础到高级的全方位培训，并有点播、直播和虚拟三种方式选择，让您可以按照自己的日程安排学习时间。各项认证可以帮助您核实并证明您在 Google Cloud 技术方面的技能与专业知识。

本手册的最后更新时间：2025 年 5 月 5 日

本实验的最后测试时间：2025 年 5 月 5 日

版权所有 2025 Google LLC 保留所有权利。Google 和 Google 徽标是 Google LLC 的商标。其他所有公司名和产品名可能是其各自相关公司的商标。