---
# System prepended metadata

title: 效率神器：Python 協同 Gemini，辦公事半功倍

---

# 效率神器：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`

        ![截圖 2025-11-28 凌晨12.39.35](https://hackmd.io/_uploads/B1u6kWUbWl.png =80%x)

    2. 在 `Choose an imported project` 欄位點選 `Gemini API`

        ![截圖 2025-11-28 凌晨12.16.25](https://hackmd.io/_uploads/SkiVgbUWWl.png =80%x)

    3. 點選 `Create key`

        ![截圖 2025-11-28 凌晨12.47.17](https://hackmd.io/_uploads/ry4yZZ8bbl.png =80%x)

    4. 複製 API key 。注意不要洩漏出去，以免出現安全疑慮

        ![截圖 2025-11-28 凌晨12.42.56](https://hackmd.io/_uploads/H1AR-bLbWg.png =80%x)

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

    1. 進入 Colab 檔案，點選 Secret (左側鑰匙形狀的圖標)，新增密鑰，將剛剛得到的 API Key 貼到值當中，並且命名為 `GEMINI_API_KEY`。

        ![截圖 2025-11-28 凌晨2.12.14](https://hackmd.io/_uploads/HJZ9Vz8ZWe.png =60%x)

    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 左側 -> 檔案`
        
        ![截圖 2025-11-28 凌晨2.13.50](https://hackmd.io/_uploads/r13yBzIbZx.png =50%x)
        
        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 所有欄位的 標籤名稱。
        
        ![截圖 2025-11-28 凌晨2.33.15](https://hackmd.io/_uploads/HksOFM8-Zl.png)

    2. #### `df[標籤名稱]`

        用途：取得指定標籤對應的 欄位 資料（可以選取多欄）。
        
        ![截圖 2025-11-28 凌晨2.33.42](https://hackmd.io/_uploads/SJ79tf8-bx.png =60%x)
        
    3. #### `df.loc[index, (標籤名稱)]`

        - `df.loc[index]`
        
            用途：取得第 index + 1 列 的資料（標籤列不算一列）
            
            ![截圖 2025-11-28 凌晨2.34.39](https://hackmd.io/_uploads/ByjaFf8--g.png)


        - `df.loc[index, 標籤名稱]`
        
            用途：取得第 index + 1 列 中指定標籤對應到的 欄位 資料
            
            ![截圖 2025-11-28 凌晨2.35.36](https://hackmd.io/_uploads/Sk4ZczLZ-l.png =80%x)

        ![](https://hackmd.io/_uploads/B1wmUqEj1e.jpg =90%x)

    4. #### `df.iterrows()`

        用途：逐列走訪 DataFrame，回傳 (index, row)，通常搭配 for 迴圈使用。

        - `index`：每一列的索引值。
        - `row`：第 index + 1 列的資料。
        - `row[標籤名稱]`：該列按照指定標籤對應到的值，以第一列為例：
            - `row["姓名"]` 對應到值「小燈」
            - `row["學號"]` 對應到值「411151921」
        
        ![截圖 2025-11-28 凌晨2.42.39](https://hackmd.io/_uploads/BJ6soGLbZg.png =70%x)

    5. #### `row.items()` (承上)
        
        用途：取得該列所有欄位的 (label, value)，通常搭配 for 迴圈使用。

        - `label`：標籤名稱。
        - `value`：該列資料由此 label 對應到的值。
        
        ![截圖 2025-11-28 凌晨2.48.43](https://hackmd.io/_uploads/S15fazUZWe.png =90%x)

        ![](https://hackmd.io/_uploads/By_AMJfqke.jpg =80%x)

    6. #### `df[df['標籤'] == '值']`
        
        用途：篩選特定條件的列，回傳只包含滿足條件的列。

        ![截圖 2025-11-28 凌晨2.51.30](https://hackmd.io/_uploads/B1epTzI-Wg.png)

        ![image](https://hackmd.io/_uploads/HyNkyQUZWl.png =80%x)


## 結合 Gemini 與 Pandas 來分析 Excel

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


- ### **分析一：統整面試者資訊**
    
    - **步驟：**

        遍歷 Excel 表格的每一列，提取該面試者的相關資訊，對每一列進行以下步驟：
        1. 遍歷此列資訊的每一欄，整理成一個 prompt
        2. 將 prompt 傳給 Gemini 進行分析
        3. 將此列資訊新增一欄，放置分析結果

        最後將 df 輸出成新的 Excel 檔案。
    
    ![截圖 2025-11-28 凌晨3.12.22](https://hackmd.io/_uploads/Hy7iGXU-Ze.png)
    
    ![截圖 2025-11-28 凌晨3.18.55](https://hackmd.io/_uploads/S12X4XI-Wx.png =50%x)

- ### **分析二：統計組別人數**

    - **步驟：**

        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?