透過 LiteLLM 轉接 AOAI / Azure AI Foundry 模型實現進階管理

2026-09-19 08:24 PM

企業的 AI 模型整合開發應用，資安治理上有許多額外要求，例如身分驗證、金鑰管理、資料隱私、法規遵循... 等，考量多如牛毛，使用 Azure AI Foundry (更早前叫 AOAI，現更名為 Microsoft Foundry) 這類 MaaS (Model as a Service 模型即服務) 是省時省力的做法。(懂的都懂)

若直接用 Foundry 專案共用的 API Key，一把金鑰可存取專案所有模型，很難再細分使用者、程式、系統，個別設定權限及統計用量。要實現這個目標，最簡單直覺的解法是在 Foundry 模型與客戶端之間插入一個中間層，也就是所謂 LLM Proxy 或 LLM Gateway 角色，在這層我們可任意加上想要的管理功能。

評估了一下，LiteLLM 是這類需求中受歡迎的解決方案，它支援一百種以上的 LLM 模型，提供負載平衡、故障自動轉移(Fallback) 等高可用性機制，能建立虛擬金鑰 (Virtual Keys)，分別設定預算上限、統計使用量，具敏感個資遮蔽等安全護欄 (Guardrails)功能，有完整 Log 能詳細追蹤請求及 Token 消耗，還支援 Prometheus 等主流觀測監控平台，功能應有盡有，是值得學習的 LLM 應用工具。

這篇來簡單筆記如何透過 LiteLLM 串接 Foundry 的 GPT 模型。

要跑 LiteLLM 服務，用 Docker Compose 是首選，以下的 docker-compose.yml 會建立兩個容器分別跑 LiteLLM 及 Posgres 資料庫：

services:
  litellm:
    image: docker.litellm.ai/berriai/litellm-database:latest
    container_name: litellm # 指定容器名稱
    ports:
      - "4000:4000"
    environment:
      LITELLM_MASTER_KEY: sk-1234567
      LITELLM_SALT_KEY: sk-7654321 # 啟用後勿改，否則會導致加密資料無法讀取
      # 小訣竅： Composer 內部有 DNS，可由服務名稱(如：db)轉換對應 IP 地址
      # 而 db 未設 ports 對外開放，只供內部服務存取，保障安全性
      DATABASE_URL: postgresql://litellm:litellm@db:5432/litellm
      STORE_MODEL_IN_DB: "True"
    depends_on:
      db:
        condition: service_healthy # 確認資料庫服務健康後再啟動 litellm
  db:
    image: postgres:16
    container_name: litellm-db # 指定容器名稱
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: litellm
      POSTGRES_DB: litellm
    healthcheck: # 檢查資料庫服務是否健康
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes: # 設定將資料存在本地目錄方便備份及搬移 (不然可存 Docker Volume)
      - ./postgres_data:/var/lib/postgresql/data

啟動後，使用 http://<litellm-ip>:4000/ui 可連上管理介面，LiteLLM 的教學很多，操作上也挺直覺，這裡不多著墨。但實際使用過程，我卡在不知道 Foundry 模型要怎麼選擇 Provider？Endpoint 網址要輸入什麼？這段比較值得筆記。

在 LiteLLM 新增模型時，Provider 清單中有 Azure、Azure AI Foundry (Studio)、Azure Text 三種 Azure 相關選項，三者有什麼不同？

Azure
對應 Azure OpenAI Service，在 LiteLLM 會加上 azure/ 前綴，例如 azure/gpt-4o、azure/gpt-5.6-luna，適用微軟託管的 OpenAI 對話與多模態模型，API 路徑 /chat/completions (OpenAI 規格) 背後呼叫的是標準的 Azure OpenAI Chat Completions 端點 .../openai/deployments/{deployment_id}/chat/completions?api-version=...），需要設定：AZURE_API_KEY, AZURE_API_BASE, AZURE_API_VERSION。
Azure AI Foundry (Studio)
對應 Azure AI Foundry (前身為 Azure AI Studio) 代管的第三方非 OpenAI 模型 (如 Meta Llama、Cohere、Anthropic Claude、Mistral 等)，前綴為 azure_ai/，例如：azure_ai/claude-3-5-sonnet, azure_ai/command-r-plus，API 路徑 /models 或各廠商原生 Messages 格式。這類 API 端點與 OpenAI 傳統路徑不同（網址通常為 https://<resource>.services.ai.azure.com/...）
Azure Text
對應 Azure OpenAI 舊版 Completion 古老的單字/純文字補齊 (Instruct) 模型，前綴為 azure_text/，例如：azure_text/gpt-3.5-turbo-instruct。只需傳 prompt 內容，不支援 messsage: [ { "role": "user", ... } ] 對話結構，這個現在應該沒人在用了。

