← 回到筆記2025-11-05

LiteLLM Pass-through Endpoint

介紹 LiteLLM 與 pass-through endpoint，並以本地 Ollama 實作 YAML passthrough 與自訂 adapter server 兩種測試。

發佈 ~6 分鐘 #LLM#LiteLLM

🧭 TL;DR I: What is LiteLLM?

LiteLLM 是一個 多模型統一代理層 (proxy + SDK)。

可以用一套 OpenAI-compatible API 格式，去打任何下層模型服務（如 Azure OpenAI、Bedrock、Ollama、Claude、Gemini、Mistral 等）。

👉 主要功能：

  • 統一 API 格式（/v1/chat/completions、/v1/embeddings…）
  • 管理多個 provider 的 key / quota / routing
  • 提供代理伺服器模式（LiteLLM Proxy）
  • 支援 passthrough 模式（可把請求轉給任意 endpoint，例如本地 Ollama）

這讓上層應用（Python SDK、LangChain、或者 Web App）不用改 code，就能切換不同模型或供應商。

🧭 TL;DR II: What is Pass Through Endpoint?

在 LiteLLM Proxy 裡，「每個 model」定義（在 config.yaml 的 model_list 裡）

都會對應到一個 pass-through route（轉發路徑）。

每條 route 知道要轉給哪個底層 API（api_base），

所以可以把它理解成「一個 model = 一個 pass-through endpoint」。

⚙️ custom passthrough endpoint vs 直接內建 provider 的差異

項目內建 provider (ex: Azure, OpenAI)custom passthrough endpoint
設定方式直接在 config.yaml 裡寫 model + api_base + api_key在 config.yaml 中設置 "model":"custom/<name>" 並指定 passthrough endpoint
認證方式SDK 幫帶 key（例如 api_key, azure_ad_token）自行決定 header/body 內容（LiteLLM 只轉發）
請求結構LiteLLM 封裝成各 provider 的格式要確保下游 endpoint 能理解 OpenAI 格式
適用場景常見 LLM API（OpenAI, Azure, Anthropic, etc.）任何自建推論服務（如 Ollama, vLLM, Bedrock custom, LoRA endpoint）
是否需 adapter❌ 不需要，官方已內建✅ 若 endpoint 不是標準 OpenAI 格式，需要自訂 adapter

🔧 adapter 的實際用途（advanced custom adapters）

官方文件（Advanced Custom Adapters）裡提到的 adapter，是針對這種情況：

後端 endpoint 不是 OpenAI-compatible API 格式，LiteLLM 需要轉換請求與回應。

例如：

  • 你有一個 FastAPI 服務 /api/v1/inference，body schema 完全不同。
  • 你要讓 LiteLLM 能把 /v1/chat/completions 的格式轉成你後端的格式。

此時你可以寫一個自訂 adapter，例如：

from litellm.adapters.custom_httpx import CustomHttpxAdapter

class MyAdapter(CustomHttpxAdapter):
    def format_request(self, body, headers):
        # 轉換 LiteLLM 的 body 成你後端的格式
        return {"prompt": body["messages"][-1]["content"]}

    def format_response(self, response):
        # 轉換你後端回傳的結果成 OpenAI 格式
        return {"choices": [{"message": {"content": response["output"]}}]}

然後在 config.yaml 指定：

model_list:
  - model_name: mycustom
    litellm_params:
      model: custom/mycustom
      api_base: http://localhost:5000
      adapter: my_module.MyAdapter

🧩 測試一：本地 Ollama passthrough 實作

目標

在 本地機器上用 Docker 起一個 LiteLLM Proxy，讓它：

達到「讓 LiteLLM 當作 Ollama 的 OpenAI API 介面」。

🏗️ 最終工作架構

[openai-python SDK]
        │
        ▼
http://localhost:4000/v1/chat/completions
        │
        ▼
[LiteLLM Proxy container]
        │
        ▼
http://ollama:11434/api/chat
        │
        ▼
    [Ollama]

