تحریر: Matt Connor 2026-08-05 · اپ ڈیٹ شدہ 2026-08-13

LiteLLM کو اپنا LLM gateway کیسے بنائیں

Q: جب virtual key کا budget ختم ہو جائے تو کیا ہوتا ہے؟

کال HTTP 401 کے ساتھ ناکام ہو جاتی ہے اور body کی شکل ExceededBudget: Current spend for token: 7.2e-05; Max Budget for Token: 2e-07 جیسی ہوتی ہے۔ 401 یہاں گمراہ کن ہے: client library اسے authentication failure کے طور پر report کرتی ہے، اس لیے لوگ message پڑھنے کے بجائے یہ جانچنا شروع کر دیتے ہیں کہ key valid ہے یا نہیں۔ Response body کو status code کے ساتھ log کریں۔ Master key کے مقابل key کی اصل position /key/info?key=sk-... سے confirm کریں، اور اگر budget بہت کم set کیا گیا ہو تو /key/update سے ceiling بڑھائیں۔

Q: کیا gateway hosted models کے ساتھ local model کو بھی route کر سکتا ہے؟

ہاں، اور یہ model_list میں ایک مزید entry ہوتی ہے۔ ollama_chat/ prefix کو api_base کے ساتھ استعمال کریں، مثلاً model: ollama_chat/llama3.1 کو api_base: http://ollama:11434 کے ساتھ۔ Container کے اندر localhost سے مراد وہی container ہوتا ہے، اس لیے Compose service name یا Docker network پر host کا address استعمال کریں، 127.0.0.1 کبھی استعمال نہ کریں۔ Local model کو چلانا الگ کام ہے: VPS پر Ollama کے ساتھ LLM کی self-hosting دیکھیں۔

LiteLLM کو VPS پر چلائیں اور تمام providers کے لیے ایک OpenAI-compatible endpoint بنائیں، virtual keys، فی key budget، fallbacks اور pinned images کے ساتھ۔

خود host کردہ LLM gateway کیا کرتا ہے

LiteLLM ایک open source LLM gateway ہے جسے آپ خود host کرتے ہیں۔ یہ ایک HTTP endpoint فراہم کرتا ہے جسے آپ کی تمام applications استعمال کرتی ہیں، اور پھر gateway ہر request کو اس provider کو بھیج دیتا ہے جسے اس کا جواب دینا چاہیے۔ LLM سے مراد large language model ہے۔ یہ gateway OpenAI chat completions API (application programming interface) سے درخواستیں وصول کرتا ہے، اس لیے جو client library پہلے ہی OpenAI سے بات کرتی ہو وہ صرف دو تبدیلیوں کے بعد اس کے ساتھ کام کرتی ہے: base URL اور key تبدیل کریں۔

یہ درمیانی layer ہی اصل مقصد ہے۔ آپ کی applications میں provider credentials محفوظ نہیں رہتے۔ Model تبدیل کرنے کے لیے پانچ services کے code میں تبدیلی کرنے کے بجائے server پر config file میں صرف ایک لائن بدلنی پڑتی ہے۔ چونکہ ہر call ایک ہی process سے گزرتی ہے، اس لیے budget مقرر کرنے اور خرچ کا record رکھنے کے لیے ایک مرکزی جگہ موجود ہوتی ہے۔

چلنے کے بعد آپ کے پاس یہ سہولتیں ہوتی ہیں:

ایک endpoint۔ Applications https://gateway.example.com/v1 کو target کرتی ہیں اور آپ کے مقرر کردہ model name کی درخواست کرتی ہیں، مثلاً bulk یا strong۔
Virtual keys۔ ہر application کو اپنی key ملتی ہے، جس کے ساتھ اس کی اپنی model allowlist اور spend ceiling ہوتی ہے۔ ایک key کو دوسری keys کو متاثر کیے بغیر revoke کیا جا سکتا ہے۔
Fallbacks۔ اگر call ناکام ہو جائے یا prompt بہت بڑا ہو، تو request خودکار طور پر کسی مختلف model کو دوبارہ بھیجی جاتی ہے۔
Logged record۔ ہر request اپنی cost کے ساتھ ایک row لکھتی ہے، اس لیے یہ معلوم کیا جا سکتا ہے کہ خرچ کس application نے کیا۔

خود gateway کیوں چلائیں

