LiteLLM

LiteLLM to open-source proxy z API zgodnym z OpenAI. W kontekście WEBCON pełni rolę pośrednika między AI Proxy a modelami językowymi - zarówno hostowanymi lokalnie (np. Llama, Mistral przez Ollama), jak i u zewnętrznych dostawców chmurowych (OpenAI, Azure, Anthropic). Umożliwia korzystanie z funkcji AI bez uzależnienia od jednego dostawcy.

Kiedy wybrać LiteLLM

Chcesz uruchamiać modele językowe we własnej infrastrukturze - bez wysyłania danych do zewnętrznych dostawców AI.

Wymagania

• działająca instancja LiteLLM (self-hosted),
• wirtualny klucz LiteLLM (master_key lub klucz wygenerowany przez /key/generate).

Jeśli organizacja wymaga uwierzytelniania przez OIDC, dodatkowo potrzebne są:

• serwer tokenów OIDC obsługujący przepływ client_credentials (np. Keycloak, Azure AD),
• ClientId i ClientSecret zarejestrowanego klienta OIDC.

Krok 1: Przygotowanie LiteLLM

Uruchom LiteLLM

Poniższy przykład konfiguruje LiteLLM z modelami hostowanymi lokalnie przez Ollama - bez połączenia z zewnętrznymi dostawcami AI.

# litellm_config.yaml
model_list:
  - model_name: llama3
    litellm_params:
      model: ollama/llama3
      api_base: http://ollama:11434

  - model_name: mistral
    litellm_params:
      model: ollama/mistral
      api_base: http://ollama:11434

general_settings:
  master_key: sk-litellm-master-key

docker run -d \
  -p 4000:4000 \
  -v ./litellm_config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml

informacja

Pełna dokumentacja konfiguracji LiteLLM dostępna jest pod adresem docs.litellm.ai.

Utwórz wirtualny klucz

Wirtualne klucze LiteLLM służą do kontroli dostępu i ograniczania zasobów przypisanych do danego klienta.

curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-litellm-master-key" \
  -H "Content-Type: application/json" \
  -d '{"models": ["llama3", "mistral"], "max_budget": 10}'

Odpowiedź zawiera pole key - to wirtualny klucz LiteLLM, który będzie używany przez AI Proxy.

Krok 2: Konfiguracja AI Proxy

Wybierz jeden z trzech wariantów uwierzytelniania w zależności od konfiguracji Twojej instancji LiteLLM.

Wariant A - standardowy nagłówek Authorization (zalecany)

Najprostszy wariant: AI Proxy przekazuje wirtualny klucz jako Authorization: Bearer <klucz>. Nie wymaga żadnych dodatkowych zmian po stronie LiteLLM.

aiconfiguration.json

{
  "ProviderConnections": {
    "LiteLlm": {
      "Description": "LiteLLM - standardowy Authorization Bearer",
      "Type": "OpenAiApiCompatible",
      "ProviderConfiguration": {
        "Endpoint": "http://litellm:4000",
        "ApiKey": "sk-your-litellm-virtual-key",
        "InlineFileAttachments": true,
        "InlineFileAttachmentsMaxBytes": 20971520
      }
    }
  }
}

ApiKey a nagłówek Authorization

Wartość ApiKey jest wysyłana przez SDK automatycznie jako Authorization: Bearer <ApiKey>. Należy podać wyłącznie sam klucz - bez przedrostka Bearer.

docker-compose.yml

environment:
  - ProviderConnections__LiteLlm__ProviderConfiguration__Endpoint=http://litellm:4000
  - ProviderConnections__LiteLlm__ProviderConfiguration__ApiKey=sk-your-litellm-virtual-key

Wariant B - własny nagłówek HTTP z wirtualnym kluczem

Użyj tego wariantu, jeśli chcesz, aby LiteLLM czytał wirtualny klucz z niestandardowego nagłówka HTTP zamiast ze standardowego Authorization. Wymaga to zmiany konfiguracji LiteLLM.