簡單來說，OpenAI 的模型選 Azure、非 OpenAI 模型如 Anthropic、Meta、Mistral... 選 Azure AI Foundry，二者端點網址不同。至於 Azure Text 是 gpt-3.5-turbo-instruct 等上古模型在用的，可略過。

在 Azure Foundry 專案介面可以查到 API Key 及 OpenAI Endpoint 網址，新增模型時會用到：

千萬不要每次新增模型都重新輸入端點網址跟 API Key，未來要輪替更換金鑰時，會換到你想抓狂。LiteLLM 當然有想到這點，允許我們在 LLM Credentials 輸入 API Key 新增一筆認證資料，未來新增模型時，指定使用這組認證：

設定時，Provider 選 Azure，輸入 API Base (不用加 openai/v1) 跟 Azure API Key 即可，其他欄位不用填：

建好認證資料，在新增模型時，選擇使用現有認證，就不用重複輸入下方的 API Base、API Key，未來要修改端點 Url 或更新 API Key，只需修改認證，所有模型一次更新，這是符合實務應用的做法：

另外，新增模型時，要選擇模型的模式，有 Chat、Complete... 等選項，用途整理以下：

Mode	Endpoint	主要用途	輸入 → 輸出
Chat	`/chat/completions`	對話式文字生成，絕大部分應用都是這個	文字/圖片等 → 文字
Completion	`/completions`	傳統 Prompt 接 Completion，上古模型適用	Prompt → 文字
Embedding	`/embeddings`	將文字轉成向量，用於 RAG、語意搜尋、相似度比對	文字 → Vector
Audio Speech	`/audio/speech`	Text-to-Speech，將文字轉成語音	文字 → 音訊
Audio Transcription	`/audio/transcriptions`	Speech-to-Text，將錄音/語音轉成文字	音訊 → 文字
Image Generation	`/images/generations`	根據 Prompt 產生新圖片	文字 → 圖片
Image Edit	`/images/edits`	編輯既有圖片，例如修改、補圖、移除/加入元素	圖片 + Prompt → 圖片
Video Generation	`/videos`	根據文字或其他輸入產生影片	Prompt/素材 → 影片
Rerank	`/rerank`	將搜尋/RAG 找到的候選文件重新排序，提升相關性	Query + Documents → 排名結果
Realtime	`/realtime`	即時、低延遲的互動，例如語音對話、串流輸入輸出	即時多模態 ↔ 即時輸出
Batch	`/batch`	大量 API 工作的非同步批次處理，適合不要求即時回應的任務	大量 Requests → 批次結果
OCR	`/ocr`	從圖片、掃描文件等擷取文字	圖片/文件 → 文字

設定好模型，接著我們就可以建立多把虛擬金鑰，指定其可使用的模型、可用預算上限，進行細緻化管理。至於使用上，跟標準 OpenAI 模型一模一樣，只是把 Endpoint 換成 http://<litellm-ip>:4000，API Key 換成在 LiteLLM 建立的虛擬金鑰，其餘照舊，以下用微軟官方 AI 程式庫 MEAI 示範：

using System.ClientModel;
using System.Diagnostics;
using DotNetEnv;
using Microsoft.Extensions.AI;
using OpenAI;

Env.Load();

var apiKey = Environment.GetEnvironmentVariable("LITELLM_KEY"); // http://<litellm-ip>:4000
var liteLlmUrl = Environment.GetEnvironmentVariable("LITELLM_URL"); // 例: sk-QQ9-FpEq8w1MiuqlNZItxm

if (string.IsNullOrWhiteSpace(apiKey) || string.IsNullOrWhiteSpace(liteLlmUrl))
{
    throw new InvalidOperationException(
        "請在 .env 設定 LITELLM_KEY 與 LITELLM_URL。");
}

var baseUrl = liteLlmUrl.TrimEnd('/');
var endpoint = baseUrl.EndsWith("/v1", StringComparison.OrdinalIgnoreCase)
    ? $"{baseUrl}/"
    : $"{baseUrl}/v1/"; // 補上 v1

IChatClient chatClient = new OpenAIClient(
    new ApiKeyCredential(apiKey),
    new OpenAIClientOptions { Endpoint = new Uri(endpoint) })
    .GetChatClient("gpt-5.6-luna")
    .AsIChatClient();
    
var prompt = "一句話介紹 LiteLLM？";
var sw = new Stopwatch();
sw.Start();
var response = await chatClient.GetResponseAsync(prompt);
sw.Stop();
Console.WriteLine($"({sw.ElapsedMilliseconds:n0} ms) {response.Text}");