LiteLLM 教學與自架成本全解：AI 閘道一定要自己跑嗎？想用自己的金鑰，有不用維運 proxy 的做法

查詢日：2026-09-14（台北時間）。 LiteLLM 的指令與設定格式取自其官方文件當日版本，開源專案更新頻繁，動手前請再對一次官方文件；BazaarLink 的產品行為以我們自己站上的實際設定為準。

會搜到這篇的人，多半在兩種狀態之一：還沒架，想知道 LiteLLM 到底是什麼、值不值得架；或者已經在 docker compose 跟 config.yaml 之間來回幾輪了，開始懷疑這台 proxy 是不是非跑不可。

這篇兩種人都照顧。前半段是一份能直接照做的 LiteLLM 安裝教學，後半段把「自架 AI 閘道」這件事真正的帳算給你看——包括我們自己的方案做不到的那幾格。

LiteLLM 是什麼？一句話講清楚

LiteLLM 是一個開源的 AI 閘道（AI Gateway）／LLM proxy。它自己不賣 token，做的是這件事：

把你自己的 OpenAI、Anthropic、Google 等各家 API 金鑰放進它的設定檔，它對外給出一個 OpenAI 相容的端點。你的程式只認這一個網址，換模型、換供應商都在設定檔裡改，程式碼不動。

順便它還做這幾件事：

• 虛擬金鑰（Virtual Keys）：不把真正的上游金鑰交給每個工程師或每個 agent，而是發一把「虛擬」的金鑰，可以設預算、設速率、隨時撤銷
• 負載平衡與路由：同一個模型名稱掛好幾條上游，它幫你分流
• 失敗退回（fallback）：一條上游掛了，自動改打另一條
• 用量與費用紀錄：哪把金鑰花了多少，存進資料庫

這四件事加起來，就是一個「AI 閘道」的核心能力。接下來的問題只有一個：這四件事，你要自己跑，還是讓別人跑？ 先教你自己跑，再談這個問題。

LiteLLM 教學：十分鐘用 Docker 架起來

第一步：寫一份最小的 config.yaml

LiteLLM 的核心就是 model_list。每一條寫「對外叫什麼名字」和「實際打哪一家、用哪把金鑰」：

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY

api_key: os.environ/OPENAI_API_KEY 的意思是從環境變數讀金鑰，不要把金鑰明碼寫進 yaml——這份檔案很容易不小心進版控。

第二步：啟動容器

最簡單的跑法，不接資料庫：

docker run \
  -v $(pwd)/litellm_config.yaml:/app/config.yaml \
  -e OPENAI_API_KEY=<你的 OpenAI 金鑰> \
  -e LITELLM_MASTER_KEY=sk-1234 \
  -p 4000:4000 \
  docker.litellm.ai/berriai/litellm:latest \
  --config /app/config.yaml

跑起來之後，proxy 在 http://localhost:4000。LITELLM_MASTER_KEY 是管理用的主金鑰，上線前一定要換掉 sk-1234 這種範例值。

第三步：把程式指過去

from openai import OpenAI

client = OpenAI(base_url="http://localhost:4000", api_key="sk-1234")
resp = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "你好"}],
)

model 填的是你在 model_list 裡取的 model_name，不是上游的原始名稱。到這裡就通了。

第四步（多數人會需要）：接 Postgres，開虛擬金鑰

上面那個跑法有一個很多教學沒講清楚的限制：沒有資料庫，就沒有虛擬金鑰、沒有預算控制、沒有用量紀錄。 官方文件寫得很直接——沒接資料庫的話，帶虛擬金鑰的請求會直接失敗，花費上限只能回到各家上游自己的後台去設。

所以實務上你會用官方的 compose 檔，一次帶起 proxy 和 Postgres：

curl -sSL https://docs.litellm.ai/docker-compose.yml | docker compose -f - up -d

起來之後打開 http://localhost:4000/ui，在「Virtual Keys」建立金鑰、設預算與速率。這一步做完，你才真的擁有前面說的四件事。

第五步：上線前必做的兩件事

1. 設定 LITELLM_SALT_KEY。 這是用來加密你存進去的各家上游金鑰的鹽值。官方標為上線前的必要項目——沒設的話，你的上游金鑰在資料庫裡的保護程度就不是你以為的那樣。
2. 把 LITELLM_MASTER_KEY 換成長隨機值。 誰拿到主金鑰，誰就能開任何虛擬金鑰。

這兩把 key 一設下去，你就正式接下了「保管別人金鑰」的責任。後面會回來談這件事的重量。

進階設定：負載平衡與失敗退回怎麼寫

