如何使用 Google 的 Gemini 模型 API？(基礎教學，附上 Python 範例程式)

前言

在上個禮拜(12/6)推出了 Google DeepMind 開發的 Gemini (雙子星)，是第一個在 MMLU (大規模多任務語言理解) 方面超越人類專家的模型，要與 OpenAI 的 GPT-4 來抗衡。

我之前寫過一篇如何使用 OpenAI ChatGPT API，而在前幾天(12/13) Google 也開放了 Gemini Pro 版本的 API，可以透過「Google AI Studio 中的 Gemini API」或「Google Cloud 的 Vertex AI 平臺」來存取。

右邊有目錄，可直接跳至你想看的章節 →

Gemini 簡介

Gemini 是一個原生多模態的 LLM (大型語言模型)，從訓練時就餵進去文字、影像、音訊等等多種形態的資料，使用 Google 自行開發的 TPU 晶片訓練而成，是第一個在 MMLU (大規模多任務語言理解) 方面超越人類專家的模型。

* 官方 Gemini 簡介文章：https://blog.google/technology/ai/google-gemini-ai

而官方有釋出一部試用 Gemini Ultra 的展示影片，我看完真的覺得很驚訝，在網路上也掀起了一陣熱烈討論。

* 有 CC 中文字幕

* 有文章版可以看：How it's Made: Interacting with Gemini through multimodal prompting

* Gemini 的訓練資料是到 2023 年初，在此之後的它可能就不知道了。

Gemini 模型三種尺寸

Gemini 依照尺寸分成三種版本：

Gemini Ultra：最強大，適用高度複雜的任務
Gemini Pro：最通用
Gemini Nano：可於行動裝置上運作

目前 Google 的 Bard 背後已經換成了 Gemini Pro (好像只有英文版)，Gemini Nano 也應用於 Google Pixel 8 上。
而 Gemini Ultra 應該明年初會推出。

* Gemini Ultra 對比 OpenAI GPT-4；Gemini Pro 對比 OpenAI GPT-3.5。
* 目前只開放 Gemini Pro 版本的 API。

API 價格

以下價格都是 12/16 查詢的金額。

在明年初全面上市之前，可以 "免費" 使用相同速率限制、相同模型來嘗試，不確定之後還會不會有免費方案(但降低使用速率)。
* 免費方案的輸入輸出資料會被拿去訓練，需要注意。

Gemini Pro 的 API 限制每分鐘最多 60 個請求(以個人使用絕對夠用)，預計明年初之後收費如下：

Price (input)
$0.00025 / 1K characters
$0.0025 / image
Price (output)
$0.0005 / 1K characters

而 OpenAI GPT 的 API 收費如下 (以 GPT-3.5 Turbo 為例)：

Price (input)
$0.001 / 1K tokens
Price (output)
$0.002 / 1K tokens

* 以上價格皆為美金，撰寫文章當下約 1 美金 = 31.3 新台幣。

比較一下，可以看到 Google 的 Gemini 相較來說更划算，便宜了 4 倍，而且注意看他們的計算方式也不同，一個是用 character、一個是用 token，我們來看看不同的計算方式差多少。

底下我自己實際用它們官網計算 token 的工具，來比較兩者的差距。

先測試一段英文，兩者算出來的 token 是差不多的 (分別為 24 跟 25)：

Gemini is built from the ground up for multimodality — reasoning seamlessly across image, video, audio, and code.

但是，如果是中文，因為計算方式的差異，整整差了兩倍！！ (分別為 25 跟 50)

Gemini 是一個原生多模態的大型語言模型，在大規模多任務語言理解方面甚至超越人類專家。

Gemini Pro API

創建 API key

進到 Google AI for Developers 的網站，可以查看 Google AI 模型的介紹、價格、說明文件與範例。

點擊 "Get API key in Google AI Studio" 前往 Google AI Studio 來在網頁上測試 LLM AI 模型(類似 Playground 頁面的用途) 與取得 API key，

Google AI Studio 是以瀏覽器為基礎的 IDE，可使用生成式模型進行原型設計。Google AI Studio 可讓您快速試用模型並嘗試各種提示建構符合需求的項目後，您可以從 Gemini API 提供支援的程式語言，並將其匯出為程式碼。

