LiteLLM Proxy: 1 API dla 100+ LLM (konfiguracja w Dockerze w 15 min)

LiteLLM Proxy: 1 API dla 100+ LLM (konfiguracja w Dockerze w 15 min)

Twój zespół udostępnia klucze API OpenAI na prywatnych wiadomościach Slacka. Nikt nie wie, kto wydał 400 USD w zeszły wtorek. Nie ma limitowania przepustowości, nie ma mechanizmu awaryjnego, gdy dostawca przestaje działać, a przełączenie się z GPT-4o na Claude wymaga zmiany kodu w dwunastu miejscach. Brzmi znajomo? Samodzielnie hostowana bramka LLM rozwiązuje wszystkie te problemy, a proxy LiteLLM jest najpopularniejszą opcją open-source – pojedynczym endpointem kompatybilnym z OpenAI, który kieruje żądania do ponad 100 dostawców LLM.

Ten przewodnik obejmuje pełną konfigurację proxy litellm: Docker Compose z PostgreSQL, wirtualne klucze zespołowe z budżetami, śledzenie kosztów, limity przepustowości oraz podłączanie IDE AI, takich jak Claude Code i Cursor. Jeśli oceniasz narzędzia typu LLM gateway, to jest praktyczny tutorial, który przeprowadzi Cię od zera do środowiska produkcyjnego.

Jedna ważna uwaga przed rozpoczęciem: SDK LiteLLM (biblioteka Pythona) i Serwer Proxy to dwie różne rzeczy. SDK służy pojedynczemu deweloperowi wywołującemu wiele API LLM z poziomu Pythona. Proxy jest przeznaczone dla zespołów – działa jako serwer pośredniczący między Twoimi aplikacjami a dostawcami LLM. Jeśli jesteś samotnym deweloperem piszącym skrypt, SDK wystarczy. Jeśli zarządzasz kluczami, budżetami i dostępem dla zespołu, potrzebujesz proxy. Właśnie to będziemy tutaj konfigurować.

LiteLLM Proxy w skrócie

Oto porównanie metod wdrażania:

Dla większości zespołów Docker Compose z PostgreSQL to złoty środek. Do tego będziemy dążyć, ale najpierw uruchommy proxy w 60 sekund.

Wymagania wstępne i konfiguracja środowiska

Zanim zaczniesz, upewnij się, że masz:

• Zainstalowane Docker i Docker Compose (Docker Desktop zawiera oba)
• Co najmniej jeden klucz API LLM (OpenAI, Anthropic lub lokalna instancja Ollama)
• Podstawową znajomość terminala / CLI

Sprawdź, czy Docker jest gotowy i wyeksportuj swoje klucze API:

# Check Docker is installed
docker --version
docker compose version

# Export your LLM API keys (add to your shell profile for persistence)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Optional: set a master key for your proxy (you'll need this later)
export LITELLM_MASTER_KEY="sk-master-your-secret-key"

To wszystko. Nie potrzebujesz specjalnej wersji Pythona ani narzędzi specyficznych dla systemu operacyjnego. Jeśli Docker działa na Twojej maszynie, jesteś gotowy.

Szybki start: Twoje pierwsze proxy LiteLLM w 60 sekund

Jedno polecenie, aby uruchomić proxy z GPT-4o:

docker run -d \
  --name litellm-proxy \
  -p 4000:4000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e LITELLM_MASTER_KEY=$LITELLM_MASTER_KEY \
  ghcr.io/berriai/litellm:main-stable \
  --model openai/gpt-4o

Przetestuj je za pomocą curl:

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Say hello from LiteLLM"}]
  }'

Lub przetestuj z poziomu Pythona:

from openai import OpenAI

# Point the standard OpenAI SDK at your proxy
client = OpenAI(
    api_key="sk-master-your-secret-key",
    base_url="http://localhost:4000/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Say hello from LiteLLM"}]
)
print(response.choices[0].message.content)

Co właśnie się stało? Twój kod komunikuje się z localhost:4000, używając standardowego formatu SDK OpenAI. Proxy otrzymuje żądanie, przekazuje je do API OpenAI z prawdziwym kluczem i zwraca odpowiedź. Kod Twojej aplikacji nigdy nie dotyka rzeczywistego klucza API.

To jest sedno sprawy. Teraz zbudujmy konfigurację produkcyjną.

Produkcyjna konfiguracja Docker Compose z PostgreSQL

Pojedyncze polecenie docker run działa do testów, ale zespoły produkcyjne potrzebują trwałego śledzenia kosztów, wirtualnych kluczy i odpowiedniego przechowywania danych w bazie. Oznacza to Docker Compose z PostgreSQL.

