اپنا LiteLLM LLM gateway خود host کریں
LiteLLM سے ایک OpenAI-compatible endpoint بنائیں، virtual keys اور فی key بجٹ رکھیں، provider fallback چلائیں، اور pinned images سے deploy ثابت قدم رکھیں۔
خود 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 لکھیں
config file یہ طے کرتی ہے کہ client کن models کے لیے درخواست کر سکتا ہے۔ چار top-level 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
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 وہ نام ہے جو آپ کے clients بھیجتے ہیں۔ litellm_params.model اصل model ہے، جسے provider/model کے طور پر لکھا گیا ہے۔ اپنے models کے نام vendor کے بجائے کام کی بنیاد پر رکھیں۔ جو application bulk کے لیے درخواست کرتی ہے، وہ اس وقت بھی کام کرتی رہے گی جب آپ اگلے ماہ فیصلہ کریں کہ bulk کوئی مختلف model ہونا چاہیے۔
api_key: os.environ/ANTHROPIC_API_KEY LiteLLM کو بتاتا ہے کہ وہ یہ variable runtime پر پڑھے۔ اصل key file میں ظاہر نہیں ہوتی، جو اس لیے اہم ہے کہ config.yaml وہ file ہے جسے آپ commit کرتے ہیں۔
دو entries جان بوجھ کر strong نام share کرتی ہیں۔ جب ایک سے زیادہ deployments کے پاس ایک ہی model_name ہو، تو router انہیں interchangeable سمجھتا ہے اور اس نام کی requests ان کے درمیان تقسیم کرتا ہے۔ اسی طرح strong اس وقت بھی کام کرتا رہتا ہے جب کسی ایک provider کا ایک گھنٹہ خراب گزر رہا ہو: جب کوئی deployment cooldown میں چلا جائے، جس کی وضاحت نیچے ہے، تو strong کی نئی requests دوسرے deployment کو بھیجی جاتی ہیں۔
num_retries: 2 قابلِ retry error کو زیادہ سے زیادہ دو بار دوبارہ آزماتا ہے۔ یہ retries اسی model group میں موجود کسی دوسرے دستیاب deployment کو منتخب کر سکتی ہیں: 2026-10-29 کو دیکھی گئی LiteLLM architecture docs retries کو group کے اندر اور cross-group fallbacks کو الگ مراحل کے طور پر بیان کرتی ہیں۔ اس لیے strong کی retry weighted failover فعال کیے بغیر دوسرے provider تک پہنچ سکتی ہے۔ Fallback صرف اس وقت چلتا ہے جب یہ retries مکمل ہو جائیں۔
allowed_fails اور cooldown_time router options ہیں، اس لیے یہ router_settings کے اندر رہتے ہیں۔ Proxy اسی section سے اپنا router بناتا ہے، اور v1.95.0 میں litellm_settings کے اندر لکھا گیا cooldown_time router تک کبھی نہیں پہنچتا۔ نتیجتاً cooldowns خاموشی سے 5 second کی default value پر رہتے ہیں۔ cooldown_time: 30 یہ طے کرتا ہے کہ cooldown میں جانے کے بعد کوئی deployment کتنی دیر rotation سے باہر رہے گا۔ Configuration reference allowed_fails کو اس failure count کے طور پر بیان کرتی ہے جس سے کسی deployment کو cooldown_time کے اندر تجاوز کرنا ہو، تب اسے cooldown میں بھیجا جائے گا۔ v1.95.0 source میں allowed_fails: 3 default value ہے، اور default پر router انہی built-in triggers تک محدود رہتا ہے؛ failure count صرف اس وقت مؤثر ہوتا ہے جب آپ مختلف number set کریں۔ ان triggers میں ایک سے زیادہ deployments والے group کے لیے 429 response پر فوری cooldown، ایسے group کے لیے current minute میں کم از کم 5 requests کے بعد 50% سے زیادہ failures، اور وہ errors شامل ہیں جنہیں router retry نہیں کرے گا، مثلاً غلط key کی وجہ سے 401۔ ایک الگ trigger اس وقت single deployment کو بھی cooldown میں بھیجتا ہے جب current minute کی تمام requests fail ہوں اور traffic SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD تک پہنچ جائے، جس کی default value 1000 requests ہے۔ لہٰذا strong کے دو deployments ہونے کی وجہ سے، 500 errors کا burst واپس کرنے والا provider ہر request پر دوبارہ آزمایا نہیں جاتا، جبکہ ہر چند منٹ بعد آنے والا ایک 500 cooldown trigger نہیں کرتا۔ bulk کا صرف ایک deployment ہے، اس لیے failure rate trigger اس پر لاگو نہیں ہوتا: 1000 requests فی minute سے کم رہنے والا 500 errors کا burst اسے rotation میں رکھتا ہے، اور اس کے callers کو تحفظ num_retries کے بعد strong کے fallback سے ملتا ہے۔
fallbacks اور context_window_fallbacks کے triggers مختلف ہیں، اور دوسرا وہ مفید option ہے جسے لوگ اکثر نظرانداز کر دیتے ہیں۔
fallbacksاس وقت چلتا ہے جب primary call fail ہو۔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 تعینات کریں
ایک directory بنائیں جس میں یہ تین files ہوں: config.yaml، docker-compose.yml اور .env۔ upstream quickstart latest tag حاصل کرتا ہے۔ اس کے بجائے کسی release tag کو pin کریں، تاکہ upgrade صرف file میں تبدیلی کرنے پر ہو اور rollback ایک line میں کیا جا سکے۔ صرف tag استعمال کرنا یکساں contents کی ضمانت نہیں دیتا، کیونکہ image tags تبدیل کیے جا سکتے ہیں اور publisher کسی tag کو نئی image کی طرف point کر سکتا ہے۔ اگر docker compose up -d کو اگلے ماہ آج والی بالکل وہی gateway فراہم کرنی ہو تو image digest بھی شامل کریں، اس format میں ghcr.io/berriai/litellm:v1.95.0@sha256:<digest>؛ docker buildx imagetools inspect ghcr.io/berriai/litellm:v1.95.0 اسے print کرتا ہے۔
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 کو check کریں اور 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.0port line 127.0.0.1:4000:4000 ہے، جو port کو صرف loopback interface پر publish کرتی ہے۔ اس کے بجائے 4000:4000 لکھیں تو آپ کی gateway پورے internet سے قابل رسائی ہو جائے گی، کیونکہ Docker اپنی rules iptables کی FORWARD chain میں شامل کرتا ہے اور ان rules کا جائزہ 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 .envLITELLM_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 نہیں بھیجی جاتی۔
Virtual 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"کے ساتھ، ہر calendar month کے لیے پانچ US dollars ہے۔ LiteLLM ہر ماہ کی 1 تاریخ کو midnight پر30dbudget reset کرتا ہے۔ یہ وقت UTC میں ہوتا ہے، جب تک آپlitellm_settingsکے تحتtimezoneset نہ کریں۔ budget rolling 30 days کے حساب سے reset نہیں ہوتا۔ اس لیے key کے پانچ dollars خرچ کرنے کے بعد وہ اگلی 1 تاریخ تک کام کرنا بند کر دیتی ہے۔rpm_limitاورtpm_limitصرف اس key کے لیے requests per minute اور tokens per minute کی حد مقرر کرتے ہیں۔key_aliasوہ نام ہے جسے آپ چھ ہفتے بعد spend log میں پہچان سکیں گے۔ اسے ہمیشہ set کریں۔
جب budget ختم ہو جائے تو call budget_exceeded type کی error کے ساتھ fail ہوتی ہے، اور message کی شکل یہ ہوتی ہے:
Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>status code release کے لحاظ سے مختلف ہوتا ہے۔ pinned v1.95.0 میں یہ HTTP 429 ہے۔ v1.104.0 سے default HTTP 422 ہے، اور litellm_settings کے تحت budget_exceeded_status_code: 429 set کرنے سے پہلے والا code بحال ہو جاتا ہے۔ حقیقی rpm_limit اور tpm_limit hits دونوں releases میں 429 ہی return کرتے ہیں۔ ہر upgrade کے بعد دیکھیں کہ آپ کو کون سا code مل رہا ہے۔
یہ status code ہی اس مسئلے کو confusing بناتا ہے، کیونکہ دونوں codes میں "budget" کا ذکر نہیں ہوتا۔ client library 429 کو rate limit سمجھ کر اسے backoff کے ساتھ retry کر سکتی ہے، حالانکہ budget reset ہونے تک واپس نہیں آئے گا۔ اسی طرح وہ 422 کو ایسی request سمجھتی ہے جس پر عمل نہیں ہو سکا۔ response body کو status code کے ساتھ log کریں، ورنہ budget ختم ہونا ہر بار کسی اور مسئلے جیسا دکھائی دے گا۔
اسی 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 کی بنیادی کڑی ہے۔
سستا ماڈل استعمال کرتے ہوئے بڑے پیمانے کا کام بھیجیں
کلائنٹ کو gateway پر بھیجیں۔ 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 اسی طرح کام کرتی ہے، اگرچہ option names زبان کے لحاظ سے مختلف ہوتے ہیں۔ Python client میں base_url کو https://gateway.example.com/v1 اور api_key کو virtual key پر set کریں۔ JavaScript اور TypeScript client calls میں یہی دو options baseURL اور apiKey استعمال ہوتے ہیں۔
config.yaml میں موجود routing policy اب caller کے علم کے بغیر لاگو ہوتی ہے۔ bulk کی request سستے model کو بھیجی جاتی ہے۔ اگر اس call کی تمام retries کے بعد failure ہو جائے تو request کو strong کے خلاف دوبارہ بھیجا جاتا ہے۔ اگر prompt bulk کے لیے بہت طویل ہو تو context_window_fallbacks اسے error واپس کرنے کے بجائے strong کو بھیجتا ہے۔ Classification pass یا summarising backlog جیسے بڑے پیمانے کے کام default طور پر سستے model پر چلتے ہیں، اور صرف مشکل requests کی لاگت زیادہ ہوتی ہے۔
یہاں tool-using agents کے لیے gateway کی افادیت بھی واضح ہوتی ہے۔ اسی VPS پر موجود MCP (model context protocol) server اور اسے چلانے والا agent دونوں ایک ہی endpoint کو استعمال کر سکتے ہیں، اس لیے کسی کو redeploy کیے بغیر ان کے پیچھے موجود model تبدیل کیا جا سکتا ہے۔
آپ کو کیسے معلوم ہوگا کہ fallback ہوا ہے؟
یہ وہ failure mode ہے جس پر رقم خرچ ہوتی ہے، کیونکہ بظاہر کچھ بھی خراب نہیں لگتا۔ کامیاب fallback، HTTP 200 اور عام response body واپس کرتا ہے۔ آپ کا سستا model ایک دن تک down رہ سکتا ہے، ہر call خاموشی سے مہنگے model سے serve ہو سکتی ہے، اور پہلا ثبوت 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وہ model name ہے جس کے تحت request route کی گئی، جیسےbulk۔x-litellm-model-idاس deployment کی ID ہے جس نے جواب دیا؛ آپ اسے/v1/model/info?litellm_model_id=...کے ذریعے تلاش کر سکتے ہیں۔ جب یہ ID آپ کیbulkdeployments میں شامل نہ ہو تو fallback ہوا ہے۔x-litellm-attempted-fallbacksاورx-litellm-attempted-retriesان کی تعداد گنتے ہیں۔ صحت مند call میں دونوں میں سے کسی کی count 0 سے زیادہ نہیں ہونی چاہیے۔x-litellm-response-costاس ایک call کی US dollars میں لاگت ہے۔x-litellm-call-idوہ identifier ہے جسے آپ اپنے logs میں یہی call تلاش کرنے کے لیے استعمال کرتے ہیں۔
ہر request پر x-litellm-attempted-fallbacks record کریں اور جب بھی اس کی قدر 0 سے زیادہ ہو تو alert بھیجیں۔ یہی ایک number اس routing policy کے درمیان فرق ہے جو درست کام کر رہی ہو اور اس routing policy کے درمیان جو خاموشی سے "always use the expensive 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.comLangfuse v3 اور بعد کے versions کے لیے، LiteLLM کا Langfuse page اب اس کا langfuse_otel preset تجویز کرتا ہے؛ اوپر دیا گیا langfuse callback اب بھی documented ہے۔ failure_callback کے ساتھ success_callback بھی set کریں۔ اسے چھوڑ دیں تو آپ کے پاس صرف وہ traces محفوظ رہیں گے جن میں کچھ غلط نہیں ہوا۔ اس سب سے الگ، LiteLLM ہر request کے لیے Postgres میں ایک spend row لکھتا ہے، اور /ui پر موجود Admin UI اسی table کو پڑھتا ہے۔ Traffic بڑھنے کے ساتھ یہ table بھی بڑھتی ہے، اس لیے چھوٹی disk پر اس کی نگرانی کریں۔
گیٹ وے کو reverse proxy کے پیچھے رکھیں
باکس کے باہر سے کوئی چیز 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;
}ان میں سے دو سطریں اکثر چھوڑ دی جاتی ہیں۔ proxy_buffering off اہم ہے کیونکہ streaming completion، server-sent events کی ایک سیریز ہوتی ہے۔ buffering فعال ہونے پر nginx chunks کو آگے بھیجنے سے پہلے buffers میں جمع کرتا ہے، جس سے client تک delivery میں تاخیر ہوتی ہے۔ proxy_read_timeout 600s اہم ہے کیونکہ nginx کا 60 سیکنڈ کا default، gateway سے دو reads کے درمیان زیادہ سے زیادہ انتظار ہے، پوری response کی حد نہیں۔ Non-streamed completion، generation مکمل ہونے تک کچھ نہیں بھیجتی۔ اس لیے اگر generation طویل ہو تو 60 سیکنڈ گزر جاتے ہیں اور کوئی byte موصول نہیں ہوتا۔ نتیجتاً client کو 504 ملتا ہے اور error log میں upstream timed out (110: Connection timed out) while reading response header from upstream درج ہو جاتا ہے۔ Streamed completion جو مسلسل chunks بھیجتی رہے، 60 سیکنڈ سے کہیں زیادہ چل سکتی ہے۔ Timeout صرف اس وقت trigger ہوتا ہے جب model اتنے وقت تک خاموش رہے۔
Certificate کے لیے nginx پر Let's Encrypt کے ساتھ Certbot مختصر راستہ ہے۔ اگر یہ باکس پہلے ہی کئی containers چلا رہا ہے تو متعدد Compose apps کے سامنے Traefik routing اور certificates کو ایک جگہ manage کرتا ہے۔
گیٹ وے اب ناکامی کا واحد نقطہ ہے
جو کچھ آپ نے بنایا ہے، اس کے بارے میں حقیقت پسند رہیں۔ اب آپ کی ہر ایپ ایک VPS پر موجود ایک container پر منحصر ہے۔ جب یہ بند ہو، تو کوئی بھی ایپ کسی model کو call نہیں کر سکتی، حتیٰ کہ وہ providers بھی نہیں جو بالکل درست کام کر رہے ہوں۔ اس کے چار نتائج ہیں۔
- غلط configuration سب کچھ ایک ساتھ بند کر دیتی ہے۔
restart: unless-stoppedcrash ہونے والی سروس کو restart کرتا ہے، اور ایسے container کو بھی بار بار restart کرتا ہے جو config.yaml کو parse نہیں کر سکتا۔ ہر configuration تبدیلی کے بعدdocker compose logs litellmپڑھیں، اور configuration میں تبدیلی اس وقت کریں جب آپ اس کی نگرانی کر سکیں۔ - Cache miss ہونے پر Postgres request path میں شامل ہوتا ہے۔ Virtual key lookup اس وقت اسے استعمال کرتا ہے جب key cache میں موجود نہ ہو؛ spend recording response کے بعد asynchronous طور پر چلتی ہے۔
/health/readinessکا 503 واپس کرنا اس بات کی وارننگ ہے کہ gateway چل رہا ہے، لیکن دونوں میں سے کوئی کام نہیں کر سکتا۔ - پہلے cores استعمال کریں، پھر instances شامل کریں۔ project کی production guidance، یعنی ہر instance کے لیے ایک worker (
--num_workers 1)، Kubernetes یا کسی دوسرے pod autoscaler کے لیے ہے جو خود instances شامل کرتا ہے۔ اس جیسے single VM یا bare container کے لیے اس کا مطلب الٹ ہے: worker count کو machine کے vCPU count کے برابر کریں۔ اوپر والے 1 vCPU box پر یہ اب بھی--num_workers 1ہے؛ بڑے box پر اسے بڑھائیں، اور یاد رکھیں کہ ہر worker اپنی memory استعمال کرتا ہے۔ load balancer کے پیچھے دوسرا gateway رکھنے سے single container پر انحصار ختم ہو جاتا ہے۔ database پھر بھی single point of failure رہتا ہے۔ - جس 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 واپس نہیں ہوتی۔
جس version پر آپ جائیں، صرف اس کے نہیں بلکہ جن versions کو آپ چھوڑ کر آگے بڑھیں، ان سب کی release notes پڑھیں۔ v1.95.0 سے v1.104.0 یا اس کے بعد کے version پر جانے سے کئی breaking changes آتی ہیں: اوپر بیان کردہ budget status code، ایسا proxy جو unset، empty یا publicly known master key کے ساتھ start ہونے سے انکار کرتا ہے، اور ایسا proxy جو startup پر database setup ناکام ہونے کی صورت میں exit کر جاتا ہے؛ restart: unless-stopped کے تحت یہ restart loop کی صورت میں ظاہر ہوتا ہے۔ اگر آپ v1.102.x یا اس سے پہلے کے version سے آ رہے ہیں، تو v1.104.0 کی notes میں یہ بھی کہا گیا ہے کہ دو LiteLLM_SpendLogs indexes خود بنائیں۔
FAQ
کیا LiteLLM ہر کال میں قابلِ ذکر تاخیر شامل کرتا ہے؟
پروجیکٹ 1000 requests per second پر 95th percentile میں 8 ms بتاتا ہے، جیسا کہ نومبر 2026 میں اس کے README میں درج تھا۔ اسے vendor کی فراہم کردہ قدر سمجھیں۔ آپ کی latency کو حقیقت میں جو چیز متاثر کرتی ہے وہ آپ کی applications اور gateway کے درمیان network distance ہے، کیونکہ ہر کال میں ایک اضافی round trip شامل ہو جاتا ہے۔ gateway کو ان applications کے اسی region میں چلائیں جو اسے call کرتی ہیں، پھر حقیقی response پر x-litellm-overhead-duration-ms header کے ذریعے اپنا overhead ناپیں۔
nginx کو سامنے رکھنے کے بعد streaming نے کام کرنا کیوں بند کر دیا؟
کیونکہ nginx upstream responses کو default طور پر buffer کرتا ہے، جبکہ streaming completion server-sent events کی ایک series ہوتی ہے۔ proxy_buffering فعال ہونے پر nginx chunks کو client تک پہنچانے سے پہلے buffers میں جمع کرتا ہے، جس سے delivery میں تاخیر ہوتی ہے۔ location block میں proxy_buffering off; set کریں۔ اسی block میں proxy_read_timeout کی قدر بھی بڑھائیں۔ default طور پر nginx gateway سے 60 seconds تک data نہ ملنے پر request ختم کر دیتا ہے۔ طویل non-streamed generation اس مدت تک آسانی سے پہنچ سکتی ہے، اور client کو 504 ملتا ہے۔
جب virtual key کا budget ختم ہو جائے تو کیا ہوتا ہے؟
کال budget_exceeded type کی error اور Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget> جیسی message کے ساتھ fail ہو جاتی ہے۔ pinned v1.95.0 پر status HTTP 429 ہے؛ v1.104.0 سے default HTTP 422 ہے۔ دونوں codes budget کا ذکر نہیں کرتے، اور یہی مسئلہ ہے: client library 429 کو rate limit سمجھ کر retry کر سکتی ہے، اس لیے لوگ message پڑھنے کے بجائے throttling تلاش کرنا شروع کر دیتے ہیں۔ response body کو status code کے ساتھ log کریں۔ master key کے مقابلے میں /key/info?key=sk-... سے key کی حقیقی position کی تصدیق کریں، اور اگر 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 کے ساتھ۔ Compose کی default networking میں container کے اندر localhost سے مراد وہی container ہوتا ہے، اس لیے Compose service name یا Docker network پر host کا address استعمال کریں، 127.0.0.1 کبھی نہیں۔ Host networking اس سے مستثنیٰ ہے، کیونکہ اس میں container، host کا network stack share کرتا ہے۔ Local model کو چلانا ایک الگ کام ہے: Ollama کے ساتھ VPS پر LLM کی self-hosting دیکھیں۔