會搜「litellm 教學」的人，通常卡在這一段。官方文件的語法如下（取自 2026-09-14 版本）。

同一個名字掛多條上游 = 負載平衡

把兩條 model_list 的 model_name 取一樣，LiteLLM 就會在它們之間分流。可以各自設 rpm／tpm 做加權：

model_list:
  - model_name: my-flash
    litellm_params:
      model: openai/gpt-5.6-luna
      api_key: os.environ/OPENAI_API_KEY
      rpm: 60
  - model_name: my-flash
    litellm_params:
      model: gemini/gemini-3.8-flash
      api_key: os.environ/GEMINI_API_KEY
      rpm: 60

分流策略在 router_settings 的 routing_strategy 設，可選 simple-shuffle（預設）、least-busy、usage-based-routing、latency-based-routing。

失敗退回（fallbacks）

litellm_settings:
  fallbacks: [{"my-flash": ["gpt-5.6-terra"]}]
  context_window_fallbacks: [{"my-flash": ["gpt-5.6-terra"]}]

fallbacks 是一般錯誤時退到哪裡；context_window_fallbacks 是專門針對「上下文超長」錯誤的退回——這兩個要分開設，很多人只設第一個，遇到長文件照樣噴錯。

到這裡，一套能用的 LiteLLM 就架完了。

架好之後最常撞到的五個錯誤

這一段是給已經跑起來、但某個地方不通的人。每一條都是設定層的問題，不是 LiteLLM 的 bug。

如果這五條都對過還是不通，下一步是看 proxy 的容器 log，不要先懷疑上游——九成問題在你和 LiteLLM 之間，不在 LiteLLM 和上游之間。

接下來講的，是任何教學文都不會列在步驟裡的部分。

什麼情況你應該繼續自架

先講反面，因為這比較重要：下面三種情況，任何託管服務都不該說服你，包括我們。

1. 請求內容不能離開你的機房。 這是自架最根本、也最無法替代的理由。金融、醫療、政府，或是內部規範寫死「不得經第三方轉送」的團隊，自架是唯一解。託管閘道無論怎麼加密、怎麼保證不留存，請求本身都會經過別人的機器。
2. 你要改它的行為。 自訂路由邏輯、插自己的中介層、改計費公式、接內部的模型伺服器。開源的價值就在這裡。
3. 你已經有 DevOps 能量，而且這台 proxy 是既有系統的一部分。 你本來就在跑 service mesh 和 API gateway，多一個容器的邊際成本接近零。

如果你屬於這三種，下面可以不用看了——繼續自架是對的決定，而且上面那份教學就是給你的。

自架真正要付的成本（不是「跑起來」那一次）

把 LiteLLM 跑起來確實不難，上面十分鐘的事。真正的成本在那之後，而且不會出現在任何比較表上。

這些事情單獨看都不難。加起來是一個常設的維運職務，而且那個職務不會結束。

另一條路：把金鑰放上來，但不用自己跑

如果你自架的理由只有一個——「我已經有自己的 API 金鑰，想要一個統一入口去管它們」——那你要的是「自帶金鑰」這個能力，不是「自己跑一台伺服器」這件事。這兩件事在 LiteLLM 裡被綁在一起，但它們本來可以分開。

BYOK（Bring Your Own Key，自帶金鑰） 做的就是 LiteLLM 那一層，差別在伺服器不是你的。

你把自己的上游帳號接上來，之後那個供應商的請求就用你自己的金鑰打出去、帳算在你自己的上游帳戶上，平台不對這些請求收費。設定是三步：填名稱與 base URL、系統即時打一次驗證並比對回傳的模型清單、完成。

對照 LiteLLM 的每一項功能

最後一列值得多講一句。你把自己的 OpenAI 金鑰接進來，團隊裡有人送了一個違規請求——那個請求是用你的帳號打到上游的。自架 LiteLLM 這一層要自己接審核；BYOK 這裡是平台的過濾層先擋。

呼叫方式

curl https://api.bazaarlink.ai/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "hello"}]
  }'

OpenAI 相容，既有 SDK 只改 base URL——跟上面把程式指向 LiteLLM 是同一個動作，差別只是網址。

誠實的對照表

這張表的重點是右邊那欄的「做不到」。 拿掉那幾格，下面的比較就沒有參考價值。

⚠️ 一個你應該先知道的限制

自帶金鑰的請求，我們記錄的費用是 0——因為那筆錢是你直接付給你自己的上游，我們沒有經手。