Plik Docker Compose

# docker-compose.yml
version: "3.9"

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    container_name: litellm-proxy
    ports:
      - "4000:4000"         # Proxy API port
    volumes:
      - ./config.yaml:/app/config.yaml   # Mount your config file
    environment:
      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DATABASE_URL=postgresql://litellm:litellm_password@postgres:5432/litellm
      - LITELLM_SALT_KEY=${LITELLM_SALT_KEY:-sk-salt-random-string}
    command: --config /app/config.yaml --detailed_debug
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    container_name: litellm-db
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: litellm_password
    volumes:
      - litellm_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  litellm_pgdata:

LITELLM_SALT_KEY szyfruje dane wirtualnych kluczy w bazie danych. Dokumentacja najlepszych praktyk produkcyjnych LiteLLM zaleca ustawienie tego parametru przy każdej wdrożeniu zespołowym.

Uruchamianie stosu

# Create a .env file with your keys (don't commit this to git)
echo "LITELLM_MASTER_KEY=sk-master-your-secret" > .env
echo "OPENAI_API_KEY=sk-..." >> .env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
echo "LITELLM_SALT_KEY=sk-salt-$(openssl rand -hex 16)" >> .env

# Start everything
docker compose up -d

# Check logs
docker compose logs -f litellm

Weryfikacja działania

# Health check
curl http://localhost:4000/health

# Test a request
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}]}'

Jeśli widzisz pomyślną odpowiedź, Twój stos produkcyjny działa. PostgreSQL przechowuje wszystkie dane kosztowe, wirtualne klucze i metryki użycia w sposób trwały, nawet po restartach kontenerów.

Werdykt: Docker Compose + PostgreSQL to zalecana konfiguracja produkcyjna. Zapewnia trwałe przechowywanie, śledzenie kosztów i wirtualne klucze przy około 10 minutach pracy. Dokumentacja wdrożeń Docker omawia Kubernetes i Helm, jeśli później będziesz potrzebować auto-scalingu.

Przegląd config.yaml: Prawdziwa konfiguracja wielodostawcza

Większość tutoriali pokazuje config.yaml z jednym modelem. Oto jak wygląda prawdziwa konfiguracja zespołowa z trzema dostawcami, fallbackami i load balancingiem.

Plik konfiguracyjny

# config.yaml -- Real multi-provider setup
model_list:
  # Primary: OpenAI GPT-4o
  - model_name: gpt-4o          # The name YOUR code uses
    litellm_params:
      model: openai/gpt-4o      # The actual provider/model
      api_key: os.environ/OPENAI_API_KEY

  # Secondary: Anthropic Claude
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

  # Local: Ollama for development / cost-free testing
  - model_name: local-llama
    litellm_params:
      model: ollama/llama3.1
      api_base: http://host.docker.internal:11434

  # Fallback: route "gpt-4o" to Claude if OpenAI is down
  - model_name: gpt-4o
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

router_settings:
  routing_strategy: least-busy    # Load balance across same-name models
  num_retries: 3
  retry_after: 5                  # Seconds between retries
  fallbacks: [{"gpt-4o": ["claude-sonnet"]}]

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

Aliasy modeli i routing

Zauważ, że gpt-4o pojawia się w konfiguracji dwukrotnie: raz wskazując na OpenAI, raz na Anthropic. Gdy Twój kod zażąda gpt-4o, LiteLLM najpierw spróbuje OpenAI. Jeśli to się nie powiedzie, ustawienie fallbacks automatycznie przekieruje ruch do Claude. Kod Twojej aplikacji w ogóle się nie zmienia.

Jeśli używasz produkcyjnych backendów wnioskowania, takich jak vLLM lub SGLang, możesz dodać je w ten sam sposób, ustawiając api_base na adres swojego serwera wnioskowania.

Szybka referencja dostawców

Ustawienie routing_strategy: least-busy rozdziela żądania między modele o tej samej nazwie model_name. Jeśli masz dwa klucze OpenAI (np. z różnych organizacji z różnymi limitami), wymień je oba pod gpt-4o, a LiteLLM zrównoważy obciążenie.

Wirtualne klucze: Klucze API per zespół z budżetami i limitami

W tym miejscu LiteLLM przestaje być „tylko proxy”, a staje się narzędziem do zarządzania zespołem. Wirtualne klucze pozwalają nadać każdemu członkowi zespołu lub usłudze własny klucz API z limitami wydatków i przepustowości, wszystko kierowane przez Twój pojedynczy zestaw kluczy API dostawców.

