# 效率神器：Python 協同 Gemini，辦公事半功倍(1)

## 課程目標
- 了解如何獲取與應用Gemini API Key
- 從0開始，利用Gemini與Python讀寫分析Excel檔案
- 實際體驗Prompt Engineering與微調參數對生成式語言模型的影響

## 為何要教這個?
當我們想要分析一個現象，例如**咖啡廳該如何制定未來的營銷策略**，我們需要兩個關鍵要素：

1️⃣ 好的資料來源——確保我們獲取的資訊是準確且有價值的，例如顧客消費行為、熱門時段、產品銷售數據等。
2️⃣ 有效的資料分析與整理——將這些原始數據轉化為有意義的見解，例如哪些產品最受歡迎、促銷活動是否提升了營收，甚至是不同天氣對顧客來店率的影響。

這正是本課程的核心！🎯 利用Gemini輔佐我們，更快與更好的整理、分析、生成結論，節省許多時間！

## 嘗試在Pyhton中使用Gemini，利用Gemini API Key
若要在 Python 中使用 Gemini，您需要先取得 Gemini API 金鑰。
>[!Note] API Key
>你可以把 Gemini 想像成圖書館，圖書館不是任何人都能隨意進出的，你必須先辦一張借書證，才能使用館內的資源。
>API 金鑰 = 圖書館給予的身分憑證，確保你能夠順利存取 Gemini 的功能，並且與 Gemini 互動

### 第一步 : 到[Google AI Studio](https://aistudio.google.com/)取得API Key

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/Bk9daIx5ke.png" style="width: 70%; border: 2px solid black; padding: 5px;" />
</div>

點擊Sign in Google AI Studio，登入自己的Google帳號
<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/B1IC6Lg5Je.png" style="width: 75%; border: 2px solid black; padding: 5px;" />
</div>

進入到Studio中，點擊`API Keys -> Create API Key`，如果你有出現`Search Google Cloud project`此欄位的話，請選擇**Generative Language Client**或**Gemini AI**帳號，並且Create API

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/BknGkwg5Jg.png" style="width: 70%; border: 2px solid black; padding: 5px;" />
</div>

而你將會得到一串API Key，請複製後好好保存，並且不要洩漏出去，以免出現安全疑慮

>[!Important] Generative Language Client帳號 或 Gemini AI帳號
> 這個帳號主要是一個專門建立API Key的一個GCP帳號，此帳號有免費與付費專案(預設為免費，不用填寫信用卡資訊)。
> <div style="text-align: center;">
<img src="https://hackmd.io/_uploads/HyDAkDg5kg.png" style="width: 60%; border: 2px solid black; padding: 5px;" />
</div>

---
### 第二步 : 將得到的API Key放到Python程式中，以[Colab](https://colab.research.google.com/drive/1vUng8b8uXYsnTzNSDFIyY1tfElsh16u8?usp=sharing)為例

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/ByX3-De9kl.png" style="width: 70%; border: 2px solid black; padding: 5px;" />
</div>

新增與進入新的Colab檔案當中，並且點選Secret(左側鑰匙形狀的圖標)。
並將剛剛得到的API Key貼到**值**當中，並且命名為`GEMINI_API_KEY`。
<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/B1fwvDl5ye.png" style="width: 75%; border: 2px solid black; padding: 5px;" />
</div>

安裝完必要的函式庫之後，利用userdata去call我們剛剛儲存的API Key。
點擊左側"執行"按鈕以啟動該區間程式。
如果剛剛到現在的步驟皆正確的話，則你在此區間會得到`✅ GEMINI API Key 已成功載入！`此訊息出來

>[!Warning]如果它顯示無法讀取，可能發生的問題:
> - 他未讀取到新的設定 : 到左上角`執行階段->重新啟動工作階段`讓他重新讀取GEMINI_API_KEY的設定
> - 變數名稱打錯 : 可能你在Secret的部分輸錯名稱，導致讀取失敗
> - API Key出錯 : 請回到第一步重新抓取一個信的API Key

