# 效率神器：Python 協同 Gemini，辦公事半功倍
## 課程目標
* 了解如何獲取與應用 Gemini API Key
* 從 0 開始，利用 Gemini 與 Python 讀寫分析 Excel 檔案
* 實際體驗 Prompt Engineering 與微調參數對生成式語言模型的影響
## 為何要學這個?
當我們想要分析一個現象，例如咖啡廳該如何制定未來的營銷策略，我們需要兩個關鍵要素：
1. 好的資料來源：
確保我們獲取的資訊是準確且有價值的，例如顧客消費行為、熱門時段、產品銷售數據等。
2. 有效的資料分析與整理：
將這些原始數據轉化為有意義的見解，例如哪些產品最受歡迎、促銷活動是否提升了營收，甚至是不同天氣對顧客來店率的影響。
這正是本課程的核心！🎯 利用Gemini輔佐我們，更快與更好的整理、分析、生成結論，節省許多時間！
## 在 Pyhton 中使用 Gemini
- ### 先到 [Google AI Studio](https://aistudio.google.com/api-keys) 取得API Key
若要在 Python 中使用 Gemini，您需要先取得 Gemini API 金鑰，預設是免費的。
> [!NOTE]API Key
你可以把 Gemini 想像成圖書館，圖書館不是任何人都能隨意進出的，你必須先辦一張借書證，才能使用館內的資源。
API 金鑰 = 圖書館給予的身分憑證，確保你能夠順利存取 Gemini 的功能，並且與 Gemini 互動
1. 點選 `Create API key`
2. 在 `Choose an imported project` 欄位點選 `Gemini API`
3. 點選 `Create key`
4. 複製 API key 。注意不要洩漏出去，以免出現安全疑慮
- ### 將得到的 API Key 放到 Python 程式中，以 [Colab](https://colab.research.google.com/drive/1g8T3vHKo1zsfNsaqtrIVFPjGKOE5_cUf?usp=sharing) 為例
1. 進入 Colab 檔案，點選 Secret (左側鑰匙形狀的圖標)，新增密鑰，將剛剛得到的 API Key 貼到值當中，並且命名為 `GEMINI_API_KEY`。
2. 安裝 Gemini 必要的函式庫
```python=
!pip install -q -U google-genai
```
3. 利用 API key 進行身份驗證
```python=
from google import genai
# --------- 1. 取得 API Key ---------
from google.colab import userdata
# 從 Colab Secret 讀取 API Key
api_key = userdata.get('GEMINI_API_KEY')
# ------ 2. 建立 Gemini Client ------
# 確定是否有抓取到API Key
if api_key:
client = genai.Client(api_key=api_key) # 重點是這句，驗證 API Key
print("✅ GEMINI API Key 已成功載入！")
else:
print("❌ 無法讀取 GEMINI_API_KEY，請確認 Secret 設定正確。")
```
>[!Important]為何不將 API key 直接貼到程式碼中
如果直接將 API Key 代碼直接寫在程式碼中就像把鑰匙掛在門口，誰都能輕易取得。
Secret 就像保險箱，安全地儲存敏感資訊（API 金鑰），只有授權的程式才能存取。
- ### 開始使用看看Gemini
- 尋找要使用的 Gemini 模型：
可以將所有可用模型列出來
```python=
for model in client.models.list():
print(model)
```
或是在 Gemini API 官方文件中查詢 [模型相關資訊](https://ai.google.dev/gemini-api/docs/models?utm_source=chatgpt.com&hl=zh-tw)。
並且可以查看不同方案下（我們使用免費版）每個模型的使用的 [頻率限制](https://ai.google.dev/gemini-api/docs/rate-limits?utm_source=chatgpt.com&hl=zh-tw)。
下面我要使用的模型是 Gemini 2.5 Flash，它是目前最新的 Flash 模型。相較於 Pro 模型而言，Flash 模型較輕量、快速。
- 第一種 Gemini API 呼叫方式
```python=
# 將 '選擇的模型' 以及 '詢問的內容' 同時作為參數傳入函式中，取得回應
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="請簡單介紹 Gemini 是什麼？"
)
# 將回答的 '文字內容' 輸出
print(response.text)
```
- 第二種 Gemini API 呼叫方式
```python=
# 預先設定我們要使用的模型，創建「聊天物件」
chat = client.chats.create(model="gemini-2.5-flash")
# 將詢問內容傳入聊天物件，取得回應
response = chat.send_message("請簡單介紹 Gemini 是什麼？")
print(response.text)
```
> [!Note]與第一種方式的差異：
> 1. 每次詢問都是使用同一個模型，因此後面每次呼叫都不用再設定模型名稱。
> 2. 它會自動「儲存對話紀錄」，每次對話都會參考先前的對話紀錄來進行回應。
## Pandas 套件
- ### 載入 Excel 表格
1. 將 [Excel 表格](https://docs.google.com/spreadsheets/d/1lO1SU-guGcBmGoO6b6osZVI4npiTK_A_/edit?usp=sharing&ouid=109758665493429366534&rtpof=true&sd=true) 上傳到 Colab 當中
a. 點擊 `Colab 左側 -> 檔案`
b. 將 Excel 表格拖入其中。或點擊左上角的上傳按鍵選擇上傳的檔案。
2. 讀取 Excel 檔案
```python=
import pandas as pd
df = pd.read_excel("幹部招募.xlsx", sheet_name="Sheet1")
```
* 第一個參數為 檔案名稱
* sheet_name 參數為 Sheet 名稱
- ### 功能介紹
Pandas 是一個強大的 Python 資料分析庫，讓我們能輕鬆處理和分析資料。以下介紹幾個接下來會用到的 Pandas 函式：
1. #### `df.columns`
用途：取得 DataFrame 所有欄位的 標籤名稱。
2. #### `df[標籤名稱]`
用途：取得指定標籤對應的 欄位 資料（可以選取多欄）。
3. #### `df.loc[index, (標籤名稱)]`
- `df.loc[index]`
用途：取得第 index + 1 列 的資料（標籤列不算一列）
- `df.loc[index, 標籤名稱]`
用途：取得第 index + 1 列 中指定標籤對應到的 欄位 資料
4. #### `df.iterrows()`
用途：逐列走訪 DataFrame，回傳 (index, row)，通常搭配 for 迴圈使用。
- `index`：每一列的索引值。
- `row`：第 index + 1 列的資料。
- `row[標籤名稱]`：該列按照指定標籤對應到的值，以第一列為例：
- `row["姓名"]` 對應到值「小燈」
- `row["學號"]` 對應到值「411151921」
5. #### `row.items()` (承上)
用途：取得該列所有欄位的 (label, value)，通常搭配 for 迴圈使用。
- `label`：標籤名稱。
- `value`：該列資料由此 label 對應到的值。
6. #### `df[df['標籤'] == '值']`
用途：篩選特定條件的列，回傳只包含滿足條件的列。
## 結合 Gemini 與 Pandas 來分析 Excel
我們將 Excel 表格中的面試者資訊傳遞給 Gemini 進行分析。每位面試者的資料將獨立處理，確保資訊不會相互混用。
- ### **分析一：統整面試者資訊**
- **步驟：**
遍歷 Excel 表格的每一列，提取該面試者的相關資訊，對每一列進行以下步驟：
1. 遍歷此列資訊的每一欄，整理成一個 prompt
2. 將 prompt 傳給 Gemini 進行分析
3. 將此列資訊新增一欄，放置分析結果
最後將 df 輸出成新的 Excel 檔案。
- ### **分析二：統計組別人數**
- **步驟：**
1. 從 Excel 表格整理出一個 prompt
2. 將 prompt 傳給 Gemini 進行分析
3. 將第一列資訊新增一欄，放置分析結果
4. 將 df 輸出成新的 Excel 檔案
- **第一種 prompt：**
```python=
prompt = ""
for index, row in df.iterrows():
label = '投稿餐與組別'
prompt += f"{label}:{row[label]}\n"
prompt += "幫我統計一下各組別報名的人數，並且統整出哪個組別報名人數最多"
```
- **第二種 prompt：**
```python=
prompt = f"幫我統計一下各組別報名的人數，並且統整出哪個組別人數最多，以下是報名資訊：\n{df['投稿餐與組別']}"
```
- **分析與匯出檔案：**
```python=
response = chat.send_message(prompt)
print(response.text)
df.loc[0,'AI回應'] = response.text
df.to_excel("幹部招募(Gemini)2.xlsx", index=False)
```
## Prompt Engineering
- ### 什麼是 Prompt Engineering？
想像一下，你走進咖啡店，對店員說：「我要咖啡」
你可能會得到任何一種咖啡如美式、摩卡，甚至甜度、冷熱、杯數都完全取決於店員的猜測，結果往往與你的預期不符，導致需要花費大量時間重新敘述要求。
但如果你清楚地說： 「您好，我要點兩杯咖啡。一杯大杯冰美式，加一包糖，希望使用深度烘焙的咖啡豆；一杯熱拿鐵，改用燕麥奶，不加糖，拉花圖案希望是貓咪」
這樣的指令更具體，店員能夠準確地提供你想要的兩杯咖啡。
這就像在使用 AI 時的 Prompt Engineering——你的Prompt越清晰、細緻，AI 生成的回應就越符合你的期待。
- ### 具體化你所想的內容
- ❌ 不佳的 Prompt：「幫我整理這些資訊，我要用來面試」
- ✅ 優化後的 Prompt：「請幫我根據他們填寫的履歷，整理後提出適合實體面試此人的題目」
→ 這樣 Gemini 才會知道 "你希望 AI 產生的是面試問題，而不是單純整理履歷"。
- ### 提供額外的背景資訊
- ❌ 不佳的 Prompt：「幫我整理這些資訊，我要用來面試」
- ✅ 優化後的 Prompt：「請幫我整理這些 '申請擔任社團幹部的面試者' 所提供的資料，使我能更快速理解他們的經歷與能力。」
→ 這樣 Gemini 才能清楚理解 "這些資料的背景是社團幹部招募的申請資訊，並據此提供更有針對性的整理方式"。
- ### 明確指定輸出格式
- ❌ 不佳的 Prompt：「幫我整理這些資訊，我要用來面試」
- ✅ 優化後的 Prompt：
「請幫我根據這些資訊，幫我整理出約100字的簡介:
1.他是否有擔任社團、活動組織等經歷
2.他對於科技知識的理解程度
3.他常使用的科技工具主題
4.他是否對於我們的社團具有足夠的熱忱」
→ 指定輸出格式，使Gemini能夠根據列點，回應更符合所需。
> [!Important]請不用擔心 Prompt 寫的內容太多
> 當前目標是 確保輸出的精確性與穩定性，需要更多說明以幫助 Gemini 更清楚理解需求。
> 當 AI 穩定輸出符合預期結果後，再逐步微調 Prompt，減少冗長內容，提高效率。
## 微調模型參數
- ### 介紹
當使用 API 或其他模 型配置時，還可以調整以下參數來影響回應的風格：
> *詳細資訊可參考相關說明文件：[文件一](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference?utm_source=chatgpt.com&hl=zh-tw#generationconfig), [文件二](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/content-generation-parameters#max-output-tokens)*
| 參數 | 說明 | 範圍 | 2.0 flash 預設值 |
| --- | --- | ---- | --- |
| **temperature** | 隨機性：調整詞語機率分布的平滑度 | `0 ~ 2` | `1` |
| **top_k** | 多樣性：選擇幾率最高的`k`個詞作為候選 | `0 ~ 100` | `40` |
| **top_p** | 多樣性：選擇機率累積在`p`以內的詞作為候選 | `0 ~ 1` | `0.95` |
| **candidate_count** | 生成候選回應數量，然後選擇其中最佳的一個 | `1 ~ 8` | `1` |
| **seed** | 如果使用相同的種子，模型生成的文本會是相同的，用於重現結果 | `任意整數` | `None` |
| **max_output_tokens** | 限制最大輸出長度 | `正整數` | `8192` |
| **stop_sequences** | 設定停止生成的關鍵字 | `文字字串` | `None` |
| **presence_penalty** | 懲罰已經出現過的詞語 | `-2 ~ 2` | `None` |
| **frequency_penalty** | 懲罰高頻出現的詞語 | `-2 ~ 2` | `None` |
- ### 範例
1. **生成精確且嚴謹的技術回應**
```python=
chat = client.chats.create(
model="gemini-2.0-flash",
config={
"temperature": 0.2, # 創意性調低，避免胡亂想像
"top_p": 0.3, # 限制詞語多樣性，讓他更能回答專業術語
# "max_output_tokens": 500 # 減少回答 token 數，逼迫他精簡回答
}
)
```
2. **生成具有創意性的文案稿**
```python=
chat = client.chats.create(
model="gemini-2.0-flash",
config={
"temperature": 1.5, # 控制創意性，適度開放但不過度隨意
"top_p": 0.99, # 提高多樣性，讓語言更具靈活性
"top_k": 90 # 提高多樣性，讓語言更具靈活性
}
)
```
3. **生成具有創意性且多樣的內容**
```python=
chat = client.chats.create(
model="gemini-2.0-flash",
config={
"temperature": 1.5, # 控制創意性，適度開放但不過度隨意
"top_p": 0.99, # 提高多樣性，讓語言更具靈活性
"top_k": 90, # 提高多樣性，讓語言更具靈活性
"frequency_penalty": 1.5, # 懲罰頻繁出現的詞彙，減少重複
"presence_penalty": 1.2 # 懲罰已出現過的詞彙，讓內容更具新意
}
)
```
## **練習：銷售策略分析**
- ### 目標：
你有咖啡廳最近一週銷售狀況的 [Excel 表格](https://docs.google.com/spreadsheets/d/18q1woK2aDSyWuQUf4lCCdJ7w-HuQkv9o/edit?usp=sharing&ouid=109758665493429366534&rtpof=true&sd=true)，請讓 Gemini 根據「各種因素 + 總銷售量」，回答「各種因素下與咖啡銷量相關的可能性」，讓老闆能有更好的銷售決策可以準備。
- ### 步驟指引：
- 使用 Gemini API 需要做甚麼前置作業?
- 怎麼讀取 Excel 表格?
- Excel 表格中有哪些欄位是我們需要的?
- 要如何整理資料？並且如何準確地提出指令給 Gemini?
Sign in with Wallet
Connect another wallet