LiteLLM: çok kullanıcılı LLM kapısı

Modeliniz çalışıyor, hatta iki kopyası var. Sıra onu bir ekibe açmaya geldi: herkesin kendi anahtarı olsun, kimse tek başına makineyi doldurmasın, kimin ne kadar token harcadığı görünsün. Bu sayfa o kapıyı LiteLLM ile kuruyor — ve kurmanın bedelini de ölçüyor.

Önce beklentiyi doğru kuralım

LiteLLM'i "daha iyi bir yük dengeleyici" diye almayın. Aynı donanım, aynı iki kopya, aynı kıyaslama (200 istem, 512 girdi / 256 çıktı):

Doğru boyutlandırılmış LiteLLM, HAProxy'nin %90'ına çıkıyor ama TTFT'de arayı kapatmıyor.

Buna rağmen doğru araç olabilir, çünkü HAProxy'nin yapamadığı şeyleri yapar: kullanıcı başına sanal anahtar, token/dakika ve istek/dakika tavanı, bütçe, harcama kaydı, model erişim kısıtı, yeniden deneme ve yedekleme. HAProxy token'ı görmez bile. Seçim "hangisi daha hızlı" değil, "veri yolunda mı yoksa denetim düzleminde mi duruyorum" sorusudur.

Yığın

istemci -- sk-... sanal anahtar --> LiteLLM (N işçi) --least-busy--> vLLM r1
                                       |                            vLLM r2
                            Postgres (anahtar / bütçe / harcama)
                            Redis (işçiler arası sayaç)

Postgres olmadan sanal anahtar, bütçe ve harcama kaydı çalışmaz — geriye yalnızca yönlendirme ve model başına tavan kalır, yani LiteLLM'e geçme sebebinin çoğu kaybolur. Redis olmadan ise her işçi kendi sayacını tutar ve tavanlarınız işçi sayısıyla çarpılır.

sh -lc "apk add --no-cache libatomic >/dev/null 2>&1; \
  cd /app && prisma db push --schema=./schema.prisma --accept-data-loss --skip-generate; \
  exec litellm --config /app/proxy_server_config.yaml --port 4000 --num_workers 4"

model_list:
  - model_name: kaptan-llm
    litellm_params:
      model: hosted_vllm/Qwen/Qwen3.8-27B-FP8
      api_base: http://qwen-r1-svc:8000/v1
      api_key: none
      # 4 işçi x 4 = kopya başına 16 eşzamanlı istek. Sınırsız bıraktığımızda
      # 32K bağlamda TTFT 4,2 saniyeden 37,5 saniyeye çıkmıştı.
      max_parallel_requests: 4
  - model_name: kaptan-llm
    litellm_params:
      model: hosted_vllm/Qwen/Qwen3.8-27B-FP8
      api_base: http://qwen-r2-svc:8000/v1
      api_key: none
      max_parallel_requests: 4

  # Aynı iki kopya, bu kez sabit adlarla — ön ek yakınlığı isteyen istemci için.
  - model_name: kaptan-llm-r1
    litellm_params:
      model: hosted_vllm/Qwen/Qwen3.8-27B-FP8
      api_base: http://qwen-r1-svc:8000/v1
      api_key: none
      max_parallel_requests: 4
  - model_name: kaptan-llm-r2
    litellm_params:
      model: hosted_vllm/Qwen/Qwen3.8-27B-FP8
      api_base: http://qwen-r2-svc:8000/v1
      api_key: none
      max_parallel_requests: 4

router_settings:
  # least-busy, shuffle değil. LLM istekleri çok eşitsizdir: 32K'lık bir istem
  # 512'liğin ~64 katı prefill demektir, yani "kimin sırası" değil "kim boş" önemli.
  routing_strategy: least-busy
  num_retries: 2
  # 32K bağlamda tek bir istek yük altında 76 saniye sürdü.
  timeout: 600
  # Ağırlıklarını yükleyen bir kopya ~7 dakika sürüyor; havuzdan düşsün.
  allowed_fails: 3
  cooldown_time: 60
  # Bu olmadan her işçi kendi sayacını tutar ve tavanlarınız çarpılır.
  redis_host: llm-redis-svc
  redis_port: 6379

