1. 事前準備
在本程式碼研究室中,您將瞭解如何使用 Gemini API 的函式呼叫和多模態功能,自動處理 Google Workspace 工作。
必要條件
- 熟悉 Apps Script、JavaScript 或類似的程式設計語言
課程內容
- 如何使用 Gemini API 的函式呼叫和多模態功能。
- 如何鏈結多個 Gemini API 呼叫。
- 如何使用 Gemini API 自動執行 Google Workspace 工作。
需求條件
- 網路瀏覽器。
- Gmail 帳戶。或者,使用的是已導入 Gemini API 特定設定的 Google Workspace 帳戶。
- 來自 Gemini API 支援地區的連結。
- 選用:搭配
curl
程式的指令列介面,用於測試直接 API 要求。
如需本程式碼研究室的完整程式碼,請參閱 GitHub 上的 Gemini API 教戰手冊。如果您需要完整的程式碼,請進行檢查。
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 格式的模型清單,例如 model/gemini-1.0-pro。代表這個成功了。
3. 選用:向 Gemini API 提出要求
在這個選用步驟中,您會先向 Gemini API 提出要求,進一步瞭解內容生成功能的運作方式,再將其新增至 Apps Script 應用程式。
關於模型
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 Script 呼叫 Gemini API
- 造訪 script.new,系統就會自動為您建立
code.gs
Apps Script 檔案。 - 將遊標懸停在
code.gs
檔案上,然後按一下 >「重新命名」。 - 將檔案名稱變更為
utils.gs
。 - 在檔案中移除
myFunction
函式,讓檔案保持空白。
將 API 金鑰加進專案
- 在導覽選單中,選取「Project settings」。
- 按一下「指令碼屬性」下方的「新增指令碼屬性」。
- 在「Property」(資源) 下方輸入
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 Script 設定會議
首先,您可以在 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 的函式呼叫功能。接下來,您需要定義工具函式。
- 在編輯器左側,按一下「Service」(服務) 旁的「+ Add a service」(+ 新增服務) >Google Calendar 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
檔案。Gemini API 的函式在步驟 3 中呼叫會自動傳回這個檔案名稱。setupMeeting()
函式會呼叫 Gemini API,取得檔案內容摘要、透過 Google 日曆應用程式使用任意形式的說明設定會議,並將摘要新增至會議中。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 Script 撰寫電子郵件草稿
接下來,您可以在 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
檔案中,於You add tools here
註解後方將下列程式碼新增至WORKSPACE_TOOLS
物件:
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 Script 建立基本架構
接下來,您可以使用 Apps Script 自動在 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 Script 填寫基本架構。
- 在
utils.gs
檔案中,於You add tools here
註解後方將下列程式碼新增至WORKSPACE_TOOLS
物件:
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 和程式碼研究室「建構支援 Gemini 的 Google Chat 應用程式」。
- 使用您在 Google 雲端硬碟或 Keep 中的資料擷取增強生成 (RAG)。在本程式碼研究室中,您只會使用單一文字檔案進行摘要。不過,你也可以將個人 Google 雲端硬碟和 Keep 中的內容 (例如記事、PDF 和圖片) 與 Gemini API、向量資料庫,以及 LangChain 等自動化調度管理工具 (選用) 搭配使用,藉此執行 RAG 並依據資料個人化模型回應。
- 使用 Gemini API 的多輪函式呼叫功能。Gemini API 的函式呼叫功能不限於一輪,您還可以多輪函式呼叫處理較複雜的工作。
- 發揮 Google Workspace 以外的效益。您已瞭解如何整合 Gemini API 與 Google Workspace,現在可以使用 Google Workspace 以外的服務,並運用世界各地的其他 API。
12. 恭喜
您已瞭解 Gemini API 的多模態功能和函式呼叫。您已透過 Apps Script 處理部分 Google Workspace 工作!