>[!Important] 為何要這樣設定，儲存到Secret後要又要用userdata去撈
>如果直接貼上API Key代碼，就像把家裡的鑰匙放在保險箱裡，直接寫在程式碼中就像把鑰匙貼在門上，誰都能輕易取得。
>Secret 就像保險箱，安全地儲存敏感資訊（API 金鑰），只有授權的程式才能存取。
---
### 第三步 : 開始使用看看Gemini

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/ryQerqVj1e.png" style="width: 70%; border: 2px solid black; padding: 5px;" />
</div>

我們一開始使用的時候，我們要宣告 ==**要使用的model編號、內容content指引**==。
以上圖為例，我們使用`gemini-pro`這個model，並且要求此model的content為"請簡單介紹 Gemini 是甚麼"。

> 白話來說 : 我們問模型`gemini-pro`回答:"請簡單介紹 Gemini 是甚麼"

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/SkT57Fx5kg.png" style="width: 70%; border: 2px solid black; padding: 5px;" />
</div>

最終，你會看到Gemini的回應，則代表你成功call到Gemini AI，並且收到Gemini的回應了

## 開始結合Excel表格

### 第一步 : 先將[Excel表格](https://docs.google.com/spreadsheets/d/1zjJChpz_G2jZiHZ1mITh3kSwuaz9m0lW/edit?usp=sharing&ouid=118066717766893473329&rtpof=true&sd=true)上傳到Colab當中

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/r1-yUAZq1x.png" style="width: 70%; border: 2px solid black; padding: 5px;" />
</div>

將上述連結下載下來的Excel表格拉到`Colab左側->檔案`中，讓其Colab資料夾中有我們要用來分析的表格。

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/SkI6wR-qJx.png" style="width: 50%; border: 2px solid black; padding: 5px;" />
</div>

上傳成功後，您應該能夠在 Colab 的「檔案」管理器中看到該 Excel 檔案。

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/BJtJdRZqyx.png" style="width: 50%; border: 2px solid black; padding: 5px;" />
</div>

接者，我們將會利用pandas函式庫來操作我們的表格，我們先讓變數`df`吃到Sheet，我們宣告`pd.read_excel("Excel檔案名稱"，sheet_name = "要用於分析的Sheet名稱")`。
成功執行後，df 變數將會包含 Excel 表格的內容，之後對df做事情 = 對指定Excel檔案做事情。
> 以上述下載下來的Excel，Excel檔案名稱 = "幹部招募"，sheet_name = Sheet1
> Sheet的名稱在Excel檔案打開後，左下角即可看到
<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/rJPdDRZ5yx.png" style="width: 80%; border: 2px solid black; padding: 5px;" />
</div>

### 第二步 : 理解一些pandas函式
Pandas 是一個強大的 Python 資料分析庫，讓我們能輕鬆處理和分析資料。以下介紹幾個接下來會用到的 Pandas 函式：

---
#### a.`df.columns`
用途：返回 DataFrame 中所有欄位的名稱，以 Series 的形式呈現。
<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/ryuTi0b9yl.png" style="width: 100%; border: 2px solid black; padding: 5px;" />
</div>

以範例來說，df.columns的結果即是各Column代表的標籤，從"姓名"開始羅列

---

#### b.`df["(標籤名稱)"]`
用途：擷取 DataFrame 中指定標籤（欄位名稱）的整個欄位資料。
<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/SkrHn0W5ye.png" style="width: 60%; border: 2px solid black; padding: 5px;" />
</div>

以範例來說，我們要求輸出表單Column標籤為"姓名"，則他就會列出所有所有人人的名字

---

#### c.`df.loc[(index),(標籤名稱)]`
用途：在指定欄位（標籤名稱）的整個欄位中，修改第 index+1 的資料。

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/B1wmUqEj1e.jpg" style="width: 80%; border: 2px solid black; padding: 5px;" />
</div>

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/BJzn2RZ5kl.png" style="width: 80%; border: 2px solid black; padding: 5px;" />
</div>

以範例來說，我們要求輸出表單Column標籤為"姓名"且"index為1"的資料，則他就會列出"小祥"

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/ry_As5Ej1l.png" style="width: 110%; border: 2px solid black; padding: 5px;" />
</div>

我們要求輸出表單"row index = 4"的資料，則他就會列出"小樂的所有資訊"

---