關於 Google AI Studio 的使用我就不多介紹了。提醒如果想輸入圖片，右邊的 Model 記得要切換成 Gemini Pro Vision，才有支援圖像。

* Google AI Studio 官方教學文章

點擊左邊的 "Get API key" > "Create API key in new project" 來自動產生一個 Google Cloud 專案並創建一個 API key。

Gemini 模型種類說明

Gemini models 種類說明列出目前可使用的 Gemini 模型資訊，包含 "模型說明"、"模型更新時間"、"輸入輸出類型"、"Token限制"、"頻率限制"

Gemini Pro 用在文字輸入，而 Gemini Pro Vision 可以文字加影像輸入。

API 版本說明

目前 Gemini API 有 v1 和 v1beta 版本：

v1：API 的穩定版。在主要版本的生命週期內，穩定版本的功能都能完整支援。如有任何破壞性變更，系統會建立 API 的下一個主要版本，並在合理的時間內淘汰現有版本。
v1beta：包含可能處於開發階段的搶先體驗功能，且需要快速更新及破壞性變更。請勿使用此版本於正式版應用程式。

傳入參數

我們使用的 generateContent 方法其 Request 相關資訊如下：

POST https://generativelanguage.googleapis.com/v1/models/{gemini-pro or gemini-pro-vision}:generateContent?key={API_KEY}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "contents": [
    {
      "parts": [
      {
        "text": "prompt..."
      }
    ],
    "role": "user or model"
    }
  ],
  "safetySettings": [
    {
      "category": "<enum (HarmCategory)>",
      "threshold": "<enum (HarmBlockThreshold)>"
    }
  ],
  "generationConfig": {
    "temperature": "<number>",
    "topP": "<number>",
    "topK": "<number>",
    "candidateCount": "<integer>",
    "maxOutputTokens": "<integer>",
    "stopSequences": ["<string>"]
  }
}

contents 放 prompt 提示 (text) 與角色 (role，可以是 user 或 model，不填則預設 user)。

safetySettings 是 OpenAI GPT 沒有的參數，用於封鎖不安全的回覆內容。

safetySettings > category 類別，可以使用以下數值：

數值	代表意思
HARM_CATEGORY_HARASSMENT	騷擾內容。
HARM_CATEGORY_HATE_SPEECH	仇恨言論和內容。
HARM_CATEGORY_SEXUALLY_EXPLICIT	情色露骨內容。
HARM_CATEGORY_DANGEROUS_CONTENT	危險內容。

* 其他還有 HARM_CATEGORY_UNSPECIFIED、HARM_CATEGORY_DEROGATORY、HARM_CATEGORY_TOXICITY、HARM_CATEGORY_VIOLENCE、HARM_CATEGORY_SEXUAL、HARM_CATEGORY_MEDICAL、HARM_CATEGORY_DANGEROUS，不過那是給 PaLM 2（舊版）模型使用的，Gemini 模型不支援。

safetySettings > threshold 封鎖門檻，可以使用以下數值：

數值	代表意思
HARM_BLOCK_THRESHOLD_UNSPECIFIED	未指定門檻。
BLOCK_LOW_AND_ABOVE	允許含有「NEGLIGIBLE」的內容
BLOCK_MEDIUM_AND_ABOVE	允許含有「NEGLIGIBLE」、「LOW」的內容。
BLOCK_ONLY_HIGH	允許含有「NEGLIGIBLE」、「LOW」、「MEDIUM」的內容。
BLOCK_NONE	允許所有內容。

generationConfig 用於設定模型生成和輸出的設定參數，其中幾個比較會用到的是：

temperature：輸出內容的隨機性。越接近 1.0，產生的回應會豐富、多元、更有創意；反之越接近 0.0，則會產生較有確定性、可能性較高的回覆。
maxOutputTokens：最大輸出回應 Token 數量。Gemini Pro 模型預設 2048；Gemini Pro Vision 模型預設 4096。
candidateCount：要傳回的回應數量。預設 1，可設定 1~8，但目前好像限制只能用 1。