litellm_config.yaml

Dodaj opcję litellm_key_header_name w sekcji general_settings:

general_settings:
  master_key: sk-litellm-master-key
  litellm_key_header_name: "x-litellm-key"  # LiteLLM będzie szukał klucza w tym nagłówku

aiconfiguration.json

{
  "ProviderConnections": {
    "LiteLlm": {
      "Description": "LiteLLM - własny nagłówek z wirtualnym kluczem",
      "Type": "OpenAiApiCompatible",
      "ProviderConfiguration": {
        "Endpoint": "http://litellm:4000",
        "Headers": {
          "x-litellm-key": "Bearer sk-your-litellm-virtual-key"
        },
        "InlineFileAttachments": true,
        "InlineFileAttachmentsMaxBytes": 20971520
      }
    }
  }
}

ostrzeżenie

Wartość nagłówka musi zawierać przedrostek Bearer Nagłówki zdefiniowane w sekcji Headers są przekazywane dosłownie. Jeśli LiteLLM oczekuje formatu Bearer <klucz> w nagłówku x-litellm-key, wartość w konfiguracji musi zawierać pełne Bearer sk-....

docker-compose.yml

environment:
  - ProviderConnections__LiteLlm__ProviderConfiguration__Endpoint=http://litellm:4000
  - ProviderConnections__LiteLlm__ProviderConfiguration__Headers__x-litellm-key=Bearer sk-your-litellm-virtual-key

Wariant C - uwierzytelnianie OIDC (client_credentials)

Użyj tego wariantu, jeśli instancja LiteLLM wymaga tokenu dostępu z serwera OIDC zamiast statycznego klucza.

aiconfiguration.json

{
  "ProviderConnections": {
    "LiteLlm": {
      "Description": "LiteLLM - OIDC client_credentials",
      "Type": "OpenAiApiCompatible",
      "ProviderConfiguration": {
        "Endpoint": "http://litellm:4000",
        "OidcAuthorization": {
          "TokenEndpoint": "https://your-oidc-provider/realms/your-realm/protocol/openid-connect/token",
          "ClientId": "your-client-id",
          "ClientSecret": "your-client-secret"
        },
        "InlineFileAttachments": true,
        "InlineFileAttachmentsMaxBytes": 20971520
      }
    }
  }
}

docker-compose.yml

environment:
  - ProviderConnections__LiteLlm__ProviderConfiguration__Endpoint=http://litellm:4000
  - ProviderConnections__LiteLlm__ProviderConfiguration__OidcAuthorization__TokenEndpoint=https://your-oidc-provider/realms/your-realm/protocol/openid-connect/token
  - ProviderConnections__LiteLlm__ProviderConfiguration__OidcAuthorization__ClientId=your-client-id
  - ProviderConnections__LiteLlm__ProviderConfiguration__OidcAuthorization__ClientSecret=your-client-secret

---

Konfiguracja modeli i routingu

Sekcja ProviderModels i AiTaskTypesConfiguration jest wspólna dla wszystkich wariantów:

{
  "ProviderModels": [
    {
      "Id": "11111111-1111-1111-1111-111111111111",
      "ConnectionName": "LiteLlm",
      "Priority": 100,
      "Name": "LiteLLM Llama3",
      "Description": "",
      "TextModel": {
        "ModelName": "llama3"
      }
    },
    {
      "Id": "22222222-2222-2222-2222-222222222222",
      "ConnectionName": "LiteLlm",
      "Priority": 90,
      "Name": "LiteLLM Mistral",
      "Description": "",
      "TextModel": {
        "ModelName": "mistral"
      }
    }
  ],
  "AiTaskTypesConfiguration": {
    "ConciergePrompt": [ "11111111-1111-1111-1111-111111111111" ],
    "ConciergeExecuteTool": [ "22222222-2222-2222-2222-222222222222" ]
  }
}

Krok 3: Pełny przykład docker-compose.yml

Poniższy przykład używa wariantu A (standardowy Authorization Bearer):

