跳轉到

Gemini API 設定指南（AI 規劃功能）

本文檔涵蓋如何透過 Google AI Studio 建立 Gemini API Key，並在 Time Compass 中完成設定，讓 AI 驅動的規劃功能可用。

本文可獨立完成；若你先前已做過 Google Cloud 專案設定，也可以直接把那邊的 project 匯入 Google AI Studio 來使用。這份設定同時也是後續 Gradio Web UI 指南 與 LiteLLM Proxy 設定指南 的重要基礎。

[!INFO] ☁️ 完整體驗（Real Data World）— 進階選項 | ⏱️ 預計 5–10 分鐘 此文檔涵蓋如何啟用 Gemini API 以使用 AI 驅動的規劃功能。這是完整體驗中的可選進階步驟。

前置條件：無。你可以直接從這份文件開始；若你已完成 Google Cloud 專案設定，則會多一個現成 project 可匯入使用。

[!NOTE] 本文件採用 Google AI Studio 路線。 你可以獨立完成這份流程，在 Google AI Studio 中直接選擇已匯入的專案、匯入既有專案，或建立新專案，然後建立 API Key。 若你已完成前一份「Google Cloud 專案設定」，代表你會多一個可直接匯入的 Google Cloud project。 若你需要多個 API Key，可以直接重複建立 key，或另外建立新的 project 來分開管理。

簡介：完整設定流程

本指南分為 3 個主要步驟，從在 Google AI Studio 開始建立 key 並選擇 project、建立 API Key，到填入環境變數完成設定。

最終目的：取得 GEMINI_API_KEY，填入專案根目錄的 .env 檔案，讓 AI 規劃功能可以正常呼叫 Gemini。

TOC

如果你已經熟悉 Google AI Studio 與 API 金鑰流程

如果您已熟悉整體流程，可先依下列精簡步驟完成配置。 如果您不熟悉，請直接從下方「準備工作」開始，依序完成完整流程。

  1. 前往 Google AI Studio 的 API Keys 頁面
  2. 輸入 key 名稱，並選擇既有專案、匯入專案，或建立新專案
  3. 建立並複製 API Key
  4. 填入 .env

3 大步驟概覽

這裡先提供流程概覽，幫您快速掌握整體有哪些步驟，以及每一步完成後會得到什麼。

  1. 在 Google AI Studio 準備 key 與 project

  2. 目的與效果：開啟建立 API Key 的流程，填入 key 名稱，並選定、匯入或建立要綁定的 project。

  3. 完成後您會得到：✅ 已填好 key 名稱，並選定或建立目標 project

  4. 建立 API Key

  5. 目的與效果：完成建立並複製 API Key，供應用程式使用。

  6. 完成後您會得到：✅ 一組可複製的 API Key

  7. 配置環境變數

  8. 目的與效果：把 API Key 寫入 .env，讓 Time Compass 可以讀取。

  9. 完成後您會得到：✅ .env 中已包含 GEMINI_API_KEY

[!NOTE] 關於「執行」：本指南中的「執行 [指令]」表示：

  1. 複製下方框框中的完整指令
  2. 貼到終端機中
  3. 按下 Enter 鍵執行

準備工作

  1. 確認 已登入 Google 帳號，並可正常使用 Google AI Studio 您會看到：可以進入 Google AI Studio API Keys 頁面

  2. 若你打算匯入既有 project，確認你知道要使用哪一個 Google Cloud project 您會看到：你知道 project 名稱，或稍後可在匯入清單中找到它

  3. 若你打算匯入既有 project，確認你有權限管理該 Google Cloud project 您會看到：你可以在相關 Google Cloud 專案中看到該 project

Step 1：在 Google AI Studio 準備 key 與 project

Step 1.1：進入 Google AI Studio

  1. 前往 Google AI Studio API Keys 頁面 Google AI Studio API Keys 您會看到：API Keys 頁面

  2. 完成登入 若系統要求登入或同意條款，請依畫面完成。 您會看到：可以正常進入 AI Studio 主畫面

Step 1.2：選擇專案路徑

  1. 點擊 右上角的 Create API key 按鈕 您會看到：建立 API Key 的對話框

Google AI Studio API Keys 頁面，右上角可點擊 Create API key

  1. 在 Name your key 底下的欄位輸入名稱 您會看到：key 名稱已填入

Create a new key 對話框，已輸入 key 名稱並選好 project

  1. 在 Choose an imported project 底下選擇要使用的 project 若尚未看到要用的 project，可先展開下拉選單後選擇 Import project 或 Create project。 您會看到：欄位中已顯示目標 project 名稱

