LiteLLM म्हणजे काय आणि ते स्वतः कसे होस्ट करावे?
LiteLLM द्वारे सर्व LLM प्रोव्हायडर्ससाठी एकच OpenAI सुसंगत endpoint तयार करा. VPS वर हे गेटवे होस्ट करून व्हर्च्युअल की, बजेट मर्यादा आणि फॉलबॅक फीचर्सचा वापर कसा करावा हे जाणून घ्या.
Self-hosted LLM gateway काय करते
LiteLLM हे एक open source LLM gateway आहे जे तुम्ही स्वतः host करता: हे एक HTTP endpoint आहे ज्याला तुमची सर्व ॲप्लिकेशन्स कॉल करतात, आणि ते प्रत्येक विनंती योग्य provider कडे पाठवते. LLM म्हणजे large language model. हे gateway OpenAI chat completions API (application programming interface) वापरते, त्यामुळे ज्या client library आधीच OpenAI शी संवाद साधतात, त्या दोन बदल केल्यानंतर यावर काम करतात: base URL आणि key.
हा एक अतिरिक्त स्तर असणे हाच याचा मुख्य उद्देश आहे. तुमच्या ॲप्लिकेशन्सना provider चे credentials साठवून ठेवण्याची गरज उरत नाही. एखादा model बदलणे म्हणजे पाच वेगवेगळ्या सर्व्हिसेसमधील कोड बदलण्याऐवजी सर्व्हरवरील एका config फाईलमधील एक ओळ बदलणे इतके सोपे होते. आणि प्रत्येक कॉल एकाच प्रक्रियेतून जात असल्याने, तुमच्याकडे बजेट ठरवण्यासाठी आणि खर्चाची नोंद ठेवण्यासाठी एक मध्यवर्ती जागा उपलब्ध होते.
एकदा हे सुरू झाले की तुम्हाला खालील गोष्टी मिळतात:
- एक endpoint. ॲप्लिकेशन्स
https://gateway.example.com/v1ला लक्ष्य करतात आणि तुम्ही ठरवलेल्या model चे नाव विचारतात, जसे कीbulkकिंवाstrong. - Virtual keys. प्रत्येक ॲप्लिकेशनला स्वतःची key मिळते, ज्यामध्ये स्वतःची model allowlist आणि खर्चाची मर्यादा (spend ceiling) असते. तुम्ही इतरांना धक्का न लावता एक key रद्द करू शकता.
- Fallbacks. एखादा कॉल अयशस्वी झाल्यास किंवा prompt खूप मोठा असल्यास, तो आपोआप दुसऱ्या model वर पुन्हा प्रयत्न (retry) केला जातो.
- नोंदवलेला रेकॉर्ड. प्रत्येक विनंतीचा खर्च एका ओळीत लिहिला जातो, त्यामुळे "कोणत्या ॲपने तो खर्च केला" याचे उत्तर मिळते.
गेटवे स्वतः का चालवावा
मॅनेज्ड राउटरचा आकार सारखाच असतो, परंतु प्रत्येक विनंतीच्या मध्यभागी दुसऱ्या कोणाची तरी प्रक्रिया कार्यरत असते. स्वतः गेटवे चालवल्यामुळे तुमचे प्रोव्हायडर कीज (provider keys) आणि प्रॉम्प्ट मजकूर तुम्ही नियंत्रित करत असलेल्या सर्व्हरवर राहतात. याची किंमत मोजावी लागते: आता तुम्ही अशा घटकाचे संचालन करत आहात ज्यावर प्रत्येक ॲप्लिकेशन अवलंबून आहे. या मार्गदर्शिकेचा शेवटचा विभाग याच खर्चाबद्दल आहे, कारण बहुतेक लेख या महत्त्वाच्या भागाकडे दुर्लक्ष करतात.
आवश्यक गोष्टी
- Ubuntu 24.04 वर चालणारा एक VPS (virtual private server), ज्यावर Docker आणि Compose प्लगइन इन्स्टॉल केलेले असावे.
- जर बाहेरील यंत्रे TLS (transport layer security) द्वारे गेटवेपर्यंत पोहोचणार असतील, तर त्याकडे निर्देशित करणारे एक domain name.
- किमान एक provider API key.
गेटवे कोणतीही inference प्रक्रिया करत नाही. तो विनंत्या पुढे पाठवतो आणि उत्तरे स्ट्रीम करतो, त्यामुळे त्याचा CPU लोड हा मॉडेलच्या आकारापेक्षा विनंत्यांच्या संख्येवर अवलंबून असतो. 1 vCPU असलेला सर्व्हर कोणत्याही तक्रारीशिवाय काही अंतर्गत ॲप्लिकेशन्स हाताळू शकतो. डेटाबेसचा आकार वाढत जातो, कारण गेटवे प्रत्येक विनंतीसाठी खर्चाची एक नोंद (spend row) लिहितो.
प्रथम config.yaml लिहा
ग्राहक कोणत्या मॉडेलसाठी विनंती करू शकतो हे configuration file ठरवते. चार 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 म्हणून लिहिलेले आहे. मॉडेलना vendor च्या नावाऐवजी त्यांच्या कामानुसार नावे द्या. bulk साठी विनंती करणारे application पुढील महिन्यात bulk वेगळे model असावे असे ठरवले तरी कार्यरत राहते.
api_key: os.environ/ANTHROPIC_API_KEY LiteLLM ला run time वर तो variable वाचण्यास सांगते. Literal key file मध्ये कधीही दिसत नाही. कारण तुम्ही commit करता ती file config.yaml आहे.
दोन entries मध्ये जाणीवपूर्वक strong हेच नाव आहे. एकापेक्षा जास्त deployments कडे समान model_name असल्यास router त्यांना परस्पर विनिमययोग्य मानतो आणि त्या नावासाठीच्या requests त्यांच्यात वितरित करतो. एका provider मध्ये काही काळ समस्या असली तरी strong अशा प्रकारे कार्यरत राहते. एखादा deployment cooldown मध्ये गेल्यावर (खाली पाहा), strong साठीच्या नवीन requests दुसऱ्या deployment कडे जातात.
num_retries: 2 retry करता येणाऱ्या error साठी जास्तीत जास्त दोनदा retry करते. या retries मध्ये त्याच model group मधील दुसरा उपलब्ध deployment निवडला जाऊ शकतो. 2026-10-29 रोजी तपासलेल्या LiteLLM च्या architecture docs मध्ये group अंतर्गत retries आणि cross-group fallbacks हे स्वतंत्र टप्पे असल्याचे नमूद आहे. त्यामुळे strong साठीचा retry weighted failover सक्षम न करताही दुसऱ्या provider कडे जाऊ शकतो. त्या retries संपल्यानंतरच fallback सक्रिय होतो.
allowed_fails आणि cooldown_time हे router options आहेत, त्यामुळे ते router_settings अंतर्गत असतात. Proxy त्या section वरून router तयार करतो. v1.95.0 मध्ये litellm_settings अंतर्गत लिहिलेला cooldown_time router पर्यंत पोहोचत नाही. त्यामुळे cooldowns शांतपणे 5 seconds या default वरच राहतात. cooldown_time: 30 deployment cooldown मध्ये गेल्यानंतर किती वेळ rotation मधून बाहेर राहील ते ठरवते. Configuration reference नुसार allowed_fails म्हणजे cooldown_time कालावधीत deployment ने ओलांडलेली failure count. v1.95.0 source मध्ये allowed_fails: 3 हे default आहे. ते default ठेवले असता router अंगभूत triggers वापरतो. तुम्ही वेगळी संख्या सेट केल्यावरच failure count लागू होते. या triggers मध्ये एकापेक्षा जास्त deployments असलेल्या group साठी 429 response मिळताच होणारा cooldown, अशा group साठी किमान 5 requests झाल्यानंतर चालू minute मध्ये 50% पेक्षा जास्त failures, तसेच router retry करणार नाही अशा errorsचा समावेश होतो. चुकीच्या key मुळे मिळणारा 401 याचे उदाहरण आहे. सर्व requests चालू minute मध्ये fail झाल्या आणि traffic SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD पर्यंत पोहोचला तर single deployment साठीही स्वतंत्र trigger cooldown लागू करतो. SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD चे default 1000 requests आहे. त्यामुळे दोन deployments असलेल्या strong मध्ये burst दरम्यान provider ने 500 errors परत केल्यास प्रत्येक request वर त्याचा पुन्हा प्रयत्न होत नाही. मात्र दर काही मिनिटांनी एक 500 error आल्यास cooldown लागू होत नाही. bulk कडे केवळ एक deployment आहे. त्यामुळे failure rate trigger त्याला लागू होत नाही. एका minute मध्ये 1000 requestsपेक्षा कमी असलेला 500 errorsचा burst आला तरी तो rotation मध्ये राहतो. त्याच्या callers चे संरक्षण num_retries आणि त्यानंतर strong कडे होणारा fallback करतो.
fallbacks आणि context_window_fallbacks यांचे triggers वेगवेगळे आहेत. यांपैकी दुसरा trigger उपयुक्त असूनही लोक तो अनेकदा वगळतात.
- Primary call fail झाल्यावर
fallbacksसक्रिय होतो. - Provider ने त्या model च्या context window पेक्षा request मोठी असल्यामुळे ती नाकारल्यावर
context_window_fallbacksसक्रिय होतो. त्यामुळे oversized prompt caller ला error परत देण्याऐवजी पुरेशी जागा असलेल्या model कडे पाठवला जातो.
Provider ने content policy मुळे request नाकारल्यास त्यासाठी content_policy_fallbacks देखील आहे. अशा calls पाठवण्यासाठी योग्य ठिकाण असल्यासच ते सेट करा.
VPS वर Docker Compose सह LiteLLM तैनात करा
config.yaml, docker-compose.yml आणि .env या तीन फाइल्स असलेली एक directory तयार करा. Upstream quickstart latest tag वापरतो. त्याऐवजी release tag निश्चित करा. त्यामुळे फाइल संपादित केल्यावरच upgrade होईल आणि rollback एका ओळीने करता येईल. मात्र tag स्वतःहून समान contents ची हमी देत नाही, कारण image tags बदलता येतात आणि publisher एखाद्या tag कडे नवीन image निर्देशित करू शकतो. docker compose up -d ने पुढील महिन्यात आज दिलेला gateway अगदी तसाच द्यावा असे आवश्यक असल्यास, image digest देखील जोडा. त्याचा नमुना ghcr.io/berriai/litellm:v1.95.0@sha256:<digest> असा आहे; docker buildx imagetools inspect ghcr.io/berriai/litellm:v1.95.0 तो दाखवते.
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} चे substitution करण्यासाठी आणि दुसऱ्यांदा env_file द्वारे प्रत्येक variable container मध्ये पाठवण्यासाठी.
v1.95.0 हा August 2026 मधील current release होता. प्रकल्पाचे releases page तपासा आणि deployment वेळी current असलेला 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 मध्ये जोडते आणि ते ufw च्या rules पूर्वी evaluate होतात. त्यामुळे ufw deny 4000 हे थांबवू शकत नाही. Self-hosted gateway अनवधानाने उघडा राहण्याची ही सर्वात सामान्य पद्धत आहे: Docker container port थेट ufw च्या पलीकडे कसा publish करते ते पहा. बाहेरून येणारा traffic reverse proxy मार्फत पोहोचतो.
प्रोव्हायडर कीज (keys) इमेजच्या बाहेर ठेवा
.env फाईलमध्ये सर्व सिक्रेट्स असतात. रन-टाइमला ती एनवायरमेंट व्हेरिएबल म्हणून पास केली जाते, त्यामुळे ती कधीही इमेजमध्ये समाविष्ट (bake) केली जात नाही आणि ती कधीही कमिट केली जात नाही.
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 कीज खऱ्या रँडमनेससह जनरेट करा आणि त्यानंतर फाईल लॉक करा:
printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .envLITELLM_MASTER_KEY हे ॲडमिन क्रेडेंशियल आहे. हे मॅनेजमेंट API ला ऑथेंटिकेट करते आणि /ui वरील ॲडमिन UI साठी हा पासवर्ड आहे. कोणत्याही ॲप्लिकेशनकडे हे कधीही नसावे.
LITELLM_SALT_KEY डेटाबेसमध्ये साठवलेल्या प्रोव्हायडर क्रेडेंशियल्सना एनक्रिप्ट करते. हे एकदा सेट करा आणि तसेच राहू द्या. जर तुम्ही ते नंतर बदलले, तर आधी साठवलेली क्रेडेंशियल्स डिक्रिप्ट करता येणार नाहीत. परिणामी, गेटवे सामान्यपणे सुरू होईल, परंतु त्यानंतर त्या प्रोव्हायडर्सना केलेली प्रत्येक कॉल ऑथेंटिकेशनमध्ये अपयशी ठरेल.
STORE_MODEL_IN_DB=True तुम्हाला config.yaml ला स्पर्श न करता ॲडमिन UI वरून मॉडेल्स जोडण्याची आणि संपादित करण्याची सुविधा देते. हे सोयीचे आहे, परंतु यामुळे तुमची माहितीचे स्रोत (source of truth) दोन भागात विभागले जातात. यापैकी अधिकृत स्रोत कोणता हे ठरवा आणि तो निर्णय config च्या शेजारी लिहून ठेवा.
ज्या तर्कामुळे कीज कॉन्फिग फाईलच्या बाहेर ठेवल्या जातात, त्याच तर्कामुळे त्या तुम्ही एजंटला दिलेल्या टूल्सच्या बाहेरही ठेवल्या पाहिजेत. प्रोव्हायडर सिक्रेट्सना AI एजंट्सपासून दूर ठेवणे या पॅटर्नबद्दल माहिती देते, आणि Docker Compose मधील env फाईल्स आणि सिक्रेट्स त्याची कार्यपद्धती स्पष्ट करते.
सर्व्हिस सुरू करा आणि पहिल्या बूटवर लक्ष ठेवा:
docker compose up -d
docker compose logs -f litellmते प्रत्यक्षात काम करत असल्याची खात्री करा
येथे दोन अनधिकृत (unauthenticated) प्रोब्स आणि एक अधिकृत (authenticated) प्रोब आहे, आणि ते वेगवेगळ्या कारणांमुळे अयशस्वी होतात.
curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readiness/health/liveliness ला कोणत्याही ऑथेंटिकेशनची गरज नसते आणि प्रक्रिया सुरू असताना ते "I'm alive!" असे उत्तर देते. /health/readiness ला देखील कोणत्याही ऑथेंटिकेशनची गरज नसते. ते "status": "healthy" आणि db फील्ड असलेला JSON ऑब्जेक्ट परत करते, किंवा डेटाबेस पोहोचण्यायोग्य नसल्यास 503 एरर देते. तुमची मॉनिटरिंग सिस्टिम readiness वर सेट करा, कारण liveliness अशा गेटवेवरही 'green' राहते जो एखादी व्हर्च्युअल की शोधू शकत नाही.
अधिकृत चेक तो आहे जो प्रोव्हायडर्सशी संवाद साधतो:
curl -s http://127.0.0.1:4000/health \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"ते healthy_endpoints आणि unhealthy_endpoints ॲरेसह उत्तर देते. unhealthy_endpoints मध्ये असलेला मॉडेल जर ऑथेंटिकेशन एरर दाखवत असेल, तर याचा अर्थ .env मधील प्रोव्हायडर की चुकीची आहे किंवा गहाळ आहे, आणि हीच ती त्रुटी आहे जी तुम्हाला आता शोधायची आहे. background_health_checks: true सेट केलेले असल्यामुळे, प्रॉक्सी स्वतःहून दर health_check_interval सेकंदांनी हे प्रोब्स चालवते आणि /health शेवटचा निकाल परत करते, त्यामुळे वारंवार पोलिंग केल्याने प्रत्येक वेळी तुमच्या प्रोव्हायडर्सना टेस्ट रिक्वेस्ट पाठवली जात नाही.
आभासी keys आणि प्रत्येक key साठी budgets
प्रत्येक application ला स्वतंत्र key मिळते. ही 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ही या key कडून कोणत्या requests करता येतील याची allowlist आहे. वरील key फक्तbulkमागू शकते.max_budget: 5आणिbudget_duration: "30d"मिळून प्रत्येक calendar month साठी five US dollars इतके असतात. LiteLLM प्रत्येक महिन्याच्या 1 तारखेला मध्यरात्री30dbudget reset करते. तुम्हीlitellm_settingsअंतर्गतtimezoneसेट केले नसेल, तर ही वेळ UTC असते. हा कालावधी rolling 30 days नसतो. त्यामुळे key ने five dollars खर्च केल्यानंतर ती पुढील 1 तारखेपर्यंत काम करणे थांबवते.rpm_limitआणिtpm_limitया key साठी स्वतंत्रपणे प्रति मिनिट requests आणि tokens ची कमाल मर्यादा ठरवतात.key_aliasहे सहा आठवड्यांनंतर spend log मध्ये तुम्हाला ओळखता येणारे नाव असते. ते नेहमी सेट करा.
Budget संपल्यावर call budget_exceeded प्रकारच्या 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 सेट केल्यास आधीचा code पुन्हा वापरला जातो. वास्तविक rpm_limit आणि tpm_limit hits साठी दोन्ही releases मध्ये 429 परत मिळतो. प्रत्येक upgrade नंतर तुम्हाला कोणता code मिळतो ते तपासा.
Status code मुळे हा प्रकार गोंधळात टाकतो, कारण कोणताही code "budget" असे सांगत नाही. Client library 429 ला rate limit म्हणून नोंदवू शकते आणि backoff सह retry करू शकते. मात्र reset होईपर्यंत budget पुन्हा उपलब्ध होणार नसतो. तीच library 422 ला process न करता आलेली request म्हणून नोंदवते. Response body status code सोबत log करा. अन्यथा budget संपल्याचे प्रत्येक वेळी वेगळ्या समस्येसारखे दिसेल.
त्याच management API द्वारे keys तपासा आणि बदल करा:
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 वर सेट करा. JavaScript आणि TypeScript client मध्ये याच दोन options साठी baseURL आणि apiKey वापरले जातात.
config.yaml मधील routing policy आता caller ला याची माहिती नसतानाही लागू होते. bulk साठीची request स्वस्त मॉडेलकडे जाते. त्या call चे retries संपल्यानंतरही अपयश आल्यास, request पुन्हा strong विरुद्ध पाठवली जाते. prompt bulk साठी खूप मोठा असल्यास, त्रुटी परत करण्याऐवजी context_window_fallbacks ती strong कडे पाठवते. classification pass किंवा summarising backlog यांसारखे मोठ्या प्रमाणातील काम default ने स्वस्त मॉडेलवर चालते; फक्त कठीण requests साठी अधिक खर्च होतो.
tool-using agents साठी gateway उपयुक्त ठरण्याचे हे आणखी एक कारण आहे. त्याच VPS वरील MCP (model context protocol) server आणि ते नियंत्रित करणारा agent दोघेही एकाच endpoint कडे निर्देशित करता येतात. त्यामुळे दोघांपैकी कोणताही पुन्हा deploy न करता त्यांच्यामागील मॉडेल बदलता येते.
फॉलबॅक झाले हे कसे कळेल?
हा failure mode खर्चिक ठरतो, कारण काहीही बिघडलेले दिसत नाही. यशस्वी फॉलबॅकनंतर HTTP 200 आणि सामान्य response body मिळते. तुमचे स्वस्त 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हे request ज्या model नावाखाली route केले गेले त्याचे नाव आहे, उदाहरणार्थbulk.x-litellm-model-idहा response देणाऱ्या deployment चा ID आहे. हा ID/v1/model/info?litellm_model_id=...वापरून शोधता येतो. हा ID तुमच्याbulkdeployments पैकी नसेल, तर फॉलबॅक झाला आहे.x-litellm-attempted-fallbacksआणिx-litellm-attempted-retriesफॉलबॅकची संख्या मोजतात. प्रणाली निरोगी असताना यापैकी कोणत्याही header मध्ये 0 पेक्षा मोठी संख्या नसते.x-litellm-response-costहा त्या एकाच call चा US dollars मधील खर्च आहे.x-litellm-call-idहा तोच call logs मध्ये शोधण्यासाठी वापरायचा identifier आहे.
प्रत्येक request वर x-litellm-attempted-fallbacks नोंदवा आणि त्याचे मूल्य 0 पेक्षा जास्त असेल तेव्हा alert पाठवा. ही एकच संख्या कार्यरत routing policy आणि शांतपणे “नेहमी महागडे model वापरा” अशी झालेली routing policy यांमधील फरक दाखवते.
याची संपूर्ण आवृत्ती tracing आहे आणि त्यासाठी स्वतंत्र setup आवश्यक आहे: agent calls साठी self-hosted Langfuse. LiteLLM मध्ये हा callback उपलब्ध आहे. त्यामुळे wiring साठी credentialsसह दोन ओळी पुरतात.
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 आणि त्यानंतरच्या आवृत्त्यांसाठी LiteLLM च्या Langfuse पृष्ठावर आता langfuse_otel preset ची शिफारस केली आहे; वरील langfuse callback चे documentation अजूनही उपलब्ध आहे. failure_callback आणि success_callback दोन्ही सेट करा. हे वगळल्यास, काहीही चुकीचे झाले नाही अशाच requests चे traces तुमच्याकडे राहतील. यापासून स्वतंत्रपणे LiteLLM प्रत्येक request साठी Postgres मध्ये spend row लिहिते आणि /ui वरील Admin UI ती table वाचते. Traffic वाढल्यावर ही table मोठी होते, त्यामुळे कमी disk space असलेल्या प्रणालीवर तिचे निरीक्षण करा.
गेटवेला रिव्हर्स प्रॉक्सीच्या मागे ठेवा
बॉक्सच्या बाहेरील कोणत्याही गोष्टीने पोर्ट 4000 वर पोहोचू नये. Nginx किंवा Caddy मध्ये TLS टर्मिनेट करा आणि विनंत्या 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;
}यातील दोन ओळी अशा आहेत ज्यांकडे लोक दुर्लक्ष करतात. proxy_buffering off महत्त्वाचे आहे कारण स्ट्रीमिंग पूर्ण होणे ही server-sent events ची मालिका असते, आणि बफरिंग सुरू असल्यास Nginx ते चंक्स फॉरवर्ड करण्यापूर्वी बफरमध्ये गोळा करते, ज्यामुळे क्लायंटला मिळणारा डेटा उशिरा मिळतो. proxy_read_timeout 600s महत्त्वाचे आहे कारण Nginx चा 60 सेकंदांचा डीफॉल्ट कालावधी हा गेटवेकडून दोन रीड्समधील जास्तीत जास्त प्रतीक्षा वेळ आहे, संपूर्ण प्रतिसादाची मर्यादा नाही. नॉन-स्ट्रीम्ड पूर्णता जनरेशन पूर्ण होईपर्यंत काहीही पाठवत नाही, त्यामुळे एखादी मोठी जनरेशन 60 सेकंदांपेक्षा जास्त वेळ घेते आणि क्लायंटला 504 एरर मिळतो, तर एरर लॉगमध्ये upstream timed out (110: Connection timed out) while reading response header from upstream नोंदवले जाते. स्ट्रीमिंग पूर्णता जी चंक्स पाठवत राहते ती 60 सेकंदांपेक्षा जास्त काळ चालू शकते; जर मॉडेलने तितका वेळ काहीही प्रतिसाद दिला नाही तरच टाइमआउट होतो.
प्रमाणपत्रासाठी, Nginx वर Let's Encrypt सह Certbot हा सर्वात सोपा मार्ग आहे. जर बॉक्स आधीच अनेक कंटेनर्स चालवत असेल, तर अनेक Compose ॲप्सच्या समोर Traefik राउटिंग आणि प्रमाणपत्रे एकाच ठिकाणी हाताळते.
गेटवे आता अपयशाचे एकच केंद्र (single point of failure) बनले आहे
तुम्ही काय तयार केले आहे याबद्दल प्रामाणिक राहा. तुमच्या मालकीचे प्रत्येक ॲप्लिकेशन आता एका VPS वरील एका कंटेनरवर अवलंबून आहे. जेव्हा तो बंद असतो, तेव्हा कोणतीही सेवा कोणत्याही मॉडेलला कॉल करू शकत नाही, अगदी त्या प्रोव्हाइडर्सना सुद्धा जे पूर्णपणे व्यवस्थित काम करत आहेत. यातून चार गोष्टी निष्पन्न होतात.
- चुकीच्या कॉन्फिगरेशनमुळे सर्व काही एकाच वेळी बंद पडते.
restart: unless-stoppedक्रॅश झाल्यानंतर पुन्हा सुरू होते, आणि ते अशा कंटेनरला पुन्हा सुरू करते जो config.yaml पार्स करू शकत नाही, हे वारंवार घडते. प्रत्येक कॉन्फिगरेशन बदलानंतरdocker compose logs litellmवाचा आणि कॉन्फिगरेशनमध्ये बदल तेव्हाच करा जेव्हा तुमच्याकडे ते तपासण्यासाठी वेळ असेल. - कॅशे मिस (cache miss) झाल्यास Postgres विनंतीच्या मार्गामध्ये (request path) येते. जेव्हा की (key) कॅशेमध्ये नसते तेव्हा व्हर्च्युअल की लूकअप त्याचा वापर करतो; रिस्पॉन्स मिळाल्यानंतर स्पेंड रेकॉर्डिंग (spend recording) असिंक्रोनस पद्धतीने चालते.
/health/readinessने 503 एरर देणे ही तुमची चेतावणी आहे की गेटवे चालू आहे पण यापैकी काहीही करू शकत नाही. - प्रथम कोअर्सचा (cores) वापर करा, त्यानंतर इन्स्टन्सेस वाढवा. प्रकल्पाचे उत्पादन मार्गदर्शन (production guidance) जे प्रति इन्स्टन्स एक वर्कर (
--num_workers 1) सुचवते, ते Kubernetes किंवा इतर पॉड ऑटोस्केलरसाठी आहे जे तुमच्यासाठी इन्स्टन्सेस वाढवतात. एका सिंगल VM किंवा अशा बेअर कंटेनरसाठी हे उलट सांगते: वर्करची संख्या मशीनच्या vCPU संख्येइतकी सेट करा. वरील 1 vCPU बॉक्सवर ती अजूनही--num_workers 1आहे; मोठ्या बॉक्सवर ती वाढवा आणि लक्षात ठेवा की प्रत्येक वर्करची स्वतःची मेमरी असते. लोड बॅलन्सरच्या मागे दुसरा गेटवे लावल्यास सिंगल कंटेनरची समस्या दूर होते. पण त्यामुळे डेटाबेसची समस्या दूर होत नाही. - जे तुम्ही पुन्हा तयार करू शकत नाही त्याचा बॅकअप घ्या. हे
config.yamlआणि.envआहे, सोबत डेटाबेसचाpg_dumpदेखील आहे.LITELLM_SALT_KEYगमावल्यास त्या डंपमधील एनक्रिप्टेड प्रोव्हाइडर क्रेडेंशियल्स निरुपयोगी ठरतात, म्हणून env फाईल आणि डंप एकाच बॅकअप जॉबमध्ये असावेत: restic बॅकअप ऑफ-बॉक्स स्टोरेजवर.
अपग्रेड करण्यासाठी इमेज टॅग एडिट करा आणि docker compose up -d रन करा. LiteLLM स्टार्टअपवर डीफॉल्टनुसार prisma migrate deploy रन करते, त्यामुळे नवीन कंटेनर पहिल्या बूटवर डेटाबेस स्कीमा मायग्रेट करतो. टॅग बदलण्यापूर्वी डंप घ्या, कारण जुनी इमेज परत टाकल्याने आधीच झालेली मायग्रेशन प्रक्रिया पूर्ववत होत नाही.
तुम्ही ज्या व्हर्जनवर पोहोचता त्याव्यतिरिक्त, तुम्ही मध्ये सोडलेल्या प्रत्येक व्हर्जनच्या रिलीज नोट्स वाचा. v1.95.0 वरून v1.104.0 किंवा त्यानंतरच्या व्हर्जनवर जाणे अनेक महत्त्वाचे बदल (breaking changes) घडवून आणते: वरील बजेट स्टेटस कोड, असा प्रॉक्सी जो अनसेट, रिकामी किंवा सार्वजनिकरित्या ज्ञात मास्टर की असल्यास सुरू होण्यास नकार देतो, आणि असा प्रॉक्सी जो स्टार्टअपवर डेटाबेस सेटअप अयशस्वी झाल्यास बंद होतो, जे restart: unless-stopped अंतर्गत रिस्टार्ट लूप म्हणून दिसते. v1.102.x किंवा त्यापूर्वीच्या व्हर्जनवरून येत असल्यास, v1.104.0 च्या नोट्स तुम्हाला दोन LiteLLM_SpendLogs इंडेक्स स्वतः तयार करण्यासही सांगतात.
FAQ
LiteLLM प्रत्येक कॉलमध्ये जाणवण्याजोगा विलंब जोडते का?
नोव्हेंबर 2026 मधील README मध्ये प्रकल्पाने 1000 requests per second वर 95th percentile मध्ये 8 ms असा आकडा प्रकाशित केला आहे. हा vendor ने दिलेला आकडा आहे असे समजा. तुमच्या latency वर प्रत्यक्ष परिणाम करणारी गोष्ट म्हणजे तुमचे applications आणि gateway यांच्यातील network distance, कारण प्रत्येक कॉलमध्ये तुम्ही आणखी एक round trip जोडला आहे. Gateway ला त्याला कॉल करणाऱ्या applications च्या त्याच region मध्ये चालवा. त्यानंतर प्रत्यक्ष response वरील x-litellm-overhead-duration-ms header वापरून तुमचा स्वतःचा overhead मोजा.
nginx समोर ठेवल्यानंतर streaming का बंद झाले?
कारण nginx upstream responses default ने buffer करते आणि streaming completion ही server-sent events ची मालिका असते. proxy_buffering सुरू असल्यास nginx chunks buffers मध्ये जमा करून नंतर forward करते. त्यामुळे client कडे delivery उशिरा होते. location block मध्ये proxy_buffering off; सेट करा. त्याच block मध्ये proxy_read_timeout चे मूल्यही वाढवा. Default ने gateway कडून 60 seconds पर्यंत data न आल्यास nginx connection बंद करते. दीर्घकाळ चालणारी non-streamed generation सहजपणे ही मर्यादा गाठू शकते आणि client ला 504 मिळतो.
Virtual key चे budget संपल्यावर काय होते?
कॉल budget_exceeded प्रकारच्या error सह fail होतो आणि message चे स्वरूप Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget> सारखे असते. Pinned v1.95.0 वर status HTTP 429 असतो; v1.104.0 पासून default HTTP 422 असतो. यापैकी कोणताही code budget असल्याचे सांगत नाही. हाच मुख्य trap आहे: client library 429 ला rate limit समजून retry करू शकते. त्यामुळे लोक message वाचण्याऐवजी throttling शोधू लागतात. Status code सोबत response body देखील log करा. Master key विरुद्ध /key/info?key=sk-... वापरून key ची वास्तविक स्थिती तपासा. Budget खूप कमी सेट केले असल्यास /key/update वापरून मर्यादा वाढवा.
Gateway hosted models प्रमाणे local model कडेही route करू शकतो का?
होय. model_list मध्ये ही आणखी एक entry असते. ollama_chat/ prefix सोबत api_base वापरा. उदाहरणार्थ, api_base: http://ollama:11434 सोबत model: ollama_chat/llama3.1 वापरता येते. 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 सुरू करणे हे स्वतंत्र काम आहे: VPS वर Ollama वापरून LLM self-host करणे पहा.