#### d.`df.iterrows()`
用途：將 DataFrame 中的每一行拆分成一個 Series，並依序返回索引和對應的 Series。
而其返回值:
- index: 每一行的索引值。
- row: 該索引對應的 Series，包含該行所有欄位的值。
>[!Warning]注意：
iterrows() 會自動跳過第一行（pandas函數庫預設Sheet第一個row都是放Column屬性）。

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/S1SgWyGcyl.jpg" style="width: 100%; border: 2px solid black; padding: 5px;" />
</div>

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/HJq8bJGqkg.png" style="width: 80%; border: 2px solid black; padding: 5px;" />
</div>

以範例來說，for迴圈遍巡了所有"子表單"，並將所有子表單Column標籤為"姓名"跟"學號"顯示出來。

---

#### e.`for col_name, value in row.items()`
用途：遍歷 Series (row) 中的每個元素。
而其返回值:
- col_name: 欄位名稱。
- value: 該欄位對應的值。

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/By_AMJfqke.jpg" style="width: 80%; border: 2px solid black; padding: 5px;" />
</div>

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/ryXbm1G9ye.png" style="width: 100%; border: 2px solid black; padding: 5px;" />
</div>

以範例來說，for迴圈遍巡了所有"當前子表單的所有內容"，其實就等於抓取了一位面試者的所有填寫資訊(一row的資訊)。

---
#### f.`df_split = df[df['(標籤)'] == '(值)']`

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/B1HUa-Osyx.jpg" style="width: 100%; border: 2px solid black; padding: 5px;" />
</div>

大概操作邏輯如上圖，通常來說只要把`'(標籤)'`跟`'(值)'`替換成需要的標籤與值，他就能幫我們整理出有條件的Row資料成一表格

### 第三步 : 將指定的資訊儲存成Prompt，並將他給Gemini分析
<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/SyfUrJGqyl.png" style="width: 100%; border: 2px solid black; padding: 5px;" />
</div>

以範例來說，我們將 Excel 表格中的面試者資訊傳遞給 Gemini 進行分析。每位面試者的資料將獨立處理，確保資訊不會相互混用。

並且，我們會遍歷 Excel 表格的每一行，提取該面試者的相關資訊，並將其轉換為 prompt，再傳送給 Gemini 進行分析。

### 第四步 : 將Gemini生成的response存到df中並輸出新的Excel檔案
最終，我們的程式完整版就會長:

for index, row in df.iterrows():
    prompt = ""
    for col_name, value in row.items():
        prompt += f"{col_name}: {value}\n"
    try:
        prompt += "幫我整理這位面試者的資訊，整理成約100字介紹"
        response = model.generate_content(prompt)
        print(response.text)
        print("-" * 20) 
        df.loc[index, 'Gemini_Summary'] = response.text  

    except Exception as e:
        print(f"Error processing row {index + 1}: {e}")
        df.loc[index, 'Gemini_Summary'] = f"Error: {e}" # Record the error in the DataFrame
df.to_excel("幹部招募(Gemini).xlsx", index=False)

和上面圖片不同的是，我們這裡的程式有將 Gemini 回應直接儲存到`df.loc[index, 'Gemini_Summary']`中，如同儲存 **"當前面試者的index中，標籤為Gemini_Summary的欄位中"**

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/HyEkqJM9ye.png" style="width: 50%; border: 2px solid black; padding: 5px;" />
</div>

最後利用`df.to_excel("幹部招募(Gemini).xlsx", index=False)`儲存新的Excel檔案，而你在檔案夾中，應該會看到新的檔案出現。

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/HkPbqkMq1e.png" style="width: 100%; border: 2px solid black; padding: 5px;" />
</div>

點開後，你就會看到妳的檔案中多了一個Gemini_Summary的欄位。
這樣，我們就對Gemini與Excel的操作有一定認識了!
## Prompt Engineering 與微調參數以讓Gemini回答更精確
>[!Important]什麼是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的能力
> 
> 我在將面試者的所有填寫資訊填入後，加入這樣的Prompt，最終五次輸出結果
> 1.格式亂七八糟
> 2.他沒看懂我的面試者是有根據組別投稿的
> 3.他不知道我的社團性質，所以他把我當作公司面試，並且也沒有生出面試問題
>> 請根據上面的Prompt原則，優化他，使他能夠生出
>> "格式固定、理解不同組別的差異後，生成適合大學社團幹部面試的題目"。