用法可以直接看下一章節的 Python 範例程式碼。其他更詳細的說明，請參考以下官方文件：

回覆內容

API 範例回覆內容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "我知道王建民。王建民，1980年3月31日出生於台灣台中市，是一位前台灣棒球選手，司職投手。他曾效力於中華職棒的興農牛隊，美國職棒的紐約洋基隊、華盛頓國民隊和芝加哥白襪隊，以及中國棒球聯賽的北京猛虎隊。\n\n王建民是台灣史上第一位大聯盟先發勝投破百的投手，也是第一位入選大聯盟全明星賽的台灣選手。他在2006年締造19勝6敗、 防禦率3.63的優異成績，並在季後賽拿下3勝0敗的戰績，幫助洋基隊奪得世界大賽冠軍。王建民也因此成為台灣的棒球英雄，並獲得「台灣之光」的稱號。\n\n然而，王建民在2008年季初因傷缺陣，並在2009年進行了韌帶移植手術。此後，他的成績大幅下滑，並在2012年離開了大聯盟。王建民於2013年回歸中華職棒，效力於義大犀牛隊。2016年，他宣布正式退休。\n\n王建民的職業生涯戰績為127勝72敗， 防禦率3.92，三振數1718次。他是台灣棒球史上最成功的投手之一，也是台灣人民的驕傲。"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

candidates 就是回應候選內容，目前好像只會有一個，因為輸入的 generationConfig > candidateCount 它也只讓我設定 1。

content：生成回應內容，格式跟輸入的 contents 一樣。
finishReason：模型停止產生 token 的原因。

數值	代表意思
FINISH_REASON_UNSPECIFIED	預設值。這個值未使用。
STOP	模型的自然停止或提供的停止序列。
MAX_TOKENS	已達到請求中指定的 token 數量上限。
SAFETY	內容因安全原因而被標記。
RECITATION	內容因遭檢舉為引用原因而被標記。
OTHER	未知原因。

index：此候選內容在候選清單中的索引 (目前只有一則)。
safetyRatings：安全性評級清單。顯示此回覆內容在各項安全性類別的等級(可能性)。

我自己在測試時，有時會如下回應，不知道是不是剛推出，所以還不太穩。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "candidates": [{"finishReason": "OTHER", "index": 0}],
  "promptFeedback": {
    "safetyRatings": [
      {"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE"},
      {"category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE"},
      {"category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE"},
      {"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE"}
    ]
  }
}

其他更詳細的說明，請參考以下官方文件：

Gemini API GenerateContentResponse 參考資料

Python 範例程式碼

在官網的範例是使用他們創建的 google-generativeai 套件。
不過這邊我想改用我們熟悉的 Requests 套件來嘗試、示範。

首先要確認有安裝 Requests 套件：

1
pip install requests

那我們開始吧~🏃

單個純文字

純粹問它一段話：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# 單個純文字
import json
import requests

url = f'https://generativelanguage.googleapis.com/v1/models/gemini-pro:generateContent?key={API_KEY}'
headers = {'Content-Type': 'application/json'}
data = {
    "contents": [
        {
            "parts": [{"text": "你知道王建民嗎？"}]
        }
    ]
}
response = requests.post(url, headers=headers, json=data)
print(f"response status_code: {response.status_code}")
print(json.dumps(response.json(), indent=4, ensure_ascii=False))

單個純文字 + 參數

問它一段話，並且加上一些參數設定：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 單個純文字 + 參數
import json
import requests

url = f'https://generativelanguage.googleapis.com/v1/models/gemini-pro:generateContent?key={API_KEY}'
headers = {'Content-Type': 'application/json'}
data = {
    "contents": [
        {
            "parts": [{"text": "你知道王建民嗎？"}]
        }
    ],
    "safetySettings": [
        {
            "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
            "threshold": "BLOCK_NONE"
        }
    ],
    "generationConfig": {
        "temperature": 1.0,
        "maxOutputTokens": 30,
        "topP": 0.8,
        "topK": 10
    }
}
response = requests.post(url, headers=headers, json=data)
print(f"response status_code: {response.status_code}")
print(json.dumps(response.json(), indent=4, ensure_ascii=False))