Managed router میں ہر request کے درمیان کسی دوسرے فریق کا process موجود ہوتا ہے۔ اسے خود چلانے سے آپ کے provider keys اور prompt text آپ کے زیرِ انتظام server پر رہتے ہیں۔ اس کی حقیقی لاگت بھی ہے: اب آپ کو وہ component چلانا ہوگا جس پر ہر application انحصار کرتی ہے۔ اس guide کا آخری section اسی لاگت کے بارے میں ہے، کیونکہ اکثر تحریری وضاحتوں میں یہی حصہ شامل نہیں کیا جاتا۔

ضروری چیزیں

Ubuntu 24.04 چلانے والا VPS (virtual private server)، جس پر Docker اور Compose plugin نصب ہو۔
اگر سرور سے باہر موجود مشینیں TLS (transport layer security) کے ذریعے gateway تک پہنچیں گی تو ایسا domain name جو اس VPS کی طرف point کرتا ہو۔
کم از کم ایک provider API key۔

gateway خود کوئی inference نہیں چلاتا۔ یہ requests کو آگے بھیجتا ہے اور answers کو stream کے ذریعے واپس فراہم کرتا ہے، اس لیے اس کا CPU load model size کے بجائے requests کی تعداد کے مطابق بڑھتا ہے۔ 1 vCPU والا سرور کئی internal applications کو آسانی سے چلا سکتا ہے۔ جو چیز بڑھتی ہے وہ database ہے، کیونکہ gateway ہر request کے لیے ایک spend row لکھتا ہے۔

پہلے `config.yaml` لکھیں

configuration فائل یہ طے کرتی ہے کہ client کن models کے لیے درخواست کر سکتا ہے۔ اوپری سطح کے چار sections اہم ہیں: model_list، litellm_settings، router_settings اور 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
  allowed_fails: 3
  cooldown_time: 30
  json_logs: true
  set_verbose: false

router_settings:
  fallbacks: [{"bulk": ["strong"]}]
  context_window_fallbacks: [{"bulk": ["strong"]}]

general_settings:
  background_health_checks: true
  health_check_interval: 300

model_name وہ نام ہے جو آپ کے clients بھیجتے ہیں۔ litellm_params.model اصل model ہے، جسے provider/model کی صورت میں لکھا جاتا ہے۔ اپنے models کے نام vendor کے بجائے کام کے مطابق رکھیں۔ جو application bulk کے لیے درخواست کرتی ہے، وہ اس وقت بھی کام کرتی رہے گی جب آپ اگلے ماہ فیصلہ کریں کہ bulk کوئی مختلف model ہونا چاہیے۔

api_key: os.environ/ANTHROPIC_API_KEY LiteLLM کو بتاتا ہے کہ یہ variable runtime پر پڑھے۔ اصل key فائل میں ظاہر نہیں ہوتی، جو اس لیے اہم ہے کہ آپ config.yaml کو commit کرتے ہیں۔

دو entries کا نام جان بوجھ کر strong ایک ہی رکھا گیا ہے۔ جب ایک سے زیادہ deployments میں ایک ہی model_name ہو، تو router انہیں باہم قابل تبادلہ سمجھتا ہے اور پہلی deployment ناکام ہونے پر دوسری deployment آزمانے کی کوشش کرتا ہے۔ اسی طرح strong اس وقت بھی کام کرتا رہتا ہے جب کسی ایک provider میں کچھ دیر کے لیے خرابی ہو۔

num_retries: 2 retry کے قابل error پر اسی deployment کو دوبارہ آزماتا ہے۔ fallback ان retries کے مکمل استعمال کے بعد فعال ہوتا ہے۔ allowed_fails: 3 کو cooldown_time: 30 کے ساتھ استعمال کرنے سے کوئی deployment 3 بار ناکام ہونے کے بعد 30 seconds کے لیے rotation سے نکال دی جاتی ہے۔ اس طرح 500 errors واپس کرنے والے provider کو ہر request پر دوبارہ آزمایا نہیں جاتا۔

fallbacks اور context_window_fallbacks کے triggers مختلف ہیں، اور دوسرا وہ مفید trigger ہے جسے لوگ اکثر نظرانداز کر دیتے ہیں۔