Tworzenie klucza zespołowego z budżetem

# Create a virtual key with a $50/month budget
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "frontend-team",
    "max_budget": 50.0,
    "budget_duration": "1mo",
    "models": ["gpt-4o", "claude-sonnet"],
    "metadata": {"purpose": "frontend AI features"}
  }'

Odpowiedź zawiera nowy klucz, np. sk-team-abc123.... Przekaż go zespołowi frontendowemu. Mogą go używać dokładnie jak klucza OpenAI, ale jest on ograniczony do 50 USD/miesiąc i ma dostęp tylko do określonych przez Ciebie modeli.

Ustawianie limitów przepustowości

# Create a key with rate limits: 100 requests/minute, 50K tokens/minute
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "backend-team",
    "max_budget": 200.0,
    "budget_duration": "1mo",
    "rpm_limit": 100,
    "tpm_limit": 50000,
    "models": ["gpt-4o", "claude-sonnet", "local-llama"]
  }'

Dokumentacja wirtualnych kluczy omawia każdy parametr. Możesz również ustawić budżety i limity przepustowości per użytkownik dla jeszcze bardziej szczegółowej kontroli.

Monitorowanie użycia kluczy

import requests

# Check a key's current spend and limits
response = requests.get(
    "http://localhost:4000/key/info",
    headers={"Authorization": f"Bearer {MASTER_KEY}"},
    params={"key": "sk-team-abc123..."}
)
info = response.json()
print(f"Spent: ${info['spend']:.2f} / ${info['max_budget']:.2f}")
print(f"RPM used: {info['rpm_limit_used']} / {info['rpm_limit']}")

Potrzebujesz unieważnić skompromitowany klucz? Jedno wywołanie API:

curl -X POST http://localhost:4000/key/delete \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["sk-team-abc123..."]}'

Werdykt: To wirtualne klucze czynią z LiteLLM narzędzie zespołowe, a nie tylko osobiste proxy. Bez nich jedynie dodajesz dodatkowy hop między swoim kodem a LLM. Dzięki nim masz kontrolę dostępu, egzekwowanie budżetu i przypisywanie użycia – rzeczy, które zapobiegają panice Twojego dyrektora finansowego.

Śledzenie kosztów i panel LiteLLM

Gdy PostgreSQL jest podłączony, LiteLLM automatycznie śledzi koszt każdego żądania. Nie musisz nic konfigurować – system zna ceny za token dla każdego obsługiwanego modelu.

Panel sterowania

Uzyskaj dostęp do wbudowanego interfejsu pod adresem http://localhost:4000/ui (zaloguj się za pomocą klucza master). Zobaczysz:

• Całkowite wydatki we wszystkich zespołach i kluczach
• Podział per model, które modele zjadają Twój budżet
• Wydatki per zespół, kto czego używa
• Wolumen żądań w czasie

Dla zespołów poważnie nastawionych na obniżanie kosztów API LLM, sam panel uzasadnia uruchomienie proxy. Możesz także podłączyć LiteLLM do zewnętrznych platform observability AI, takich jak Langfuse lub Helicone, aby uzyskać głębszą analitykę.

Porównanie kosztów per dostawca

Oto ile kosztują główne modele za milion tokenów (stan na kwiecień 2026):

Gdy widzisz te liczby w panelu rozdzielone według zespołów, rozmowy na temat „czy powinniśmy użyć tańszego modelu do tego przypadku użycia?” stają się bardzo konkretne.

Werdykt: Samo śledzenie kosztów uzasadnia użycie proxy w każdym zespole wydającym >100 USD miesięcznie na API LLM. Nie zoptymalizujesz tego, czego nie mierzysz.

Podłączanie IDE AI: Claude Code, Cursor i Continue

Oto coś, co większość przewodników po LiteLLM całkowicie pomija: możesz skierować swoje narzędzia do kodowania AI na proxy. Jedno proxy, wszystkie Twoje narzędzia IDE, zunifikowane rozliczenia.

Claude Code

# Set Claude Code to use your LiteLLM proxy
export ANTHROPIC_BASE_URL=http://localhost:4000/v1
export ANTHROPIC_API_KEY=sk-team-your-virtual-key

To wszystko. Claude Code wysyła żądania do Twojego proxy, które kieruje je do Anthropic (lub tam, gdzie wskazuje Twoja konfiguracja), jednocześnie śledząc koszty pod Twoim wirtualnym kluczem.

