【LiteLLM 完全入門】系列 #04（共 4 篇）｜難度：L2-進階

前三篇我們都在講 LiteLLM SDK：在 Python 程式裡 import litellm，用一行 completion() 打遍各家模型。這對「一個人、一支程式」很夠用。

但當團隊變大，情況就不一樣了：

• 五個工程師、三個專案，各自把 API key 塞在自己的 .env 裡，key 外洩了都不知道是誰。
• 老闆問「這個月 OpenAI 花了多少？哪個團隊花最兇？」——沒人答得出來。
• 想從 GPT-4o 換成 Claude，結果每支程式都要改 code。

這時候就輪到 LiteLLM Proxy Server 出場了。它是一個你自己架的中央閘道：所有人不再直接打 OpenAI／Anthropic，而是打你的 proxy，proxy 再幫忙轉發、記帳、限額。

這篇的重點一樣不是教你「架一個 production 等級的 proxy」，而是教你看懂 AI 幫你生的 config.yaml 在設定什麼、每個區塊管什麼、驗收時該 curl 哪個端點確認它活著。

版本提醒：LiteLLM Proxy 用 litellm[proxy] 這個 extra 安裝，指令是 litellm --config config.yaml。本文範例以此為準。

一句話說明

一句話：SDK 是「我這支程式要打模型」，Proxy 是「全公司打模型都走我這個閘道」。

看 code 時心裡一直問：這是在教我怎麼「打」proxy（client 端），還是怎麼「設定」proxy（server 端）？ 這兩件事的檔案長得完全不一樣。

什麼時候該架 Proxy？（先判斷該不該用）

不是每個情況都需要 proxy。先看紅綠燈：

✅ 該架 proxy：

• 多人／多專案要共用同一批 API key，不想每台機器都貼 key。
• 要能回答「誰花了多少錢」、想設每月預算上限。
• 想統一切換模型供應商，client 端 code 不動。
• 團隊裡有非 Python 的服務（Node、Go、n8n…）也要打模型。

📌 先別急著架 proxy：

• 就你一個人、一支腳本 → 直接用 SDK 就好，proxy 是多餘的維運負擔。

看到 AI 一上來就幫你架 proxy，但你其實只是要跑個一次性腳本——這時候要能喊停：「我只有一支程式，用 SDK 就好，不用架 server 吧？」

最小範例：一個 config.yaml + 一行啟動

Proxy 的核心就是一個 YAML 設定檔。最小長這樣：

# config.yaml
model_list:
  - model_name: gpt-4o                      # 對外公開的「菜單名稱」
    litellm_params:
      model: openai/gpt-4o                   # 實際要轉發到哪個模型
      api_key: os.environ/OPENAI_API_KEY     # key 從環境變數讀，不寫死在檔案裡
Code language: PHP (php)

逐行翻譯：

• model_list：這台 proxy 對外提供哪些模型的清單，就是它的「菜單」。
• model_name: gpt-4o：client 要點餐時用的名字。這是你自己取的別名，可以叫 my-smart-model 都行。
• model: openai/gpt-4o：這道菜實際上是什麼——轉發到 OpenAI 的 gpt-4o。格式就是前幾篇的 供應商/模型名。
• api_key: os.environ/OPENAI_API_KEY：重點——os.environ/XXX 是 LiteLLM 的特殊語法，意思是「去讀名為 XXX 的環境變數」，而不是把字串 os.environ/OPENAI_API_KEY 當成 key。這樣 key 就不會被寫死在 YAML 裡（更不會被 commit 進 git）。

啟動只要一行：

litellm --config config.yaml
# 預設跑在 http://0.0.0.0:4000
Code language: PHP (php)

「這在幹嘛」：讀 config.yaml，把裡面那張菜單架成一個 OpenAI 相容的 API server，開在 4000 埠等人來點餐。

Client 怎麼接：把 base_url 指向 proxy 就好

這是 proxy 最爽的地方：client 端不用裝 LiteLLM，直接用 OpenAI 官方 SDK，只要把「網址」改掉。

from openai import OpenAI                       # 注意：這是 OpenAI 官方套件，不是 litellm

client = OpenAI(
    base_url="http://localhost:4000",           # 指向你的 proxy，而不是 openai.com
    api_key="sk-1234",                           # 這是「proxy 的 key」，不是 OpenAI 的 key
)