fallbacks اس وقت فعال ہوتا ہے جب primary call ناکام ہو جائے۔
context_window_fallbacks اس وقت فعال ہوتا ہے جب provider اس لیے request مسترد کرے کہ وہ اس model کی context window سے زیادہ طویل ہے۔ اس صورت میں بہت بڑا prompt caller کو error واپس کرنے کے بجائے گنجائش رکھنے والے model کو بھیج دیا جاتا ہے۔

content_policy_fallbacks بھی موجود ہے، جو provider کی جانب سے content policy کی بنیاد پر request مسترد کرنے کے لیے ہے۔ اسے صرف اسی وقت set کریں جب ان calls کو بھیجنے کے لیے کوئی مناسب جگہ موجود ہو۔

Docker Compose کے ساتھ VPS پر LiteLLM deploy کریں

ایک directory بنائیں جس میں یہ تین files ہوں: config.yaml، docker-compose.yml اور .env۔ upstream quickstart latest tag حاصل کرتا ہے۔ اس کے بجائے release tag کو pin کریں، تاکہ اگلے ماہ docker compose up -d آج والا ہی gateway فراہم کرے، اور rollback کے لیے صرف ایک line درکار ہو۔

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 یہاں .env کو دو مرتبہ پڑھتا ہے۔ پہلی مرتبہ compose file کے اندر ${POSTGRES_PASSWORD} کو substitute کرنے کے لیے، اور دوسری مرتبہ env_file کے ذریعے ہر variable کو container میں منتقل کرنے کے لیے۔

v1.95.0، August 2026 میں موجودہ release تھا۔ project کے releases page کو چیک کریں اور deployment کے وقت جو release موجودہ ہو اسے pin کریں۔ ہر release ایک signature شائع کرتا ہے، اس لیے اسے قابل اعتماد سمجھنے سے پہلے image کی تصدیق کر سکتے ہیں:

cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0

port line 127.0.0.1:4000:4000 ہے، جو port کو صرف loopback interface پر publish کرتی ہے۔ اس کے بجائے 4000:4000 لکھیں تو gateway پورے internet سے قابل رسائی ہو جائے گا، کیونکہ Docker خود iptables کی FORWARD chain میں rules شامل کرتا ہے اور ان rules کی evaluation ufw کے rules سے پہلے ہوتی ہے، اس لیے ufw deny 4000 اسے نہیں روکتا۔ self-hosted gateway کے غیر ارادی طور پر کھلے رہ جانے کی یہ سب سے عام وجہ ہے: دیکھیں Docker کس طرح container port کو براہ راست ufw سے آگے publish کرتا ہے۔ باہر سے آنے والا traffic اس کے بجائے reverse proxy کے ذریعے پہنچتا ہے۔

پروائیڈر کیز کو image سے باہر رکھیں

.env فائل میں تمام secrets موجود ہوتے ہیں۔ اسے runtime پر environment کے طور پر فراہم کیا جاتا ہے، اس لیے یہ image میں شامل نہیں ہوتی اور نہ ہی commit کی جاتی ہے۔

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-...

LiteLLM کی دونوں keys حقیقی randomness کے ساتھ generate کریں، پھر فائل کی permissions محدود کریں:

printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .env

LITELLM_MASTER_KEY admin credential ہے۔ یہ management API کی authentication کرتا ہے اور /ui پر موجود Admin UI کا password ہے۔ کسی بھی application کے پاس یہ credential نہیں ہونا چاہیے۔

LITELLM_SALT_KEY database میں محفوظ provider credentials کو encrypt کرتا ہے۔ اسے ایک بار set کریں اور پھر تبدیل نہ کریں۔ بعد میں اسے تبدیل کرنے سے پہلے سے محفوظ credentials decrypt نہیں ہو سکیں گے۔ اس صورت میں gateway معمول کے مطابق start ہو جائے گا، لیکن ان providers کو کی جانے والی ہر call authentication پر fail ہو گی۔

STORE_MODEL_IN_DB=True آپ کو config.yaml میں تبدیلی کیے بغیر Admin UI سے models شامل اور edit کرنے دیتا ہے۔ یہ سہولت کار ہے، لیکن اس سے source of truth دو جگہ تقسیم ہو جاتا ہے۔ طے کریں کہ authoritative source کون سا ہوگا، اور یہ فیصلہ config کے ساتھ درج کریں۔