🧱 主要設置過程回顧

  1. Docker Compose 服務架構

    services:
  ollama:
    image: ollama/ollama:latest
    ports: ["11434:11434"]
    volumes: ["ollama_data:/root/.ollama"]

  litellm:
    image: ghcr.io/berriai/litellm:main
    platform: linux/amd64    # for M1/M2 macs
    ports: ["4000:4000"]
    environment:
      LITELLM_API_KEY: sk-local-123
      OLLAMA_API_BASE: http://ollama:11434
    volumes:
      - ./lite.yaml:/app/proxy_server_config.yaml
    command:
      [
        "litellm",
        "--host","0.0.0.0",
        "--port","4000",
        "--config","/app/proxy_server_config.yaml"
      ]
    depends_on: [ollama]

  2. lite.yaml（覆蓋預設 Azure config）

    model_list:
  - model_name: tinyllama
    litellm_params:
      model: ollama/tinyllama
      api_base: http://ollama:11434

litellm_settings:
  drop_params: true
  set_verbose: true

  3. 測試：

    curl http://localhost:4000/health
# → {"status":"ok"}

curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-local-123" \
  -H "Content-Type: application/json" \
  -d '{"model":"tinyllama","messages":[{"role":"user","content":"hi"}]}'

    成功即代表整個 pipeline 正常。

  4. Python SDK 測試：

    from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000/v1",
    api_key="sk-local-123",
)
resp = client.chat.completions.create(
    model="tinyllama",
    messages=[{"role": "user", "content": "Hello world"}],
)
print(resp.choices[0].message.content)

🧩 測試二：Ollama + Custom Server Adapter

目標

在本地環境驗證以 自訂 FastAPI + LiteLLM Adapter Server 為核心的新版 Pass-through 架構。

相較於 YAML 直通配置，本版本透過 自建 server.py 服務：

  • 直接實作 /v1/custom-ollama-openai（OpenAI → Ollama 格式轉換）
  • 提供 /v1/custom-ollama（Ollama 原生 passthrough）
  • 保留 /v1/chat/completions（標準 LiteLLM 介面）
  • 支援 /health 深度健康檢查與 /healthz 輕量健康檢查

此架構讓 LiteLLM 不再僅是 Proxy，而成為可程式化的 LLM 接入層。

⚙️ 架構概念

┌────────────────────────────┐
│ OpenAI / LangChain / SDK   │
│ (OpenAI-compatible Client) │
└──────────────┬─────────────┘
               │
               ▼
     http://localhost:4000
               │
               ▼
┌────────────────────────────────────┐
│ Custom LiteLLM Adapter Server      │
│  • /v1/custom-ollama-openai        │ ← OpenAI → Ollama 格式轉換
│  • /v1/custom-ollama               │ ← 原生 passthrough
│  • /v1/chat/completions            │ ← 標準 OpenAI API
│  • /health /healthz                │ ← 健康檢查
└────────────────────────────────────┘
               │
               ▼
     http://ollama:11434/api/generate
               │
               ▼
┌───────────────────────────┐
│ Ollama Container (LLM)    │
└───────────────────────────┘

💡 此版本不再使用 pass_through_endpoints 的 YAML 設定，而是由 server.py 動態載入 lite.yaml，解析其中的 model_list 與 api_base。

🧱 主要設定架構

  1. lite.yaml

    定義模型別名與路由資訊，例如：

    model_list:
  - model_name: tinyllama
    litellm_params:
      model: ollama/tinyllama
      api_base: http://ollama:11434

general_settings:
  master_key: sk-1234

litellm_settings:
  default_model: tinyllama

    這讓 /v1/chat/completions 與 /health 自動識別所有已登錄模型，無須再配置 pass_through_endpoints。

  2. Docker 結構

    services:
  ollama:
    image: ollama/ollama:latest
    ports: ["11434:11434"]
    volumes: ["ollama_data:/root/.ollama"]

  litellm-custom:
    build: .
    ports: ["4000:4000"]
    environment:
      MASTER_KEY: "sk-1234"
      OLLAMA_URL: "http://ollama:11434"
    volumes:
      - ./lite.yaml:/app/lite.yaml
    depends_on: [ollama]
    restart: unless-stopped