resp = client.chat.completions.create(
    model="gpt-4o",                              # 這裡填 config.yaml 裡的 model_name（菜單名）
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
Code language: PHP (php)

逐行翻譯：

• from openai import OpenAI：用的是原廠 OpenAI SDK。因為 proxy 講的是「OpenAI 相容」的語言，所以任何原本會打 OpenAI 的工具都能無痛接上。
• base_url="http://localhost:4000"：關鍵改動——把目的地從 openai.com 換成你的 proxy。
• api_key="sk-1234"：這把 key 不是 OpenAI 給的，而是你的 proxy 認的 key（virtual key，等下會講）。真正的 OpenAI key 藏在 proxy 那邊，client 完全碰不到。
• model="gpt-4o"：填的是 config.yaml 裡 model_name 那個別名。proxy 收到後會查菜單，轉發到對應的真實模型。

「這在幹嘛」：client 以為自己在打 OpenAI，其實打的是你家 proxy；proxy 拿真 key 去轉發，回來的格式一模一樣，client 毫無感覺。

Vibe Coder 抓重點：看到 client code 裡 base_url 指向一個 :4000 之類的內網位址、api_key 長得像 sk-1234 這種假 key——這就是「這支程式在走 proxy」的訊號，不是直連 OpenAI。

config.yaml 的三大區塊：各管什麼

AI 生出來的 config 通常有三個頂層區塊。看懂這三個，八成就抓到了：

# 1. 菜單：對外提供哪些模型
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude                       # 可以掛多個，統一從這台 proxy 出去
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

# 2. LiteLLM 行為設定：重試、逾時、記錄…
litellm_settings:
  drop_params: true                          # 某模型不支援的參數自動丟掉，不報錯
  num_retries: 3                             # 失敗自動重試 3 次

# 3. proxy 本身的管理設定：認證、資料庫…
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY  # 管理員金鑰，用來建 virtual key
Code language: PHP (php)

三區塊各管什麼，用一句話記：

📌 知道就好：litellm_settings 底下選項非常多（快取、fallback、callback…），不用背。看到不認得的 key，直接問 AI「這個 config 選項在幹嘛」即可。

Virtual Key 與 Budget：這才是團隊控管的核心

前面 client 用的那把 sk-1234，就是 virtual key（虛擬金鑰）。這是 proxy 最有價值的功能：

你可以幫每個團隊／每個人發一把自己的 key，各自設預算上限。

發 key 是打 proxy 的管理 API（要用 master_key 當認證）：

curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-master-1234" \   # 這裡用的是 master_key（管理員）
  -H "Content-Type: application/json" \
  -d '{
    "models": ["gpt-4o"],                        # 這把 key 只能用 gpt-4o
    "max_budget": 100,                           # 這把 key 花到 100 美元就停
    "budget_duration": "30d"                     # 每 30 天重置一次額度
  }'
Code language: PHP (php)

逐行翻譯：

• Authorization: Bearer sk-master-1234：發 key 是管理員操作，所以要帶 master_key，不是隨便一把 key 都能發。
• "models": ["gpt-4o"]：權限控制——這把 key 只能點 gpt-4o，想點 claude 會被擋。
• "max_budget": 100：成本天花板——這把 key 累積花費超過 100 美元，proxy 就直接拒絕請求。
• "budget_duration": "30d"：額度多久重置一次。這裡是每 30 天。

回傳會給你一把新 key，例如 sk-abc123...，把它交給那個團隊，他們塞進自己的 base_url client 就能用。

「這在幹嘛」：像社區的分表——總表（master key）握在你手上，你幫每戶（每個團隊）裝一個有上限的分表（virtual key），用超了那戶自己斷水，不影響別人，你也看得到每戶用多少。

這解決了開頭三個痛點：key 集中管理（真 key 只在 proxy）、能回答誰花多少（每把 virtual key 獨立記帳）、有預算上限（max_budget）。

補充：要記帳和存 virtual key，proxy 通常需要接一個 Postgres 資料庫（在 general_settings 設 database_url）。看到 config 裡有 database_url 別緊張，那就是拿來存花費紀錄和 key 的。

記錄與觀測：錢花去哪、誰在打

光有預算上限還不夠，你會想知道每一次呼叫的細節（誰、打了什麼、花多少）。LiteLLM 用 callbacks 把這些事件送到外部系統：

litellm_settings:
  success_callback: ["langfuse"]     # 成功的呼叫，把紀錄送去 Langfuse
  failure_callback: ["langfuse"]     # 失敗的呼叫也送，方便排查
Code language: CSS (css)

逐行翻譯：

• success_callback：呼叫成功時，要把這筆紀錄（用了哪個模型、幾個 token、花多少）送到哪些觀測平台。這裡是 Langfuse。
• failure_callback：呼叫失敗時往哪送，方便你事後查為什麼掛掉。
• 值是一個清單，代表可以同時送去好幾個地方（例如同時送 Langfuse 和自建的 log 系統）。

