Samodzielny hosting LiteLLM jako bramka LLM
Uruchom własną bramkę LiteLLM dla wielu dostawców modeli AI. Zarządzaj wirtualnymi kluczami, limitami budżetowymi oraz mechanizmami fallback w jednym punkcie końcowym API.
Czym jest samodzielnie hostowana bramka LLM
LiteLLM to otwartoźródłowa bramka LLM hostowana we własnym zakresie: jeden punkt końcowy HTTP, z którym łączą się wszystkie aplikacje, a który następnie przekazuje każde żądanie do odpowiedniego dostawcy. LLM oznacza duży model językowy (ang. large language model). Bramka obsługuje API (ang. application programming interface) czatu OpenAI, dzięki czemu każda biblioteka kliencka współpracująca z OpenAI zadziała po wprowadzeniu dwóch zmian: adresu bazowego URL oraz klucza.
Ta jedna warstwa pośrednicząca jest kluczowa. Aplikacje przestają przechowywać dane uwierzytelniające dostawców. Zmiana modelu sprowadza się do jednej linii w pliku konfiguracyjnym na serwerze, zamiast modyfikacji kodu w pięciu usługach. Ponieważ każde wywołanie przechodzi przez jeden proces, istnieje centralne miejsce do zarządzania budżetem oraz prowadzenia rejestru wydatków.
Oto co otrzymujesz po uruchomieniu rozwiązania:
- Jeden punkt końcowy. Aplikacje kierują żądania do
https://gateway.example.com/v1i wskazują zdefiniowaną przez Ciebie nazwę modelu, taką jakbulklubstrong. - Wirtualne klucze. Każda aplikacja otrzymuje własny klucz z przypisaną listą dozwolonych modeli oraz limitem wydatków. Możesz unieważnić jeden klucz bez wpływu na pozostałe.
- Mechanizmy awaryjne (fallbacks). Nieudane wywołanie lub zbyt długi prompt są automatycznie ponawiane z użyciem innego modelu.
- Rejestr logów. Każde żądanie zapisuje wiersz z informacją o koszcie, co pozwala jednoznacznie określić, która aplikacja wygenerowała dany wydatek.
Dlaczego warto samodzielnie uruchomić bramę
Zarządzany router ma taką samą formę, lecz w każdym żądaniu pośredniczy proces zewnętrznego dostawcy. Samodzielne uruchomienie usługi pozwala zachować klucze dostawcy oraz tekst promptów na serwerze, nad którym sprawuje się pełną kontrolę. Wiąże się to z realnymi kosztami: użytkownik staje się administratorem komponentu, od którego zależą wszystkie aplikacje. Ostatnia sekcja tego przewodnika poświęcona jest właśnie tym kosztom, ponieważ jest to aspekt pomijany w większości opracowań.
Wymagania
- VPS (virtual private server) z systemem Ubuntu 24.04 oraz zainstalowanym Docker i wtyczką Compose.
- Nazwa domeny wskazująca na serwer, jeśli maszyny zewnętrzne mają łączyć się z bramą przez TLS (transport layer security).
- Przynajmniej jeden klucz API dostawcy.
Brama nie przeprowadza wnioskowania. Przekazuje żądania i przesyła odpowiedzi, więc obciążenie procesora zależy od liczby żądań, a nie od rozmiaru modelu. Serwer z 1 vCPU bez problemu obsłuży kilka wewnętrznych aplikacji. Zasobem, który rośnie, jest baza danych, ponieważ brama zapisuje wiersz z informacją o koszcie dla każdego żądania.
Najpierw utwórz plik config.yaml
Plik konfiguracyjny określa, o jakie modele może pytać klient. Istotne są cztery sekcje najwyższego poziomu: model_list, litellm_settings, router_settings oraz general_settings.
model_list:
- model_name: bulk
litellm_params:
model: anthropic/claude-haiku-4-5
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: strong
litellm_params:
model: anthropic/claude-sonnet-5
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: strong
litellm_params:
model: openai/gpt-5.5
api_key: os.environ/OPENAI_API_KEY
litellm_settings:
num_retries: 2
request_timeout: 120
json_logs: true
set_verbose: false
router_settings:
allowed_fails: 3
cooldown_time: 30
fallbacks: [{"bulk": ["strong"]}]
context_window_fallbacks: [{"bulk": ["strong"]}]
general_settings:
background_health_checks: true
health_check_interval: 300model_name to nazwa wysyłana przez klientów. litellm_params.model to rzeczywisty model, zapisany jako provider/model. Modele należy nazywać według ich przeznaczenia, a nie dostawcy. Aplikacja żądająca bulk będzie działać poprawnie, nawet jeśli w przyszłym miesiącu decyzja o zmianie bulk na inny model zostanie wdrożona.
api_key: os.environ/ANTHROPIC_API_KEY instruuje LiteLLM, aby odczytał tę zmienną w czasie wykonywania. Klucz w postaci jawnej nigdy nie pojawia się w pliku, co jest istotne, ponieważ config.yaml jest plikiem przeznaczonym do commitowania.
Dwa wpisy współdzielą nazwę strong celowo. Gdy więcej niż jedno wdrożenie posiada tę samą wartość model_name, router traktuje je jako zamienne i rozdziela żądania dla tej nazwy pomiędzy nie. W ten sposób strong zachowuje ciągłość działania, gdy jeden z dostawców przechodzi awarię: gdy wdrożenie trafi do stanu cooldown (opisany poniżej), nowe żądania dla strong są kierowane do drugiego wdrożenia.
num_retries: 2 ponawia próbę wykonania żądania w przypadku wystąpienia błędu kwalifikującego się do ponowienia maksymalnie dwa razy. Te ponowne próby mogą wybrać inne dostępne wdrożenie w tej samej grupie modeli: dokumentacja architektury LiteLLM, sprawdzona w dniu 2026-10-29, opisuje ponowne próby w obrębie grupy oraz mechanizmy fallback między grupami jako odrębne kroki. Ponowna próba dla strong może zatem trafić do innego dostawcy bez konieczności włączania mechanizmu weighted failover. Mechanizm fallback uruchamia się dopiero po wyczerpaniu liczby ponownych prób.
allowed_fails oraz cooldown_time to opcje routera, dlatego znajdują się w sekcji router_settings. Proxy buduje swój router na podstawie tej sekcji, a w wersji v1.95.0 parametr cooldown_time zapisany w litellm_settings nie jest uwzględniany, przez co czas cooldownu pozostaje na domyślnym poziomie 5 sekund. cooldown_time: 30 określa, jak długo wdrożenie pozostaje wyłączone z rotacji po przejściu w stan cooldown. Dokumentacja konfiguracji opisuje allowed_fails jako liczbę błędów, którą wdrożenie musi przekroczyć w czasie cooldown_time, aby zostało wyłączone z rotacji. W kodzie źródłowym v1.95.0 wartość allowed_fails: 3 jest domyślna; przy ustawieniach domyślnych router korzysta z wbudowanych wyzwalaczy. Liczba błędów staje się aktywnym parametrem dopiero po zdefiniowaniu innej wartości. Wyzwalacze te obejmują natychmiastowy cooldown po otrzymaniu odpowiedzi 429 dla grupy z więcej niż jednym wdrożeniem, przekroczenie 50% błędów w bieżącej minucie po wykonaniu co najmniej 5 żądań dla takiej grupy oraz błędy, których router nie ponawia, takie jak 401 wynikający z błędnego klucza. Osobny wyzwalacz wyłącza pojedyncze wdrożenie, gdy wszystkie żądania w bieżącej minucie kończą się niepowodzeniem, a ruch osiągnie SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD, co domyślnie wynosi 1000 żądań. Zatem dla strong, posiadającego dwa wdrożenia, dostawca zwracający serię błędów 500 przestaje być wybierany przy każdym kolejnym żądaniu, podczas gdy pojedynczy błąd 500 co kilka minut nie uruchamia cooldownu. bulk posiada tylko jedno wdrożenie, więc wyzwalacz oparty na wskaźniku błędów nie ma tu zastosowania: seria błędów 500, która nie przekracza 1000 żądań na minutę, nie powoduje wyłączenia z rotacji, a ochronę dla klientów stanowi num_retries, po którym następuje fallback do strong.
fallbacks oraz context_window_fallbacks posiadają różne wyzwalacze, przy czym ten drugi jest przydatny, choć często pomijany.
fallbacksuruchamia się, gdy główne wywołanie kończy się niepowodzeniem.context_window_fallbacksuruchamia się, gdy dostawca odrzuca żądanie z powodu przekroczenia okna kontekstowego modelu, dzięki czemu zbyt długi prompt trafia do modelu o większej pojemności zamiast zwracać błąd do klienta.
Dostępny jest również content_policy_fallbacks, przeznaczony dla sytuacji, gdy dostawca odmawia realizacji żądania ze względu na politykę treści. Należy go skonfigurować tylko wtedy, gdy istnieje odpowiednie miejsce do przekierowania takich wywołań.
Wdrożenie LiteLLM na VPS przy użyciu Docker Compose
Utwórz katalog zawierający trzy pliki: config.yaml, docker-compose.yml oraz .env. Szybki start w dokumentacji pobiera tag latest. Przypnij konkretny tag wydania, aby aktualizacja następowała tylko po edycji pliku, co umożliwia szybki powrót do poprzedniej wersji jedną linią kodu. Sam tag nie gwarantuje identycznej zawartości, ponieważ tagi obrazów są zmienne i wydawca może wskazać nim nowy obraz. Jeśli docker compose up -d w przyszłym miesiącu ma dostarczyć dokładnie tę samą bramę, co dzisiaj, dołącz również skrót (digest) obrazu w formacie ghcr.io/berriai/litellm:v1.95.0@sha256:<digest>; polecenie docker buildx imagetools inspect ghcr.io/berriai/litellm:v1.95.0 wyświetla go.
services:
litellm:
image: ghcr.io/berriai/litellm:v1.95.0
restart: unless-stopped
command: ["--config", "/app/config.yaml", "--num_workers", "1"]
ports:
- "127.0.0.1:4000:4000"
volumes:
- ./config.yaml:/app/config.yaml:ro
env_file: .env
depends_on:
db:
condition: service_healthy
db:
image: postgres:16
restart: unless-stopped
environment:
POSTGRES_USER: litellm
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
POSTGRES_DB: litellm
healthcheck:
test: ["CMD-SHELL", "pg_isready -U litellm"]
interval: 5s
timeout: 5s
retries: 10
volumes:
- postgres_data:/var/lib/postgresql/data
volumes:
postgres_data:Compose odczytuje .env w tym przypadku dwukrotnie. Raz w celu podstawienia ${POSTGRES_PASSWORD} wewnątrz samego pliku compose, a drugi raz poprzez env_file, aby przekazać każdą zmienną do kontenera.
v1.95.0 było aktualnym wydaniem w sierpniu 2026 roku. Sprawdź stronę wydań projektu i przypnij wersję, która jest aktualna w momencie wdrażania. Każde wydanie publikuje sygnaturę, dzięki czemu można zweryfikować obraz przed jego użyciem:
cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0Linia portu to 127.0.0.1:4000:4000, co publikuje port wyłącznie na interfejsie loopback. Zapisz 4000:4000, a brama będzie dostępna z całego Internetu, ponieważ Docker dodaje własne reguły w łańcuchu iptables FORWARD, które są oceniane przed regułami ufw, więc ufw deny 4000 nie blokuje tego ruchu. Jest to najczęstszy sposób, w jaki samodzielnie hostowana brama staje się publicznie dostępna: zobacz jak Docker publikuje port kontenera z pominięciem ufw. Ruch z zewnątrz dociera natomiast przez reverse proxy.
Przechowywanie kluczy dostawców poza obrazem
Plik .env zawiera wszystkie sekrety. Jest on przekazywany jako zmienne środowiskowe w czasie uruchomienia, dzięki czemu nigdy nie jest trwale zapisywany w obrazie ani przesyłany do repozytorium.
LITELLM_MASTER_KEY=sk-REPLACE_ME
LITELLM_SALT_KEY=sk-REPLACE_ME_TOO
POSTGRES_PASSWORD=REPLACE_ME_AS_WELL
DATABASE_URL=postgresql://litellm:REPLACE_ME_AS_WELL@db:5432/litellm
STORE_MODEL_IN_DB=True
LITELLM_MODE=PRODUCTION
LITELLM_LOG=ERROR
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...Wygeneruj dwa klucze LiteLLM przy użyciu losowych wartości, a następnie zabezpiecz plik:
printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .envLITELLM_MASTER_KEY to poświadczenie administratora. Uwierzytelnia ono API zarządzania i stanowi hasło do interfejsu Admin UI pod adresem /ui. Żadna aplikacja nie powinna go przechowywać.
LITELLM_SALT_KEY szyfruje poświadczenia dostawców przechowywane w bazie danych. Ustaw tę wartość raz i nie zmieniaj jej. Późniejsza zmiana spowoduje, że zapisane poświadczenia staną się niemożliwe do odszyfrowania, co sprawi, że bramka uruchomi się poprawnie, ale każde wywołanie dostawcy zakończy się błędem uwierzytelnienia.
STORE_MODEL_IN_DB=True umożliwia dodawanie i edycję modeli z poziomu interfejsu Admin UI bez modyfikowania pliku config.yaml. Jest to wygodne, ale dzieli źródło prawdy na dwie części. Zdecyduj, które z nich jest nadrzędne i zapisz tę decyzję obok konfiguracji.
Logika, która nakazuje trzymać klucze poza plikiem konfiguracyjnym, jest taka sama, jak w przypadku narzędzi przekazywanych agentowi. Przechowywanie sekretów dostawców poza agentami AI omawia ten wzorzec, a pliki env i sekrety w Docker Compose wyjaśnia kwestie techniczne.
Uruchom usługę i monitoruj pierwsze uruchomienie:
docker compose up -d
docker compose logs -f litellmWeryfikacja poprawności działania
Istnieją dwie sondy niewymagające uwierzytelnienia oraz jedna wymagająca uwierzytelnienia; każda z nich kończy się niepowodzeniem z innego powodu.
curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readiness/health/liveliness nie wymaga uwierzytelnienia i odpowiada "I'm alive!", gdy proces jest uruchomiony. /health/readiness również nie wymaga uwierzytelnienia. Zwraca obiekt JSON z polami "status": "healthy" oraz db lub kod 503, gdy baza danych jest nieosiągalna. Należy skierować monitoring na readiness, ponieważ liveliness pozostaje zielony w bramie, która nie jest w stanie odnaleźć pojedynczego klucza wirtualnego.
Uwierzytelniona kontrola to ta, która komunikuje się z dostawcami:
curl -s http://127.0.0.1:4000/health \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"Odpowiada ona tablicami healthy_endpoints oraz unhealthy_endpoints. Model znajdujący się w unhealthy_endpoints z błędem uwierzytelnienia oznacza, że klucz dostawcy w .env jest błędny lub go brakuje; jest to awaria, którą należy teraz zidentyfikować. Ponieważ background_health_checks: true jest ustawione, proxy wykonuje te sondy samodzielnie co health_check_interval sekund, a /health zwraca ostatni wynik, więc odpytywanie go nie wysyła za każdym razem żądania testowego do dostawców.
Wirtualne klucze i budżety dla poszczególnych kluczy
Każda aplikacja otrzymuje własny klucz, wygenerowany na podstawie klucza głównego.
curl -s http://127.0.0.1:4000/key/generate \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H 'Content-Type: application/json' \
-d '{
"key_alias": "nightly-summariser",
"models": ["bulk"],
"max_budget": 5,
"budget_duration": "30d",
"rpm_limit": 60,
"tpm_limit": 200000
}'Odpowiedź zawiera pole key rozpoczynające się od sk-. Ten ciąg znaków jest jedynym elementem, który otrzymuje aplikacja.
modelsto lista dozwolonych operacji, które może wykonać dany klucz. Powyższy klucz może żądać jedyniebulki niczego więcej.max_budget: 5z wartościąbudget_duration: "30d"oznacza limit pięciu dolarów amerykańskich na miesiąc kalendarzowy. LiteLLM resetuje budżet30dpierwszego dnia każdego miesiąca o północy czasu UTC (chyba że ustawionotimezonew sekcjilitellm_settings), zamiast stosować okres kroczący 30 dni. Po wydaniu pięciu dolarów klucz przestaje działać do pierwszego dnia kolejnego miesiąca.rpm_limitoraztpm_limitograniczają liczbę żądań na minutę oraz liczbę tokenów na minutę wyłącznie dla tego klucza.key_aliasto identyfikator widoczny w dzienniku wydatków po sześciu tygodniach. Należy go zawsze ustawiać.
Po wyczerpaniu budżetu wywołanie kończy się błędem typu budget_exceeded z komunikatem o następującej strukturze:
Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>Kod statusu zależy od wersji oprogramowania. W przypiętej wersji v1.95.0 jest to HTTP 429. Od wersji v1.104.0 domyślnym kodem jest HTTP 422, a ustawienie budget_exceeded_status_code: 429 w sekcji litellm_settings przywraca poprzedni kod. Rzeczywiste przekroczenia rpm_limit oraz tpm_limit nadal zwracają kod 429 w obu wersjach. Należy weryfikować otrzymywany kod po każdej aktualizacji.
Kod statusu bywa mylący, ponieważ żaden z nich nie oznacza bezpośrednio "wyczerpania budżetu". Biblioteka kliencka interpretuje kod 429 jako limit szybkości (rate limit) i może ponawiać żądania z opóźnieniem (backoff) w stosunku do budżetu, który nie zostanie odnowiony przed resetem. Kod 422 jest interpretowany jako żądanie, którego nie można przetworzyć. Należy logować treść odpowiedzi obok kodu statusu, w przeciwnym razie wyczerpanie budżetu będzie za każdym razem wyglądać jak inny problem.
Klucze można sprawdzać i modyfikować za pomocą tego samego API zarządzania:
curl -s "http://127.0.0.1:4000/key/info?key=sk-..." \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"
curl -s -X POST http://127.0.0.1:4000/key/update \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H 'Content-Type: application/json' \
-d '{"key": "sk-...", "max_budget": 25}'Budżet wymuszany na poziomie bramy (gateway) działa nawet w przypadku awarii samego agenta, dlatego stanowi on podstawę kontroli kosztów agentów AI na serwerze VPS.
Przekierowanie zadań masowych do taniego modelu
Skieruj klienta na adres bramy. Wymagane dane to Base URL, klucz oraz nazwa modelu:
curl -s http://127.0.0.1:4000/v1/chat/completions \
-H "Authorization: Bearer sk-<the virtual key>" \
-H 'Content-Type: application/json' \
-d '{
"model": "bulk",
"messages": [{"role": "user", "content": "Say hello in five words."}]
}'Każda biblioteka kliencka zgodna z OpenAI działa w ten sam sposób, choć nazwy opcji różnią się w zależności od języka. W kliencie Python ustaw base_url na https://gateway.example.com/v1, a api_key na klucz wirtualny. W klientach JavaScript i TypeScript te same dwie opcje nazywają się baseURL oraz apiKey.
Polityka routingu zdefiniowana w config.yaml jest teraz stosowana bez wiedzy klienta. Żądanie skierowane do bulk trafia do taniego modelu. Jeśli wywołanie to zakończy się niepowodzeniem po wykonaniu prób ponowienia, żądanie zostanie ponowione względem strong. Jeśli prompt jest zbyt długi dla bulk, context_window_fallbacks prześle go do strong zamiast zwracać błąd. Zadania masowe, takie jak klasyfikacja czy podsumowywanie zaległości, są domyślnie przetwarzane tanio, a wyższy koszt generują tylko trudne zapytania.
To również moment, w którym brama zyskuje na znaczeniu w pracy agentów korzystających z narzędzi. Serwer MCP (model context protocol) na tym samym VPS oraz sterujący nim agent mogą wskazywać na ten sam punkt końcowy, dzięki czemu model stojący za nimi można zmienić bez konieczności ponownego wdrażania któregokolwiek z tych komponentów.
Jak rozpoznać, że nastąpiło przełączenie na tryb awaryjny (fallback)?
Jest to tryb awarii generujący koszty, ponieważ z zewnątrz wszystko wygląda na sprawne. Udany fallback zwraca kod HTTP 200 wraz ze standardową treścią odpowiedzi. Tani model może być niedostępny przez cały dzień, podczas gdy każde wywołanie jest cicho obsługiwane przez model droższy, a pierwszym dowodem na ten stan rzeczy jest faktura.
Dowody znajdują się w nagłówkach odpowiedzi. Należy je sprawdzić:
curl -s -D - -o /dev/null http://127.0.0.1:4000/v1/chat/completions \
-H "Authorization: Bearer sk-<the virtual key>" \
-H 'Content-Type: application/json' \
-d '{"model":"bulk","messages":[{"role":"user","content":"ping"}]}' \
| grep -i '^x-litellm'x-litellm-model-groupto nazwa modelu, do którego skierowano żądanie, na przykładbulk.x-litellm-model-idto identyfikator wdrożenia, które udzieliło odpowiedzi; można go sprawdzić za pomocą/v1/model/info?litellm_model_id=.... Jeśli ten identyfikator nie należy do Twoich wdrożeńbulk, oznacza to, że nastąpił fallback.x-litellm-attempted-fallbacksorazx-litellm-attempted-retrieszliczają takie zdarzenia. W przypadku poprawnego wywołania żadna z tych wartości nie przekracza 0.x-litellm-response-costto koszt pojedynczego wywołania w dolarach amerykańskich.x-litellm-call-idto identyfikator, którego używasz do odnalezienia tego samego wywołania w logach.
Rejestruj x-litellm-attempted-fallbacks przy każdym żądaniu i ustaw alert na każdą wartość powyżej 0. Ta jedna liczba stanowi różnicę między działającą polityką routingu a polityką, która po cichu zmieniła się w „zawsze używaj drogiego modelu”.
Pełną wersją tego rozwiązania jest tracing, który wymaga osobnej konfiguracji: samodzielnie hostowany Langfuse do śledzenia wywołań agenta. LiteLLM dostarcza gotowy callback, więc jego podłączenie to dwie linie kodu oraz dane uwierzytelniające.
litellm_settings:
success_callback: ["langfuse"]
failure_callback: ["langfuse"]LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.comDla Langfuse w wersji 3 i nowszych, strona Langfuse w dokumentacji LiteLLM zaleca użycie presetu langfuse_otel; wspomniany wyżej callback langfuse jest nadal udokumentowany. Ustaw failure_callback oraz success_callback. Jeśli tego nie zrobisz, zachowasz ślady tylko dla tych wywołań, w których nic nie poszło nie tak. Niezależnie od tego, LiteLLM zapisuje wiersz z informacją o wydatkach dla każdego żądania w bazie Postgres, a interfejs Admin UI pod adresem /ui odczytuje tę tabelę. Rośnie ona wraz z ruchem, więc monitoruj jej rozmiar na małym dysku.
Umieszczenie bramy za reverse proxy
Żaden ruch z zewnątrz nie powinien docierać do portu 4000. Należy zakończyć TLS w nginx lub Caddy i przekierować ruch na adres loopback.
location / {
proxy_pass http://127.0.0.1:4000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_read_timeout 600s;
}Dwie z tych linii są często pomijane przez użytkowników. proxy_buffering off jest istotne, ponieważ strumieniowe generowanie odpowiedzi (streaming completion) to seria zdarzeń typu server-sent events. Przy włączonym buforowaniu nginx gromadzi fragmenty w buforach przed ich przekazaniem, co opóźnia dostarczenie danych do klienta. proxy_read_timeout 600s jest istotne, ponieważ domyślny limit 60 sekund w nginx to maksymalny czas oczekiwania na odczyt danych z bramy, a nie limit czasu trwania całej odpowiedzi. Odpowiedź niestrumieniowana nie wysyła żadnych danych do momentu zakończenia generowania, więc długi proces przekracza 60 sekund bez przesłania ani jednego bajta, co skutkuje błędem 504 u klienta i wpisem upstream timed out (110: Connection timed out) while reading response header from upstream w logu błędów. Strumieniowana odpowiedź, która stale wysyła fragmenty danych, może trwać znacznie dłużej niż 60 sekund; limit czasu zostanie przekroczony tylko wtedy, gdy model przestanie odpowiadać na tak długi czas.
W przypadku certyfikatu, Certbot z Let's Encrypt na nginx stanowi najkrótszą drogę. Jeśli serwer obsługuje już kilka kontenerów, Traefik przed wieloma aplikacjami Compose pozwala zarządzać routingiem i certyfikatami w jednym miejscu.
Brama staje się pojedynczym punktem awarii
Należy zachować realizm w ocenie zbudowanego rozwiązania. Każda posiadana aplikacja zależy teraz od jednego kontenera na jednym VPS. Gdy jest on niedostępny, żadna usługa nie może wywołać modelu, nawet jeśli dostawcy działają poprawnie. Wynikają z tego cztery kwestie.
- Błędna konfiguracja wyłącza wszystko jednocześnie.
restart: unless-stoppedrestartuje proces po awarii, co powoduje ciągłe restartowanie kontenera, który nie może przetworzyć pliku config.yaml. Po każdej zmianie konfiguracji należy wykonaćdocker compose logs litellm, a zmiany wprowadzać w czasie, gdy można monitorować ich skutki. - Postgres znajduje się na ścieżce żądania w przypadku chybienia pamięci podręcznej. Wyszukiwanie klucza wirtualnego korzysta z bazy, gdy klucz nie jest w pamięci podręcznej; zapisywanie wydatków odbywa się asynchronicznie po wysłaniu odpowiedzi.
/health/readinesszwracające 503 to ostrzeżenie, że brama działa, ale nie może wykonać żadnej z tych operacji. - Najpierw wykorzystaj rdzenie, potem dodawaj instancje. Zalecenie produkcyjne projektu dotyczące jednego procesu roboczego na instancję (
--num_workers 1) dotyczy Kubernetes lub innego autoskalera podów, który dodaje instancje automatycznie. W przypadku pojedynczej maszyny wirtualnej lub kontenera, zalecenie jest odwrotne: ustaw liczbę procesów roboczych zgodnie z liczbą vCPU maszyny. Na wspomnianej wcześniej maszynie z 1 vCPU jest to nadal--num_workers 1; na większej maszynie zwiększ tę wartość, pamiętając, że każdy proces roboczy zużywa własną pamięć. Druga brama za load balancerem eliminuje pojedynczy kontener jako punkt awarii, ale nie eliminuje bazy danych. - Twórz kopie zapasowe tego, czego nie można odtworzyć. Dotyczy to
config.yamloraz.env, wraz zpg_dumpbazy danych. UtrataLITELLM_SALT_KEYsprawia, że zaszyfrowane poświadczenia dostawców wewnątrz zrzutu stają się bezużyteczne, dlatego plik env oraz zrzut bazy powinny być objęte tym samym zadaniem kopii zapasowej: kopie zapasowe restic do pamięci zewnętrznej.
Aktualizacja polega na edycji tagu obrazu i uruchomieniu docker compose up -d. LiteLLM domyślnie wykonuje prisma migrate deploy przy starcie, więc nowy kontener migruje schemat bazy danych podczas pierwszego uruchomienia. Przed zmianą tagu należy wykonać zrzut bazy, ponieważ przywrócenie starego obrazu nie cofa migracji, która została już wykonana.
Należy zapoznać się z informacjami o wydaniu dla każdej pominiętej wersji, a nie tylko dla wersji docelowej. Przejście z v1.95.0 do v1.104.0 lub nowszej wiąże się z kilkoma zmianami powodującymi niekompatybilność: wspomniany wyżej kod stanu budżetu, proxy odmawiające startu z nieustawionym, pustym lub publicznie znanym kluczem głównym (master key) oraz proxy kończące działanie, gdy konfiguracja bazy danych nie powiedzie się przy starcie, co w ramach restart: unless-stopped objawia się pętlą restartów. W przypadku przejścia z wersji v1.102.x lub starszych, informacje o wydaniu v1.104.0 wymagają również samodzielnego utworzenia dwóch indeksów LiteLLM_SpendLogs.
FAQ
Czy LiteLLM wprowadza zauważalne opóźnienia w każdym wywołaniu?
Projekt deklaruje opóźnienie na poziomie 8 ms dla 95. percentyla przy 1000 żądań na sekundę, zgodnie z informacjami w pliku README z listopada 2026 roku. Należy traktować to jako wartość dostarczoną przez producenta. Wartością, która faktycznie wpływa na opóźnienie, jest odległość sieciowa między aplikacjami a bramą, ponieważ każde wywołanie wymaga wykonania dodatkowego pełnego cyklu komunikacji (round trip). Bramę należy uruchomić w tym samym regionie, w którym znajdują się aplikacje korzystające z niej, a następnie zmierzyć narzut własny za pomocą nagłówka x-litellm-overhead-duration-ms w rzeczywistej odpowiedzi.
Dlaczego strumieniowanie przestało działać po umieszczeniu nginx przed usługą?
Ponieważ nginx domyślnie buforuje odpowiedzi z backendu, a kompletowanie strumienia jest serią zdarzeń typu server-sent events. Przy włączonym proxy_buffering, nginx gromadzi fragmenty w buforach przed ich przekazaniem, co opóźnia dostarczenie danych do klienta. Należy ustawić proxy_buffering off; w bloku location. W tym samym bloku należy również zwiększyć proxy_read_timeout. Domyślnie nginx przerywa połączenie po 60 sekundach braku danych z bramy, co w przypadku długich generacji bez strumieniowania jest łatwe do osiągnięcia, skutkując błędem 504 u klienta.
Co się dzieje, gdy wirtualny klucz wyczerpie budżet?
Wywołanie kończy się błędem typu budget_exceeded oraz komunikatem w formacie Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>. W wersji v1.95.0 status to HTTP 429; od wersji v1.104.0 domyślnie zwracane jest HTTP 422. Żaden z tych kodów nie informuje wprost o wyczerpaniu budżetu, co stanowi pułapkę: biblioteki klienckie interpretują 429 jako limit szybkości (rate limit) i mogą ponawiać próbę, przez co użytkownicy szukają przyczyn w ograniczaniu przepustowości zamiast analizować treść komunikatu. Należy logować treść odpowiedzi wraz z kodem statusu. Należy zweryfikować rzeczywisty stan klucza za pomocą /key/info?key=sk-... względem klucza głównego i zwiększyć limit za pomocą /key/update, jeśli budżet został ustawiony zbyt nisko.
Czy brama może kierować ruch zarówno do modelu lokalnego, jak i hostowanego?
Tak, jest to kolejny wpis w model_list. Należy użyć prefiksu ollama_chat/ wraz z api_base, na przykład model: ollama_chat/llama3.1 obok api_base: http://ollama:11434. W domyślnej konfiguracji sieciowej Docker Compose, localhost wewnątrz kontenera oznacza ten sam kontener, dlatego należy używać nazwy usługi Compose lub adresu hosta w sieci Docker, nigdy 127.0.0.1. Wyjątkiem jest tryb host networking, w którym kontener współdzieli stos sieciowy hosta. Uruchomienie modelu lokalnego jest osobnym zadaniem: zobacz samodzielne hostowanie LLM za pomocą Ollama na VPS.