volumes:
  ollama_data:

🤖 Server 中的 Adapter 與 Custom Pass-Through Endpoint 介紹

在 測試二 中，我們使用了自訂的 Adapter 與 Custom Pass-Through Endpoint，這使得 LiteLLM 不僅限於將請求直接轉發至標準 OpenAI 或其他內建模型服務，而是提供了更多的自訂與擴展功能，特別是在處理 非標準 LLM 服務 時的靈活性與彈性。

  1. Adapter 的角色

    Adapter 是用來處理非標準 OpenAI 格式的請求與回應轉換，將 LiteLLM 的 OpenAI-style API 格式轉換為目標服務（如 Ollama）所期望的格式。這使得 LiteLLM 可以與 任何自建或非標準的推論服務（如 Ollama、vLLM 等）順利對接。

    例如在專案中，MyOllamaAdapter 就是負責將 OpenAI 的 messages 格式轉換為 Ollama 所需的 prompt 格式，並將 Ollama 的回應轉換回 OpenAI 所期望的格式。這不僅簡化了 API 對接的工作，還允許你為每個服務實現自定義的邏輯，例如：

    • 修改請求的 body 格式
    • 改寫 header（如客製化的授權 token）
    • 實作回應的格式化與錯誤處理邏輯

  2. Custom Pass-Through Endpoint 的應用

    Custom Pass-Through Endpoint 是 LiteLLM 的一個強大特性，它允許你定義一個 自訂的路由，將請求轉發到任何模型或推論服務。當使用者呼叫 /v1/custom-ollama 這個路由時，LiteLLM 不會直接將請求發送給內建的 API，而是根據配置將其轉發給你指定的 endpoint。

    在專案中，這個 endpoint 實現了兩種功能：

    • 原生 passthrough（/v1/custom-ollama）：這是將請求無任何修改直接轉發到 Ollama 的路由。這對於標準的 LLM 服務（如 Ollama）非常有效，因為它們本身就與 OpenAI 兼容。
    • Adapter + Pass-Through（/v1/custom-ollama-openai）：這個路由在將請求轉發到 Ollama 之前，會先進行格式轉換，將 OpenAI 的請求格式（包含 messages 和 temperature 等參數）轉換為 Ollama 所能理解的格式。轉換後，再將其送出，並在收到回應後，將其格式化為 OpenAI 所期待的結果。

    這樣的結構不僅能支援標準的 OpenAI 兼容服務，也能靈活應對任何自建模型或非標準的 LLM 接口，並可根據需求進行精細化控制，增加了系統的擴展性與靈活性。

  3. 應用場景

    這種 Adapter + Custom Pass-Through Endpoint 的模式非常適用於以下場景：

    • 跨雲混合架構：當你需要在同一個架構中同時運行來自不同雲端提供者（如 OpenAI、Azure、AWS Bedrock）的模型服務時，可以利用 Adapter 層進行轉換，讓它們無縫協同工作。
    • 自建推論服務：如 Ollama、vLLM 等，這些模型服務未必支持標準的 OpenAI 格式，這時 Adapter 就能提供必要的格式轉換，讓 LiteLLM 與這些服務兼容。
    • 客製化管控需求：例如需要自訂授權 token、加入額外的流量控制或監控邏輯時，Adapter 提供了程式化的可擴展點。

🧩 健康檢查

  • /healthz：輕量檢查，確認服務啟動與預設模型。
  • /health：深度檢查（需 Bearer Token），會：
    • 讀取 lite.yaml 的所有模型；
    • 對每個 api_base 執行連線測試；
    • 對 Ollama 檢查模型是否存在；
    • 回傳延遲、可用性與 endpoint 清單。
curl -H "Authorization: Bearer sk-1234" http://localhost:4000/health

