1. 准备工作
在此 Codelab 中，您将学习如何使用 Gemini API 的函数调用和多模态功能自动执行 Google Workspace 任务。
前提条件
- 基本熟悉 Apps 脚本、JavaScript 或类似编程语言
学习内容
- 如何利用 Gemini API 的函数调用和多模态功能。
- 如何将多个 Gemini API 调用链接在一起。
- 如何使用 Gemini API 自动执行 Google Workspace 任务。
所需条件
- 网络浏览器。
- Gmail 账号。或者，使用已实现 Gemini API 特定设置的 Google Workspace 账号。
- 来自 Gemini API 支持区域的连接。
- 可选：包含
curl程序的命令行界面，用于测试直接 API 请求。
您可在 GitHub 上的 Gemini API 实战宝典中找到此 Codelab 的完整代码。如果您需要完整的代码，请查看。
2. 设置 Gemini API
关于 Gemini
Gemini 模型是 Google 规模最大、功能最强大的 AI 模型系列。如需在您的应用中利用这些模型，您可以使用 Gemini API。您还可以在 Google AI Studio 中试用 Gemini API，这是一个 API 的网页界面，您可以在其中尝试提示、调整模型设置并调优自定义模型，而无需编写任何代码。
获取密钥
- 如需使用 Gemini API，请在 Google AI Studio 中创建 API 密钥。
可选：测试密钥
如果您可以通过 curl 访问命令行，请将密钥添加到以下代码块的第一行，然后在终端中运行该密钥以测试 API 密钥。
export GOOGLE_API_KEY=Paste_your_API_key_here
curl "https://generativelanguage.googleapis.com/v1beta/models?key=${GOOGLE_API_KEY}"
您应该会看到 JSON 格式的模型列表，例如 models/gemini-1.0-pro。这意味着它有效。
3. 可选：向 Gemini API 发出请求
在此可选步骤中，您会先向 Gemini API 发出请求，以便更好地了解内容生成的运作方式，然后再将其添加到 Apps 脚本应用。
模型简介
Gemini API 提供了许多模型，它们具有不同的功能和限制。Gemini 模型页面中会列出每个模型及其功能。
发出第一个请求
如需让 Gemini API 完成文本提示，您需要构建 JSON 请求并将其发送到 REST API 端点。
具体步骤如下：
- 在新文件中，输入以下 JSON 请求：
{
contents: [
{
parts: [
{ text: 'The most important aspects of a persuasive presentation are:' }
]
}
]
}
JSON 请求包含以下提示：The most important aspects of a persuasive presentation are:。模型将完成此说明并直接为您提供结果。
JSON 请求包含三个要填充的顶级字段：contents、generationConfig 和 safetySettings。只有 contents 是必填字段。其他代码则提供用于控制输出的机制。
- 将此 JSON 保存在
presentation.txt文件中，然后直接将其传递给curl，如下所示：
curl -H 'Content-Type: application/json' -X POST -d @presentation.txt \
'https://generativelanguage.googleapis.com/v1beta/models/gemini-1.0-pro-latest:generateContent?key='${GOOGLE_API_KEY}
在此示例中，您在网址中设置了以下值：
v1beta用于指定 API 版本。gemini-1.0-pro-latest将 Gemini 1.0 Pro 指定为模型并使用最新快照。generateContent指定您调用的 API 方法。
您应该会看到如下所示的结果：
{
"candidates": [
{
"content": {
"parts": [
{
"text": "* **Credibility:** The audience must trust that you are an expert on the subject matter and that you have their best interests at heart.\n* **Clearness:** Your message must be easy to understand and follow. Avoid using jargon or technical terms that your audience may not be familiar with.\n* **Concreteness:** Use specific examples and data to support your arguments. Avoid making vague or general claims.\n* **Emotional appeal:** In addition to appealing to the audience's logical side, you should also try to connect with them on an emotional level. Use storytelling, humor, and personal anecdotes to make your points more memorable and engaging.\n* **Strong closing:** End your presentation with a strong call to action. Tell the audience what you want them to do and why it is important for them to do it."
}
],
"role": "model"
},
"finishReason": "STOP",
"index": 0,
"safetyRatings": [...]
}
],
"promptFeedback": {
"safetyRatings": [...]
}
}
为了方便阅读，下面给出了常规格式的终端输出：
- 值得信赖：你必须相信你是相关主题的专家，并且你以他们的利益为重。
- 清晰度：您的广告信息必须易于理解和遵循。避免使用观众可能不熟悉的术语或技术术语。
- 具体性：使用具体示例和数据来支持您的论点。避免做出模糊或笼统的声明。
- 情感感染力：除了吸引观众的逻辑之外，您还应尝试从情感层面与他们建立联系。通过讲故事、幽默和个人轶事来让您的观点更加令人难忘和富有吸引力。
- 强有力的结束语：使用有感召力的号召性用语结束演示。告诉观众您希望他们做什么，以及为什么这对他们很重要。
如需详细了解其他设置（包括 generationConfig 和 safetySettings），请参阅提示和安全指南。
4. 通过 Apps 脚本调用 Gemini API
- 访问 script.new，系统会自动为您创建
code.gsApps 脚本文件。 - 将光标悬停在
code.gs文件上，然后点击
>重命名。 - 将文件名更改为
utils.gs。 - 在文件中，移除
myFunction函数，使文件为空。
将您的 API 密钥添加到项目中
- 在导航菜单中，选择项目设置。
- 在脚本属性下，点击添加脚本属性。
- 在属性下，输入
GOOGLE_API_KEY。 - 在值下，输入您在 Google AI Studio 中提供的 API 密钥。
- 点击保存脚本属性。
- 返回编辑器。
添加 Gemini API 代码
在 utils.gs 文件中，请按以下步骤操作：
设置 API 密钥和端点：
const properties = PropertiesService.getScriptProperties().getProperties();
const geminiApiKey = properties['GOOGLE_API_KEY'];
const geminiEndpoint = `https://generativelanguage.googleapis.com/v1beta/models/gemini-1.0-pro-latest:generateContent?key=${geminiApiKey}`;
- 添加以下函数，以使用特定提示调用 Gemini API：
function callGemini(prompt, temperature=0) {
const payload = {
"contents": [
{
"parts": [
{
"text": prompt
},
]
}
],
"generationConfig": {
"temperature": temperature,
},
};
const options = {
'method' : 'post',
'contentType': 'application/json',
'payload': JSON.stringify(payload)
};
const response = UrlFetchApp.fetch(geminiEndpoint, options);
const data = JSON.parse(response);
const content = data["candidates"][0]["content"]["parts"][0]["text"];
return content;
}
- 添加以下函数来设置提示：
function testGemini() {
const prompt = "The best thing since sliced bread is";
const output = callGemini(prompt);
console.log(prompt, output);
}
测试应用
- 点击
保存。 - 在函数下拉列表中选择
testGemini，然后点击
。 - 接受必要的权限。您的代码应该会运行，并且应该会在执行日志中看到一些控制台输出及结果。
成功了！
5. 使用图片调用 Gemini API
Gemini 系列模型最强大的功能之一是支持多模态输入，这意味着你可以提供的内容不仅限于文本！在本部分中，您将添加一个函数，用于使用图片调用 Gemini API。
- 在
utils.gs文件顶部现有const geminiEndpoint声明后面，添加以下代码行：
const geminiProVisionEndpoint = `https://generativelanguage.googleapis.com/v1beta/models/gemini-1.0-pro-vision-latest:generateContent?key=${geminiApiKey}`;
添加 Gemini Vision 代码
- 在
utils.gs文件中添加一个函数，以调用以下新添加的端点：
function callGeminiProVision(prompt, image, temperature=0) {
const imageData = Utilities.base64Encode(image.getAs('image/png').getBytes());
const payload = {
"contents": [
{
"parts": [
{
"text": prompt
},
{
"inlineData": {
"mimeType": "image/png",
"data": imageData
}
}
]
}
],
"generationConfig": {
"temperature": temperature,
},
};
const options = {
'method' : 'post',
'contentType': 'application/json',
'payload': JSON.stringify(payload)
};
const response = UrlFetchApp.fetch(geminiProVisionEndpoint, options);
const data = JSON.parse(response);
const content = data["candidates"][0]["content"]["parts"][0]["text"];
return content;
}
- 添加以下测试函数：
function testGeminiVision() {
const prompt = "Provide a fun fact about this object.";
const image = UrlFetchApp.fetch('https://storage.googleapis.com/generativeai-downloads/images/instrument.jpg').getBlob();
const output = callGeminiProVision(prompt, image);
console.log(prompt, output);
}
此函数从互联网加载测试图片，并将其传递给您定义的函数。稍后，您需要将其连接以使用电子表格中的图表，因此这只是测试。
测试应用
- 保存并运行
testGeminiVision函数，然后检查输出。
6. 使用工具调用 Gemini API
除了文字和图片之外，您还可以在提示中使用各种工具。
添加工具处理代码
- 将一个函数添加到接受工具规范的
utils.gs文件中：
function callGeminiWithTools(prompt, tools, temperature=0) {
const payload = {
"contents": [
{
"parts": [
{
"text": prompt
},
]
}
],
"tools" : tools,
"generationConfig": {
"temperature": temperature,
},
};
const options = {
'method' : 'post',
'contentType': 'application/json',
'payload': JSON.stringify(payload)
};
const response = UrlFetchApp.fetch(geminiEndpoint, options);
const data = JSON.parse(response);
const content = data["candidates"][0]["content"]["parts"][0]["functionCall"];
return content;
}
如需详细了解此架构和可用字段，请参阅 FunctionDeclaration API 参考文档。
测试应用
- 定义一个模型可用于查找当前日期和时间的工具：
function testGeminiTools() {
const prompt = "Tell me how many days there are left in this month.";
const tools = {
"function_declarations": [
{
"name": "datetime",
"description": "Returns the current date and time as a formatted string.",
"parameters": {
"type": "string"
}
}
]
};
const output = callGeminiWithTools(prompt, tools);
console.log(prompt, output);
}
此处使用的格式是 FunctionDeclaration 架构。您实际上并没有调用日期时间函数，您只会收到表明模型请求了函数调用的指示。您将在后续步骤中处理函数调用。
- 保存并运行
testGeminiTools函数以查看输出。
7. 与 Google Workspace 的演示集成概览
现在，您已了解函数调用的工作原理，可以轻松地将 Gemini 模型的功能扩展到其他服务。在接下来的几个部分中，您将构建针对 Google Workspace 产品（例如 Google 云端硬盘、Google 幻灯片和 Google 表格）的集成。下面是一个简化的图表：
概括来讲，当用户查询进入时，您可以使用 Gemini API 的函数调用来确定使用哪个工具。您将构建三个可以执行以下操作的工具：
- 设置会议。图中的
setupMeeting()函数会调用 Gemini 1.0 Pro API，以总结 Google 云端硬盘中的博客，并将摘要添加到 Google 日历中新建的会议中。 - 根据图表中的数据分析起草电子邮件。图中的
draftEmail()函数会调用 Gemini 1.0 Pro Vision，以分析 Google 表格中的图表，并根据分析结果在 Gmail 中撰写电子邮件。 - 创建框架组。图中的
createDeck()函数会调用 Gemini 1.0 Pro，以便为 Google 幻灯片中的演示文稿集思广益。
对于每种工具，您需要执行以下三项操作：
- 确定 Gemini API 的函数调用响应是否要求调用
if...else代码块中的特定工具。 - 添加实际函数以实现工具功能。
- 使用 Gemini API 声明该工具，以便 Gemini 模型知道该工具的存在，并返回正确的函数调用响应。
8. 使用 Apps 脚本设置会议
首先，在 Google 日历中自动设置会议，但同时添加了说明（即 Google 云端硬盘中文件的摘要）。
具体步骤如下：
- 下载此文本文件，这是 Gemini 1.5 Pro 发布博客的文字副本。
- 将文件上传到您在 Google 云端硬盘中的根文件夹。
- 在编辑器中，创建一个
main.gs文件，然后添加以下代码：
function main() {
const userQuery = "Set up a meeting at 10AM tomorrow with Helen to discuss the news in the Gemini-blog.txt file.";
var tool_use = callGeminiWithTools(userQuery, WORKSPACE_TOOLS);
Logger.log(tool_use);
if(tool_use['name'] == "setupMeeting") {
setupMeeting(tool_use['args']['time'], tool_use['args']['recipient'], tool_use['args']['filename']);
Logger.log("Your meeting has been set up.");
}
else
Logger.log("no proper tool found");
}
在此示例中，您将调用 Gemini API 的函数调用功能。接下来，您需要定义工具函数。
- 在编辑器左侧的服务旁边，点击 + 添加服务 >Google 日历 API >添加。这将启用高级 Google 日历服务，您稍后需要为某些高级 API 使用该服务。
- 在
utils.gs文件中，添加以下代码：
function attachFileToMeeting(event, file, fileName) {
// Get the iCal ID for the event.
const iCalEventId = event.getId();
// Log the ID and title for debugging.
console.log(`iCal event ID: ${iCalEventId}`);
console.log(`event Title: ${event.getTitle()}`);
// Set up the options for listing the event with the advanced Google Calendar service.
const options = {
iCalUID: iCalEventId,
};
// Use the primary calendar as the calendar ID to list events.
const calendarId = 'primary';
// Use the advanced Google Calendar service to list the event.
const calEvents = Calendar.Events.list(calendarId, options);
// Get the Calendar ID used by the advanced Google Calendar service.
const eventId = calEvents.items[0].id;
// Get the file URL for the attachment.
const fileUrl = file.getUrl();
// Set up the patch options to add the file.
var patch = {
attachments: [{
'fileUrl': fileUrl,
'title': fileName
}]
};
// Patch the event to add the file as an attachment.
Calendar.Events.patch(patch, 'primary', eventId, {"supportsAttachments": true});
}
function setupMeeting(time, recipient, filename) {
const files = DriveApp.getFilesByName(filename);
const file = files.next();
const blogContent = file.getAs("text/*").getDataAsString();
var geminiOutput = callGemini("Give me a really short title of this blog and a summary with less than three sentences. Please return the result as a JSON with two fields: title and summary. \n" + blogContent);
// The Gemini model likes to enclose the JSON with ```json and ```
geminiOutput = JSON.parse(geminiOutput.replace(/```(?:json|)/g, ""));
const title = geminiOutput['title'];
const fileSummary = geminiOutput['summary'];
const event = CalendarApp.getDefaultCalendar().createEventFromDescription(`meet ${recipient} at ${time} to discuss "${title}"`);
event.setDescription(fileSummary);
attachFileToMeeting(event, file, filename);
}
此代码将执行以下操作：
setupMeeting()函数会遍历您的 Google 云端硬盘并查找Gemini-blog.txt文件。在第 3 步中，Gemini API 的函数调用会自动返回此文件名。setupMeeting()函数会调用 Gemini API 来总结文件内容，使用自由格式说明与日历应用安排会议，并将摘要添加到会议中。setupMeeting()函数会调用attachFileToMeeting()函数，以使用高级 Google 日历服务将博客文件附加到会议中。
- 在
utils.gs文件的顶部，添加以下代码：
const WORKSPACE_TOOLS = {
"function_declarations": [
{
"name": "setupMeeting",
"description": "Sets up a meeting in Google Calendar.",
"parameters": {
"type": "object",
"properties": {
"time": {
"type": "string",
"description": "The time of the meeting."
},
"recipient": {
"type": "string",
"description": "The name of the recipient."
},
"filename": {
"type": "string",
"description": "The name of the file."
},
},
"required": [
"time",
"recipient",
"filename"
]
}
},
// You add tools here.
]
};
- 在编辑器中，返回
main.gs文件，然后点击。 - 如果 Google Workspace 要求您提供运行脚本的权限，请点击确定。
几秒钟后，执行日志会显示一条消息，告知您会议已设置完毕。
- 在 Google 日历中，找到包含摘要和附件的会议。
9. 使用 Apps 脚本起草电子邮件
接下来，您将在 Gmail 中自动撰写电子邮件草稿。请看以下情景：假设您在 Google 表格中进行数据分析。将所有数字准备好并创建一个图表。您想使用 Gemini Pro Vision API 根据图表起草电子邮件。
具体步骤如下：
- 打开此工作表，然后点击文件 ->复制。
- 在复制文档对话框的名称文本框中，将默认名称
Copy of CollegeExpenses替换为CollegeExpenses。 - 在
main.gs文件中，将之前的用户查询替换为新的用户查询，然后将以下代码添加到if...else语句中：
function main() {
// const userQuery = "Set up a meeting at 5PM with Helen to discuss the news in the Gemini-1.5-blog.txt file.";
const userQuery = "Draft an email for Mary with insights from the chart in the CollegeExpenses sheet.";
if(...) {...}
// Add this code
else if(tool_use['name'] == "draftEmail") {
draftEmail(tool_use['args']['sheet_name'], tool_use['args']['recipient']);
Logger.log("Check your Gmail to review the draft");
}
else {...}
}
- 在
utils.gs文件中，添加以下代码：
function draftEmail(sheet_name, recipient) {
const prompt = `Compose the email body for ${recipient} with your insights for this chart. Use information in this chart only and do not do historical comparisons. Be concise.`;
var files = DriveApp.getFilesByName(sheet_name);
var sheet = SpreadsheetApp.openById(files.next().getId()).getSheetByName("Sheet1");
var expenseChart = sheet.getCharts()[0];
var chartFile = DriveApp.createFile(expenseChart.getBlob().setName("ExpenseChart.png"));
var emailBody = callGeminiProVision(prompt, expenseChart);
GmailApp.createDraft(recipient+"@demo-email-provider.com", "College expenses", emailBody, {
attachments: [chartFile.getAs(MimeType.PNG)],
name: 'myname'
});
}
此函数会从工作表中检索大学费用图表，并将其发送到 Gemini Pro Vision 以起草电子邮件。Gemini Pro Vision 会从图表中提取信息，并代您起草电子邮件正文。
- 在
utils.gs文件中，将以下代码添加到WORKSPACE_TOOLS对象的You add tools here注释后面：
WORKSPACE_TOOLS = {
"function_declarations": [
// You add tools here.
{
"name": "draftEmail",
"description": "Write an email by analyzing data or charts in a Google Sheets file.",
"parameters": {
"type": "object",
"properties": {
"sheet_name": {
"type": "string",
"description": "The name of the sheet to analyze."
},
"recipient": {
"type": "string",
"description": "The name of the recipient."
},
},
"required": [
"sheet_name",
"recipient"
]
}
},
]
};
- 在编辑器中，导航回
main.gs文件，然后点击。 - 等待 10 到 20 秒后，打开您的 Gmail。您应该会看到如下电子邮件草稿：
您可以先修改电子邮件草稿，然后再发送。在您给出简短的提示和图表后，电子邮件将完全由 Gemini Pro Vision 撰写。
10. 使用 Apps 脚本创建框架组
接下来，您可以使用 Apps 脚本在 Google 幻灯片中自动创建框架组。
具体步骤如下：
- 在
main.gs文件中，将之前的用户查询替换为新的用户查询，并将以下代码添加到if...else语句中：
function main() {
// const userQuery = "Draft an email for Mary with insights from the chart in the CollegeExpenses sheet.";
const userQuery = "Help me put together a deck about water conservation.";
if(...) {...}
// Add this code
else if(tool_use['name'] == 'createDeck') {
deckURL = createDeck(tool_use['args']['topic']);
Logger.log("Deck URL: " + deckURL);
}
else {...}
}
- 在
utils.gs文件中，添加以下代码：
function createDeck(topic) {
const prompt = `I'm preparing a ${NUM_SLIDES}-slide deck to discuss ${topic}. Please help me brainstorm and generate main bullet points for each slide. Keep the title of each slide short. Please produce the result as a valid JSON so that I can pass it to other APIs.`;
var geminiOutput = callGemini(prompt, 0.4);
// The Gemini model likes to enclose the JSON with ```json and ```
geminiOutput = geminiOutput.replace(/```(?:json|)/g, "");
const bulletPoints = JSON.parse(geminiOutput);
// Create a Google Slides presentation.
const presentation = SlidesApp.create("My New Presentation");
// Set up the opening slide.
var slide = presentation.getSlides()[0];
var shapes = slide.getShapes();
shapes[0].getText().setText(topic);
var body;
for (var i = 0; i < NUM_SLIDES; i++) {
slide = presentation.appendSlide(SlidesApp.PredefinedLayout.TITLE_AND_BODY);
shapes = slide.getShapes();
// Set title.
shapes[0].getText().setText(bulletPoints['slides'][i]['title']);
// Set body.
body = "";
for (var j = 0; j < bulletPoints['slides'][i]['bullets'].length; j++) {
body += '* ' + bulletPoints['slides'][i]['bullets'][j] + '\n';
}
shapes[1].getText().setText(body);
}
return presentation.getUrl();
}
此函数会调用 Gemini API 来集思广益，想出某个特定主题，以如下格式返回项目符号：
，然后使用 Apps 脚本填充框架组。
- 在
utils.gs文件中，将以下代码添加到WORKSPACE_TOOLS对象的You add tools here注释后面：
WORKSPACE_TOOLS = {
"function_declarations": [
// You add tools here.
{
"name": "createDeck",
"description": "Build a simple presentation deck with Google Slides and return the URL.",
"parameters": {
"type": "object",
"properties": {
"topic": {
"type": "string",
"description": "The topic that the presentation is about."
},
},
"required": [
"topic"
]
}
},
]
};
- 在
utils.gs文件的顶部，定义以下常量：
const NUM_SLIDES = 3;
此数量是除初始幻灯片之外，Gemini 模型创建的幻灯片数量。
- 在编辑器中，导航回
main.gs文件，然后点击。几秒钟后，您会在执行日志中看到一个演示文稿网址。 - 使用浏览器打开该网址。您应该会看到一个布满项目符号的骷髅卡组。
11. 可供探索的点子
除了这三种集成之外，您还可以探索以下思路：
- 在 Google Chat 中构建聊天机器人。大型语言模型 (LLM) 最受欢迎的用例之一是构建聊天机器人。借助 Gemini API，您可以轻松地为 Google Chat 构建聊天机器人。如需了解详情，请参阅 Google Chat API 和 Codelab 使用 Gemini 构建 Google Chat 应用。
- 在 Google 云端硬盘或 Keep 中使用您自己的数据进行检索增强生成 (RAG)。在此 Codelab 中，您只使用一个文本文件进行摘要。不过，您还可以将个人 Google 云端硬盘和 Keep 中的内容（例如记事、PDF 和图片）与 Gemini API、矢量数据库和（可选）协调工具（例如 LangChain）搭配使用，执行 RAG 并根据您的数据个性化模型响应。
- 使用 Gemini API 的多轮函数调用功能。Gemini API 的函数调用不限于一次，对于更复杂的任务，您可以多轮函数调用。
- Google Workspace 更胜以往。现在，您已了解如何将 Gemini API 与 Google Workspace 集成，可以不局限于 Google Workspace 并利用世界各地的其他 API。
12. 恭喜
您了解了 Gemini API 的多模态功能和函数调用。您已使用它们通过 Apps 脚本自动执行一些 Google Workspace 任务！