跳轉到

LiteLLM Proxy 與 Gradio 配置指南

這份文件對應 scripts/serve_litellm_proxy.py，重點是： 1. 它提供了什麼功能 2. 你要怎麼配置 3. 它如何和 src/time_compass/domain/llm_config.py 協作

0. 使用建議（強烈推薦）

本專案強烈推薦「Gradio + LiteLLM Proxy」一起使用，尤其是舊版互動流程（情緒承接、路由、排程對話）：

  1. Gradio 端通常會產生較密集的對話請求，Proxy 可提供較穩定的本地路由與 fallback。
  2. 可以同時使用多把 Gemini key（GEMINI_API_KEY_n）分流，減少單一 key 的壓力。
  3. llm_config.py 已內建「先走 proxy、失敗再 fallback」邏輯，和 Gradio 體驗最契合。

1. 這個 Proxy 在專案中的功能

LiteLLM Proxy 在本專案扮演「模型路由層」：

  1. 提供統一 OpenAI 相容入口（本地 http://127.0.0.1:4001/v1）。
  2. 將多把 Gemini keys 組成可輪替/降級的 tier 路由（tier-a、tier-b）。
  3. 在 llm_config.py 中，讓 DSPy 優先走 proxy；proxy 不可用時再 fallback 直連 Gemini。

換句話說，這不是只有 env 設定，而是「本地模型編排與容錯」基礎設施。

2. 配置流程（Step-by-step）

2.1 準備 Gemini API keys

至少準備一把： - GEMINI_API_KEY_1

建議多把： - GEMINI_API_KEY_2 - GEMINI_API_KEY_3 ...

原因：serve_litellm_proxy.py 會掃描 GEMINI_API_KEY_n，動態展開 litellm_config.yaml 的 model_list，做分流與備援。

2.2 設定 .env

最小配置：

GEMINI_API_KEY_1=your_key_1

常用配置：

GEMINI_API_KEY_1=your_key_1
GEMINI_API_KEY_2=your_key_2

LITELLM_HOST=127.0.0.1
LITELLM_PORT=4001
LITELLM_DEBUG=1

2.3 啟動 Proxy

uv run scripts/serve_litellm_proxy.py

啟動後會做兩件事： 1. 依 .env 內容重寫 litellm_config.yaml 2. 啟動 LiteLLM，並等待 /health/readiness 通過

2.4 驗證是否成功

  1. 看到 readiness 成功訊息（或手動打 http://127.0.0.1:4001/health/readiness）。
  2. 在需要 LLM 的流程中觀察是否走 tier-a / tier-b。
  3. 若 proxy 關閉，llm_config.py 會 fallback 到直連 Gemini（可作為對照）。

3. 與 llm_config.py 的整合

檔案： - src/time_compass/domain/llm_config.py

行為摘要： 1. 啟動時檢查 http://127.0.0.1:4001/health/readiness。 2. 若可用： - lm_a = openai/tier-a（api_base 指向本地 proxy） - lm_b = openai/tier-b 3. 若不可用： - fallback gemini/gemini-2.5-flash - fallback gemini/gemma-3-12b-it

重點：
Proxy 是「優先路徑」，不是唯一路徑；系統具備自動退回策略。

4. 環境變數清單（補充）

必要： - GEMINI_API_KEY_1（至少一把）

常用可選： - LITELLM_HOST（預設 127.0.0.1） - LITELLM_PORT（預設 4001） - LITELLM_CONFIG（預設 <repo>/litellm_config.yaml） - LITELLM_ENV_FILE（預設 ../.env，相對於 scripts/） - LITELLM_DEBUG（預設開啟） - LITELLM_NO_EMOJI - LITELLM_TEST - LITELLM_TEST_MODEL（建議 tier-a 或 tier-b）

相容項： - LITELLM_MASTER_KEY（目前 disable_auth: true，通常可不設）

5. 常見問題

  1. 有 GEMINI_API_KEY 但沒 GEMINI_API_KEY_1
  2. 症狀：動態 config 不按預期展開

  3. 解法：改成序號格式至少一把 key

  4. 你改了 proxy 埠號，但 llm_config.py 仍檢查 4001

  5. 症狀：系統判定 proxy 不可用，直接 fallback

  6. 解法：同步調整 llm_config.py 或維持 4001

  7. LITELLM_TEST_MODEL=tier-s

  8. 症狀：測試模式失敗
  9. 解法：改成現有別名（通常是 tier-a 或 tier-b）

6. 交叉引用

  • Gemini API key 取得：docs/how-to/google-cloud-project-prerequisites.md
  • Google OAuth 驗證：docs/how-to/google-oauth-validation.md
  • Google OAuth 架構：docs/reference/google-oauth.md