跳轉到

LiteLLM Proxy 設定指南

本文檔涵蓋如何使用 scripts/serve_litellm_proxy.py 啟動並驗證 Time Compass 的 LiteLLM Proxy。

此為 quickstart 與 Gemini API 設定 的後續步驟，也是後續使用 Gradio Web UI 與專案內 LLM 路由的推薦條件。

簡介：完整設定流程

本指南分為 3 個主要步驟，從準備 Gemini API Keys 到啟動本地 Proxy，再到用 readiness endpoint 驗證連線是否成功。LiteLLM Proxy 在本專案中主要負責提供本地 OpenAI 相容入口，並把多把 GEMINI_API_KEY_n 整理成 tier-a / tier-b 路由供專案使用。

最終目的: 取得可用的 LiteLLM Proxy 端點 http://127.0.0.1:4001/v1，並讓專案中的 tier-a / tier-b 模型路由可正常運作。

TOC - 準備工作 - Step 1：設定 .env 環境變數 - Step 2：啟動 LiteLLM Proxy 腳本 - Step 3：驗證 readiness endpoint - 完成後檢查清單 - 官方文檔參考

如果你已經熟悉 LiteLLM Proxy 流程

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

  1. 確認已完成 Gemini API 設定
  2. 在專案根目錄的 .env 內至少填入 GEMINI_API_KEY_1
  3. 視需要填入 LITELLM_HOST=127.0.0.1、LITELLM_PORT=4001
  4. 執行 uv run python scripts/serve_litellm_proxy.py
  5. 看到 Proxy is ready! 或手動打開 http://127.0.0.1:4001/health/readiness

3 大步驟概覽

這裡先提供流程概覽，幫您快速掌握整體有哪些步驟，以及每一步會帶來的結果。

  1. 設定 .env 環境變數
  2. 目的與效果：讓腳本可讀到 GEMINI_API_KEY_n，並動態重寫 litellm_config.yaml。

  3. 完成後您會得到：✅ 至少一把可用的 Gemini API Key

  4. 啟動 LiteLLM Proxy 腳本

  5. 目的與效果：使用 serve_litellm_proxy.py 啟動 LiteLLM，並自動等待 /health/readiness 通過。

  6. 完成後您會得到：✅ 本地 LiteLLM Proxy 服務與 http://127.0.0.1:4001/

  7. 驗證 readiness endpoint

  8. 目的與效果：確認 Proxy 已經 ready，可以接受請求。
  9. 完成後您會得到：✅ 可供專案與 UI 使用的 LiteLLM Proxy 服務

[!NOTE] 關於「執行」：本指南中的「執行 [指令]」表示： 1. 複製下方框框內的完整指令 2. 貼到終端機中 3. 按下 Enter 鍵執行

準備工作

  1. 進入 Time Compass 專案根目錄 您會看到：資料夾內有 scripts/、docs/、src/、litellm_config.yaml 等檔案

  2. 確認 您已完成 Gemini API 設定 您會看到：您手上已有至少一把可用的 Gemini API Key

  3. 確認 您已完成專案基本環境建置，例如 quickstart 您會看到：您可以在專案內正常執行 uv run ... 指令

Step 1：設定 .env 環境變數

Step 1.1：填入必要的 Gemini API Keys

  1. 開啟 專案根目錄的 .env 您會看到：可編輯的環境變數設定檔

  2. 填入 至少一把 Gemini API Key，建議使用序號格式：

GEMINI_API_KEY_1=your_gemini_api_key_here

您會看到：.env 中已有 GEMINI_API_KEY_1

  1. 視需要新增 第二把以上的 Key：
GEMINI_API_KEY_1=your_gemini_api_key_here
GEMINI_API_KEY_2=your_second_gemini_api_key
GEMINI_API_KEY_3=your_third_gemini_api_key

您會看到：.env 中的 key 名稱以 _1、_2、_3 依序編號

[!IMPORTANT] 這支腳本掃描的是 GEMINI_API_KEY_n，不是單獨的 GEMINI_API_KEY。 如果您只有 GEMINI_API_KEY 而沒有 GEMINI_API_KEY_1，動態 config 不會依預期展開。