Cursor

W ustawieniach Cursora dodaj niestandardowy endpoint kompatybilny z OpenAI:

{
  "openai.apiBaseUrl": "http://localhost:4000/v1",
  "openai.apiKey": "sk-team-your-virtual-key"
}

Continue (VS Code)

W pliku config.json Continue:

{
  "models": [
    {
      "title": "GPT-4o via LiteLLM",
      "provider": "openai",
      "model": "gpt-4o",
      "apiBase": "http://localhost:4000/v1",
      "apiKey": "sk-team-your-virtual-key"
    }
  ]
}

Po co zawracać sobie głowę? Ponieważ teraz użycie IDE każdego dewelopera przechodzi przez proxy. Otrzymujesz śledzenie kosztów per osoba dla asystentów kodowania AI, limity przepustowości, dzięki którym nikt przypadkowo nie przepali 500 USD podczas sesji kodowania, oraz jedno miejsce do przełączania modeli, jeśli znajdziesz lepszą opcję.

Rozwiązywanie typowych problemów

„Config file not found”

Zwykle oznacza to błędną ścieżkę montowania woluminu w Dockerze. Upewnij się, że Twój config.yaml znajduje się w katalogu, z którego montujesz:

# Check the file exists where you think it does
ls -la ./config.yaml

# The volume mount in docker-compose.yml should match
# volumes:
#   - ./config.yaml:/app/config.yaml

„Connection refused” do PostgreSQL

Sieć Dockera łapie każdego przynajmniej raz. Jeśli LiteLLM nie może połączyć się z Postgresem, sprawdź, czy:

• Nazwa usługi w DATABASE_URL pasuje do nazwy usługi Docker Compose (postgres, a nie localhost)
• Ustawiono depends_on z warunkiem condition: service_healthy (aby LiteLLM czekał na gotowość Postgresa)
• Obie usługi są w tej samej sieci Docker (domyślnie są w Compose)

„Invalid API key format”

Najczęstsze nieporozumienie: Twój LITELLM_MASTER_KEY służy do operacji administracyjnych (tworzenie wirtualnych kluczy, dostęp do panelu). Wirtualne klucze (sk-team-...) są tym, czego używają Twoje aplikacje. Nie myl ich.

„Model not found”

Pole model w Twoim żądaniu musi pasować do model_name w config.yaml. Jeśli Twoja konfiguracja definiuje gpt-4o, a Twój kod żąda openai/gpt-4o, nie będzie dopasowania. Sprawdź dokładną pisownię.

Proxy startuje, ale żądania wiszą

Zazwyczaj problem z firewallem lub bindingiem portów. Zweryfikuj, czy port 4000 jest wystawiony i nie zablokowany:

# Check if the port is listening
docker port litellm-proxy
# Should show: 4000/tcp -> 0.0.0.0:4000

Bezpieczeństwo: Unikaj wersji 1.82.7 i 1.82.8

W marcu 2026 r. incydent supply chain dotknął wersje LiteLLM 1.82.7 i 1.82.8. Skompromitowane wersje zostały wycofane, a czysta wersja została wypuszczona jako 1.83.0. Zawsze przypinaj swój obraz Docker do konkretnej wersji i sprawdzaj oficjalną aktualizację bezpieczeństwa przed aktualizacją. Jeśli korzystasz z wersji 1.82.7 lub 1.82.8, zaktualizuj natychmiast.

Którą metodę konfiguracji LiteLLM wybrać?

Jeśli czytasz ten przewodnik po raz pierwszy, zacznij od Docker Compose + PostgreSQL. Zawsze możesz później migrować do Kubernetes, a config.yaml pozostanie taki sam.

FAQ

Czym jest proxy LiteLLM i jak działa?

Proxy LiteLLM to serwer bramki AI open-source, który znajduje się między Twoimi aplikacjami a dostawcami LLM, takimi jak OpenAI i Anthropic. Udostępnia pojedynczy endpoint kompatybilny z OpenAI, więc Twój kod komunikuje się z jednym URL-em, podczas gdy proxy zajmuje się routingiem, zarządzaniem kluczami, śledzeniem kosztów i fallbackami w tle.

Jak skonfigurować proxy LiteLLM z Docker Compose?

Utwórz plik docker-compose.yml z obrazem proxy LiteLLM i bazą danych PostgreSQL, zamontuj swój config.yaml, ustaw klucze API jako zmienne środowiskowe i uruchom docker compose up -d. Sekcja Produkcyjna konfiguracja Docker Compose powyżej zawiera kompletny plik gotowy do skopiowania i wklejenia.

