LiteLLM

接入鏈路

ChatBox
    ↓ 本機 Master Key
http://127.0.0.1:4000/v1/chat/completions
    ↓ LiteLLM 模型對應
https://www.coffeerouter.ai/v1/chat/completions
    ↓ CoffeeRouter API Key
MiniMax-M2.7

LiteLLM 對用戶端提供別名 coffee-minimax-m2-7，而傳送給 CoffeeRouter 的實際模型 ID 是 MiniMax-M2.7。兩者用途不同，不要混用。

01. 準備並安裝 LiteLLM

開始前請準備：

• CoffeeRouter API Base：https://www.coffeerouter.ai/v1。
• CoffeeRouter 中建立的有效令牌，以及該令牌允許使用的準確模型 ID。
• 用於儲存設定的目錄，例如 Windows 的 C:\litellm-coffeerouter。
• 選用：已安裝最新版 ChatBox，用來完成用戶端驗證。

LiteLLM 1.84.0 及以上版本需要 Python 3.10 或更高版本。官方安裝腳本和 uv 可以自動準備相容的 Python 環境。

macOS、Linux 或 Windows WSL

LiteLLM 官方將下面的一鍵腳本列為本機和初學者的推薦安裝方式：

curl -fsSL https://raw.githubusercontent.com/BerriAI/litellm/main/scripts/install.sh | sh

腳本安裝 litellm[proxy] 後可能自動進入通用設定精靈。本文會使用專用的 config.yaml 接入 CoffeeRouter，因此可以退出精靈並繼續下一節。

Windows PowerShell

原生 PowerShell 通常沒有 sh，建議先安裝 uv，再使用 LiteLLM 官方提供的 uv tool 安裝方式：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install "litellm[proxy]"
litellm --version

安裝完成後如找不到 uv 或 litellm，請關閉並重新開啟終端。

02. 設定 CoffeeRouter 與 LiteLLM 金鑰

在設定目錄中新建 .env：

COFFEEROUTER_API_BASE=https://www.coffeerouter.ai/v1
COFFEEROUTER_API_KEY=sk-your-coffeerouter-key
LITELLM_MASTER_KEY=sk-your-litellm-master-key

• COFFEEROUTER_API_KEY 是在 CoffeeRouter 令牌管理頁取得的上游令牌。
• LITELLM_MASTER_KEY 是用戶端連線本機 LiteLLM 時使用的獨立密碼，必須以 sk- 開頭。
• 兩個 Key 不應相同，也不要把真實值寫入 config.yaml、截圖或 Git。

將 .env 加入專案的 .gitignore：

.env

03. 設定模型對應

在同一目錄新建 config.yaml：

model_list:
  - model_name: coffee-minimax-m2-7
    litellm_params:
      model: openai/MiniMax-M2.7
      api_base: os.environ/COFFEEROUTER_API_BASE
      api_key: os.environ/COFFEEROUTER_API_KEY

litellm_settings:
  drop_params: true

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

設定項目	作用	範例
model_name	用戶端呼叫 LiteLLM 時使用的別名	coffee-minimax-m2-7
model	LiteLLM 傳送至上游的 Provider 與實際模型 ID	openai/MiniMax-M2.7
api_base	CoffeeRouter 的 OpenAI 相容 Base URL	https://www.coffeerouter.ai/v1
api_key	CoffeeRouter 上游令牌	從 .env 讀取

CoffeeRouter 是 OpenAI 相容介面，因此 LiteLLM Provider 前綴使用 openai/。MiniMax-M2.7、coffee-minimax-m2-7 及 ChatBox 中填寫的模型名稱都必須逐字符合各自設定，並注意大小寫。

需要加入更多模型時，可以在 model_list 中繼續增加項目：

  - model_name: coffee-your-model
    litellm_params:
      model: openai/your-exact-coffeerouter-model-id
      api_base: os.environ/COFFEEROUTER_API_BASE
      api_key: os.environ/COFFEEROUTER_API_KEY

04. 啟動本機 LiteLLM

從包含 .env 和 config.yaml 的目錄啟動：

cd C:\litellm-coffeerouter
litellm --config .\config.yaml --port 4000

macOS、Linux 或 WSL：

cd ~/litellm-coffeerouter
litellm --config ./config.yaml --port 4000

看到 LiteLLM 監聽 http://0.0.0.0:4000 後保持終端執行。本機用戶端請使用更明確的回環地址 http://127.0.0.1:4000。

05. 進階選項：使用 Docker 長期執行

如果需要背景常駐、伺服器部署或容器隔離，可以改用 Docker。一般本機體驗可以略過本節。