>[!Warning]請不用擔心Prompt寫的內容太多
>當前目標是 ==**確保輸出的精確性與穩定性**==，需要更多說明以幫助 Gemini 更清楚理解需求。
>當 AI 穩定輸出符合預期結果後，再逐步微調 Prompt，減少冗長內容，提高效率。

### 微調模型參數以獲得最佳結果
當使用 API 或其他模型配置時，還可以調整以下參數來影響回應的風格：

| 參數 | 說明 | 範圍 |
|------|------|------|
| **temperature** | 控制隨機性（值越高，創意性越高） | `0 ~ 1` |
| **top_p** | 確保生成詞語的多樣性 | `0 ~ 1` |
| **top_k** | 選擇概率最高的 K 個詞來生成 | `1 ~ 100` |
| **candidate_count** | 生成候選回應數量，然後選擇其中最佳的一個 | `1 ~ 10` |
| **seed** | 如果每次都使用相同的種子，模型生成的文本將會是相同的，可用於重現結果 | `任意整數` |
| **max_output_tokens** | 限制最大輸出長度 | `50 ~ 4096` |
| **stop_sequences** | 設定停止生成的關鍵字 | `文字字串` |
| **presence_penalty** | 懲罰已經出現過的詞語 | `-2 ~ 2` |
| **frequency_penalty** | 懲罰高頻出現的詞語 | `-2 ~ 2` |

### 如何組合這些參數來達到最佳效果？
我們在宣告model的時候，我們可以不僅說"我要使用Gemini pro模型"，我們還可以多補充我們所想要的微調參數，以下是依些微調例子模板:

---
#### 1.生成精確且嚴謹的技術回應

model = genai.GenerativeModel(
    model_name="gemini-1.5-flash",  
    generation_config={        #在這裡輸入微調參數
      "temperature": 0.2,      #創意性調低，避免胡亂想像
      "top_p": 0.3,            #限制詞語多樣性，讓他更能回答專業術語
      "max_output_tokens": 100 #減少回答token數，逼迫他精簡回答
    }
)

**適用範圍：** FAQ、自動化程式碼生成、法律條款解釋等需要準確性的內容。

---
#### 2.生成具有創意性的文案稿

model = genai.GenerativeModel(
    model_name="gemini-1.5-flash",  
    generation_config={
      "temperature": 0.9,  # 創意性調高，提升想像
      "top_p": 0.8,        # 設定詞語選擇的多樣性，較高的值會增加多樣性
      "top_k": 50,         # 設定選擇概率最高的 K 個詞進行生成，有助於提高生成內容的品質和合理性
    }
)

**適用範圍：** 於詩詞創作、小說情節發想、品牌故事撰寫等需要較高創意性的文案。

---

#### 3. 生成長篇內容並控制內容多樣性

model = genai.GenerativeModel(
    model_name="gemini-2.0-flash",  
    generation_config={        
      "temperature": 0.7,        # 控制創意性，適度開放但不過度隨意
      "top_p": 0.9,              # 提高多樣性，讓語言更具靈活性
      "top_k": 40,               # 控制選擇詞彙的範圍，避免過度冗長
      "frequency_penalty": 1.5,  # 懲罰頻繁出現的詞彙，避免重複
      "presence_penalty": 1.2    # 懲罰已出現過的詞彙，讓內容更具新意
    }
)

**適用範圍：** 於長篇寫作、新聞摘要、對話生成等場景，特別需要保持流暢且多樣化的內容。

## 進階操作 : 在Google AI Studio中訓練調優模型並應用
當你使用 Gemini 來處理簡單的 Excel 操作或一般問答時，它的表現通常令人滿意。然而，當你希望建立一個 客服 AI，並讓它回答特定的標準答案時，事情可能會變得複雜。即使不斷調整 Prompt（提示詞），結果可能還是不如預期，出現偏差或無法精確對應你的需求。

在 Google AI Studio，我們可以透過微調（fine-tuning） 來提升模型的表現

### 第一步：進入 Google AI Studio 的「Tune a Model」頁面
返回 Google AI Studio：

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/Hkhg86AjJg.png" style="width: 100%; border: 2px solid black; padding: 5px;" />
</div>
在您取得 API 金鑰的頁面下方，您會看到多個標籤，點擊「Tune a Model」標籤，進入模型微調介面。