litellm_settings:
  drop_params: true
  request_timeout: 600
  json_logs: true

general_settings:
  master_key: sk-BURAYA-KENDI-ANAHTARINIZ
  background_health_checks: true
  health_check_interval: 30

curl -s localhost:4000/key/generate \
  -H "Authorization: Bearer $MASTER_KEY" -H 'Content-Type: application/json' \
  -d '{"key_alias":"musteri-alfa",
       "models":["kaptan-llm"],
       "max_budget":5.0, "budget_duration":"30d",
       "tpm_limit":20000, "rpm_limit":60}'

key/generate: 200
key/info:     {'key_alias': 'musteri-alfa', 'spend': 0.0, 'max_budget': 5.0,
               'tpm_limit': 20000, 'rpm_limit': 60, 'models': ['kaptan-llm']}
izin verilmeyen modele istek:  403  "key not allowed to access model"

curl -s localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $VIRTUAL_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"kaptan-llm",
       "messages":[{"role":"user","content":"Merhaba"}],
       "max_tokens":64,
       "chat_template_kwargs":{"enable_thinking":false}}'

x-litellm-model-api-base       = http://qwen-r1-svc:8000/v1
x-litellm-overhead-duration-ms = 2.159
x-litellm-attempted-retries    = 0

Kurulumdaki üç tuzak

Yukarıdaki uzun command satırı bunları kapatmak için. Üçü de canlıda yaşandı.

1. libatomic eksik → veritabanı hiç kurulmuyor. LiteLLM, Prisma CLI'ını çalışma anında npm ile indirir; imajdaki node ikilisi libatomic.so.1: cannot open shared object file diyip düşer. Sonuç sessizdir: kapı açılır, /health/readiness db: connected der, ama tablo yoktur ve ilk anahtar denemesi şunu verir:

The table `public.LiteLLM_VerificationToken` does not exist in the current database.

Çare apk add --no-cache libatomic.

2. Şema dosyası var, migration yok. İmaj schema.prisma taşır ama prisma/migrations klasörü boştur, yani migrate deploy "No migration found" deyip hiçbir şey yapmaz. Doğru komut prisma db push — ve idempotenttir, her açılışta güvenle çalışır.

3. DISABLE_SCHEMA_UPDATE=true vermezseniz kapı hiç açılmaz. libatomic düzeldikten sonra LiteLLM kendi prisma migrate deploy adımını gerçekten çalıştırmaya başlar ve sonsuz döngüye girer. Belirtisi log değil, süreç tablosudur — her ~10 saniyede bir yeni asılı süreç:

    1  7:37  litellm ... --num_workers 4
  177  4:07  schema-engine-d
  229  3:58  node-MainThread
  291  3:48  node-MainThread
  345  3:38  node-MainThread     <- her 10 saniyede bir yenisi

Şemayı zaten kendimiz kurduğumuz için onun migration'ına ihtiyaç yok.

Aynı kullanıcı hep aynı kopyaya gitsin mi

least-busy bir sohbeti turdan tura farklı kopyaya atabilir, bu da ön ek önbelleğini böler. Ölçtük: 8 eşzamanlı kullanıcı, 4'er tur, ~3.100 tokenlık ortak ön ek, ikisi de kapıdan geçerek, birbirinin aynı iki kopya (fp8 + --prefix-match-unit 16), tek fark yönlendirme.

Sabitleme ~4 puan isabet ve ~%20 gecikme kazandırıyor. Dikkat çeken asıl fark tekrarlanabilirlik: sabit yönlendirme iki koşuda da tam olarak 100.480 isabet üretti, least-busy her koşuda başka sayı verdi.

Bir adım ötesi: vLLM production-stack router

Yukarıdaki "sabit model adı" yöntemi, piyasanın önbellek-farkında yönlendirici dediği şeyin elle kurulmuş hâli. Gerçeği de Gao Kaptan'da pod olarak çalışıyor — denendi.