📌 知道就好：支援的 callback 目標很多（Langfuse、Datadog、Prometheus、S3…），名字認得就好。重點是理解「callback = 呼叫發生後，把這件事通知出去」這個概念。

最陽春的做法是直接讓 proxy 把每筆呼叫印在終端機（適合開發時看），這在啟動時加 --detailed_debug 就有。

🚩 紅旗：看到這些要警覺

紅旗 1：真 API key 被寫死在 config.yaml 裡

litellm_params:
  model: openai/gpt-4o
  api_key: sk-proj-REALKEY1234567890    # 🚩 真 key 直接寫死，會被 commit 進 git 外洩
Code language: PHP (php)

正確應該是 api_key: os.environ/OPENAI_API_KEY。看到一長串真的 key 明碼寫在檔案裡，尤其這檔案要進版控——直接喊卡。跟 AI 說：「把 api_key 改成從環境變數讀，不要寫死。」

紅旗 2：proxy 直接對外開放又沒設 master_key / key 認證

litellm --config config.yaml --host 0.0.0.0   # 🚩 對全世界開放，但沒任何認證
Code language: CSS (css)

0.0.0.0 代表任何人都連得到。如果沒設 master_key、也沒要求 virtual key，等於開放全世界免費用你的付費 API 帳單。問 AI：「這個 proxy 有沒有做認證？會不會被人白嫖我的 API 額度？」

紅旗 3：client 端還留著真 key

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="sk-proj-REALOPENAIKEY...",   # 🚩 走了 proxy 卻還塞真 OpenAI key
)
Code language: PHP (php)

走 proxy 的意義就是讓 client 拿不到真 key。client 這裡應該放 virtual key（sk-1234 那種），真 key 只該存在 proxy。看到 client 還抱著真 key，等於白架了 proxy。

紅旗 4：沒設 max_budget 就發 key 給外部團隊

沒有預算上限的 key，一旦被濫用或程式跑爆迴圈，帳單會直接噴上天。發 key 給人前，確認有 max_budget。

Vibe Coder 驗收檢查點

架好 proxy 後，用這幾個做得到的動作確認它真的活著：

1. 確認 proxy 有起來（健康檢查）

curl http://localhost:4000/health/liveliness
# 預期：回 "I'm alive!" 之類的存活訊息
Code language: PHP (php)

2. 確認菜單載對了（列出模型清單）

curl http://localhost:4000/v1/models \
  -H "Authorization: Bearer sk-1234"
# 預期：回一份 JSON，裡面 data 陣列有你在 config.yaml 設的 model_name（例如 gpt-4o、claude）
Code language: PHP (php)

如果這裡少了你以為有設的模型，代表 config.yaml 的 model_list 沒載到——先檢查 YAML 縮排。

3. 實際打一發，確認轉發成功

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-1234" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "說一句話"}]}'
# 預期：回一段正常的模型回覆 JSON。若回 401 → key 不對；回 400 找不到模型 → model_name 拼錯
Code language: PHP (php)

4. 確認 key 認證有生效

curl http://localhost:4000/v1/models   # 故意不帶 Authorization
# 預期：被擋下來（401 之類）。如果沒帶 key 也能通 → 🚩 你的 proxy 沒做認證
Code language: PHP (php)

5. 讓 AI 幫你複查 config

把 config.yaml 貼給 AI 問：「這份 LiteLLM proxy 設定有沒有把真 key 寫死？有沒有做認證？外部團隊拿到 key 會不會沒有預算上限？」

看不懂就這樣問 AI

• 「用白話一段一段解釋這份 config.yaml 在設定什麼，我只想知道每個區塊管什麼。」
• 「我這支程式的 client 是直連 OpenAI 還是走 LiteLLM proxy？從哪一行看得出來？」
• 「幫我檢查這份 proxy 設定有沒有安全問題：真 key 寫死、沒認證、沒預算上限。」
• 「我只有一支一次性腳本，真的需要架 proxy 嗎？還是用 SDK 就好？」

系列回顧

到這裡，【LiteLLM 完全入門】四篇走完了：

• #01：LiteLLM 是什麼、completion() 一行打遍各家。
• #02：切換模型、串流、參數對齊。
• #03：錯誤處理、重試、fallback 讓呼叫更穩。
• #04（本篇）：從「一支程式」升級到「全團隊統一閘道」——Proxy Server 做 key 集中、成本控管與觀測。

判斷原則記一句話就好：個人／單一腳本用 SDK，多人／多專案／要記帳就架 Proxy。 看 code 時永遠先分清楚，你面對的是 client 端（打 proxy）還是 server 端（設定 proxy）。