### 第二步:準備訓練資料

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/HyGwLaCikg.png" style="width: 70%; border: 2px solid black; padding: 5px;" />
</div>

為了讓 Gemini 模型能精確回答特定問題，我們需要提供包含「問題」和「對應答案」的訓練資料集，點擊`Create a Structured prompt`建立結構化提示，建立適合微調的資料集。

為了加速課程進度，請先點擊[此連結](https://aistudio.google.com/app/prompts?state=%7B%22ids%22:%5B%221FZJlEg1oydWpNjQkS9lJzwUSxvKZkxY6%22%5D,%22action%22:%22open%22,%22userId%22:%22118066717766893473329%22,%22resourceKeys%22:%7B%7D%7D&usp=sharing)

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/r1lWuTAjkg.png" style="width: 100%; border: 2px solid black; padding: 5px;" />
</div>

進入後，你會看到此畫面
- Optional tone and style instruction : 這裡將會決定此model**全局的回應方式**為何，通常用來調整**回應的語氣、結構、風格** (例如設定模型以「專業、禮貌、親切」的語氣回應，例如「先生/小姐您好，請問有什麼能為您服務的嗎？」。)
- INPUT/OUTPUT : 這裡可以用來決定**對於特定問題的回應方式**，它建立的是「條件反射」式的回應模式，當模型接收到特定的「INPUT」時，就會輸出對應的「OUTPUT」。

### 第三步:建立好Data後，準備Tune a Model

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/H1APY6AsJe.png" style="width: 50%; border: 2px solid black; padding: 5px;" />
</div>

當你建立好你的Dataset後，往右上角看，點擊Save按鈕，並返回到Tune a Model頁面。

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/BktCYT0i1l.png" style="width: 80%; border: 2px solid black; padding: 5px;" />
</div>

在Data source中，引用我們剛剛建立的Dataset
<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/ryIW9TCsyx.png" style="width: 60%; border: 2px solid black; padding: 5px;" />
</div>

準備好後，就可以Tune這個模型了，請等待他訓練完成。

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/Syzcqa0jke.png" style="width: 100%; border: 2px solid black; padding: 5px;" />
</div>

訓練完成後，你會看到Model ID，請將他複製下來，這就是你訓練完之後，他所給予的Model ID名稱，等等就可以貼到Pyhton程式碼中做使用了!

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/BJop9aCo1l.png" style="width: 100%; border: 2px solid black; padding: 5px;" />
</div>

請先滑動到下方，看到`ADD API access`，這裡是要將其模型授權到你的Google Cloud projects當中，請點擊你剛剛生成API Key的那個帳號(通常來說是Generative Language Client 或 Gemini AI)，並點擊`Grant access`

<div style="text-align: center;">
<img src="https://hackmd.io/_uploads/H1QqiT0jyx.png" style="width: 100%; border: 2px solid black; padding: 5px;" />
</div>

我們執行一個簡單的程式，在這邊請幫我把`model = genai.GenerativeModel()`貼上你剛剛複製的Model ID，這樣就可以使用你所設計的調優參數囉!

## 來一次從0開始的挑戰吧!

### 範例一[簡單] : 綜整出大家給予的心得
我現在有一個新的[Excel檔案](https://docs.google.com/spreadsheets/d/1GJAroK200d8_YgtUkFgsK62t6yFVBhx6cNsYr_EFCCE/edit?usp=sharing)，請幫我分析"所有人給予的評價"，利用Gemini列出課程的優缺點。

### 範例二[中等] : 根據一周咖啡廳數據想出更好銷售攻略
我現在有一個新的[Excel表格](https://docs.google.com/spreadsheets/d/1IqzkolFnBZTKX_GRIrdJpyywWkjuHnGMwP8Z61Mvd8U/edit?usp=sharing)，請幫我讓Gemini根據"各種因素 + 總銷售額"，寫出"各種因素下與咖啡銷量相關的可能性"，讓老闆能夠有更好的銷售決策可以準備

> 提示:你可以自己找看看 df.groupby('標籤')['標籤'] 是甚麼，這將有助於你更好去整理資料!