keys کو config file سے باہر رکھنے کی وجہ وہی ہے جو انہیں agent کو فراہم کیے جانے والے tools سے باہر رکھنے کی وجہ ہے۔ AI agents سے provider secrets الگ رکھنا اس طریقے کی وضاحت کرتا ہے، جبکہ Docker Compose میں env files اور secrets عملی طریقہ بیان کرتا ہے۔

اسے start کریں اور پہلے boot کی نگرانی کریں:

docker compose up -d
docker compose logs -f litellm

یہ تصدیق کریں کہ یہ واقعی کام کر رہا ہے

دو probes کے لیے authentication درکار نہیں، جبکہ ایک probe authenticated ہے۔ یہ مختلف وجوہات کی بنا پر ناکام ہوتے ہیں۔

curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readiness

/health/liveliness کے لیے authentication درکار نہیں، اور process چلنے کے دوران یہ "I'm alive!" کا جواب دیتا ہے۔ /health/readiness کے لیے بھی authentication درکار نہیں۔ یہ ایک JSON object واپس کرتا ہے جس میں "status": "healthy" اور db field شامل ہوتا ہے، یا database ناقابل رسائی ہونے پر 503 واپس کرتا ہے۔ اپنی monitoring کو readiness پر متعین کریں، کیونکہ ایسا gateway جس میں ایک بھی virtual key lookup نہ ہو سکے، اس کی liveliness پھر بھی green رہتی ہے۔

Authenticated check ہی providers سے رابطہ کرتا ہے:

curl -s http://127.0.0.1:4000/health \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

یہ healthy_endpoints اور unhealthy_endpoints arrays کے ساتھ جواب دیتا ہے۔ اگر unhealthy_endpoints میں موجود model authentication error دکھائے تو اس کا مطلب ہے کہ .env میں provider key غلط ہے یا موجود نہیں۔ یہی وہ failure ہے جسے آپ کو ابھی تلاش کرنا ہے۔ چونکہ background_health_checks: true set ہے، proxy خود ہر health_check_interval seconds بعد یہ probes چلاتا ہے، اور /health آخری result واپس کرتا ہے۔ اس لیے اسے poll کرنے سے ہر بار آپ کے providers کو test request نہیں بھیجی جاتی۔

ورچوئل keys اور فی-key budgets

ہر application کو اپنی الگ key ملتی ہے، جو master key کی بنیاد پر بنائی جاتی ہے۔

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
  }'

response میں key field شامل ہوتی ہے، جو sk- سے شروع ہوتی ہے۔ یہی string application کو دی جاتی ہے، اور application کو اس کے علاوہ کچھ نہیں ملتا۔

models اس بات کی allowlist ہے کہ یہ key کیا request کر سکتی ہے۔ اوپر دی گئی key صرف bulk مانگ سکتی ہے، اس کے علاوہ کچھ نہیں۔
max_budget: 5 کو budget_duration: "30d" کے ساتھ مقرر کرنے سے rolling 30 days کے لیے پانچ US dollars کی حد نافذ ہوتی ہے۔ اس کے بعد key کام کرنا بند کر دیتی ہے۔
rpm_limit اور tpm_limit اس key کے لیے بالترتیب requests per minute اور tokens per minute کی حد مقرر کرتے ہیں۔
key_alias وہ نام ہے جسے آپ چھ ہفتے بعد spend log میں شناخت کریں گے۔ اسے ہمیشہ set کریں۔

جب budget ختم ہو جائے تو call HTTP 401 کے ساتھ اس شکل کی body دے کر ناکام ہو جاتی ہے:

ExceededBudget: Current spend for token: 7.2e-05; Max Budget for Token: 2e-07

یہ status code اس مسئلے کو الجھا دیتا ہے۔ client library 401 کو authentication problem کے طور پر report کرتی ہے، اس لیے stack trace پڑھنے والا developer یہ جانچنا شروع کر دیتا ہے کہ key valid ہے یا نہیں۔ response body کو status code کے ساتھ log کریں، ورنہ ہر بار budget ختم ہونے کا مسئلہ broken credential جیسا دکھائی دے گا۔

اسی management API کے ذریعے keys کا معائنہ اور adjustment کریں:

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}'