多輪純文字對話（聊天）

像在 Bard 或 ChatGPT 上一樣，可以多輪對話，它會記得之前的內容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 多輪對話（聊天）
import json
import requests

url = f'https://generativelanguage.googleapis.com/v1/models/gemini-pro:generateContent?key={API_KEY}'
headers = {'Content-Type': 'application/json'}
data = {
    "contents": [
        {
            "role": "user",
            "parts": [{"text": "你知道王建民嗎？"}]
        },
        {
            "role": "model",
            "parts": [{"text": "我知道王建民。王建民，1980年3月31日出生於台灣台中市，是一位前台灣棒球選手，司職投手。他曾效力於中華職棒的興農牛隊，美國職棒的紐約洋基隊、華盛頓國民隊和芝加哥白襪隊，以及中國棒球聯賽的北京猛虎隊。\n\n王建民是台灣史上第一位大聯盟先發勝投破百的投手，也是第一位入選大聯盟全明星賽的台灣選手。他在2006年締造19勝6敗、 防禦率3.63的優異成績，並在季後賽拿下3勝0敗的戰績，幫助洋基隊奪得世界大賽冠軍。王建民也因此成為台灣的棒球英雄，並獲得「台灣之光」的稱號。\n\n然而，王建民在2008年季初因傷缺陣，並在2009年進行了韌帶移植手術。此後，他的成績大幅下滑，並在2012年離開了大聯盟。王建民於2013年回歸中華職棒，效力於義大犀牛隊。2016年，他宣布正式退休。\n\n王建民的職業生涯戰績為127勝72敗， 防禦率3.92，三振數1718次。他是台灣棒球史上最成功的投手之一，也是台灣人民的驕傲。"}]
        },
        {
            "role": "user",
            "parts": [{"text": "他現在在哪裡？"}]
        },
    ]
}
response = requests.post(url, headers=headers, json=data)
print(f"response status_code: {response.status_code}")
print(json.dumps(response.json(), indent=4, ensure_ascii=False))

單個文字和圖片

如果需要 AI 可以看圖片，需要改用 Gemini Pro Vision 模型 (支援文字和圖片輸入)，並且圖片要轉換為 Base64 編碼的字串，

圖片的 mime_type 參數目前支援「image/png」、「image/jpeg」、「image/heic」、「image/heif」、「image/webp」幾種格式。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# 單個文字和圖片
import json
import requests
import base64

# 讀取圖片檔案，並轉換成 Base64 編碼的字串
with open("gemini_test_image.jpg", "rb") as image_file:
    image_base64_string = base64.b64encode(image_file.read()).decode('utf-8')
    # print(image_base64_string)

url = f'https://generativelanguage.googleapis.com/v1/models/gemini-pro-vision:generateContent?key={API_KEY}'
headers = {'Content-Type': 'application/json'}
data = {
    "contents": [
        {
            "parts": [
                {"text": "詳細說明你在這張圖片中看到什麼？"},
                {
                    "inline_data": {
                        "mime_type": "image/jpeg",
                        "data": image_base64_string
                    }
                }
            ]
        },
    ]
}
response = requests.post(url, headers=headers, json=data)
print(f"response status_code: {response.status_code}")
print(json.dumps(response.json(), indent=4, ensure_ascii=False))

結語

v1 Beta 版本還有更多功能，像是函數呼叫(Function calling)、語意檢索器(Semantic Retriever、RAG)，雖然還在測試中，不建議用於正式版應用，但有興趣的還是可以去玩玩看🤖。

至少在今年底前使用 Google Gemini API 都是「免費」使用，你想要拿來練習、做專案、做 Side Project 都可以使盡玩(?)，但要注意不要上傳任何敏感資料，因為目前方案所有的輸入輸出都可能會被拿去當訓練資料。

參考：
Google Gemini 官方網站
 Google Gemini API 說明文件
 Google AI Studio
Google for Developers Blog

The sky’s the limit
一切皆有可能

🔻 如果覺得喜歡，歡迎在下方獎勵我 5 個讚~