🧪 測試步驟

  1. OpenAI → Ollama 自動轉換測試

    curl -X POST http://localhost:4000/v1/custom-ollama-openai \
  -H "Authorization: Bearer sk-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ollama/tinyllama",
    "messages": [{"role": "user", "content": "Hello! Say hi in a friendly way."}],
    "max_tokens": 50,
    "temperature": 0.7
  }'

  2. 直接轉發至 Ollama

    curl -X POST http://localhost:4000/v1/custom-ollama \
  -H "Authorization: Bearer sk-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tinyllama",
    "prompt": "User: Hello! Say hi in a friendly way.",
    "stream": false,
    "options": {"temperature": 0.7, "num_predict": 50}
  }'

  3. 標準 /v1/chat/completions 呼叫

    curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tinyllama",
    "messages": [{"role": "user", "content": "Hello! Say hi in a friendly way."}]
  }'

🧠 架構比較

項目測試一：Ollama passthrough測試二：Custom Adapter Server
LiteLLM 角色YAML Proxy Layer可程式化 Adapter Layer
路由管理YAML pass_through_endpointsFastAPI routes in server.py
設定來源lite.yaml + proxy_server_config.yamllite.yaml（動態載入）
可擴展性僅支援 OpenAI-compatible可轉換任意 API 結構
健康檢查/healthz（簡單）/health + /healthz
適用場景單純代理混合雲、自建推論層、企業治理

🧭 Mermaid 架構圖

flowchart TD
    A[Client / SDK] --> B['/v1/chat/completions']
    A --> C['/v1/custom-ollama-openai']
    A --> D['/v1/custom-ollama']
    subgraph S[Custom LiteLLM Adapter Server]
        B -->|auto route| E[LiteLLM Core]
        C -->|OpenAI→Ollama Adapter| F[Ollama API /api/generate]
        D -->|Raw passthrough| F
        E --> F
    end
    F --> G[(Ollama Container)]

🧠 結語

在這個新版的實驗中，LiteLLM 的定位從「OpenAI Proxy Layer」進化成一個可編程的 LLM 整合中樞（Programmable Integration Layer）。

過去它只是轉發請求、統一格式；現在則能透過自訂 Adapter Server，掌控整個模型接入、轉換與監控生命週期。

這個新結構具備三個關鍵價值：

  1. 標準化（Standardization）

    所有上層應用（SDK、LangChain、UI）依舊使用相同的 OpenAI API 介面。

    LiteLLM 負責對齊格式、路由、與金鑰管理，無論後端是 OpenAI、Azure、Bedrock、還是本地 Ollama，都可透明切換。

  2. 可程式化（Programmability）

    透過 server.py 實作的 Adapter，開發者能：

    • 改寫請求／回應 JSON 結構

    • 插入自訂認證與 header

    • 實作流量治理、降級策略、或模擬 hybrid routing

      這使 LiteLLM 不再只是 proxy，而是智慧轉接層（intelligent translation & governance layer）。

  3. 可監控與可治理（Observability & Governance）

    整合的 /health 與 /healthz 端點提供兩層健康檢查：

    • /healthz：存活檢查，確保服務運作。

    • /health：深度檢查，對每個模型與上游 endpoint 測試可用性與延遲。

      這為多模型部署提供了基礎的可觀測性（Observability），也能納入後續監控與報警系統。

綜合來看：

  • 「測試一」 驗證了 LiteLLM 的「開箱即用」能力：本地 Ollama 能以 OpenAI 介面被直接呼叫。
  • 「測試二」 則證明了 LiteLLM 在「非標準環境、混合雲與企業治理場景」中的靈活性與可延展性。

最終，LiteLLM 不只是「能轉發」的代理，而是建立了一個：

可控（Controllable）、可監控（Observable）、可替換（Interchangeable） 的

LLM Abstraction & Governance Layer ——

一個讓多模型環境真正落地、可維運、可持續演進的核心中介層。

← 回到筆記