gateway پر نافذ کیا گیا budget اس وقت بھی برقرار رہتا ہے جب خرابی خود agent میں ہو۔ اسی لیے یہ VPS پر AI agents کے لیے cost control کی بنیادی بنیاد ہے۔

سستا model استعمال کرتے ہوئے bulk کام بھیجیں

Client کو gateway کی طرف point کریں۔ Base URL، key اور model name:

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."}]
  }'

ہر OpenAI client library اسی طرح کام کرتی ہے: base_url کو https://gateway.example.com/v1 اور api_key کو virtual key پر set کریں۔

config.yaml میں موجود routing policy اب caller کے علم میں آئے بغیر لاگو ہوتی ہے۔ bulk کی request سستے model کو بھیجی جاتی ہے۔ اگر اس call کی تمام retries کے بعد بھی failure ہو جائے تو request کو strong کے خلاف دوبارہ try کیا جاتا ہے۔ اگر prompt bulk کے لیے بہت طویل ہو تو context_window_fallbacks error واپس کرنے کے بجائے اسے strong کو بھیج دیتا ہے۔ Classification pass یا summarising backlog جیسے bulk کام default طور پر سستے model پر چلتے ہیں، اور صرف مشکل requests کی لاگت زیادہ ہوتی ہے۔

یہ وہ جگہ بھی ہے جہاں tool-using agents کے ساتھ gateway کی افادیت واضح ہوتی ہے۔ اسی VPS پر موجود MCP (model context protocol) server اور اسے چلانے والا agent دونوں ایک ہی endpoint کی طرف point کر سکتے ہیں۔ اس طرح دونوں کو redeploy کیے بغیر ان کے پیچھے موجود model تبدیل کیا جا سکتا ہے۔

فالت بیک ہونے کا کیسے پتا چلتا ہے؟

یہ وہ failure mode ہے جس پر لاگت بڑھتی ہے، کیونکہ بظاہر کچھ خراب نہیں ہوتا۔ کامیاب fallback عام response body کے ساتھ HTTP 200 واپس کرتا ہے۔ آپ کا کم لاگت والا model ایک دن تک بند رہ سکتا ہے، ہر call خاموشی سے مہنگے model سے مکمل ہو سکتی ہے، اور پہلا ثبوت invoice ہوتا ہے۔

ثبوت response headers میں موجود ہوتا ہے۔ انہیں طلب کریں:

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-group وہ deployment ہے جس کی client نے درخواست کی تھی۔ x-litellm-model-id وہ deployment ہے جس نے response دیا۔ جب یہ دونوں مختلف ہوں تو fallback ہوا ہے۔
x-litellm-attempted-fallbacks اور x-litellm-attempted-retries ان کی تعداد بتاتے ہیں۔ صحت مند call میں دونوں 0 ہوتے ہیں۔
x-litellm-response-cost اس call کی US dollars میں لاگت ہے۔
x-litellm-call-id وہ identifier ہے جس سے آپ اپنے logs میں اسی call کو تلاش کرتے ہیں۔

ہر request پر x-litellm-attempted-fallbacks record کریں اور جب اس کی قدر 0 نہ رہے تو alert بھیجیں۔ یہ ایک عدد ایسے routing policy کے درمیان فرق واضح کرتا ہے جو درست کام کر رہی ہو اور ایسی routing policy کے درمیان جو خاموشی سے "ہمیشہ مہنگا model استعمال کریں" بن چکی ہو۔

اس کا مکمل طریقہ tracing ہے، اور اس کے لیے الگ setup درکار ہے: agent calls کی tracing کے لیے self-hosted Langfuse۔ LiteLLM یہ callback فراہم کرتا ہے، اس لیے اسے جوڑنے کے لیے credentials سمیت دو lines کافی ہیں۔

litellm_settings:
  success_callback: ["langfuse"]
  failure_callback: ["langfuse"]

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.com

failure_callback کے ساتھ success_callback بھی set کریں۔ اسے چھوڑنے پر آپ کے پاس صرف وہ traces محفوظ رہیں گے جن میں کچھ غلط نہیں ہوا۔ اس سے الگ، LiteLLM ہر request کے لیے Postgres میں spend row لکھتا ہے، اور /ui پر موجود Admin UI اسی table کو پڑھتا ہے۔ traffic بڑھنے کے ساتھ یہ table بھی بڑھتی ہے، اس لیے کم گنجائش والی disk پر اس کی نگرانی کریں۔