Jak zarządzać kluczami API zespołu za pomocą LiteLLM?

Używaj wirtualnych kluczy. Wywołaj endpoint /key/generate ze swoim kluczem master, aby utworzyć klucze per zespół lub per użytkownik. Każdy wirtualny klucz może mieć własny miesięczny budżet, limity przepustowości (RPM i TPM) oraz ograniczenia dostępu do modeli. Sekcja Wirtualne klucze omawia cały proces.

Jak dodać śledzenie kosztów i limity przepustowości do mojego API LLM?

Podłącz PostgreSQL do proxy (poprzez DATABASE_URL), a śledzenie kosztów odbywa się automatycznie. W przypadku limitów przepustowości ustaw rpm_limit i tpm_limit podczas generowania wirtualnych kluczy. Wbudowany panel pod /ui pokazuje wydatki per zespół i per model.

Czy proxy LiteLLM jest bezpieczne w użyciu produkcyjnym?

Tak, z jednym zastrzeżeniem: unikaj wersji 1.82.7 i 1.82.8, które zostały dotknięte incydentem supply chain w marcu 2026 r. Używaj wersji 1.83.0 lub nowszej. Przypnij wersję obrazu Docker, ustaw LITELLM_SALT_KEY do szyfrowania i przestrzegaj oficjalnych najlepszych praktyk produkcyjnych.

Jaka jest różnica między SDK LiteLLM a proxy LiteLLM?

SDK to biblioteka Pythona do wywoływania wielu API LLM z Twojego kodu. Proxy to samodzielny serwer, do którego podłącza się cały Twój zespół. Używaj SDK, gdy jesteś samotnym deweloperem piszącym skrypt. Używaj proxy, gdy potrzebujesz współdzielonej kontroli dostępu, śledzenia kosztów i limitowania przepustowości w zespole.

Czy mogę używać proxy LiteLLM z Ollama i modelami lokalnymi?

Absolutnie. Dodaj wpis do swojego config.yaml z model: ollama/llama3.1 i api_base: http://host.docker.internal:11434 (lub hostem Twojej Ollamy). Twój zespół może wtedy uzyskiwać dostęp do modeli lokalnych przez ten sam endpoint proxy, co jest świetne do developmentu i bezpłatnych testów.

Ile kosztuje proxy LiteLLM?

Proxy LiteLLM jest darmowe i open-source (licencja MIT). Hostujesz je samodzielnie na swojej infrastrukturze. Jedyne koszty to Twój serwer (mały VPS wystarczy dla większości zespołów) oraz koszty API LLM, które już płacisz. BerriAI oferuje również zarządzaną wersję chmurową, jeśli nie chcesz hostować samodzielnie.

Jakich dostawców obsługuje LiteLLM?

Ponad 100, w tym OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Google Vertex AI, Ollama, Hugging Face, Cohere, Replicate i wielu innych. Pełna lista znajduje się w repozytorium GitHub LiteLLM.

Jak bezpiecznie zaktualizować proxy LiteLLM?

Zawsze przypinaj konkretną wersję w tagu obrazu Docker (np. ghcr.io/berriai/litellm:v1.83.2-stable). Przed aktualizacją sprawdź changelog pod kątem zmian łamiących kompatybilność. Nigdy nie używaj latest w środowisku produkcyjnym. I zawsze weryfikuj, czy nowa wersja nie znajduje się na liście ostrzeżeń bezpieczeństwa – incydent z marca 2026 r. udowodnił, że nawet zaufane pakiety mogą zostać skompromitowane.

Końcowy werdykt i kolejne kroki

Jeśli Twój zespół wydaje pieniądze na API LLM i jeszcze nie masz proxy, zacznij dzisiaj od Docker Compose + Postgres. Konfiguracja zajmie 15 minut, a na koniec będziesz mieć widoczność kosztów i kontrolę dostępu.

Gdy już będziesz działać, sprawdź dodawanie guardrails do swojego pipeline'u LLM w celu filtrowania treści i sprawdzania bezpieczeństwa. Proxy jest fundamentem, wszystko inne buduje się na nim.

Źródła

• Szybki start LiteLLM Proxy, Oficjalna dokumentacja
• Przewodnik po wdrożeniu LiteLLM w Dockerze
• Dokumentacja wirtualnych kluczy LiteLLM
• Najlepsze praktyki produkcyjne LiteLLM
• Aktualizacja bezpieczeństwa LiteLLM, marzec 2026
• BerriAI/litellm, Repozytorium GitHub