• İmaj: lmcache/lmstack-router:latest
• Kaynak: 2 vCPU / 4 GB yeter
• Komut:

/opt/venv/bin/vllm-router --host 0.0.0.0 --port 8000 \
  --service-discovery static \
  --static-backends "http://qwen-r1-svc.NAMESPACE.svc.cluster.local:8000,http://qwen-r2-svc.NAMESPACE.svc.cluster.local:8000" \
  --static-models "Qwen/Qwen3.8-27B-FP8,Qwen/Qwen3.8-27B-FP8" \
  --routing-logic session --session-key x-user-id \
  --engine-stats-interval 10 --log-stats

Sonuç — dört müşteri, üçer istek, yalnızca x-user-id başlığı farklı:

musteri-A: r1r1r1   SABIT
musteri-B: r2r2r2   SABIT
musteri-C: r1r1r1   SABIT
musteri-D: r1r1r1   SABIT      sabit kalan: 4/4

Kullanıcıyı kopyaya kilitlemek için artık ayrı model adı tanımlamanıza gerek yok.

Hangi yönlendirme kipini kullanabilirsiniz

--routing-logic şunları kabul ediyor: roundrobin, session, kvaware, loadaware, prefixaware, disaggregated_prefill, disaggregated_prefill_orchestrated, priority.

Ama hepsi düz bir vLLM pod'uyla çalışmaz:

Zinciri kurmak: LiteLLM → router

Router'ı LiteLLM'in altına koymak için tek bir deployment yeter — fan-out'u artık router yapıyor:

model_list:
  - model_name: kaptan-llm
    litellm_params:
      model: hosted_vllm/Qwen/Qwen3.8-27B-FP8
      api_base: http://llm-router-svc:8000/v1
      api_key: none
      max_parallel_requests: 4

general_settings:
  # Router yakinligi x-user-id basligindan okuyor. Bu acik degilse LiteLLM
  # istemci basliklarini arkaya iletmez ve yakinlik zincirde sessizce kirilir.
  forward_client_headers_to_llm_api: true

Başlığın gerçekten geçtiğini doğrulayın — dört müşteri, üçer istek, zincir üzerinden:

musteri-A: r1r1r1   musteri-B: r2r2r2
musteri-C: r1r1r1   musteri-D: r1r1r1     sabit kalan: 4/4

Dağılım, router'a doğrudan yapılan testle birebir aynı çıktı; yani LiteLLM başlığı bozmadan iletiyor.

Ek atlamanın bedeli (200 istem, 512/256, mc=32, aynı geçit):

Verimin %4,7'si ve kuyruk gecikmesinin iki katı. Ortalama TTFT biraz iyileşiyor ama P99 belirgin şekilde kötüleşiyor.

Nereye koymalı

Router LiteLLM'in yerine değil, altına girer:

musteri --> LiteLLM (anahtar, TPM/RPM, butce, harcama)
                |
            vllm-router (oturum/yuk farkinda yonlendirme)
                |
          vLLM r1 ... rN

LiteLLM kimin ne kadar harcadığını bilir ama LLM'e kördür; router LLM'i bilir ama kimin kim olduğunu bilmez. İkisi farklı işler yapıyor, sıralama bu.

"1000 kullanıcı kaldırır mı?"

Önce soruyu düzeltmek gerekiyor: kayıtlı kullanıcı sayısı bir kapasite birimi değildir. Kapasiteyi belirleyen üç şey var — kaç istek eşzamanlı akıyor, dakikada kaç istek geliyor, ve her istemin kaç tokeni var. Üçüncüsü diğer ikisini eziyor.

32K bağlamda ölçülen tavan

İki 4g.71gb dilimi, iki kopya, kapıdan geçerek (32.768 girdi / 128 çıktı):

Verim 0,39 istek/saniyede doyuyor. Eşzamanlılığı 16 kat artırmak verime %34 ekliyor, gecikmeyi 15 katına çıkarıyor. Doymuş bir kuyrukta sıraya adam eklemek sırayı hızlandırmaz.