ریورس پراکسی کے پیچھے gateway رکھیں

box کے باہر سے کوئی بھی چیز port 4000 تک نہ پہنچ سکے۔ TLS کو nginx یا Caddy میں terminate کریں اور درخواستیں loopback address پر forward کریں۔

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;
}

ان میں سے دو directives اکثر چھوڑ دی جاتی ہیں۔ proxy_buffering off اہم ہے کیونکہ streaming completion، server-sent events کی ایک series ہوتی ہے۔ nginx میں buffering فعال ہو تو chunks کو response مکمل ہونے تک روک لیا جاتا ہے۔ اس کے نتیجے میں client خاموش رہتا ہے اور پھر تمام مواد ایک ساتھ موصول کرتا ہے۔ proxy_read_timeout 600s اہم ہے کیونکہ طویل generation nginx کی 60 second default حد سے زیادہ وقت لے سکتی ہے۔ ایسی صورت میں client کو 504 ملتا ہے اور error log میں upstream timed out (110: Connection timed out) while reading response header from upstream درج ہوتا ہے۔

certificate کے لیے nginx پر Let's Encrypt کے ساتھ Certbot مختصر طریقہ ہے۔ اگر box پہلے ہی کئی containers چلا رہا ہو تو متعدد Compose apps کے سامنے Traefik routing اور certificates کو ایک ہی جگہ manage کرتا ہے۔

گیٹ وے اب ناکامی کا واحد نقطہ ہے

اپنے بنائے ہوئے نظام کے بارے میں حقیقت پسند رہیں۔ اب آپ کی ہر ایپ ایک VPS پر موجود ایک container پر منحصر ہے۔ جب یہ بند ہو تو کوئی بھی ایپ کسی model کو call نہیں کر سکتی، حتیٰ کہ وہ providers بھی نہیں جو مکمل طور پر درست کام کر رہے ہوں۔ اس کے چار نتائج ہیں۔

غلط configuration ایک ہی وقت میں سب کچھ بند کر دیتی ہے۔ restart: unless-stopped crash ہونے والی service کو restart کرتا ہے، اور ایسے container کو بھی بار بار restart کرتا ہے جو config.yaml کو parse نہیں کر سکتا۔ ہر configuration تبدیلی کے بعد docker compose logs litellm پڑھیں، اور configuration میں تبدیلی اس وقت کریں جب آپ اس کی نگرانی کر سکیں۔
Postgres درخواست کے راستے میں شامل ہے۔ Virtual key lookup اور spend recording، دونوں اس کا استعمال کرتے ہیں۔ /health/readiness کا 503 واپس کرنا اس بات کا انتباہ ہے کہ gateway چل رہا ہے، لیکن یہ دونوں کام نہیں کر سکتا۔
ایک instance کو بڑا بنانے کے بجائے instances شامل کر کے scale کریں۔ project کی اپنی ہدایت کے مطابق ہر instance میں ایک worker ہونا چاہیے (--num_workers 1)، جبکہ متعدد instances ایک database شیئر کریں۔ load balancer کے پیچھے دو چھوٹے gateways رکھنے سے واحد container پر انحصار ختم ہو جاتا ہے۔ database پر انحصار ختم نہیں ہوتا۔
جس data کو دوبارہ generate نہیں کیا جا سکتا، اس کا backup لیں۔ اس میں config.yaml اور .env، نیز database کا ایک pg_dump شامل ہے۔ LITELLM_SALT_KEY ضائع ہونے سے اس dump میں موجود encrypted provider credentials بے کار ہو جاتے ہیں۔ اس لیے env file اور dump ایک ہی backup job میں شامل ہونے چاہییں: off-box storage پر restic backups۔

Upgrade کرنے کے لیے image tag میں ترمیم کریں اور docker compose up -d چلائیں۔ LiteLLM startup پر default طور پر prisma migrate deploy چلاتا ہے، اس لیے نیا container اپنے پہلے boot پر database schema کو migrate کرتا ہے۔ tag تبدیل کرنے سے پہلے dump لیں، کیونکہ پرانی image دوبارہ استعمال کرنے سے پہلے سے چل چکی migration واپس نہیں ہوتی۔

FAQ

کیا LiteLLM ہر کال میں قابلِ ذکر تاخیر شامل کرتا ہے؟