GEMINI_API_KEY_1 和 GEMINI_API_KEY 的差別如下： - GEMINI_API_KEY_1：給 LiteLLM Proxy 使用，會被 serve_litellm_proxy.py 掃描並放進 tier-a / tier-b 路由 - GEMINI_API_KEY：給「不開 LiteLLM 時的 fallback 直連 Gemini」使用

如果您有開 LiteLLM，請至少設定 GEMINI_API_KEY_1。 如果您沒開 LiteLLM，但仍希望專案可直接打 Gemini，才需要 GEMINI_API_KEY。

Step 1.2：填入 LiteLLM Proxy 啟動參數

  1. 不需要額外修改 LiteLLM 的 host、port、config 路徑等設定，直接使用專案預設值即可 您會看到：只要 .env 中有 GEMINI_API_KEY_1，腳本就能依預設設定啟動 Proxy

  2. 理解 這一步的重點 您會看到：這份教學的必要設定只有 Gemini API Key；其餘 LiteLLM 參數先維持預設即可

Step 1.3：儲存設定檔

  1. 按下 Ctrl + S 您會看到：編輯器標題列不再顯示未儲存變更

Step 2：啟動 LiteLLM Proxy 腳本

Step 2.1：執行啟動指令

  1. 進入 專案根目錄

  2. 執行 以下指令：

uv run python scripts/serve_litellm_proxy.py

您會看到：終端機開始輸出 LiteLLM Proxy 的啟動資訊

  1. 觀察 啟動資訊 您會看到類似以下內容：
[INFO] Generated C:\Users\Wei\Desktop\PARA\1_project\coding\time_compass\litellm_config.yaml with 5 GEMINI_API_KEYs.
Starting LiteLLM Proxy Server
Host: 127.0.0.1
Port: 4001
Config: C:\...\litellm_config.yaml
Env file: C:\...\ .env
URL: http://127.0.0.1:4001/
Waiting for LiteLLM proxy to be ready...
Proxy is ready!

Step 2.2：確認腳本已更新 config 並完成 readiness 檢查

  1. 確認 終端機中有類似 Generated ... litellm_config.yaml with N GEMINI_API_KEYs 的訊息 您會看到：腳本已根據 .env 中的 key 數量重寫 litellm_config.yaml

  2. 確認 終端機中出現 Proxy is ready! 您會看到：/health/readiness 已回傳 HTTP 200，Proxy 已可接受請求

  3. 不要關閉 這個終端機視窗 您會看到：LiteLLM Proxy 會持續在這個視窗中執行，直到您手動按下 Ctrl + C

  4. 另外開啟 一個新的終端機視窗，再繼續後續步驟 您會看到：新視窗可用來啟動其他功能，例如後續的 Gradio Web UI 單獨使用說明

[!NOTE] 如果 LITELLM_DEBUG=1，LiteLLM 原始輸出會直接串流到終端機。 如果您只想保留較少輸出，可把 LITELLM_DEBUG 改成 0 再重新啟動。

[!IMPORTANT] 專案中的 src/time_compass/domain/llm_config.py 預設會檢查 http://127.0.0.1:4001/health/readiness。 如果您把 LITELLM_PORT 改成其他埠號，請同步確認使用端設定也有跟著改，否則系統可能直接 fallback，不走 Proxy。

Step 3：驗證 readiness endpoint

Step 3.1：確認 LiteLLM Proxy 已 ready

  1. 打開 瀏覽器並輸入以下網址： http://127.0.0.1:4001/health/readiness
http://127.0.0.1:4001/health/readiness

您會看到：頁面回傳成功訊息或狀態碼 200

[!IMPORTANT] 安全提醒 - GEMINI_API_KEY_1、GEMINI_API_KEY_2 等敏感值不可上傳到版本控制 - 若您懷疑 API Key 已外流，請立即到 Gemini / Google AI Studio 後台撤銷並重新產生

完成後檢查清單

  • [ ] .env 中已設定至少一個 GEMINI_API_KEY_1
  • [ ] .env 中已設定 LITELLM_HOST 與 LITELLM_PORT
  • [ ] uv run python scripts/serve_litellm_proxy.py 可成功啟動
  • [ ] 終端機中出現 Proxy is ready!
  • [ ] http://127.0.0.1:4001/health/readiness 可成功回應
  • [ ] 未洩露任何 Gemini API Key

下一步： 1. 前往 Gradio Web UI 單獨使用說明 2. 繼續驗證需要 LLM 的互動流程

官方文檔參考