這帶來一個實務後果：你不能用「每月上限 100 美元」這種金額上限去管控自帶金鑰的用量，因為那些請求不會累積到任何金額。已經設定的支出上限仍然會擋住請求（自帶金鑰不會繞過那道閘），但它不會因為你用了自帶金鑰而往上累加。

要限制自帶金鑰的用量，目前能用的是每分鐘請求數上限，以及到你自己上游後台去設該帳號的額度。如果「對每一把虛擬金鑰設定金額預算」是你自架的主要理由，那 BYOK 現在還取代不了 LiteLLM 的虛擬金鑰，這點我們不繞過去講。

另外，自帶金鑰的用量不計入平台的用量回饋——那是給走平台計費的請求的。

那什麼情況下這條路比較划算

把上面兩張表合起來，判斷其實很簡單：

• 自架的理由是資料落地或要改程式 → 繼續自架，上面的教學拿去用
• 自架的理由是要用自己的金鑰＋一個統一入口 → 這件事不需要你跑伺服器
• 自架的理由是要按金額卡住每個人的預算 → 目前自架仍然比較合適
• 自架的理由是「別人都自架」 → 這不是理由。多一個元件就是多一份維運責任，而那份責任不會出現在任何比較表上，它會出現在某個週末

怎麼判斷你的 LiteLLM 已經從工具變成負擔

自架不是錯，沒察覺它已經開始吃人才是。下面五題，中三題以上就值得重新想：

1. 過去三個月，有沒有哪次 AI 功能的故障，根因是 proxy 本身（掛掉、OOM、升級後行為變了），而不是上游？
2. 新模型出來的時候，從「上游可用」到「你的團隊能用」中間隔了幾天？那幾天是在等誰？
3. 團隊裡除了一個人以外，還有誰知道 LITELLM_SALT_KEY 存在哪裡、怎麼輪替？
4. 上一次有人認真看 proxy 的用量報表是什麼時候？還是資料庫一直在長、沒人看？
5. 如果明天架 proxy 的那位離職，這台東西還有人敢動嗎？

這五題沒有一題在問 LiteLLM 好不好用。它們在問的是：這台 proxy 現在是你系統的一部分，還是你系統裡的一個單點。

從 LiteLLM 搬到 BYOK 的實際步驟

如果上面那五題讓你決定不再自己跑，這是一條不用停機的搬法。核心原則：先並行，再切換，最後才拆。

第一步：把 model_list 攤開

打開你的 config.yaml，列出每一條 model_list 用的是哪一家上游、哪把金鑰。這份清單就是你要接進 BYOK 的供應商清單——通常比你以為的少，多數團隊實際只用兩三家。

第二步：逐家接進 BYOK

登入後到 /keys/byok，一家一家填：名稱、該供應商的 base URL、你自己的 API 金鑰。系統會即時打一次驗證並比對回傳的模型清單——通了才算接上，不是填完就算。

第三步：決定退回模式

LiteLLM 裡的 fallbacks 在這裡對應成一個開關。你原本的 fallback 是退到另一家你自己的金鑰，那就選嚴格模式並把兩家都接上；如果你原本是「盡量用我的 key，真的不行就算了」，選無縫——你的金鑰失敗時那一筆改走平台路由完成，照平台計費。

第四步：只改一個環境變數

把程式端的 OPENAI_BASE_URL 從 http://localhost:4000 改成 https://api.bazaarlink.ai/v1，OPENAI_API_KEY 換成 BazaarLink 的金鑰。model 的名稱對照一下即可——這一步跟你當初把程式指向 LiteLLM 是同一個動作。

第五步：並行一週，看兩邊的用量紀錄

先不要拆 LiteLLM。 讓一部分流量走新入口，比對兩邊的用量紀錄：哪些請求走了你自己的金鑰、有沒有發生退回、失敗代碼是什麼。確認一週沒有意外，再把剩下的流量切過去，最後才停容器。

搬完之後，第一節那份「自架要付的成本」表格裡的每一列，都不再是你的。唯一留下的是你自己的上游金鑰和它們的帳單——那本來就該是你的。

想先試

接上第一把自己的金鑰大約五分鐘，之後那個供應商的請求就走你自己的帳號。入口在 自帶金鑰（BYOK），登入後到 /keys/byok 設定。

還沒有帳號、只想先確認相容性的話，有免費層可以試：Qwen3.7 Flash 免費、每分鐘 10 次、每天 50 次、不用信用卡——足夠把 base URL 改過來、確認 SDK 能通。

延伸閱讀：AI API 閘道、路由器、中轉站差在哪、工程團隊的 AI 模型統一入口、怎麼判斷 AI API 中轉站靠不靠譜。

台幣計費・統一發票・主流 AI 模型・OpenAI 相容 API