پروجیکٹ کی README میں اگست 2026 کے مطابق، 1000 requests per second پر 95th percentile میں 8 ms درج ہیں۔ اسے vendor figure سمجھیں۔ آپ کی latency کو حقیقت میں متاثر کرنے والی چیز آپ کی applications اور gateway کے درمیان network distance ہے، کیونکہ ہر کال میں ایک اضافی round trip شامل ہو جاتا ہے۔ Gateway کو ان applications کے same region میں چلائیں جو اسے call کرتی ہیں، پھر حقیقی response میں x-litellm-overhead-duration-ms header کے ذریعے اپنا overhead measure کریں۔

nginx کو سامنے رکھنے کے بعد streaming نے کام کرنا کیوں بند کر دیا؟

کیونکہ nginx upstream responses کو default طور پر buffer کرتا ہے، جبکہ streaming completion server-sent events کی ایک series ہوتی ہے۔ proxy_buffering فعال ہونے پر nginx chunks جمع کرتا ہے اور انہیں response مکمل ہونے کے بعد جاری کرتا ہے۔ اس لیے client خاموشی سے انتظار کرتا ہے اور پھر پورا جواب ایک ساتھ وصول کرتا ہے۔ location block میں proxy_buffering off; set کریں۔ اسی block میں proxy_read_timeout کی قدر بڑھائیں، کیونکہ بصورت دیگر طویل generation nginx کے 60 second default سے تجاوز کر جاتی ہے اور client کو 504 ملتا ہے۔

جب virtual key کا budget ختم ہو جائے تو کیا ہوتا ہے؟

کال HTTP 401 کے ساتھ ناکام ہو جاتی ہے اور body کی شکل ExceededBudget: Current spend for token: 7.2e-05; Max Budget for Token: 2e-07 جیسی ہوتی ہے۔ 401 یہاں گمراہ کن ہے: client library اسے authentication failure کے طور پر report کرتی ہے، اس لیے لوگ message پڑھنے کے بجائے یہ جانچنا شروع کر دیتے ہیں کہ key valid ہے یا نہیں۔ Response body کو status code کے ساتھ log کریں۔ Master key کے مقابل key کی اصل position /key/info?key=sk-... سے confirm کریں، اور اگر budget بہت کم set کیا گیا ہو تو /key/update سے ceiling بڑھائیں۔

کیا gateway hosted models کے ساتھ local model کو بھی route کر سکتا ہے؟

ہاں، اور یہ model_list میں ایک مزید entry ہوتی ہے۔ ollama_chat/ prefix کو api_base کے ساتھ استعمال کریں، مثلاً model: ollama_chat/llama3.1 کو api_base: http://ollama:11434 کے ساتھ۔ Container کے اندر localhost سے مراد وہی container ہوتا ہے، اس لیے Compose service name یا Docker network پر host کا address استعمال کریں، 127.0.0.1 کبھی استعمال نہ کریں۔ Local model کو چلانا الگ کام ہے: VPS پر Ollama کے ساتھ LLM کی self-hosting دیکھیں۔

#litellm #llm-gateway #self-hosted-ai #docker #cost-control

خود host کردہ LLM gateway کیا کرتا ہے

خود gateway کیوں چلائیں

ضروری چیزیں

پہلے config.yaml لکھیں

Docker Compose کے ساتھ VPS پر LiteLLM deploy کریں

پروائیڈر کیز کو image سے باہر رکھیں

یہ تصدیق کریں کہ یہ واقعی کام کر رہا ہے

ورچوئل keys اور فی-key budgets

سستا model استعمال کرتے ہوئے bulk کام بھیجیں

فالت بیک ہونے کا کیسے پتا چلتا ہے؟

ریورس پراکسی کے پیچھے gateway رکھیں

گیٹ وے اب ناکامی کا واحد نقطہ ہے

FAQ

کیا LiteLLM ہر کال میں قابلِ ذکر تاخیر شامل کرتا ہے؟

nginx کو سامنے رکھنے کے بعد streaming نے کام کرنا کیوں بند کر دیا؟

جب virtual key کا budget ختم ہو جائے تو کیا ہوتا ہے؟

کیا gateway hosted models کے ساتھ local model کو بھی route کر سکتا ہے؟

پہلے `config.yaml` لکھیں