展開 project 下拉選單後，可選 Import project 或 Create project

  1. 依照目前情況選擇其中一條路

    建議採用「一個 project 對一個 key」的方式管理。

  2. 如果已經有 import 過的專案：直接勾選要使用的專案

  3. 如果要匯入既有專案：點擊 Import project
  4. 如果要建立新專案：點擊 Create project

Step 1.3：匯入既有 Google Cloud 專案

  1. 點擊 Import project 您會看到：專案匯入畫面

  2. 打開 底下的 See more 向下箭頭 您會看到：更多可匯入的 Google Cloud 專案

  3. 勾選 想要使用的 project（點擊專案名稱左邊的方形框框） 也可以直接按 Select all。 您會看到：選取框已被勾選

  4. 點擊 Import 您會看到：專案被加入可選 project 清單，之後可用來建立 API Key

在 Import projects 畫面勾選專案後，點擊右上角 Import 完成匯入

Step 1.4：建立新的專案（如果需要）

  1. 點擊 Create project 您會看到：建立專案的對話框

  2. 在 Name your project 底下的欄位輸入名稱 您會看到：新專案名稱已填入

  3. 點擊 Create project 您會看到：新專案出現在可選 project 清單中

Step 2：建立 API Key

Step 2.1：完成建立 key

  1. 確認 已選好要綁定的 project 您會看到：目標 project 已顯示在建立 API Key 的對話框中

  2. 點擊 Create key 您會看到：新的 API Key 被建立，並顯示在畫面中

  3. 複製 API Key 您會看到：API Key 已複製到剪貼簿

[!IMPORTANT] API Key 安全提醒

  • 永遠不要把 API Key 提交到 Git 或公開儲存庫
  • 不要把 API Key 直接寫死在原始碼中
  • 建議定期輪轉 API Key
  • 雖然本專案已設定 .gitignore 忽略 .env，仍請小心保管金鑰

[!NOTE] 如果你需要多個 API Key： 同一個已匯入的專案下，可以重複執行本步驟建立新的 key。 若你偏好一個 project 配一個 key，也可以先建立新 project，再為它建立對應的 key。

Step 3：配置環境變數

Step 3.1：開啟 .env 檔案

  1. 進入 專案根目錄 您會看到：可以看到專案的主要檔案與資料夾

  2. 開啟 .env 檔案 若尚未存在，可依專案既有慣例建立。 您會看到：.env 已在編輯器中開啟

Step 3.2：填入 Gemini API Key

  1. 新增或更新 以下內容：
GEMINI_API_KEY=your_api_key_here

您會看到：.env 檔案中已出現 GEMINI_API_KEY

  1. 將 your_api_key_here 替換為 你在 Step 2 複製的真實 API Key 您會看到：環境變數值已更新為實際金鑰

範例（不是真實 Key）：

GEMINI_API_KEY=AIzaSyDx1234567890abcdefghijklmnop-qrs

Step 3.3：儲存檔案

  1. 儲存 .env 檔案 您會看到：編輯器顯示檔案已儲存

常見問題

Q：我明明已經有 Google Cloud 專案，為什麼在 AI Studio 看不到？

A：因為 AI Studio 不一定會直接列出所有 Google Cloud 專案。你可以到 API Keys 頁面，先點 Create API key，再從 Choose an imported project 裡選 Import project，並展開 See more 來勾選要匯入的 project。

Q：如果我要兩個或更多 API Key，要重新做整份文件嗎？

A：通常不用。若同一個專案已經匯入 AI Studio，只需要重複執行 Step 2：建立 API Key 即可。除非你要改用另一個 Google Cloud 專案，才需要重新做 Step 1。

Q：API Key 失效怎麼辦？

A：API Key 通常不會自己失效，但以下情況可能導致無法使用：

  • Key 被刪除：請回到 Google AI Studio 重新建立
  • Key 貼錯或 .env 未更新：請重新檢查設定值
  • 專案權限或計費設定有問題：請回頭檢查該專案狀態

Q：使用 LiteLLM Proxy 時還要設定嗎？

A：要。若你是透過 LiteLLM Proxy 作為 Gemini 的中介層，還需要額外完成代理相關設定。詳見 LiteLLM Proxy 設定指南。

完成後檢查清單

  • [ ] 已在 Google AI Studio 輸入 key 名稱
  • [ ] 已在 Google AI Studio 選定、匯入或建立要使用的 project
  • [ ] API Key 已建立並複製
  • [ ] .env 中已設定 GEMINI_API_KEY

恭喜！ 🎉 您已完成 Gemini API 設定，AI 規劃功能現在可以使用。

下一步選項：

  1. 在 Gradio Web UI 中使用 AI 功能 👉 Gradio Web UI 指南

  2. 進一步設定代理層 👉 LiteLLM Proxy 設定指南

相關文檔

官方文檔參考