先安裝並啟動 Docker Desktop；Windows 建議啟用 WSL 2 後端。然後在設定目錄建立 docker-compose.yml：

services:
  litellm:
    image: docker.litellm.ai/berriai/litellm:latest
    container_name: litellm-coffeerouter
    command:
      - "--config"
      - "/app/config.yaml"
      - "--port"
      - "4000"
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    env_file:
      - .env
    restart: unless-stopped

啟動並檢查容器：

cd C:\litellm-coffeerouter
docker compose pull
docker compose up -d --force-recreate
docker compose ps
docker compose logs --tail 50 litellm

確認 Master Key 已注入，但不要輸出真實值：

docker compose exec litellm sh -c 'test -n "$LITELLM_MASTER_KEY" && echo MASTER_KEY_OK || echo MASTER_KEY_MISSING'

驗證階段可以使用 latest；生產環境應固定經過驗證的具體版本標籤或映像摘要，方便回滾和重現。

日誌中的 Failed to fetch remote model cost map 表示遠端成本表取得失敗並回退本機備份。如果後續請求成功，該警告通常不影響基礎聊天；如果請求也失敗，請繼續檢查網路、代理和 TLS 憑證。

06. 選用：先直連 CoffeeRouter 驗證上游

如果 LiteLLM 回傳上游錯誤，可以先略過 LiteLLM，驗證 CoffeeRouter 的 Base URL、令牌與實際模型 ID：

$baseUrl = "https://www.coffeerouter.ai/v1"
$coffeeKey = "sk-your-coffeerouter-key"
$directBody = @{
    model = "MiniMax-M2.7"
    messages = @(
        @{ role = "user"; content = "請只回覆：CoffeeRouter 直連成功" }
    )
    stream = $false
} | ConvertTo-Json -Depth 10

$directResult = Invoke-RestMethod `
    -Uri "$baseUrl/chat/completions" `
    -Method Post `
    -Headers @{ Authorization = "Bearer $coffeeKey" } `
    -ContentType "application/json; charset=utf-8" `
    -Body $directBody

$directResult.choices[0].message.content

測試後請清除終端中的敏感變數或關閉該終端，不要公開命令歷史和截圖。

07. 測試 LiteLLM 本機端點

保持 LiteLLM 執行，開啟另一個 PowerShell：

$litellmKey = "sk-your-litellm-master-key"
$proxyBody = @{
    model = "coffee-minimax-m2-7"
    messages = @(
        @{ role = "user"; content = "請只回覆：LiteLLM 接入成功" }
    )
    stream = $false
} | ConvertTo-Json -Depth 10

$proxyResult = Invoke-RestMethod `
    -Uri "http://127.0.0.1:4000/v1/chat/completions" `
    -Method Post `
    -Headers @{ Authorization = "Bearer $litellmKey" } `
    -ContentType "application/json; charset=utf-8" `
    -Body $proxyBody

$proxyResult.choices[0].message.content

這裡必須使用 LiteLLM Master Key 和用戶端別名 coffee-minimax-m2-7，不能改用 CoffeeRouter Key 或實際上游模型 ID。

08. ChatBox 接入 LiteLLM

在 ChatBox 中進入 設定 → Model Provider → Add Custom Provider，選擇 OpenAI API Compatible，然後填寫：

ChatBox 設定項目	填寫內容
Name	LiteLLM
API Mode	OpenAI API Compatible
API Key	.env 中的 LITELLM_MASTER_KEY
API Host	http://127.0.0.1:4000
API Path	/v1/chat/completions
Model	coffee-minimax-m2-7

點擊 Fetch 或手動加入 coffee-minimax-m2-7，儲存後返回聊天頁面，選擇該模型並傳送測試訊息。

ChatBox 只儲存本機 LiteLLM Master Key，不應填寫 CoffeeRouter 上游令牌。

常見問題

安全提示

• 為 LiteLLM 建立獨立 CoffeeRouter 令牌，方便單獨撤銷與更換。
• .env、終端歷史和 LiteLLM 日誌都可能包含憑證或請求資訊，不要上傳或分享。
• 不要讓用戶端直接取得 CoffeeRouter 上游令牌；用戶端只使用 LiteLLM Master Key。
• 如果任一 Key 疑似外洩，請先在對應系統中撤銷，再更新 .env 並重新啟動 LiteLLM。

官方資料

• LiteLLM Getting Started 與推薦安裝方式
• LiteLLM 官方文件
• LiteLLM 官方儲存庫
• uv 官方安裝文件
• ChatBox 服務商設定說明