Token cinsinden aynı tavan: 96 istek × 32.768 token ÷ 247 saniye = 12.740 girdi tok/sn — iki kopyanın teorik prefill toplamının (2 × 7.700) %83'ü. İki yoldan aynı sayıya varıyoruz.

Buradan kullanıcı sayısına

Sürdürülebilir istek hızı 0,39/sn ise, N kullanıcı ancak N ÷ 0,39 saniyede bir istek gönderirse sistem yetişir:

Yani "1000 kullanıcı" ancak herkes yaklaşık kırk dakikada bir 32K'lık soru soruyorsa kaldırılır — ve o noktada bile cevaplar iki dakika sürer. Aynı sonucu token tarafından da alırsınız: 12.740 tok/sn ÷ 1000 kullanıcı = kullanıcı başına ~760 girdi tokeni/dakika. tpm_limit değerinizi tahminle değil bu sayıyla koyun.

Uzun istem kısa sohbeti boğuyor

Bu, çok kullanıcılı kurulumda tek bir havuz kullanmanın bedelidir. Aynı kısa istem kıyaslaması (512 girdi / 128 çıktı, 8 eşzamanlı), önce tek başına, sonra arkada 32K yükü akarken:

TTFT 13 katına, tam cevap 7 katına çıkıyor. Sekiz uzun bağlam isteği, sohbet eden herkesin deneyimini bozmaya yetiyor — çünkü hepsi aynı prefill kuyruğunda bekliyor.

Doğru yapı ne

Bu sayfadaki yığın şekil olarak doğru — kullanıcı anahtarı, tavan, bütçe ve sınırlı eşzamanlılık çok kullanıcılı bir sistemin olmazsa olmazı. Ama 1000 kullanıcı için üç eksiği var:

1. Havuzları ayrı kopyalara sabitleyin. Tek bir vLLM kopyasında paralellik yoktur: bir zamanlayıcı, bir GPU dilimi. Sürekli gruplama istekleri aynı anda taşır ama aynı anda çalıştırmaz — 32K'lık bir prefill dilimin bütün gücünü ~4,25 saniye meşgul eder. (Parçalı prefill hasarı sınırlar, kapalı olsa çok daha kötü olurdu.)

Ama iki kopya ayrı dilimlerde gerçekten paraleldir. Ölçtük — kısa istem yalnızca r1'de, 32K yükü yalnızca r2'de:

Sıfır bozulma. Aynı havuzda 13 kata çıkan TTFT, ayrı kopyalarda hiç kıpırdamıyor. Yapılandırma tarafında zaten hazır — sabit adları havuz olarak kullanın:

  - model_name: kaptan-chat        # yalnizca r1
    litellm_params: { api_base: http://qwen-r1-svc:8000/v1, ..., max_parallel_requests: 12 }
  - model_name: kaptan-longctx     # yalnizca r2
    litellm_params: { api_base: http://qwen-r2-svc:8000/v1, ..., max_parallel_requests: 2 }

Bedeli, her havuzun donanımın yarısıyla kalması. Ama ölçümde bu bedel beklenenden küçük çıktı: kısa istemde tek kopya 2,74 req/sn verdi, iki kopya 3,03 — yani %10. Çünkü mc=8'de sınır GPU değil, eşzamanlılık tavanıdır. Kısa sohbet trafiği için tek kopya çoğu zaman yeter; asıl kazanç, uzun bağlamın onu artık boğamamasıdır.

2. Tavanları ölçümden türetin. tpm_limit için yukarıdaki 760 tok/dk hesabını kullanın. rpm_limit'i de kullanıcı başına adil paydan verin — 0,39 req/sn × 60 ÷ kullanıcı sayısı.

3. Tek nokta arızalarını kaldırın. Bu sayfadaki kurulumda kapı, Postgres ve Redis'in her biri tek pod. Üretimde kapıyı çoğaltın (Redis sayaçları zaten paylaşıyor) ve Postgres'i yedekleyin.

Hangi yapıyı seçmeli

Sık karşılaşılan hatalar