LiteLLM-ஐ உங்கள் சொந்த சர்வரில் நிறுவுவது எப்படி?
LiteLLM மூலம் அனைத்து LLM சேவைகளையும் ஒரே OpenAI compatible endpoint-ல் இணைக்கலாம். VPS-ல் virtual keys, budget limits மற்றும் fallback வசதிகளை எவ்வாறு அமைப்பது என்பதை அறியுங்கள்.
self-hosted LLM gateway-ன் செயல்பாடுகள்
LiteLLM என்பது நீங்கள் சொந்தமாக host செய்யும் ஒரு open source LLM gateway ஆகும். இது ஒரு HTTP endpoint-ஐ வழங்குகிறது; உங்கள் அனைத்து applications-ம் இந்த endpoint-ஐ அழைக்கும், இது ஒவ்வொரு கோரிக்கையையும் (request) அதற்குரிய provider-க்கு அனுப்பி வைக்கும். LLM என்பது large language model-ஐக் குறிக்கும். இந்த gateway, OpenAI chat completions API (application programming interface)-ஐப் பயன்படுத்துகிறது. எனவே, ஏற்கனவே OpenAI-உடன் தொடர்புகொள்ளும் எந்தவொரு client library-யும், base URL மற்றும் key ஆகிய இரண்டையும் மாற்றிய பிறகு இதனுடன் வேலை செய்யும்.
இந்த ஒரு அடுக்கு மறைமுகத்தன்மை (indirection) தான் இதன் முக்கிய நோக்கம். உங்கள் applications-ல் provider credentials-ஐச் சேமிக்க வேண்டிய அவசியம் இருக்காது. ஒரு model-ஐ மாற்றுவதற்கு, ஐந்து வெவ்வேறு services-ல் code மாற்றங்களுக்குப் பதிலாக, server-ல் உள்ள ஒரு config file-ல் ஒரே ஒரு வரியை மாற்றினால் போதும். மேலும், ஒவ்வொரு அழைப்பும் ஒரே process வழியாகச் செல்வதால், செலவு வரம்பை (budget) நிர்ணயிக்கவும், எவ்வளவு செலவாகியுள்ளது என்பதற்கான பதிவை (record) வைத்திருக்கவும் ஒரு மைய இடம் கிடைக்கிறது.
இது இயங்கத் தொடங்கியதும் உங்களுக்குக் கிடைப்பவை:
- ஒரே endpoint. Applications
https://gateway.example.com/v1-ஐ இலக்காகக் கொண்டு, நீங்கள் உருவாக்கியbulkஅல்லதுstrongபோன்ற model பெயர்களைக் கேட்கும். - Virtual keys. ஒவ்வொரு application-க்கும் தனித்தனி key வழங்கப்படும்; அவற்றுக்கென தனித்தனி model allowlist மற்றும் செலவு வரம்பு (spend ceiling) இருக்கும். மற்றவற்றை பாதிக்காமல் நீங்கள் ஒரு key-ஐ மட்டும் revoke செய்ய முடியும்.
- Fallbacks. ஒரு அழைப்பு தோல்வியடைந்தாலோ அல்லது prompt அளவு அதிகமாக இருந்தாலோ, அது தானாகவே வேறொரு model-க்கு மாற்றப்பட்டு மீண்டும் முயற்சி செய்யப்படும் (retry).
- பதிவு செய்யப்பட்ட விவரங்கள் (logged record). ஒவ்வொரு கோரிக்கையும் அதன் செலவு விவரங்களுடன் பதிவு செய்யப்படும், எனவே "எந்த application அந்தச் செலவைச் செய்தது" என்பதற்கான விடை கிடைக்கும்.
ஏன் gateway-ஐ நீங்களே இயக்க வேண்டும்
Managed router என்பது மற்றொன்றின் process ஒவ்வொரு கோரிக்கையின் (request) இடையிலும் அமர்ந்திருக்கும் ஒரு அமைப்பாகும். நீங்களே இயக்கும்போது, உங்கள் provider keys மற்றும் prompt text ஆகியவை நீங்கள் கட்டுப்படுத்தும் ஒரு பெட்டியில் (box) இருக்கும். இதற்கான செலவு உண்மையானது: ஒவ்வொரு application-ம் சார்ந்திருக்கும் ஒரு கூறினை (component) இப்போது நீங்கள் இயக்குகிறீர்கள். இந்த வழிகாட்டியின் கடைசிப் பகுதி அந்தச் செலவைப் பற்றியது, ஏனெனில் பெரும்பாலான கட்டுரைகள் விடுபடும் பகுதி இதுவே.
தேவையானவை
- Ubuntu 24.04 இயங்கும் ஒரு VPS (virtual private server), அதில் Docker மற்றும் Compose plugin நிறுவப்பட்டிருக்க வேண்டும்.
- இயந்திரத்திற்கு வெளியே உள்ள பிற கணினிகள் TLS (transport layer security) மூலம் gateway-ஐ அணுக வேண்டுமெனில், அதற்கு ஒரு domain name சுட்டிக்காட்டப்பட்டிருக்க வேண்டும்.
- குறைந்தபட்சம் ஒரு provider API key.
இந்த gateway எந்தவொரு inference-ஐயும் செய்வதில்லை. இது கோரிக்கைகளை (requests) முன்னனுப்பி, பதில்களைத் திரும்பப் பெறுகிறது. எனவே, இதன் CPU பயன்பாடு model-ன் அளவை விட, கோரிக்கைகளின் எண்ணிக்கையைப் பொறுத்தே அமையும். ஒரு 1 vCPU கொண்ட கணினியில் எந்தப் புகாருமின்றி பல internal applications-களை இயக்க முடியும். தரவுத்தளம் (database) மட்டுமே வளரும், ஏனெனில் ஒவ்வொரு கோரிக்கைக்கும் ஒரு spend row-ஐ gateway பதிவு செய்கிறது.
முதலில் config.yaml-ஐ எழுதவும்
config கோப்புதான் எந்தெந்த models-ஐ client-கள் கேட்கலாம் என்பதைத் தீர்மானிக்கிறது. நான்கு முக்கிய பிரிவுகள் இதில் உள்ளன: 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 என்பது உங்கள் client-கள் அனுப்பும் பெயர். litellm_params.model என்பது உண்மையான model, இது provider/model என எழுதப்படும். vendor-ன் பெயருக்குப் பதிலாக, அந்த model செய்யும் வேலையின் அடிப்படையில் பெயரிடுங்கள். bulk என்று கேட்கும் ஒரு application, அடுத்த மாதம் நீங்கள் bulk-ஐ வேறொரு model-ஆக மாற்றினாலும் தொடர்ந்து வேலை செய்யும்.
api_key: os.environ/ANTHROPIC_API_KEY, அந்த variable-ஐ run time-ல் வாசிக்குமாறு LiteLLM-க்குக் கட்டளையிடுகிறது. அந்த literal key கோப்பில் இடம்பெறாது; config.yaml-ஐ நீங்கள் commit செய்வதால் இது முக்கியமானது.
இரண்டு பதிவுகள் வேண்டுமென்றே strong என்ற ஒரே பெயரைப் பகிர்ந்து கொள்கின்றன. ஒன்றுக்கும் மேற்பட்ட deployment-கள் ஒரே model_name-ஐக் கொண்டிருக்கும்போது, router அவற்றை ஒன்றுக்கொன்று மாற்றத்தக்கதாகக் கருதி, கோரிக்கைகளை அவற்றுக்கிடையே பிரித்து அனுப்பும். ஒரு provider-ல் சிக்கல் ஏற்படும்போது strong இப்படியே செயல்படுகிறது: ஒரு deployment cooldown-ல் (கீழே காண்க) இருந்தால், strong-க்கான புதிய கோரிக்கைகள் மற்றொன்றுக்குச் செல்லும்.
num_retries: 2, மீண்டும் முயற்சி செய்யக்கூடிய (retryable) பிழைகளை இரண்டு முறை வரை மீண்டும் முயற்சிக்கும். அந்த முயற்சிகள் அதே model group-ல் உள்ள மற்றொரு deployment-ஐத் தேர்ந்தெடுக்கலாம்: 2026-10-29 அன்று சரிபார்க்கப்பட்ட LiteLLM architecture ஆவணங்களின்படி, group-க்குள் நடக்கும் retries மற்றும் group-களுக்கு இடையிலான fallbacks ஆகியவை தனித்தனி நிலைகளாகும். எனவே, strong-க்கான ஒரு retry, weighted failover-ஐ இயக்காமலேயே மற்றொரு provider-க்குச் செல்லலாம். அந்த retries முடிந்த பிறகுதான் fallback செயல்படும்.
allowed_fails மற்றும் cooldown_time ஆகியவை router விருப்பங்கள், எனவே அவை router_settings-ன் கீழ் அமையும். proxy அந்தப் பிரிவிலிருந்துதான் தனது router-ஐ உருவாக்குகிறது. v1.95.0 பதிப்பில், litellm_settings-ன் கீழ் எழுதப்படும் ஒரு cooldown_time அந்த router-ஐச் சென்றடையாது; எனவே cooldown-கள் இயல்பான 5 வினாடி அளவிலேயே இருக்கும். cooldown_time: 30, ஒரு deployment cooldown ஆன பிறகு எவ்வளவு நேரம் சுழற்சியில் (rotation) இருக்காது என்பதைத் தீர்மானிக்கிறது. configuration reference, allowed_fails-ஐ ஒரு deployment cooldown ஆவதற்கு முன்பு cooldown_time காலத்திற்குள் கடக்க வேண்டிய பிழை எண்ணிக்கை என்று விவரிக்கிறது. v1.95.0 source-ல், allowed_fails: 3 என்பது default ஆகும். அதை மாற்றாதவரை router அந்த built-in triggers-ஐப் பின்பற்றும்; நீங்கள் ஒரு எண்ணை அமைக்கும்போது மட்டுமே பிழை எண்ணிக்கை கணக்கில் கொள்ளப்படும். அந்த triggers-ல் அடங்குபவை: ஒன்றுக்கும் மேற்பட்ட deployment-களைக் கொண்ட group-ல் 429 response கிடைத்தால் உடனடியாக cooldown ஆவது, ஒரு நிமிடத்தில் 5 கோரிக்கைகளுக்கு மேல் வந்த பிறகு 50%-க்கும் அதிகமான பிழைகள் ஏற்படுவது, மற்றும் 401 போன்ற router மீண்டும் முயற்சி செய்யாத பிழைகள். ஒரு நிமிடத்தில் அனைத்து கோரிக்கைகளும் தோல்வியடைந்து, போக்குவரத்து SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD-ஐ (default 1000 கோரிக்கைகள்) அடையும்போது, ஒற்றை deployment-ஐ cooldown செய்யும் தனி trigger-ம் உள்ளது. எனவே, இரண்டு deployment-களைக் கொண்ட strong-க்கு, ஒரு provider திடீரென 500 பிழைகளைத் தந்தால், அது ஒவ்வொரு கோரிக்கையிலும் தவிர்க்கப்படும்; ஆனால் அவ்வப்போது வரும் ஒரு 500 பிழை cooldown-ஐத் தூண்டாது. bulk-ல் ஒரே ஒரு deployment மட்டுமே இருப்பதால், பிழை விகித trigger அதற்குப் பொருந்தாது: ஒரு நிமிடத்தில் 1000 கோரிக்கைகளுக்குக் குறைவாக இருக்கும் வரை, 500 பிழைகள் வந்தாலும் அது சுழற்சியிலேயே இருக்கும். அதன் callers-ஐப் பாதுகாப்பது num_retries மற்றும் அதைத் தொடர்ந்து வரும் strong fallback ஆகும்.
fallbacks மற்றும் context_window_fallbacks வெவ்வேறு triggers-ஐக் கொண்டுள்ளன; இதில் இரண்டாவதுதான் மக்கள் கவனிக்கத் தவறும் பயனுள்ள அம்சம்.
fallbacks: முதன்மை அழைப்பு தோல்வியடையும் போது இது செயல்படும்.context_window_fallbacks: ஒரு model-ன் context window-ஐ விட கோரிக்கை நீளமாக இருந்தால், provider அதை நிராகரிக்கும்போது இது செயல்படும். இதனால், பிழையைத் திருப்பி அனுப்புவதற்குப் பதிலாக, அதிக இடவசதி கொண்ட model-க்கு அந்த prompt அனுப்பப்படும்.
content_policy_fallbacks என்ற ஒன்றும் உள்ளது; இது content policy காரணங்களுக்காக ஒரு provider கோரிக்கையை மறுக்கும்போது பயன்படும். அந்த அழைப்புகளை அனுப்பத் தகுந்த இடம் இருந்தால் மட்டுமே இதை அமைக்கவும்.
Docker Compose மூலம் VPS-ல் LiteLLM-ஐ நிறுவுதல்
மூன்று கோப்புகளைக் கொண்ட ஒரு கோப்பகத்தை (directory) உருவாக்கவும்: config.yaml, docker-compose.yml மற்றும் .env. அப்ஸ்ட்ரீம் குயிக்ஸ்டார்ட் (upstream quickstart) latest டேக்-ஐப் பயன்படுத்துகிறது. அதற்குப் பதிலாக ஒரு குறிப்பிட்ட ரிலீஸ் டேக்-ஐ (release tag) பயன்படுத்தவும். அப்போதுதான் நீங்கள் கோப்பைத் திருத்தும்போது மட்டுமே மேம்படுத்தல் (upgrade) நடக்கும், மேலும் ரோல்பேக் (rollback) செய்வது ஒரு வரியில் முடிந்துவிடும். இமேஜ் டேக்-கள் மாற்றக்கூடியவை (mutable) என்பதால், ஒரு டேக் மட்டும் ஒரே மாதிரியான உள்ளடக்கத்திற்கு உத்தரவாதம் அளிக்காது; வெளியீட்டாளர் ஒரு டேக்-ஐ புதிய இமேஜிற்கு மாற்றக்கூடும். அடுத்த மாதம் docker compose up -d உங்களுக்கு இன்று கிடைத்த அதே கேட்வேயை வழங்க வேண்டும் என்றால், ghcr.io/berriai/litellm:v1.95.0@sha256:<digest> என்ற வடிவத்தில் இமேஜ் டைஜெஸ்ட்-ஐயும் (image 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 கோப்பிற்குள்ளேயே ${POSTGRES_PASSWORD}-ஐ மாற்றீடு செய்ய; இரண்டாவது, env_file வழியாக ஒவ்வொரு மாறியையும் (variable) கன்டெய்னருக்குள் அனுப்ப.
v1.95.0 என்பது ஆகஸ்ட் 2026-ல் தற்போதைய ரிலீஸாக இருந்தது. திட்டத்தின் ரிலீஸ் பக்கத்தைச் சரிபார்த்து, நீங்கள் நிறுவும் போது எது தற்போதைய பதிப்போ அதைத் தேர்வு செய்யவும். ஒவ்வொரு ரிலீஸும் ஒரு கையொப்பத்தை (signature) வெளியிடுகிறது, எனவே நீங்கள் இமேஜை நம்புவதற்கு முன்பு அதைச் சரிபார்க்கலாம்:
cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0போர்ட் வரி என்பது 127.0.0.1:4000:4000 ஆகும், இது லூப்பேக் இன்டர்ஃபேஸில் (loopback interface) மட்டுமே போர்ட்டை வெளியிடுகிறது. அதற்குப் பதிலாக 4000:4000 என்று எழுதினால், உங்கள் கேட்வே முழு இணையத்திலிருந்தும் அணுகக்கூடியதாகிவிடும். ஏனெனில், Docker தனது சொந்த விதிகளை iptables FORWARD செயினில் சேர்க்கிறது, அவை ufw-ன் விதிகளுக்கு முன்பே மதிப்பீடு செய்யப்படுகின்றன, எனவே ufw deny 4000 அதைத் தடுக்காது. ஒரு self-hosted கேட்வே தற்செயலாகத் திறக்கப்படுவதற்கு இதுவே பொதுவான வழியாகும்: Docker எவ்வாறு ufw-ஐத் தாண்டி கன்டெய்னர் போர்ட்டை வெளியிடுகிறது என்பதைப் பார்க்கவும். வெளிப்புறத்திலிருந்து வரும் டிராஃபிக் ரிவர்ஸ் ப்ராக்ஸி (reverse proxy) வழியாகவே வர வேண்டும்.
Provider keys-ஐ image-க்குள் வைக்க வேண்டாம்
.env கோப்பு அனைத்து ரகசியங்களையும் கொண்டுள்ளது. இது run time-ல் 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) உருவாக்கி, பின் கோப்பைப் பாதுகாக்கவும்:
printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .envLITELLM_MASTER_KEY என்பது நிர்வாகி சான்றாகும் (admin credential). இது management API-ஐ அங்கீகரிக்கிறது மற்றும் /ui-ல் உள்ள Admin UI-க்கான கடவுச்சொல்லாகும். எந்தவொரு application-மும் இதை வைத்திருக்கக்கூடாது.
LITELLM_SALT_KEY என்பது database-ல் சேமிக்கப்பட்டுள்ள provider சான்றுகளை குறியாக்க (encrypt) செய்கிறது. இதை ஒருமுறை அமைத்து அப்படியே விட்டுவிடவும். இதை மாற்றினால், ஏற்கனவே சேமிக்கப்பட்ட சான்றுகளை மறைகுறியாக்க (decrypt) முடியாது; இதனால் gateway சாதாரணமாகத் தொடங்கும், ஆனால் அந்த providers-க்கு செய்யப்படும் ஒவ்வொரு அழைப்பும் அங்கீகாரப் பிழையில் (authentication failure) முடியும்.
STORE_MODEL_IN_DB=True, config.yaml-ஐத் தொடாமலேயே Admin UI-லிருந்து models-ஐச் சேர்க்கவும் திருத்தவும் உங்களை அனுமதிக்கிறது. இது வசதியானது, ஆனால் இது உங்கள் source of truth-ஐ இரண்டாகப் பிரிக்கிறது. எது முதன்மையானது என்பதை முடிவு செய்து, அந்த முடிவை config-க்கு அருகில் எழுதி வைக்கவும்.
config கோப்பில் keys-ஐ வைக்காமல் இருப்பதற்கான அதே காரணம்தான், நீங்கள் ஒரு agent-க்கு வழங்கும் கருவிகளிலும் அவற்றை வைக்காமல் இருக்க உதவுகிறது. AI agents-ல் provider secrets-ஐத் தவிர்த்தல் அந்த முறையை விளக்குகிறது, மேலும் Docker Compose-ல் env கோப்புகள் மற்றும் secrets அதன் செயல்பாடுகளை விளக்குகிறது.
இதை இயக்கி, முதல் boot-ஐக் கவனிக்கவும்:
docker compose up -d
docker compose logs -f litellmஇது சரியாகச் செயல்படுகிறதா என்று சரிபார்த்தல்
அங்கீகாரம் தேவைப்படாத இரண்டு ஆய்வுகளும் (probes), அங்கீகாரம் தேவைப்படும் ஒரு ஆய்வும் உள்ளன. இவை வெவ்வேறு காரணங்களுக்காகத் தோல்வியடைகின்றன.
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 object-ஐத் தரும்; database-ஐ அணுக முடியாவிட்டால் 503 பிழையைத் தரும். உங்கள் கண்காணிப்பு அமைப்பை readiness-க்கு அமைக்கவும், ஏனெனில் ஒரு virtual key-ஐக் கண்டறிய முடியாத gateway-லும் liveliness எப்போதும் green நிலையிலேயே இருக்கும்.
provider-களுடன் தொடர்புகொள்ளும் அங்கீகாரம் தேவைப்படும் ஆய்வு இது:
curl -s http://127.0.0.1:4000/health \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"இது healthy_endpoints மற்றும் unhealthy_endpoints arrays மூலம் பதிலளிக்கும். unhealthy_endpoints-ல் உள்ள ஒரு model, அங்கீகாரப் பிழையைக் காட்டினால், .env-ல் உள்ள provider key தவறாகவோ அல்லது விடுபட்டோ உள்ளது என்று பொருள். நீங்கள் இப்போது கண்டறிய வேண்டிய தோல்வி இதுதான். background_health_checks: true அமைக்கப்பட்டிருப்பதால், proxy இந்த ஆய்வுகளைத் தானாகவே ஒவ்வொரு health_check_interval வினாடிகளுக்கும் இயக்கும். /health அதன் கடைசி முடிவை மட்டுமே வழங்கும், எனவே நீங்கள் polling செய்யும்போது ஒவ்வொரு முறையும் provider-களுக்குப் புதிய test request அனுப்பப்படாது.
Virtual keys மற்றும் per-key பட்ஜெட்
ஒவ்வொரு 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
}'பதிலில் key என்ற புலம் உள்ளது, இது sk--ல் தொடங்குகிறது. அந்த string-தான் application-க்குக் கிடைப்பது, அது மட்டுமே application-க்குத் தெரியும்.
modelsஎன்பது இந்த key எதைக் கோரலாம் என்பதற்கான allowlist ஆகும். மேலே உள்ள keybulk-ஐ மட்டுமே கோர முடியும், மற்ற எதையும் கோர முடியாது.max_budget: 5மற்றும்budget_duration: "30d"என்பது ஒரு காலண்டர் மாதத்திற்கு ஐந்து அமெரிக்க டாலர்கள் ஆகும். LiteLLM ஒரு30dபட்ஜெட்டை ஒவ்வொரு மாதமும் 1-ஆம் தேதி நள்ளிரவில் UTC நேரப்படி மீட்டமைக்கும் (நீங்கள்litellm_settings-ன் கீழ்timezone-ஐ அமைக்காவிட்டால்). இது 30 நாட்கள் சுழற்சி முறையில் இயங்காது, எனவே ஒருமுறை key ஐந்து டாலர்களைச் செலவழித்துவிட்டால், அடுத்த மாதம் 1-ஆம் தேதி வரை அது இயங்காது.rpm_limitமற்றும்tpm_limitஆகியவை இந்த key-க்கான ஒரு நிமிடத்திற்கான கோரிக்கைகள் (requests per minute) மற்றும் tokens per minute ஆகியவற்றைக் கட்டுப்படுத்துகின்றன.key_aliasஎன்பது ஆறு வாரங்களுக்குப் பிறகு spend log-ல் நீங்கள் அடையாளம் காணக்கூடிய பெயர். இதை எப்போதும் அமைக்கவும்.
பட்ஜெட் தீர்ந்துவிட்டால், அழைப்பு budget_exceeded என்ற வகை பிழையுடன் தோல்வியடையும், அதன் செய்தி பின்வருமாறு இருக்கும்:
Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>Status code என்பது software release-ஐப் பொறுத்தது. Pinned v1.95.0 பதிப்பில் இது HTTP 429 ஆகும். v1.104.0 பதிப்பிலிருந்து இயல்புநிலை HTTP 422 ஆகும், மேலும் litellm_settings-ன் கீழ் budget_exceeded_status_code: 429-ஐ அமைப்பதன் மூலம் முந்தைய code-ஐப் பெறலாம். உண்மையான rpm_limit மற்றும் tpm_limit கோரிக்கைகள் எந்த release-லும் 429-ஐயே திரும்ப அளிக்கும். ஒவ்வொரு upgrade-க்குப் பிறகும் உங்களுக்கு எது கிடைக்கிறது என்பதைச் சரிபார்க்கவும்.
Status code குழப்பத்தை ஏற்படுத்துகிறது, ஏனெனில் எந்த code-ம் "பட்ஜெட்" என்று நேரடியாகக் கூறுவதில்லை. ஒரு client library 429-ஐ rate limit என்று தெரிவிக்கும், மேலும் அது பட்ஜெட் தீர்ந்த பிறகும் மீண்டும் மீண்டும் முயலலாம் (retry). 422-ஐ செயலாக்க முடியாத கோரிக்கை என்று அது தெரிவிக்கும். Status code-உடன் சேர்த்து response body-ஐயும் log செய்யவும், இல்லையெனில் பட்ஜெட் தீர்ந்ததை வேறு ஏதோ பிழை என்று தவறாகக் கருத நேரிடும்.
அதே management API மூலம் key-களை ஆய்வு செய்து மாற்றங்களைச் செய்யலாம்:
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-க்கான செலவுக் கட்டுப்பாடு-ன் முதுகெலும்பாக உள்ளது.
மொத்தமான பணிகளை மலிவான மாடலுக்கு அனுப்புதல்
Gateway-ஐ நோக்கி client-ஐச் சுட்டிக்காட்டவும். 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-யும் இதே முறையில் செயல்படும், இருப்பினும் மொழியைப் பொறுத்து விருப்பங்களின் (options) பெயர்கள் மாறுபடும். Python client-ல், base_url-ஐ https://gateway.example.com/v1 என்றும், api_key-ஐ virtual key என்றும் அமைக்கவும். JavaScript மற்றும் TypeScript client-கள் அதே இரண்டு விருப்பங்களை baseURL மற்றும் apiKey என்று அழைக்கின்றன.
config.yaml-ல் உள்ள routing policy, அழைப்பவருக்குத் தெரியாமலேயே இப்போது செயல்படும். bulk-க்கான கோரிக்கை மலிவான மாடலுக்குச் செல்லும். அந்த அழைப்பு அதன் retries-க்குப் பிறகும் தோல்வியுற்றால், strong-க்கு எதிராக கோரிக்கை மீண்டும் முயற்சிக்கப்படும். prompt-ன் நீளம் bulk-க்கு மிக அதிகமாக இருந்தால், context_window_fallbacks பிழையைத் தருவதற்குப் பதிலாக அதை strong-க்கு அனுப்பும். வகைப்படுத்துதல் (classification) அல்லது சுருக்கம் செய்தல் (summarising backlog) போன்ற மொத்தமான பணிகள் இயல்பாகவே மலிவாக இயங்கும், கடினமான கோரிக்கைகளுக்கு மட்டுமே கூடுதல் செலவாகும்.
கருவிகளைப் பயன்படுத்தும் agents-க்கு gateway எங்கே பயனுள்ளதாக இருக்கும் என்பதும் இதுவே. ஒரே VPS-ல் உள்ள MCP (model context protocol) server மற்றும் அதை இயக்கும் agent ஆகிய இரண்டுமே ஒரே endpoint-ஐச் சுட்டிக்காட்ட முடியும். எனவே, இரண்டையும் மீண்டும் deploy செய்யாமலேயே அவற்றுக்குப் பின்னால் உள்ள மாடலை மாற்ற முடியும்.
fallback நிகழ்ந்ததை எவ்வாறு கண்டறிவது?
இதுவே அதிக செலவை ஏற்படுத்தும் தோல்வி முறையாகும், ஏனெனில் எதுவும் பழுதடைந்ததாகத் தெரியாது. ஒரு வெற்றிகரமான fallback, சாதாரண response body-உடன் HTTP 200-ஐத் திருப்பி அனுப்பும். உங்கள் மலிவான model ஒரு நாள் முழுவதும் முடங்கியிருக்கலாம், ஒவ்வொரு அழைப்பும் விலையுயர்ந்த 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என்பது கோரிக்கை எந்த model-ன் கீழ் அனுப்பப்பட்டது என்பதைக் குறிக்கும், உதாரணமாகbulk.x-litellm-model-idஎன்பது பதிலளித்த deployment-ன் ID ஆகும், இதை நீங்கள்/v1/model/info?litellm_model_id=...மூலம் தேடலாம். அந்த ID உங்கள்bulkdeployment-களில் ஒன்றாக இல்லையென்றால், fallback நிகழ்ந்திருக்கிறது என்று அர்த்தம்.x-litellm-attempted-fallbacksமற்றும்x-litellm-attempted-retriesஆகியவை அவற்றின் எண்ணிக்கையைக் காட்டுகின்றன. ஒரு சரியான அழைப்பில் இவை இரண்டுமே 0-க்கு மேல் இருக்காது.x-litellm-response-costஎன்பது அந்த ஒரு அழைப்பிற்கான அமெரிக்க டாலர் மதிப்பிலான செலவாகும்.x-litellm-call-idஎன்பது உங்கள் logs-ல் அதே அழைப்பைக் கண்டறிய நீங்கள் பயன்படுத்தும் அடையாளங்காட்டியாகும்.
ஒவ்வொரு கோரிக்கையிலும் x-litellm-attempted-fallbacks-ஐப் பதிவு செய்து, அது 0-க்கு மேல் இருக்கும்போதெல்லாம் எச்சரிக்கை (alert) பெறவும். இந்த ஒரே ஒரு எண் தான், சரியாகச் செயல்படும் routing policy-க்கும், அமைதியாக "எப்போதும் விலையுயர்ந்த model-ஐப் பயன்படுத்து" என்று மாறிவிட்ட routing policy-க்கும் உள்ள வித்தியாசமாகும்.
இதன் முழுமையான வடிவம் tracing ஆகும், இதற்குத் தனிப்பட்ட அமைப்பு தேவை: tracing agent அழைப்புகளுக்கான self-hosted Langfuse. LiteLLM இந்த callback-ஐ வழங்குகிறது, எனவே இதை இணைப்பது இரண்டு வரிகள் மற்றும் 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 இன்னும் ஆவணப்படுத்தப்பட்டுள்ளது. failure_callback மற்றும் success_callback ஆகியவற்றை அமைக்கவும். இதைத் தவிர்த்தால், எந்தப் பிழையும் ஏற்படாத அழைப்புகளை மட்டுமே நீங்கள் trace செய்ய முடியும். இதிலிருந்து தனித்தனியாக, LiteLLM ஒவ்வொரு கோரிக்கைக்கும் ஒரு spend row-ஐ Postgres-ல் எழுதுகிறது மற்றும் /ui-ல் உள்ள Admin UI அந்த அட்டவணையைப் படிக்கிறது. இது traffic-க்கு ஏற்ப வளரும், எனவே சிறிய disk-ல் இதைக் கண்காணித்து வரவும்.
Gateway-ஐ reverse proxy-க்கு பின்னால் வைத்தல்
பெட்டியின் (box) வெளிப்புறத்திலிருந்து எந்தவொரு தொடர்பும் port 4000-ஐ அடையக்கூடாது. Nginx அல்லது Caddy-ல் TLS termination செய்து, 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 இயக்கப்பட்டிருந்தால், அது தரவுத் துண்டுகளை (chunks) buffers-ல் சேகரித்து வைத்திருக்கும், இதனால் client-க்கு தரவு கிடைப்பதில் தாமதம் ஏற்படும். proxy_read_timeout 600s முக்கியமானது, ஏனெனில் nginx-ன் இயல்புநிலை 60 வினாடிகள் என்பது gateway-லிருந்து இரண்டு வாசிப்புகளுக்கு இடையே அது காத்திருக்கும் அதிகபட்ச நேரமே தவிர, முழு பதிலுக்கான கால வரம்பு அல்ல. Stream செய்யப்படாத completion, generation முடியும் வரை எதையும் அனுப்பாது; எனவே நீண்ட generation 60 வினாடிகளைத் தாண்டினால், client-க்கு 504 பிழை வரும் மற்றும் error log-ல் upstream timed out (110: Connection timed out) while reading response header from upstream பதிவாகும். Stream செய்யப்படும் completion தொடர்ந்து தரவுத் துண்டுகளை அனுப்பிக்கொண்டிருந்தால் 60 வினாடிகளுக்கு மேல் இயங்கும்; model நீண்ட நேரம் அமைதியாக இருந்தால் மட்டுமே இந்த timeout ஏற்படும்.
Certificate-க்கு, nginx-ல் Let's Encrypt உடன் Certbot பயன்படுத்துவது எளிதான வழியாகும். ஏற்கனவே அந்தப் பெட்டியில் பல containers இயங்கிக்கொண்டிருந்தால், பல Compose apps-க்கு முன்னால் Traefik பயன்படுத்துவது routing மற்றும் certificates-ஐ ஒரே இடத்தில் கையாள உதவும்.
Gateway இப்போது ஒரு ஒற்றை தோல்விப் புள்ளியாக (single point of failure) உள்ளது
நீங்கள் உருவாக்கியுள்ள அமைப்பின் யதார்த்தத்தை உணருங்கள். நீங்கள் வைத்திருக்கும் அனைத்து application-களும் இப்போது ஒரே VPS-ல் உள்ள ஒரே container-ஐச் சார்ந்துள்ளன. அது செயலிழந்தால், எந்தவொரு model-ஐயும் உங்களால் அணுக முடியாது; அந்த provider-கள் மிகச் சரியாக இயங்கிக்கொண்டிருந்தாலும் இதுவே நிலை. இதிலிருந்து நான்கு முக்கிய விஷயங்கள் எழுகின்றன:
- தவறான config அனைத்தையும் ஒரே நேரத்தில் முடக்கும்.
restart: unless-stoppedஒரு crash-ஐ மீண்டும் தொடங்கும், ஆனால் config.yaml-ஐ parse செய்ய முடியாத ஒரு container-ஐ அது மீண்டும் மீண்டும் தொடங்கும். ஒவ்வொரு config மாற்றத்திற்குப் பிறகும்docker compose logs litellm-ஐப் படியுங்கள், மேலும் மாற்றங்களைச் செய்யும்போது அவற்றைக் கண்காணிக்க நேரம் இருக்கும்போது மட்டும் செய்யுங்கள். - Cache miss ஏற்படும்போது Postgres கோரிக்கை பாதையில் (request path) அமர்கிறது. Key cache-ல் இல்லாதபோது virtual key lookup அதைத்தான் பயன்படுத்துகிறது; response கிடைத்த பிறகு spend recording asynchronous-ஆக நடக்கும்.
/health/readiness503 பிழையைத் தருகிறது என்றால், gateway இயங்குகிறது ஆனால் எதையும் செய்ய முடியவில்லை என்று அர்த்தம். - முதலில் cores-ஐப் பயன்படுத்துங்கள், பிறகு instances-ஐச் சேர்க்கவும். ஒரு instance-க்கு ஒரு worker (
--num_workers 1) என்ற திட்டத்தின் production வழிகாட்டுதல், Kubernetes அல்லது பிற pod autoscaler-களுக்காக வழங்கப்பட்டது. இது போன்ற ஒரு தனி VM அல்லது bare container-க்கு, அதற்கு நேர்மாறானதைச் செய்ய வேண்டும்: machine-ன் vCPU எண்ணிக்கைக்கு ஏற்ப worker எண்ணிக்கையை அமைக்கவும். மேலே உள்ள 1 vCPU கொண்ட பெட்டியில் அது இன்னும்--num_workers 1தான்; பெரிய பெட்டியில் அதை உயர்த்துங்கள், ஒவ்வொரு worker-க்கும் தனித்தனி memory தேவை என்பதை நினைவில் கொள்ளுங்கள். Load balancer-க்கு பின்னால் ஒரு இரண்டாவது gateway-ஐ வைப்பது, ஒற்றை container சிக்கலை நீக்கும். ஆனால் அது database-ஐ நீக்காது. - மீண்டும் உருவாக்க முடியாதவற்றை backup எடுங்கள். அது
config.yamlமற்றும்.env, அத்துடன் database-ன் ஒருpg_dumpஆகும்.LITELLM_SALT_KEY-ஐ இழந்தால், அந்த dump-ல் உள்ள encrypted provider credentials பயனற்றதாகிவிடும், எனவே env கோப்பும் dump-ம் ஒரே backup பணியில் இருக்க வேண்டும்: restic மூலம் off-box சேமிப்பகத்திற்கு backup எடுத்தல்.
Upgrade செய்ய, image tag-ஐ மாற்றி docker compose up -d-ஐ இயக்கவும். LiteLLM இயல்பாகவே தொடக்கத்தில் prisma migrate deploy-ஐ இயக்கும், எனவே புதிய container அதன் முதல் boot-ல் database schema-வை migrate செய்யும். Tag-ஐ மாற்றுவதற்கு முன் dump எடுத்துக்கொள்ளுங்கள், ஏனெனில் பழைய image-ஐ மீண்டும் வைப்பது ஏற்கனவே நடந்த migration-ஐத் திரும்பப் பெறாது.
நீங்கள் தாண்டிச் செல்லும் ஒவ்வொரு version-ன் release notes-ஐயும் படியுங்கள், நீங்கள் அடையும் version-ஐ மட்டும் படிக்காதீர்கள். v1.95.0-லிருந்து v1.104.0 அல்லது அதற்குப் பிந்தைய பதிப்பிற்கு மாறும்போது பல முக்கியமான மாற்றங்கள் (breaking changes) உள்ளன: மேலே குறிப்பிட்ட budget status code, unset, காலியாக உள்ள அல்லது பொதுவெளியில் தெரிந்த master key-உடன் தொடங்க மறுக்கும் proxy, மற்றும் தொடக்கத்தில் database setup தோல்வியுற்றால் வெளியேறும் proxy; இது restart: unless-stopped-ன் கீழ் restart loop-ஆகக் காட்டும். v1.102.x அல்லது அதற்கு முந்தைய பதிப்பிலிருந்து வரும்போது, v1.104.0 குறிப்புகள் இரண்டு LiteLLM_SpendLogs indexes-ஐ நீங்களே உருவாக்கச் சொல்கின்றன.
FAQ
LiteLLM ஒவ்வொரு அழைப்பிலும் குறிப்பிடத்தக்க தாமதத்தை (latency) ஏற்படுத்துமா?
நவம்பர் 2026-ல் அதன் README-ல் குறிப்பிட்டுள்ளபடி, வினாடிக்கு 1000 கோரிக்கைகள் என்ற விகிதத்தில் 95-வது சதவீதத்தில் (95th percentile) 8 ms தாமதம் ஏற்படுவதாக அந்தத் திட்டம் தெரிவிக்கிறது. இதை ஒரு விற்பனையாளர் வழங்கும் புள்ளிவிவரமாக மட்டும் கருதுங்கள். உங்கள் தாமதத்தை உண்மையில் பாதிக்கும் காரணி, உங்கள் பயன்பாடுகளுக்கும் (applications) gateway-க்கும் இடையிலான பிணையத் தூரம் (network distance) ஆகும், ஏனெனில் ஒவ்வொரு அழைப்பிலும் ஒரு கூடுதல் round trip-ஐ நீங்கள் சேர்த்துள்ளீர்கள். Gateway-ஐ அழைக்கும் பயன்பாடுகள் இருக்கும் அதே பிராந்தியத்தில் (region) gateway-ஐயும் இயக்குங்கள், பின்னர் ஒரு உண்மையான பதிலில் x-litellm-overhead-duration-ms header-ஐக் கொண்டு உங்கள் சொந்த overhead-ஐ அளவிடுங்கள்.
nginx-ஐ முன்னால் வைத்த பிறகு streaming ஏன் வேலை செய்யவில்லை?
ஏனெனில் nginx இயல்பாகவே upstream பதில்களை buffer செய்கிறது, மேலும் streaming completion என்பது server-sent events-ன் தொடர்ச்சியாகும். proxy_buffering ஆன் செய்யப்பட்டிருக்கும்போது, nginx துண்டுகளை (chunks) buffers-ல் சேகரித்து வைத்த பிறகே client-க்கு அனுப்புகிறது, இது விநியோகத்தைத் தாமதப்படுத்துகிறது. location block-ல் proxy_buffering off;-ஐ அமைக்கவும். அதே block-ல் proxy_read_timeout-ஐயும் அதிகரிக்கவும். இயல்பாக, gateway-லிருந்து தரவு வராமல் 60 வினாடிகள் கடந்தால் nginx முயற்சியைக் கைவிட்டுவிடும்; stream செய்யப்படாத நீண்ட generation-கள் எளிதில் இந்த நேரத்தை எட்டிவிடும், இதனால் client-க்கு 504 பிழை கிடைக்கும்.
ஒரு virtual key-ன் வரவுசெலவுத் திட்டம் (budget) தீர்ந்துவிட்டால் என்ன நடக்கும்?
அழைப்பு budget_exceeded வகை பிழையுடனும், Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget> வடிவத்திலான செய்தியுடனும் தோல்வியடையும். v1.95.0 பதிப்பில் இதன் நிலை HTTP 429 ஆகும்; v1.104.0 முதல் இயல்பான நிலை HTTP 422 ஆகும். எந்தக் குறியீடும் budget தீர்ந்துவிட்டதாகக் கூறாது, இதுவே சிக்கல்: ஒரு client library 429-ஐ rate limit என்று தெரிவிக்கும், அதனால் அது மீண்டும் மீண்டும் முயற்சி செய்யக்கூடும் (retry). எனவே, மக்கள் செய்தியைப் படிப்பதற்குப் பதிலாக throttling-ஐத் தேடத் தொடங்குவார்கள். status code-உடன் சேர்த்து response body-ஐயும் log செய்யுங்கள். master key-க்கு எதிராக /key/info?key=sk-...-ஐப் பயன்படுத்தி key-ன் உண்மையான நிலையை உறுதிப்படுத்தவும், budget குறைவாக அமைக்கப்பட்டிருந்தால் /key/update மூலம் வரம்பை உயர்த்தவும்.
gateway உள்ளூர் மாதிரிகளுக்கும் (local model) மற்றும் hosted மாதிரிகளுக்கும் routing செய்ய முடியுமா?
ஆம், இது model_list-ல் மற்றொரு உள்ளீடாக அமையும். api_base-உடன் ollama_chat/ முன்னொட்டைப் (prefix) பயன்படுத்தவும், உதாரணமாக api_base: http://ollama:11434-உடன் சேர்த்து model: ollama_chat/llama3.1-ஐப் பயன்படுத்தலாம். Compose-ன் இயல்புநிலை பிணைய அமைப்பில், ஒரு container-க்குள் localhost என்பது அந்த container-ஐயே குறிக்கும், எனவே Docker network-ல் உள்ள Compose service பெயர் அல்லது host-ன் முகவரியைப் பயன்படுத்தவும், ஒருபோதும் 127.0.0.1-ஐப் பயன்படுத்த வேண்டாம். container-ஆனது host-ன் network stack-ஐப் பகிர்ந்து கொள்ளும் host networking முறை இதற்கு விதிவிலக்காகும். உள்ளூர் மாதிரியை நிறுவுவது ஒரு தனிப்பணி: Ollama மூலம் VPS-ல் LLM-ஐ self-hosting செய்தல் என்பதைப் பார்க்கவும்.