name: aiproxy_containers
services:
  ai-proxy:
    image: webconbps/aiproxy:1.0.0.235
    container_name: ai-proxy
    restart: unless-stopped
    ports:
      - "5298:8080"
      - "7033:8081"
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - AppConfiguration__SelfHosted__Certificate__Path=/app/https/certificate.pem
      - Logging__LogLevel__Default=Information
      - Logging__LogLevel__Microsoft=Warning
      # Konfiguracja połączenia z LiteLLM
      - ProviderConnections__LiteLlm__ProviderConfiguration__Endpoint=http://litellm:4000
      - ProviderConnections__LiteLlm__ProviderConfiguration__ApiKey=sk-your-litellm-virtual-key
    volumes:
      - ./certificates/certificate.pem:/app/https/certificate.pem:ro
      - ./aiconfiguration.json:/app/aiconfiguration.json:ro

Nadpisywanie wartości przez zmienne środowiskowe

Zmienne środowiskowe w formacie ProviderConnections__LiteLlm__ProviderConfiguration__Endpoint są ładowane przez ASP.NET Core po plikach JSON i nadpisują ich wartości. Dzięki temu możesz trzymać strukturę konfiguracji w aiconfiguration.json, a sekrety i adresy URL podawać wyłącznie przez docker-compose.yml - bez zapisywania ich w plikach.

Krok 4: Uruchomienie

# Upewnij się że masz przygotowane pliki:
# - ./certificates/certificate.pem
# - ./aiconfiguration.json (z uzupełnioną strukturą ProviderConnections i ProviderModels)

# Uruchom kontener
docker-compose up -d

# Sprawdź logi
docker-compose logs -f ai-proxy

Rozwiązywanie problemów

Błąd: 401 Unauthorized

Możliwe przyczyny:

• wirtualny klucz LiteLLM jest nieprawidłowy lub wygasł,
• token OIDC nie został poprawnie pobrany (wariant C).

Rozwiązanie:

# Wariant A/B: sprawdź poprawność klucza wirtualnego
# Wariant C: zweryfikuj token OIDC ręcznie:
# curl -X POST <TokenEndpoint> \
#   -d "grant_type=client_credentials" \
#   -d "client_id=<ClientId>" \
#   -d "client_secret=<ClientSecret>"

# Zrestartuj kontener
docker-compose restart ai-proxy

Błąd: 404 Not Found / Model not found

Możliwe przyczyny:

• nazwa modelu w ModelName nie istnieje w konfiguracji LiteLLM,
• instancja LiteLLM jest niedostępna pod wskazanym adresem.

Rozwiązanie:

# Sprawdź dostępne modele w LiteLLM:
# curl http://<litellm-host>:4000/models \
#   -H "Authorization: Bearer <virtual-key>"

# Upewnij się że Endpoint wskazuje na działający serwer
# Zaktualizuj ModelName w aiconfiguration.json
docker-compose restart ai-proxy

Błąd: 429 Too Many Requests

Możliwa przyczyna:

• wirtualny klucz LiteLLM ma ustawiony limit budżetu lub TPM, który został przekroczony.

Rozwiązanie:

• sprawdź limity przypisane do klucza w panelu LiteLLM (/key/info),
• rozważ zwiększenie budżetu lub wygenerowanie nowego klucza z wyższym limitem.

Błąd połączenia z serwerem OIDC (wariant C)

Możliwe przyczyny:

• adres TokenEndpoint jest nieprawidłowy,
• kontener AI Proxy nie ma dostępu sieciowego do serwera OIDC.

Rozwiązanie:

# Sprawdź czy endpoint tokenów jest osiągalny z kontenera:
# docker exec ai-proxy curl -s <TokenEndpoint>

# Upewnij się że sieci Docker są poprawnie skonfigurowane
docker-compose logs -f ai-proxy

Dalsze zasoby

• Dokumentacja LiteLLM
• LiteLLM Virtual Keys
• LiteLLM Supported Models
• LiteLLM Docker Setup