Jinsi ya kusanidi LiteLLM kama gateway ya LLM
Jifunze kusanidi LiteLLM kwenye VPS ili kudhibiti API za LLM kupitia endpoint moja. Pata mwongozo wa kutumia virtual keys, bajeti kwa kila ufunguo, na mifumo ya fallback.
Kazi ya gateway ya LLM unayojiendeshea mwenyewe
LiteLLM ni gateway ya LLM ya chanzo huria unayojiendeshea mwenyewe: ni HTTP endpoint moja ambayo programu zako zote huipigia simu, nayo husambaza kila ombi kwa mtoa huduma anayepaswa kulijibu. LLM inamaanisha large language model. Gateway hii hutumia OpenAI chat completions API (application programming interface), kwa hivyo maktaba yoyote ya mteja inayowasiliana na OpenAI hufanya kazi nayo baada ya mabadiliko mawili: base URL na ufunguo (key).
Safu hiyo moja ya upatanishi ndiyo msingi wa kazi hii. Programu zako huacha kuhifadhi vitambulisho vya watoa huduma. Kubadilisha model huwa ni mstari mmoja tu kwenye faili ya usanidi (config file) kwenye seva badala ya kubadilisha msimbo katika huduma tano tofauti. Na kwa sababu kila ombi hupitia mchakato mmoja, unakuwa na sehemu ya kuwekea bajeti na sehemu ya kuhifadhi rekodi ya matumizi.
Hivi ndivyo unavyopata mara tu inapokuwa inafanya kazi:
- Endpoint moja. Programu hulenga
https://gateway.example.com/v1na kuomba jina la model ulilobuni, kama vilebulkaustrong. - Virtual keys. Kila programu hupata ufunguo wake ikiwa na orodha yake ya model zinazoruhusiwa na kikomo chake cha matumizi. Unaweza kufuta ufunguo mmoja bila kugusa mingine.
- Fallbacks. Ombi lililofeli au prompt kubwa kupita kiasi hujaribiwa upya kwa kutumia model tofauti moja kwa moja.
- Rekodi iliyohifadhiwa. Kila ombi huandika mstari wenye gharama yake, kwa hivyo swali la "ni programu ipi ilitumia kiasi hicho" linapata jibu.
Kwa nini uendeshe gateway mwenyewe
Router inayodhibitiwa na mtoa huduma ina umbo sawa na ile unayoiendesha mwenyewe, lakini kuna mchakato wa mtu mwingine katikati ya kila ombi. Kujiendeshea mwenyewe kunahakikisha kuwa funguo za mtoa huduma na maandishi ya prompt yako yanabaki kwenye seva unayoimiliki. Gharama yake ni ya kweli: sasa wewe ndiye unayeendesha sehemu ambayo kila programu inategemea. Sehemu ya mwisho ya mwongozo huu inahusu gharama hiyo, kwa sababu ndiyo sehemu ambayo maandiko mengi huacha kuizungumzia.
Unachohitaji
- VPS (virtual private server) inayoendesha Ubuntu 24.04, ikiwa na Docker na Compose plugin iliyosakinishwa.
- Jina la domain linaloelekeza kwenye seva hiyo, ikiwa mashine zilizo nje ya seva hiyo zitafikia gateway kupitia TLS (transport layer security).
- Angalau API key moja ya mtoa huduma.
Gateway haiendeshi inference yoyote. Inasambaza maombi na kurudisha majibu kwa mtiririko, kwa hivyo mzigo wa CPU hufuata kiasi cha maombi badala ya ukubwa wa model. Seva yenye 1 vCPU inaweza kuhudumia programu kadhaa za ndani bila matatizo. Kinachoongezeka ni database, kwa sababu gateway huandika safu moja ya matumizi kwa kila ombi.
Andika config.yaml kwanza
Faili la usanidi huamua ni mifano (models) ipi mteja anaweza kuomba. Sehemu nne za ngazi ya juu ni muhimu: model_list, litellm_settings, router_settings na 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 ni jina ambalo wateja wako hutuma. litellm_params.model ni mfano halisi, ulioandikwa kama provider/model. Taja mifano yako kulingana na kazi badala ya muuzaji. Programu inayoomba bulk itaendelea kufanya kazi wakati utakapiamua mwezi ujao kuwa bulk inapaswa kuwa mfano tofauti.
api_key: os.environ/ANTHROPIC_API_KEY huambia LiteLLM kusoma kigezo hicho wakati wa utekelezaji. Ufunguo halisi hauonekani kamwe kwenye faili, jambo ambalo ni muhimu kwa sababu config.yaml ndilo faili unaloliweka kwenye version control.
Ingizo mbili zinashiriki jina strong, kwa makusudi. Wakati zaidi ya deployment moja inabeba model_name sawa, router huichukulia kama inayoweza kubadilishana na kusambaza maombi ya jina hilo kati yao. Hivyo ndivyo strong inavyoweza kuhimili mtoa huduma anapokuwa na saa mbaya: pindi deployment inapokuwa kwenye cooldown (chini), maombi mapya ya strong huenda kwa ile nyingine.
num_retries: 2 hujaribu tena kosa linaloweza kurudiwa hadi mara mbili. Majaribio hayo yanaweza kuchagua deployment nyingine inayopatikana katika kundi lilelile la mfano: nyaraka za usanifu wa LiteLLM, zilizokaguliwa tarehe 2026-10-29, zinaelezea majaribio ndani ya kundi na fallbacks za kuvuka kundi kama hatua tofauti. Jaribio la strong linaweza kutua kwa mtoa huduma mwingine bila kuwasha weighted failover. Fallback huwashwa tu baada ya majaribio hayo kumalizika.
allowed_fails na cooldown_time ni chaguzi za router, kwa hivyo ziko chini ya router_settings. Proxy hujenga router yake kutoka sehemu hiyo, na kwenye v1.95.0 cooldown_time iliyoandikwa chini ya litellm_settings haifikii kamwe, kwa hivyo cooldowns hubaki kimya kwenye thamani chaguo-msingi ya sekunde 5. cooldown_time: 30 huweka muda ambao deployment inakaa nje ya mzunguko pindi inapopozwa. Rejeleo la usanidi linaelezea allowed_fails kama idadi ya makosa ambayo deployment lazima izidi ndani ya cooldown_time kabla ya kupozwa. Katika chanzo cha v1.95.0, allowed_fails: 3 ndiyo chaguo-msingi, na katika hali hiyo router hushikilia vichochezi vilivyojengwa ndani; idadi ya makosa huchukua nafasi tu unapoweka nambari tofauti. Vichochezi hivyo vinajumuisha cooldown ya haraka kwenye jibu la 429 kwa kundi lenye zaidi ya deployment moja, zaidi ya 50% ya makosa katika dakika ya sasa baada ya angalau maombi 5 kwa kundi kama hilo, na makosa ambayo router haitajaribu tena, kama 401 kutoka kwa ufunguo mbaya. Kichochezi tofauti pia hupozesha deployment moja wakati maombi yote katika dakika ya sasa yanashindwa na trafiki inafikia SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD, ambayo ni maombi 1000 kwa chaguo-msingi. Kwa hivyo kwa strong, ambayo ina deployments mbili, mtoa huduma anayerudisha 500s katika mlipuko huacha kujaribiwa kwenye kila ombi, wakati 500 moja inayotokea kila baada ya dakika chache haisababishi cooldown. bulk ina deployment moja tu, kwa hivyo kichochezi cha kiwango cha makosa hakitumiki kwake: mlipuko wa 500s ambao unakaa chini ya maombi 1000 kwa dakika huiacha katika mzunguko, na kinachowalinda wapigaji wake ni num_retries ikifuatiwa na fallback kwa strong.
fallbacks na context_window_fallbacks zina vichochezi tofauti, na ya pili ndiyo inayofaa ambayo watu huiruka.
fallbackshuwashwa wakati ombi la msingi linashindwa.context_window_fallbackshuwashwa wakati mtoa huduma anakataa ombi kwa kuwa refu kuliko dirisha la muktadha wa mfano huo, kwa hivyo prompt kubwa sana huenda kwa mfano wenye nafasi badala ya kurudisha kosa kwa mpigaji.
Kuna pia content_policy_fallbacks, kwa mtoa huduma anayekataa kwa misingi ya sera ya maudhui. Iweke tu ikiwa una mahali pazuri pa kutuma maombi hayo.
Kupeleka LiteLLM kwenye VPS kwa kutumia Docker Compose
Tengeneza saraka (directory) itakayohifadhi faili tatu: config.yaml, docker-compose.yml, na .env. Mwongozo wa kuanza haraka wa upstream huvuta tag ya latest. Badala yake, funga (pin) tag ya release ili uboreshaji ufanyike tu unapohariri faili, na ili uweze kurudisha toleo la awali (rollback) kwa mstari mmoja. Tag pekee si dhamana ya maudhui yaleyale, kwa sababu image tags zinaweza kubadilika na mchapishaji anaweza kuielekeza kwenye image mpya. Ikiwa docker compose up -d mwezi ujao lazima ikupe gateway ileile iliyokupa leo, ambatanisha pia image digest, kwa mfumo wa ghcr.io/berriai/litellm:v1.95.0@sha256:<digest>; docker buildx imagetools inspect ghcr.io/berriai/litellm:v1.95.0 huichapisha.
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 husoma .env mara mbili hapa. Mara ya kwanza ili kubadilisha ${POSTGRES_PASSWORD} ndani ya faili ya compose yenyewe, na mara ya pili kupitia env_file ili kupitisha kila variable ndani ya container.
v1.95.0 lilikuwa toleo la sasa mnamo Agosti 2026. Angalia ukurasa wa releases wa mradi na ufunge toleo la sasa wakati wa kupeleka (deploy). Kila release huchapisha sahihi (signature), kwa hivyo unaweza kukagua image kabla ya kuiamini:
cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0Mstari wa port ni 127.0.0.1:4000:4000, ambao huchapisha port kwenye loopback interface pekee. Andika 4000:4000 badala yake na gateway yako itafikika kutoka kwenye mtandao mzima, kwa sababu Docker huongeza sheria zake kwenye iptables FORWARD chain na hizo hutathminiwa kabla ya za ufw, kwa hivyo ufw deny 4000 haizuii hilo. Hii ndiyo njia ya kawaida zaidi ambapo gateway inayojiendesha (self-hosted) huishia kuwa wazi: angalia jinsi Docker inavyochapisha port ya container kupita ufw. Trafiki kutoka nje hufika kupitia reverse proxy badala yake.
Weka funguo za mtoa huduma nje ya image
Faili la .env huhifadhi kila siri. Hupitishwa kama environment wakati wa kuendesha programu, kwa hivyo haijajumuishwa ndani ya image, na haijawahi kuingizwa kwenye version control.
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-...Tengeneza funguo mbili za LiteLLM kwa kutumia randomness halisi, kisha linda faili hilo:
printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .envLITELLM_MASTER_KEY ni kitambulisho cha msimamizi. Huidhinisha API ya usimamizi na ndilo neno la siri kwa Admin UI katika /ui. Hakuna programu inayopaswa kulihifadhi.
LITELLM_SALT_KEY husimba kwa njia fiche vitambulisho vya mtoa huduma vilivyohifadhiwa kwenye database. Kiweke mara moja na usikibadilishe. Ukikibadilisha baadaye, vitambulisho vilivyohifadhiwa haviwezi kusomwa, kwa hivyo gateway itaanza kama kawaida lakini kila ombi kwa watoa huduma hao litafeli kwenye uthibitishaji.
STORE_MODEL_IN_DB=True hukuruhusu kuongeza na kuhariri models kutoka Admin UI bila kugusa config.yaml. Hiyo ni rahisi, lakini inagawanya chanzo chako cha ukweli katika sehemu mbili. Amua ni kipi kitakuwa na mamlaka ya mwisho na uandike uamuzi huo karibu na faili la config.
Sababu ya kuweka funguo nje ya faili la config ni ileile inayozizuia zisiingie kwenye zana unazompa wakala (agent). Kuweka siri za mtoa huduma nje ya mawakala wa AI kunaelezea muundo huo, na faili za env na siri katika Docker Compose kunaelezea mbinu za kiufundi.
Iwashe huduma na ufuatilie boot ya kwanza:
docker compose up -d
docker compose logs -f litellmThibitisha kuwa inafanya kazi kikamilifu
Kuna majaribio mawili yasiyohitaji uthibitisho na moja linalohitaji uthibitisho, na yote yanashindwa kwa sababu tofauti.
curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readiness/health/liveliness haihitaji uthibitisho na inajibu "I'm alive!" wakati mchakato unaendelea. /health/readiness pia haihitaji uthibitisho. Inarejesha kitu cha JSON chenye "status": "healthy" na sehemu ya db, au inarejesha 503 wakati database haipatikani. Elekeza ufuatiliaji wako kwenye readiness, kwa sababu liveliness inabaki kuwa kijani kwenye gateway ambayo haiwezi kutafuta ufunguo mmoja wa virtual.
Jaribio linalohitaji uthibitisho ndilo linalowasiliana na watoa huduma:
curl -s http://127.0.0.1:4000/health \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"Inajibu kwa safu za healthy_endpoints na unhealthy_endpoints. Model iliyopo kwenye unhealthy_endpoints yenye hitilafu ya uthibitisho inamaanisha kuwa ufunguo wa mtoa huduma katika .env si sahihi au haupo, ambayo ndiyo hitilafu unayotaka kuipata sasa. Kwa sababu background_health_checks: true imewekwa, proxy huendesha majaribio haya kila baada ya health_check_interval sekunde yenyewe na /health inarejesha matokeo ya mwisho, kwa hivyo kuipigia kura (polling) hakutumi ombi la majaribio kwa watoa huduma wako kila wakati.
Funguo pepe na bajeti kwa kila ufunguo
Kila programu hupata ufunguo wake, unaotengenezwa kwa kutumia ufunguo mkuu.
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
}'Jibu hubeba sehemu ya key inayoanza na sk-. Mfuatano huo ndio ambao programu hupokea, na ndicho kitu pekee ambacho programu hupata.
modelsni orodha ya kuruhusu (allowlist) ya kile ambacho ufunguo huu unaweza kuomba. Ufunguo ulio hapo juu unaweza kuombabulkna si kitu kingine.max_budget: 5yenyebudget_duration: "30d"ni dola tano za Marekani kwa kila mwezi wa kalenda. LiteLLM huweka upya bajeti ya30dkila tarehe 1 ya mwezi saa sita usiku, kwa saa za UTC isipokuwa ukiwekatimezonechini yalitellm_settings, badala ya kipindi cha siku 30 zinazozunguka. Kwa hivyo, ufunguo ukishatumia dola tano huacha kufanya kazi hadi tarehe 1 inayofuata.rpm_limitnatpm_limithuweka kikomo cha maombi kwa dakika na tokeni kwa dakika kwa ufunguo huu pekee.key_aliasndicho utakachotambua kwenye logi ya matumizi wiki sita baadaye. Kiweke kila wakati.
Bajeti ikiisha, ombi hushindwa na kutoa hitilafu ya aina ya budget_exceeded na ujumbe wa namna hii:
Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>Nambari ya hali (status code) inategemea toleo (release). Kwenye toleo lililofungwa la v1.95.0 ni HTTP 429. Kuanzia v1.104.0 chaguo-msingi ni HTTP 422, na kuweka budget_exceeded_status_code: 429 chini ya litellm_settings hurudisha nambari ya awali. Hitilafu halisi za rpm_limit na tpm_limit bado hurejesha 429 kwenye toleo lolote. Hakikisha ni ipi unayopata baada ya kila upgrade.
Nambari ya hali ndiyo inayofanya jambo hili kuwa gumu, kwa sababu hakuna nambari inayosema "bajeti". Maktaba ya mteja (client library) huripoti 429 kama kikomo cha kasi (rate limit) na inaweza kujaribu tena kwa kusubiri (backoff) dhidi ya bajeti ambayo haitarudi hadi wakati wa kuweka upya, na huripoti 422 kama ombi lisiloweza kuchakatwa. Hifadhi mwili wa jibu (response body) karibu na nambari ya hali, la sivyo kuishiwa kwa bajeti kutaonekana kama kitu kingine kila wakati.
Kagua na urekebishe funguo kupitia API ileile ya usimamizi:
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}'Bajeti inayotekelezwa kwenye gateway hudumu hata wakati kitu kilichoharibika ni wakala (agent) yenyewe, ndiyo maana ndiyo msingi wa udhibiti wa gharama kwa mawakala wa AI kwenye VPS.
Tuma kazi nyingi kwa model ya bei nafuu
Elekeza client kwenye gateway. Base URL, key, jina la model:
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."}]
}'Maktaba yoyote ya OpenAI client hufanya kazi kwa njia ile ile, ingawa majina ya chaguzi hutofautiana kulingana na lugha. Katika Python client, weka base_url kuwa https://gateway.example.com/v1 na api_key kuwa ufunguo wa virtual. Client ya JavaScript na TypeScript huita chaguzi hizo mbili baseURL na apiKey.
Sera ya routing kutoka config.yaml sasa inatumika bila mpigaji simu kujua. Ombi la bulk huenda kwenye model ya bei nafuu. Ikiwa wito huo utafeli baada ya majaribio yake, ombi hilo hujaribiwa tena dhidi ya strong. Ikiwa prompt ni ndefu sana kwa bulk, context_window_fallbacks huituma kwenye strong badala ya kurudisha error. Kazi nyingi kama vile classification pass au summarising backlog huendeshwa kwa bei nafuu kwa default, na maombi magumu pekee ndiyo yanayogharimu zaidi.
Hapa ndipo gateway inapopata thamani yake kwa mawakala wanaotumia zana. MCP (model context protocol) server kwenye VPS hiyo hiyo na wakala anayeiendesha wanaweza wote kuelekeza kwenye endpoint moja, hivyo model iliyo nyuma yao hubadilika bila kuhitaji redeploy ya yeyote kati yao.
Unajuaje kama fallback imetokea?
Hii ni hali ya hitilafu inayogharimu pesa, kwa sababu hakuna kinachoonekana kuharibika. Fallback iliyofanikiwa hurejesha HTTP 200 ikiwa na mwili wa kawaida wa majibu. Model yako ya bei nafuu inaweza kuwa chini kwa siku nzima, huku kila ombi likihudumiwa kimyakimya na ile ya gharama kubwa, na ushahidi wa kwanza ni ankara.
Ushahidi upo, ndani ya response headers. Ziombe:
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-groupni jina la model ambalo ombi lilipelekwa chini yake, kama vilebulk.x-litellm-model-idni ID ya deployment iliyojibu, ambayo unaweza kuitafuta kwa kutumia/v1/model/info?litellm_model_id=.... Wakati ID hiyo si mojawapo ya deployments zako zabulk, basi fallback imetokea.x-litellm-attempted-fallbacksnax-litellm-attempted-retrieshuyahesabu. Katika ombi zima, hakuna hata moja linaloonyesha hesabu zaidi ya 0.x-litellm-response-costni gharama ya ombi hilo moja katika dola za Marekani.x-litellm-call-idni kitambulishi unachotumia kupata ombi lilelile kwenye logs zako.
Rekodi x-litellm-attempted-fallbacks kwenye kila ombi na uweke tahadhari wakati wowote inapozidi 0. Nambari hiyo moja ndiyo tofauti kati ya sera ya routing inayofanya kazi na sera ya routing ambayo imekuwa kimyakimya "tumia kila wakati model ya gharama kubwa".
Toleo kamili la hili ni tracing, na linastahili usanidi wake wenyewe: Langfuse inayojiendesha yenyewe kwa ajili ya kufuatilia calls za wakala. LiteLLM inakuja na callback, kwa hivyo kuiunganisha ni mistari miwili pamoja na vitambulisho.
litellm_settings:
success_callback: ["langfuse"]
failure_callback: ["langfuse"]LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.comKwa Langfuse v3 na kuendelea, ukurasa wa Langfuse wa LiteLLM sasa unapendekeza preset yake ya langfuse_otel; callback ya langfuse hapo juu bado imeandikwa kwenye nyaraka. Weka failure_callback pamoja na success_callback. Ukiiruka, traces pekee utakazohifadhi ni zile ambazo hakuna kilichoharibika. Kando na haya yote, LiteLLM huandika mstari wa matumizi kwa kila ombi kwenye Postgres na Admin UI iliyopo /ui husoma jedwali hilo. Hukua kulingana na trafiki, kwa hivyo ifuatilie kwenye diski ndogo.
Weka gateway nyuma ya reverse proxy
Hakuna kitu chochote nje ya seva kinachopaswa kufikia port 4000. Malizia TLS ndani ya nginx au Caddy na uelekeze trafiki kwenye anwani ya 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;
}Mistari miwili kati ya hiyo ni ile ambayo watu husahau kuiweka. proxy_buffering off ni muhimu kwa sababu streaming completion ni mfululizo wa server-sent events, na ukiwa na buffering, nginx hukusanya vipande vya data kwenye buffers kabla ya kuvituma, jambo linalochelewesha kufika kwa data kwa mteja. proxy_read_timeout 600s ni muhimu kwa sababu muda chaguo-msingi wa sekunde 60 wa nginx ndio muda mrefu zaidi ambao husubiri kati ya usomaji mbili kutoka kwa gateway, si kikomo cha majibu yote. Completion isiyo ya streaming haitumi chochote hadi uzalishaji ukamilike, kwa hivyo ile ndefu hupita sekunde 60 bila byte yoyote kufika, na mteja hupata 504 wakati error log ikirekodi upstream timed out (110: Connection timed out) while reading response header from upstream. Completion ya streaming inayoendelea kutuma vipande inaweza kukimbia kwa muda mrefu zaidi ya sekunde 60; itapata timeout tu ikiwa model itakaa kimya kwa muda huo wote.
Kwa ajili ya cheti, Certbot na Let's Encrypt kwenye nginx ndiyo njia ya haraka. Ikiwa seva tayari inahudumia containers kadhaa, Traefik mbele ya programu nyingi za Compose hushughulikia routing na vyeti katika sehemu moja.
Gateway sasa ni sehemu moja ya kushindwa (single point of failure)
Kuwa mkweli kuhusu ulichojenga. Kila programu unayomiliki sasa inategemea kontena moja kwenye VPS moja. Wakati ikiwa imezimika, hakuna kitu kinachoweza kuita modeli yoyote, ikiwemo watoa huduma ambao wako katika hali nzuri kabisa. Mambo manne yanatokana na hili.
- Usanidi mbaya huangusha kila kitu kwa wakati mmoja.
restart: unless-stoppedhuanzisha upya (restart) baada ya crash, na huanzisha upya kontena ambalo haliwezi kusoma config.yaml, tena na tena. Somadocker compose logs litellmbaada ya kila mabadiliko ya usanidi, na fanya mabadiliko ya usanidi wakati una muda wa kuyafuatilia. - Postgres iko kwenye njia ya ombi (request path) wakati cache inakosa data. Utafutaji wa virtual key huitumia wakati key haijahifadhiwa kwenye cache; kurekodi matumizi hufanyika kwa njia ya asynchronous baada ya jibu kutumwa.
/health/readinessinayorejesha 503 ni onyo lako kwamba gateway inafanya kazi lakini haiwezi kufanya yoyote kati ya hayo. - Tumia cores kwanza, kisha ongeza instances. Mwongozo wa uzalishaji wa mradi wa mfanyakazi mmoja kwa kila instance (
--num_workers 1) ni kwa ajili ya Kubernetes au autoscaler nyingine ya pod inayokuongezea instances. Kwa VM moja au kontena kama hili, inasema kinyume chake: weka idadi ya wafanyakazi (worker count) kulingana na idadi ya vCPU za mashine. Kwenye mashine ya 1 vCPU hapo juu hiyo bado ni--num_workers 1; kwenye mashine kubwa zaidi iongeze, na kumbuka kuwa kila mfanyakazi anabeba kumbukumbu (memory) yake mwenyewe. Gateway ya pili nyuma ya load balancer huondoa kontena moja kwenye hadithi hii. Haiondoi database. - Hifadhi (backup) kile ambacho huwezi kukitengeneza upya. Hiyo ni
config.yamlna.env, pamoja napg_dumpya database. KupotezaLITELLM_SALT_KEYhufanya vitambulisho vya mtoa huduma vilivyosimbwa ndani ya dump hiyo kuwa havifai, kwa hivyo faili ya env na dump ni mali ya kazi moja ya kuhifadhi: restic backups to off-box storage.
Kupandisha toleo (upgrading) ni kuhariri image tag na kuendesha docker compose up -d. LiteLLM huendesha prisma migrate deploy wakati wa kuanza (startup) kwa chaguo-msingi, kwa hivyo kontena jipya hufanya migration ya schema ya database kwenye boot yake ya kwanza. Chukua dump kabla ya kubadilisha tag, kwa sababu kurudisha image ya zamani hakutengui migration ambayo tayari imeshafanyika.
Soma maelezo ya toleo (release notes) la kila toleo unaloruka, si lile tu unalofikia. Kuhama kutoka v1.95.0 kwenda v1.104.0 au baadaye kunavuka mabadiliko kadhaa makubwa (breaking changes): msimbo wa hali ya bajeti hapo juu, proxy inayokataa kuanza ikiwa na master key ambayo haijawekwa, tupu, au inayojulikana hadharani, na proxy inayozima wakati usanidi wa database unashindwa wakati wa kuanza, ambayo chini ya restart: unless-stopped huonekana kama mzunguko wa kuanzisha upya (restart loop). Ukitoka v1.102.x au mapema, maelezo ya v1.104.0 pia yanakuomba ujenge index mbili za LiteLLM_SpendLogs wewe mwenyewe.
FAQ
Je, LiteLLM huongeza latency inayoonekana kwenye kila ombi?
Mradi huu unachapisha 8 ms katika percentile ya 95 kwa maombi 1000 kwa sekunde, kama ilivyoelezwa kwenye README yake mnamo Novemba 2026. Ichukulie hiyo kama takwimu ya muuzaji. Namba inayobadilisha latency yako kihalisi ni umbali wa mtandao kati ya programu zako na gateway, kwa sababu umeongeza safari moja ya kwenda na kurudi (round trip) kwenye kila ombi. Endesha gateway katika kanda (region) moja na programu zinazoiita, kisha pima overhead yako mwenyewe kwa kutumia header ya x-litellm-overhead-duration-ms kwenye response halisi.
Kwa nini streaming iliacha kufanya kazi baada ya kuweka nginx mbele?
Kwa sababu nginx hufanya buffering ya majibu ya upstream kwa chaguomsingi na streaming completion ni mfululizo wa server-sent events. Ikiwa proxy_buffering imewashwa, nginx hukusanya vipande (chunks) kwenye buffers kabla ya kuvituma, jambo linalochelewesha uwasilishaji kwa mteja. Weka proxy_buffering off; kwenye location block. Ongeza proxy_read_timeout kwenye block hiyo hiyo pia. Kwa chaguomsingi, nginx hukata muunganisho baada ya sekunde 60 bila data kutoka kwa gateway, muda ambao generation ndefu isiyo ya streaming hufikia kwa urahisi, na mteja hupata 504.
Nini hutokea wakati virtual key inapoishiwa na bajeti?
Ombi linashindwa na hitilafu ya aina ya budget_exceeded na ujumbe wa mfumo wa Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>. Kwenye toleo lililofungwa la v1.95.0 hali ni HTTP 429; kuanzia v1.104.0 chaguomsingi ni HTTP 422 badala yake. Hakuna code inayosema bajeti, na huo ndio mtego: maktaba ya mteja (client library) huripoti 429 kama rate limit na inaweza kujaribu tena, kwa hivyo watu huanza kufuatilia throttling badala ya kusoma ujumbe. Hifadhi response body pamoja na status code. Thibitisha nafasi halisi ya key kwa kutumia /key/info?key=sk-... dhidi ya master key, na ongeza kikomo kwa kutumia /key/update ikiwa bajeti iliwekwa chini sana.
Je, gateway inaweza kuelekeza kwenye local model pamoja na zile zilizopangishwa (hosted)?
Ndiyo, na ni ingizo moja zaidi kwenye model_list. Tumia prefix ya ollama_chat/ pamoja na api_base, kwa mfano model: ollama_chat/llama3.1 pamoja na api_base: http://ollama:11434. Kwenye mtandao wa chaguomsingi wa Compose, localhost ndani ya container inamaanisha container hiyo, kwa hivyo tumia jina la huduma ya Compose au anwani ya host kwenye Docker network, kamwe usitumie 127.0.0.1. Host networking, ambapo container inashiriki network stack ya host, ndiyo ubaguzi. Kuweka local model ni kazi tofauti: angalia kujihostisha LLM na Ollama kwenye VPS.