LiteLLM ని మీ స్వంత సర్వర్లో హోస్ట్ చేయడం ఎలా?
LiteLLM ని ఉపయోగించి OpenAI అనుకూల గేట్వేని ఎలా సెటప్ చేయాలో తెలుసుకోండి. వర్చువల్ కీలు, బడ్జెట్ పరిమితులు మరియు మోడల్ ఫాల్బ్యాక్ ఫీచర్లతో మీ అన్ని LLM అభ్యర్థనలను ఒకే చోట
Self-hosted LLM gateway ఏమి చేస్తుంది
LiteLLM అనేది మీరు స్వయంగా హోస్ట్ చేసుకోగల ఒక open source LLM gateway: ఇది మీ అన్ని అప్లికేషన్లు కాల్ చేసే ఒకే ఒక HTTP endpoint. ఇది ప్రతి అభ్యర్థనను (request) దానికి తగిన provider కి పంపుతుంది. LLM అంటే large language model. ఈ gateway OpenAI chat completions API (application programming interface) ని ఉపయోగిస్తుంది, కాబట్టి ఇప్పటికే OpenAI తో పనిచేసే ఏ client library అయినా, కేవలం base URL మరియు key లలో రెండు మార్పులు చేయడం ద్వారా దీనితో పనిచేస్తుంది.
ఈ ఒక్క అదనపు పొర (indirection) ఉండటమే దీని ముఖ్య ఉద్దేశ్యం. మీ అప్లికేషన్లు ఇకపై provider credentials ను కలిగి ఉండవు. ఒక మోడల్ను మార్చాలంటే ఐదు వేర్వేరు సర్వీసులలో కోడ్ మార్చాల్సిన అవసరం లేదు, సర్వర్లోని config ఫైల్లో ఒక లైన్ మార్చితే సరిపోతుంది. ప్రతి కాల్ ఒకే process ద్వారా వెళ్తుంది కాబట్టి, బడ్జెట్ పరిమితులను విధించడానికి మరియు ఎంత ఖర్చయిందో రికార్డు చేయడానికి మీకు ఒక కేంద్ర స్థానం ఉంటుంది.
ఇది రన్ అవుతున్నప్పుడు మీకు లభించేవి ఇవే:
- ఒకే endpoint. అప్లికేషన్లు
https://gateway.example.com/v1ని లక్ష్యంగా చేసుకుని, మీరు సృష్టించినbulkలేదాstrongవంటి మోడల్ పేరును అడుగుతాయి. - Virtual keys. ప్రతి అప్లికేషన్కు దాని స్వంత మోడల్ allowlist మరియు ఖర్చు పరిమితి (spend ceiling) కలిగిన ప్రత్యేక key ఉంటుంది. మీరు ఒక key ని రద్దు చేసినా మిగిలిన వాటిపై ప్రభావం ఉండదు.
- Fallbacks. ఒక కాల్ విఫలమైనా లేదా prompt పరిమాణం ఎక్కువగా ఉన్నా, అది స్వయంచాలకంగా వేరొక మోడల్ ద్వారా మళ్ళీ ప్రయత్నించబడుతుంది.
- Logged record. ప్రతి అభ్యర్థన దాని ఖర్చుతో సహా రికార్డ్ చేయబడుతుంది, కాబట్టి "ఏ అప్లికేషన్ ఎంత ఖర్చు చేసింది" అనే ప్రశ్నకు సమాధానం దొరుకుతుంది.
గేట్వేను మీరే ఎందుకు నిర్వహించుకోవాలి
Managed router అనేది మీ ప్రతి అభ్యర్థన మధ్యలో వేరొకరి ప్రాసెస్ను ఉంచుతుంది. దీన్ని మీరే నిర్వహించుకోవడం వల్ల మీ ప్రొవైడర్ కీలు మరియు మీ ప్రాంప్ట్ టెక్స్ట్ మీరు నియంత్రించే బాక్స్లోనే ఉంటాయి. దీనికి అయ్యే ఖర్చు వాస్తవం: ప్రతి అప్లికేషన్ ఆధారపడే ఒక ముఖ్యమైన భాగాన్ని ఇప్పుడు మీరు నిర్వహిస్తున్నారు. ఈ గైడ్లోని చివరి విభాగం ఆ ఖర్చు గురించి వివరిస్తుంది, ఎందుకంటే చాలా కథనాలు ఈ విషయాన్ని వదిలేస్తాయి.
మీకు కావలసినవి
- Ubuntu 24.04 నడుస్తున్న ఒక VPS (virtual private server), దీనిలో Docker మరియు Compose plugin ఇన్స్టాల్ అయి ఉండాలి.
- బాహ్య యంత్రాలు TLS (transport layer security) ద్వారా ఈ గేట్వేని చేరుకోవాలంటే, దానికి అనుసంధానించబడిన ఒక domain name ఉండాలి.
- కనీసం ఒక provider API key ఉండాలి.
ఈ గేట్వే ఎటువంటి inference నిర్వహించదు. ఇది అభ్యర్థనలను పంపి, సమాధానాలను తిరిగి స్ట్రీమ్ చేస్తుంది, కాబట్టి దీని CPU లోడ్ మోడల్ పరిమాణంపై కాకుండా అభ్యర్థనల సంఖ్యపై ఆధారపడి ఉంటుంది. 1 vCPU ఉన్న సర్వర్ ఎటువంటి ఇబ్బంది లేకుండా కొన్ని అంతర్గత అప్లికేషన్లను నిర్వహించగలదు. గేట్వే ప్రతి అభ్యర్థనకు ఒక spend row ను రాస్తుంది కాబట్టి, డేటాబేస్ పరిమాణం మాత్రమే పెరుగుతుంది.
ముందుగా config.yaml రాయండి
క్లయెంట్ ఏ models ను అభ్యర్థించవచ్చో config file నిర్ణయిస్తుంది. పైస్థాయి నాలుగు 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 అనేది provider/model రూపంలో రాసే అసలు model. మీ models కు vendor పేరు కాకుండా వాటి పని ఆధారంగా పేర్లు పెట్టండి. bulk ను అభ్యర్థించే application, వచ్చే నెలలో bulk వేరే model కావాలని మీరు నిర్ణయించినా పనిచేస్తూనే ఉంటుంది.
api_key: os.environ/ANTHROPIC_API_KEY ఆ variable ను runtime లో చదవమని LiteLLM కు చెబుతుంది. 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 ను గరిష్ఠంగా రెండుసార్లు మళ్లీ ప్రయత్నిస్తుంది. ఆ retries అదే model group లో అందుబాటులో ఉన్న మరొక deployment ను ఎంచుకోవచ్చు. 2026-10-29న పరిశీలించిన LiteLLM architecture docs ప్రకారం, group లోపల retries మరియు cross-group fallbacks వేర్వేరు దశలు. అందువల్ల strong కోసం చేసే retry weighted failover ను enable చేయకుండానే మరొక 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 ప్రారంభమైన తర్వాత deployment ఎంతసేపు rotation నుండి బయట ఉండాలో cooldown_time: 30 నిర్ణయిస్తుంది. Cooldown ప్రారంభించే ముందు cooldown_time వ్యవధిలో deployment అధిగమించాల్సిన failure count గా configuration reference allowed_fails ను వివరిస్తుంది. v1.95.0 source లో allowed_fails: 3 default గా ఉంటుంది. దాని default విలువలో router అంతర్నిర్మిత triggers నే ఉపయోగిస్తుంది. మీరు వేరే సంఖ్యను సెట్ చేసినప్పుడే failure count అమలులోకి వస్తుంది. ఈ triggers లో ఒకటి, ఒక group లో ఒకటి కంటే ఎక్కువ deployments ఉన్నప్పుడు 429 response వచ్చిన వెంటనే cooldown ప్రారంభించడం. అలాగే అలాంటి group కు కనీసం 5 requests వచ్చిన తర్వాత ప్రస్తుత minute లో failures 50% కంటే ఎక్కువైతే cooldown ప్రారంభమవుతుంది. 401 వంటి retry చేయని errors కూడా cooldown కు కారణమవుతాయి. ఒకే deployment ఉన్నప్పుడు మరో trigger పనిచేస్తుంది. ప్రస్తుత minute లోని అన్ని requests విఫలమై, traffic SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD కు చేరితే ఆ deployment cooldown లోకి వెళ్తుంది. దీని default 1000 requests. కాబట్టి రెండు deployments ఉన్న strong విషయంలో provider వరుసగా 500s పంపితే ప్రతి request కు దాన్ని మళ్లీ ప్రయత్నించకుండా ఆపేస్తుంది. అయితే ప్రతి కొన్ని minutes కు ఒక 500 మాత్రమే వస్తే cooldown ప్రారంభం కాదు. bulk కు ఒకే deployment ఉంది కాబట్టి failure rate trigger దానికి వర్తించదు. ఒక minute లో requests సంఖ్య 1000 కంటే తక్కువగా ఉన్నంత వరకు వరుస 500s వచ్చినా అది rotation లోనే ఉంటుంది. దాని callers ను రక్షించేది num_retries, తరువాత strong కు వెళ్లే fallback.
fallbacks మరియు context_window_fallbacks కు triggers వేర్వేరుగా ఉంటాయి. వీటిలో చాలామంది దాటవేసే రెండవదే ఉపయోగకరమైనది.
- ప్రాథమిక call విఫలమైనప్పుడు
fallbacksఅమలవుతుంది. - ఆ model యొక్క context window కంటే request పొడవుగా ఉండటం వల్ల provider దాన్ని తిరస్కరించినప్పుడు
context_window_fallbacksఅమలవుతుంది. అందువల్ల ఎక్కువ పొడవున్న prompt caller కు error ఇవ్వకుండా, దానికి తగినంత స్థలం ఉన్న model కు వెళ్తుంది.
Provider content policy కారణాలతో request ను తిరస్కరించినప్పుడు ఉపయోగించడానికి content_policy_fallbacks కూడా ఉంది. ఆ calls ను పంపడానికి సరైన స్థలం మీ వద్ద ఉన్నప్పుడు మాత్రమే దీన్ని సెట్ చేయండి.
Docker Compose తో VPSపై LiteLLM అమలు
ఈ మూడు ఫైళ్లను ఉంచే ఒక directoryని సృష్టించండి: config.yaml, docker-compose.yml మరియు .env. Upstream quickstart latest tagను ఉపయోగిస్తుంది. దానికి బదులుగా ఒక release tagను నిర్దిష్టంగా నిర్ణయించండి. అప్పుడు మీరు ఆ ఫైల్ను సవరించినప్పుడే upgrade జరుగుతుంది. Rollback కూడా ఒకే lineతో చేయవచ్చు. Tag మాత్రమే ఉంటే ఒకే contentsకు హామీ ఉండదు. Image tags మార్చగలిగేవి కాబట్టి publisher వాటిని కొత్త 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 దాన్ని 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లోకి పంపడానికి చదువుతుంది.
ఆగస్టు 2026లో v1.95.0 ప్రస్తుత releaseగా ఉంది. మీరు deploy చేసే సమయంలో project releases pageను పరిశీలించి, అప్పటికి ప్రస్తుతంగా ఉన్న versionను 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గా ఉంది. ఇది loopback interfaceపై మాత్రమే portను 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 ద్వారా వస్తుంది.
ప్రొవైడర్ కీలను ఇమేజ్ వెలుపల ఉంచండి
.env ఫైల్ ప్రతి రహస్య సమాచారాన్ని (secret) కలిగి ఉంటుంది. ఇది రన్ టైమ్లో environment variable గా పంపబడుతుంది, కాబట్టి ఇది ఎప్పటికీ ఇమేజ్లో బేక్ చేయబడదు మరియు ఎప్పటికీ కమిట్ చేయబడదు.
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 కీలను సరైన యాదృచ్ఛికతతో (randomness) రూపొందించండి, ఆపై ఫైల్ను లాక్ చేయండి:
printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .envLITELLM_MASTER_KEY అనేది అడ్మిన్ క్రెడెన్షియల్. ఇది మేనేజ్మెంట్ APIని ప్రామాణీకరిస్తుంది మరియు /ui వద్ద ఉన్న Admin UI కోసం పాస్వర్డ్గా పనిచేస్తుంది. ఏ అప్లికేషన్ కూడా దీనిని కలిగి ఉండకూడదు.
LITELLM_SALT_KEY డేటాబేస్లో నిల్వ చేయబడిన ప్రొవైడర్ క్రెడెన్షియల్స్ను ఎన్క్రిప్ట్ చేస్తుంది. దీనిని ఒక్కసారి సెట్ చేసి వదిలేయండి. దీనిని తర్వాత మార్చితే, ఇప్పటికే నిల్వ ఉన్న క్రెడెన్షియల్స్ను డిక్రిప్ట్ చేయడం సాధ్యం కాదు. అప్పుడు గేట్వే సాధారణంగానే ప్రారంభమవుతుంది, కానీ ఆ ప్రొవైడర్లకు చేసే ప్రతి కాల్ ప్రామాణీకరణ (authentication) విఫలం కావడంతో ఆగిపోతుంది.
STORE_MODEL_IN_DB=True ద్వారా మీరు config.yaml ను తాకకుండానే Admin UI నుండి మోడళ్లను జోడించవచ్చు మరియు సవరించవచ్చు. ఇది సౌకర్యవంతంగా ఉంటుంది, కానీ ఇది మీ 'source of truth' ను రెండుగా విభజిస్తుంది. ఏది ప్రామాణికమో నిర్ణయించుకోండి మరియు ఆ నిర్ణయాన్ని config పక్కన రాసి ఉంచండి.
కీలను కాన్ఫిగరేషన్ ఫైల్ వెలుపల ఉంచడానికి గల కారణాలే, మీరు ఏజెంట్కు ఇచ్చే టూల్స్ నుండి వాటిని దూరంగా ఉంచడానికి కూడా వర్తిస్తాయి. AI ఏజెంట్ల నుండి ప్రొవైడర్ రహస్యాలను దూరంగా ఉంచడం ఆ పద్ధతిని వివరిస్తుంది, మరియు Docker Compose లో env ఫైళ్లు మరియు రహస్యాలు దాని పనితీరును వివరిస్తాయి.
దీనిని ప్రారంభించి మొదటి బూట్ (boot) ను గమనించండి:
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 ఎల్లప్పుడూ గ్రీన్గానే ఉంటుంది.
ప్రామాణీకరించబడిన చెక్ అనేది ప్రొవైడర్లతో సంభాషించేది:
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 చివరి ఫలితాన్ని తిరిగి ఇస్తుంది, కాబట్టి దీనిని పోల్ (polling) చేయడం వల్ల ప్రతిసారీ మీ ప్రొవైడర్లకు టెస్ట్ రిక్వెస్ట్ పంపబడదు.
వర్చువల్ keys మరియు ప్రతి key కు బడ్జెట్లు
ప్రతి అప్లికేషన్కు master key ఆధారంగా రూపొందించిన ప్రత్యేక 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 నే అప్లికేషన్కు అందుతుంది. అప్లికేషన్కు లభించే ఏకైక సమాచారం అదే.
modelsఈ key ఏవి request చేయవచ్చో నిర్దేశించే allowlist. పై keybulkను మాత్రమే request చేయగలదు.max_budget: 5లోనిbudget_duration: "30d"విలువ ప్రతి calendar month కు ఐదు US dollars.30dbudget ను LiteLLM ప్రతి నెల 1వ తేదీ అర్ధరాత్రి reset చేస్తుంది. మీరుlitellm_settingsకిందtimezoneసెట్ చేయకపోతే ఈ సమయం UTCలో ఉంటుంది. ఇది rolling 30 days ఆధారంగా పనిచేయదు. అందువల్ల key ఐదు dollars ఖర్చు చేసిన తర్వాత, తదుపరి 1వ తేదీ వరకు పనిచేయదు.rpm_limitమరియుtpm_limitఈ key కు మాత్రమే వర్తించే requests per minute మరియు tokens per minute పరిమితులను నిర్దేశిస్తాయి.key_aliasను ఆరు వారాల తర్వాత spend log లో మీరు గుర్తించేది ఇదే. దీన్ని ఎల్లప్పుడూ సెట్ చేయండి.
బడ్జెట్ పూర్తిగా ఖర్చయినప్పుడు, call budget_exceeded రకం error తో విఫలమవుతుంది. Message ఈ ఆకారంలో ఉంటుంది:
Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>Status code release పై ఆధారపడి ఉంటుంది. నిర్ణయించిన 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 చేయవచ్చు. అయితే budget reset అయ్యే వరకు అది తిరిగి అందుబాటులోకి రాదు. అలాగే అది 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 వద్ద అమలు చేసే బడ్జెట్ పరిమితి, సమస్య agent లోనే ఉన్నప్పటికీ అమలులో ఉంటుంది. అందుకే VPS పై AI agents కోసం ఖర్చు నియంత్రణకు ఇది ప్రధాన ఆధారం.
చౌక మోడల్కు పెద్ద పరిమాణంలోని పనిని పంపండి
Client ను 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 పేర్లు భాషను బట్టి మారుతాయి. Python client లో base_url ను https://gateway.example.com/v1 కు, api_key ను virtual key కు సెట్ చేయండి. JavaScript మరియు TypeScript client calls లో ఇదే రెండు options ను baseURL మరియు apiKey అని పిలుస్తారు.
Caller కు తెలియకుండానే config.yaml లోని routing policy ఇప్పుడు వర్తిస్తుంది. bulk కోసం వచ్చిన request cheap model కు వెళ్తుంది. ఆ call retries పూర్తయిన తర్వాత విఫలమైతే, request ను strong కు వ్యతిరేకంగా మళ్లీ ప్రయత్నిస్తారు. Prompt bulk కు చాలా పొడవుగా ఉంటే, error తిరిగి ఇవ్వడానికి బదులుగా context_window_fallbacks దాన్ని strong కు పంపుతుంది. Classification pass లేదా summarising backlog వంటి bulk పనులు default గా చౌక మోడల్లో నడుస్తాయి. కఠినమైన requests కు మాత్రమే ఎక్కువ ఖర్చవుతుంది.
Tool-using agents తో gateway ఉపయోగకరంగా ఉండే సందర్భం కూడా ఇదే. అదే VPS లోని MCP (model context protocol) server మరియు దాన్ని నడిపించే agent రెండూ ఒకే endpoint వైపు చూపవచ్చు. అందువల్ల వాటిలో దేనినీ redeploy చేయకుండా, వాటి వెనుక ఉన్న model ను మార్చవచ్చు.
ఫాల్బ్యాక్ జరిగిందని ఎలా తెలుసుకోవాలి?
ఏదీ విఫలమైనట్లు కనిపించదు కాబట్టి, ఖర్చు పెంచే వైఫల్య పరిస్థితి ఇదే. విజయవంతమైన 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అనేది request ఏ model పేరుతో route చేయబడిందో చూపిస్తుంది. ఉదాహరణకుbulk.x-litellm-model-idఅనేది response ఇచ్చిన deployment యొక్క ID. దీనిని/v1/model/info?litellm_model_id=...తో lookup చేయవచ్చు. ఆ ID మీbulkdeployments లో ఏదీ కాకపోతే, fallback జరిగింది.x-litellm-attempted-fallbacksమరియుx-litellm-attempted-retriesవాటి సంఖ్యను లెక్కిస్తాయి. ఆరోగ్యకరమైన call లో రెండింటిలోనూ 0 కంటే ఎక్కువ count ఉండదు.x-litellm-response-costఅనేది ఆ ఒక్క call కు US dollars లో అయ్యే ఖర్చు.x-litellm-call-idఅనేది అదే call ను మీ logs లో కనుగొనడానికి ఉపయోగించే identifier.
ప్రతి request పై x-litellm-attempted-fallbacks ను record చేయండి. అది 0 కంటే ఎక్కువగా ఉన్నప్పుడు alert పంపండి. ఈ ఒక్క సంఖ్యే సక్రమంగా పనిచేసే routing policy కి, నిశ్శబ్దంగా "ఎల్లప్పుడూ ఖరీదైన model ను ఉపయోగించు"గా మారిన routing policy కి మధ్య తేడా.
దీనికి పూర్తి రూపం tracing. దానికి ప్రత్యేక setup అవసరం: agent calls కోసం self-hosted Langfuse tracing. 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 పేజీ ఇప్పుడు దాని langfuse_otel preset ను సిఫారసు చేస్తుంది. అయితే పై langfuse callback ఇప్పటికీ documented గా ఉంది. failure_callback తో పాటు success_callback ను కూడా set చేయండి. దీన్ని skip చేస్తే, ఏ సమస్యా జరగని calls కు సంబంధించిన traces మాత్రమే మీ వద్ద ఉంటాయి. వీటన్నింటికి వేరుగా, LiteLLM ప్రతి request కు సంబంధించిన spend row ను Postgres లో రాస్తుంది. Admin UI లోని /ui ఆ table ను చదువుతుంది. Traffic పెరిగేకొద్దీ అది కూడా పెరుగుతుంది. కాబట్టి చిన్న disk ఉన్నప్పుడు దాన్ని monitor చేయండి.
గేట్వేను రివర్స్ ప్రాక్సీ వెనుక ఉంచడం
బాహ్య ప్రపంచం నుంచి ఏదీ నేరుగా port 4000 ను చేరుకోకూడదు. TLS termination ను nginx లేదా Caddy లో పూర్తి చేసి, అభ్యర్థనలను 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 చాలా ముఖ్యమైనది, ఎందుకంటే streaming completion అనేది server-sent events యొక్క వరుస క్రమం. nginx లో buffering ఆన్లో ఉంటే, అది డేటా ముక్కలను బఫర్లలో సేకరించి ఆ తర్వాతే పంపుతుంది, దీనివల్ల క్లయింట్కు సమాచారం అందడంలో జాప్యం జరుగుతుంది. proxy_read_timeout 600s కూడా ముఖ్యమైనదే, ఎందుకంటే nginx యొక్క 60 సెకన్ల డిఫాల్ట్ సమయం అనేది గేట్వే నుంచి వచ్చే రెండు రీడ్ ఆపరేషన్ల మధ్య గరిష్ట నిరీక్షణ సమయం, ఇది మొత్తం రెస్పాన్స్ సమయం కాదు. స్ట్రీమింగ్ లేని completion లో, generation పూర్తయ్యే వరకు ఏ సమాచారం అందదు; కాబట్టి సుదీర్ఘమైన generation 60 సెకన్లు దాటితే, క్లయింట్కు 504 error వస్తుంది మరియు error log లో upstream timed out (110: Connection timed out) while reading response header from upstream నమోదవుతుంది. నిరంతరం డేటా ముక్కలను పంపే స్ట్రీమింగ్ completion 60 సెకన్ల కంటే ఎక్కువ సమయం తీసుకోవచ్చు; మోడల్ అంత సమయం పాటు నిశ్శబ్దంగా ఉంటేనే ఈ timeout ట్రిగ్గర్ అవుతుంది.
సర్టిఫికేట్ కోసం, nginx పై Certbot మరియు Let's Encrypt సులభమైన మార్గం. ఒకవేళ మీ సర్వర్లో ఇప్పటికే అనేక కంటైనర్లు నడుస్తుంటే, అనేక Compose అప్లికేషన్ల ముందు Traefik వాడటం ద్వారా routing మరియు సర్టిఫికేట్లను ఒకే చోట నిర్వహించవచ్చు.
గేట్వే ఇప్పుడు ఒకే వైఫల్య బిందువుగా మారింది
మీరు నిర్మించిన దాని గురించి వాస్తవంగా ఉండండి. మీరు కలిగి ఉన్న ప్రతి అప్లికేషన్ ఇప్పుడు ఒకే VPSలోని ఒకే కంటైనర్పై ఆధారపడి ఉంది. అది పనిచేయనప్పుడు, ఏ మోడల్ను కూడా పిలవలేరు, ఆరోగ్యంగా ఉన్న ప్రొవైడర్లు కూడా అందుబాటులో ఉండరు. దీని వల్ల నాలుగు పరిణామాలు ఉంటాయి.
- తప్పు కాన్ఫిగరేషన్ అన్నింటినీ ఒకేసారి ఆపివేస్తుంది.
restart: unless-stoppedక్రాష్ను రీస్టార్ట్ చేస్తుంది, మరియు అదిconfig.yamlను పార్స్ చేయలేని కంటైనర్ను పదేపదే రీస్టార్ట్ చేస్తుంది. ప్రతి కాన్ఫిగరేషన్ మార్పు తర్వాతdocker compose logs litellmచదవండి, మరియు వాటిని పర్యవేక్షించడానికి సమయం ఉన్నప్పుడు మాత్రమే కాన్ఫిగరేషన్ మార్పులు చేయండి. - Cache miss అయినప్పుడు Postgres అభ్యర్థన మార్గంలో ఉంటుంది. కీ కాష్లో లేనప్పుడు వర్చువల్ కీ లుకప్ దీనిని ఉపయోగిస్తుంది; రెస్పాన్స్ తర్వాత స్పెంట్ రికార్డింగ్ అసమకాలికంగా (asynchronously) జరుగుతుంది.
/health/readiness503 ఎర్రర్ను ఇస్తుందంటే, గేట్వే రన్ అవుతున్నప్పటికీ ఏదీ చేయలేకపోతోందని అర్థం. - ముందుగా కోర్లను ఉపయోగించండి, ఆపై ఇన్స్టాన్సులను జోడించండి. ప్రాజెక్ట్ యొక్క ప్రొడక్షన్ మార్గదర్శకత్వం ప్రకారం ఒక ఇన్స్టాన్సుకి ఒక వర్కర్ (
--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 లేదా అంతకంటే ఎక్కువకు మారడం వల్ల అనేక మార్పులు వస్తాయి: పైన పేర్కొన్న బడ్జెట్ స్టేటస్ కోడ్, మాస్టర్ కీ సెట్ చేయనప్పుడు లేదా ఖాళీగా ఉన్నప్పుడు లేదా బహిరంగంగా తెలిసినప్పుడు స్టార్ట్ అవ్వని ప్రాక్సీ, మరియు స్టార్టప్లో డేటాబేస్ సెటప్ విఫలమైతే ఎగ్జిట్ అయ్యే ప్రాక్సీ, ఇది restart: unless-stopped కింద రీస్టార్ట్ లూప్గా కనిపిస్తుంది. v1.102.x లేదా అంతకంటే పాత వెర్షన్ల నుండి వస్తున్నట్లయితే, v1.104.0 నోట్స్ ప్రకారం మీరు రెండు LiteLLM_SpendLogs ఇండెక్స్లను మీరే బిల్డ్ చేయాల్సి ఉంటుంది.
FAQ
ప్రతి call కు LiteLLM గమనించదగిన latency ను జోడిస్తుందా?
నవంబర్ 2026లోని READMEలో పేర్కొన్నట్లు, 1000 requests per second వద్ద 95th percentileలో 8 ms latency ఉందని project ప్రచురిస్తుంది. దీన్ని vendor figureగా పరిగణించండి. మీ latencyపై వాస్తవంగా ప్రభావం చూపేది మీ applications మరియు gateway మధ్య network distance, ఎందుకంటే ప్రతి callకు మీరు మరో round tripను జోడించారు. gatewayను దాన్ని call చేసే 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 ఆగిపోతుంది. దీర్ఘంగా సాగే non-streamed generation సులభంగా ఈ పరిమితిని చేరుతుంది. అప్పుడు clientకు 504 అందుతుంది.
virtual key బడ్జెట్ అయిపోయినప్పుడు ఏమి జరుగుతుంది?
call budget_exceeded రకం errorతో, Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget> రూపంలోని messageతో విఫలమవుతుంది. pinned v1.95.0లో status HTTP 429. v1.104.0 నుంచి default HTTP 422. ఈ రెండు codesలోనూ budget గురించి చెప్పదు. ఇదే సమస్యకు కారణం. client library 429ను rate limitగా నివేదించి retry చేయవచ్చు. అందువల్ల message చదవకుండా throttlingను వెతకడం ప్రారంభిస్తారు. status codeతో పాటు response bodyని కూడా log చేయండి. master keyతో /key/info?key=sk-...ను ఉపయోగించి key యొక్క వాస్తవ స్థితిని నిర్ధారించండి. బడ్జెట్ చాలా తక్కువగా సెట్ అయి ఉంటే /key/updateతో ceilingను పెంచండి.
gateway hosted modelsతో పాటు local modelకు కూడా route చేయగలదా?
అవును. ఇది model_listలో మరో entry. api_baseతో పాటు ollama_chat/ prefixను ఉపయోగించండి. ఉదాహరణకు 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ను మాత్రం ఎప్పుడూ ఉపయోగించవద్దు. Container host network stackను share చేసే host networking దీనికి మినహాయింపు. Local modelను ప్రారంభించడం వేరే పని. VPSలో Ollamaతో LLMను self-host చేయడం చూడండి.