Paano i-self host ang LiteLLM bilang LLM gateway
Gamitin ang LiteLLM bilang iisang OpenAI compatible endpoint para sa lahat ng providers. Alamin kung paano mag-setup ng virtual keys, budget limits, at fallbacks sa iyong VPS.
Gamit ng self-hosted LLM gateway
Ang LiteLLM ay isang open source na LLM gateway na ikaw mismo ang nagho-host: isang HTTP endpoint na tinatawagan ng lahat ng application mo, at ipinapasa nito ang bawat request sa provider na dapat sumagot dito. Ang LLM ay nangangahulugang large language model. Ginagamit ng gateway ang OpenAI chat completions API (application programming interface), kaya gagana rito ang anumang client library na nakikipag-ugnayan na sa OpenAI matapos baguhin ang dalawang bagay: ang base URL at ang key.
Iyan ang layunin ng isang layer of indirection. Hindi na nagtatago ang iyong mga application ng provider credentials. Ang pagpapalit ng model ay nagiging isang linya lamang sa config file sa server, sa halip na code change sa limang serbisyo. Dahil dumadaan ang bawat call sa iisang process, mayroon kang lugar para magtakda ng budget at magtala ng nagastos.
Kapag tumatakbo na ito, mayroon ka ng sumusunod:
- Isang endpoint. Tinutukoy ng mga application ang
https://gateway.example.com/v1at humihingi ng model name na ikaw ang nagtakda, gaya ngbulkostrong. - Virtual keys. Bawat application ay may sariling key, sariling model allowlist, at sariling spend ceiling. Maaari mong i-revoke ang isang key nang hindi naaapektuhan ang iba.
- Fallbacks. Kapag nabigo ang isang call o masyadong malaki ang prompt, awtomatiko itong nire-retry gamit ang ibang model.
- Naka-log na record. Sa bawat request, nagsusulat ng row na naglalaman ng cost nito, kaya masasagot kung aling app ang gumastos nito.
Bakit ikaw mismo ang magpatakbo ng gateway
Ang managed router ay kapareho ng setup, pero may proseso ng ibang provider sa pagitan ng bawat request. Kapag ikaw mismo ang nagpapatakbo nito, nananatili sa server na kontrolado mo ang mga key ng provider at prompt text mo. Totoo ang kapalit nito: ikaw na ang nag-ooperate ng component na umaasa rito ang bawat application. Tungkol sa gastos na ito ang huling section ng gabay na ito, dahil ito ang bahaging kadalasang hindi kasama sa ibang write-up.
Mga kailangan
- Isang VPS (virtual private server) na nagpapatakbo ng Ubuntu 24.04, na may naka-install na Docker at Compose plugin.
- Isang domain name na nakaturo rito, kung maa-access ng mga machine sa labas ng server ang gateway gamit ang TLS (transport layer security).
- Hindi bababa sa isang provider API key.
Walang inference na isinasagawa ang gateway. Ipinapasa nito ang mga request at ini-stream pabalik ang mga sagot, kaya nakabatay ang CPU load nito sa dami ng request at hindi sa laki ng model. Kayang patakbuhin ng isang 1 vCPU na server ang ilang internal application nang walang problema. Ang lumalaki ay ang database, dahil nagsusulat ang gateway ng isang spend row para sa bawat request.
Isulat muna ang config.yaml
Tinutukoy ng config file kung aling mga model ang maaaring hilingin ng client. Apat na top-level section ang mahalaga: model_list, litellm_settings, router_settings, at 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: 300Ang model_name ang pangalan na ipinapadala ng mga client. Ang litellm_params.model ang aktuwal na model, na isinusulat bilang provider/model. Pangalanan ang mga model batay sa gawain, hindi sa vendor. Patuloy na gagana ang application na humihiling ng bulk kapag nagpasya kang ibang model na dapat gamitin ng bulk sa susunod na buwan.
Sinasabi ng api_key: os.environ/ANTHROPIC_API_KEY sa LiteLLM na basahin ang variable na iyon sa runtime. Hindi lumilitaw sa file ang literal na key, na mahalaga dahil ang config.yaml ang file na kino-commit mo.
Sinasadya ang pagkakaroon ng dalawang entry na may pangalang strong. Kapag higit sa isang deployment ang may parehong model_name, itinuturing silang interchangeable ng router at ipinapamahagi nito sa mga iyon ang mga request para sa pangalang iyon. Sa ganitong paraan nananatiling gumagana ang strong kapag may provider na pansamantalang may problema: kapag nasa cooldown ang isang deployment (ipinapaliwanag sa ibaba), ipinapadala ang mga bagong request para sa strong sa isa pa.
Muling sinusubukan ng num_retries: 2 ang isang error na maaaring i-retry nang hanggang dalawang beses. Maaaring pumili ang mga retry na ito ng ibang available na deployment sa parehong model group: inilalarawan sa architecture docs ng LiteLLM, na sinuri noong 2026-10-29, ang mga retry sa loob ng group at ang mga cross-group fallback bilang magkahiwalay na hakbang. Dahil dito, maaaring mapunta sa ibang provider ang retry para sa strong nang hindi ine-enable ang weighted failover. Magti-trigger lamang ang fallback matapos magamit ang mga retry na iyon.
Ang allowed_fails at cooldown_time ay mga router option, kaya nasa ilalim sila ng router_settings. Binubuo ng proxy ang router nito mula sa section na iyon. Sa v1.95.0, hindi nakakarating dito ang cooldown_time kapag isinulat ito sa ilalim ng litellm_settings, kaya nananatiling tahimik na 5 segundo ang default na cooldown. Itinatakda ng cooldown_time: 30 kung gaano katagal mananatiling wala sa rotation ang isang deployment kapag nasa cooldown na ito. Inilalarawan ng configuration reference ang allowed_fails bilang bilang ng mga failure na kailangang malampasan ng isang deployment sa loob ng cooldown_time bago ito ilagay sa cooldown. Sa source ng v1.95.0, ang allowed_fails: 3 ang default. Kapag default ang halaga nito, ginagamit ng router ang mga built-in trigger; gagamitin lamang ang failure count kapag nagtakda ka ng ibang numero. Kabilang sa mga trigger na ito ang agarang cooldown kapag may 429 response sa isang group na may higit sa isang deployment, higit sa 50% failure sa kasalukuyang minuto matapos ang hindi bababa sa 5 request para sa ganitong group, at mga error na hindi ire-retry ng router, gaya ng 401 dahil sa maling key. May hiwalay ding trigger na naglalagay sa isang deployment sa cooldown kapag lahat ng request sa kasalukuyang minuto ay nag-fail at umabot ang traffic sa SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD, na default na 1000 request. Kaya para sa strong, na may dalawang deployment, hindi na susubukan sa bawat request ang provider na sunod-sunod na nagbabalik ng 500. Samantala, hindi magti-trigger ng cooldown ang isang paminsan-minsang 500 bawat ilang minuto. Iisa lamang ang deployment ng bulk, kaya hindi naaangkop dito ang failure-rate trigger: kapag nananatiling mas mababa sa 1000 request kada minuto ang burst ng 500, mananatili ito sa rotation. Ang nagpoprotekta sa mga caller nito ay ang num_retries na sinusundan ng fallback sa strong.
Magkaiba ang mga trigger ng fallbacks at context_window_fallbacks, at ang pangalawa ang kapaki-pakinabang na madalas nalalaktawan.
- Nagti-trigger ang
fallbackskapag nag-fail ang primary call. - Nagti-trigger ang
context_window_fallbackskapag tinanggihan ng provider ang request dahil mas mahaba ito kaysa sa context window ng model na iyon. Dahil dito, ipinapadala ang oversized prompt sa model na may sapat na kapasidad sa halip na magbalik ng error sa caller.
Mayroon ding content_policy_fallbacks para sa pagtanggi ng provider dahil sa content policy. Itakda lamang ito kung mayroon kang maayos na destinasyon para sa mga call na iyon.
Mag-deploy ng LiteLLM sa isang VPS gamit ang Docker Compose
Gumawa ng directory na naglalaman ng tatlong file: config.yaml, docker-compose.yml, at .env. Kinukuha ng upstream quickstart ang latest tag. Sa halip, mag-pin ng release tag upang maganap lamang ang upgrade kapag in-edit mo ang file at maging isang linya lamang ang rollback. Hindi garantiya ang tag lamang na magkakapareho ang eksaktong contents, dahil mutable ang image tags at maaaring ituro ng publisher ang isang tag sa bagong image. Kung kailangan ng docker compose up -d sa susunod na buwan na eksaktong ibigay ang gateway na ibinibigay nito ngayon, idagdag din ang image digest sa anyong ghcr.io/berriai/litellm:v1.95.0@sha256:<digest>; ipinapakita ito ng 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:Binabasa ng Compose ang .env nang dalawang beses dito. Una, upang palitan ang ${POSTGRES_PASSWORD} sa mismong compose file, at ikalawa, sa pamamagitan ng env_file upang maipasa ang bawat variable sa container.
Ang v1.95.0 ang kasalukuyang release noong August 2026. Tingnan ang releases page ng proyekto at i-pin ang kasalukuyang version kapag nag-deploy ka. Naglalathala ang bawat release ng signature, kaya maaari mong suriin ang image bago mo ito pagkatiwalaan:
cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0Ang port line ay 127.0.0.1:4000:4000, na nagpa-publish ng port sa loopback interface lamang. Isulat ang 4000:4000 sa halip at maaabot ang gateway mula sa buong internet, dahil nagdaragdag ang Docker ng sarili nitong rules sa iptables FORWARD chain at sinusuri ang mga ito bago ang rules ng ufw, kaya hindi ito mapipigilan ng ufw deny 4000. Ito ang pinakakaraniwang paraan kung paano nagiging bukas sa internet ang isang self-hosted gateway: tingnan ang kung paano direktang nagpa-publish ang Docker ng container port lampas sa ufw. Sa halip, dumarating ang traffic mula sa labas sa pamamagitan ng reverse proxy.
Panatililiing wala sa image ang provider keys
Nasa .env file ang lahat ng secret. Ipinapasa ito bilang environment variable sa runtime, kaya hindi ito kailanman isinasama sa image at hindi rin ito kailanman kino-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-...Bumuo ng dalawang LiteLLM key gamit ang tunay na randomness, pagkatapos ay higpitan ang permission ng file:
printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .envAng LITELLM_MASTER_KEY ang admin credential. Ginagamit ito para mag-authenticate sa management API at ito rin ang password para sa Admin UI sa /ui. Hindi ito dapat hawakan ng anumang application.
Ini-encrypt ng LITELLM_SALT_KEY ang mga provider credential na naka-store sa database. Itakda ito nang isang beses at huwag nang palitan. Kapag pinalitan ito kalaunan, hindi na made-decrypt ang mga credential na naka-store na. Karaniwang mag-i-start ang gateway, pero mabibigo sa authentication ang bawat call sa mga provider na iyon.
Hinahayaan ka ng STORE_MODEL_IN_DB=True na magdagdag at mag-edit ng mga model mula sa Admin UI nang hindi binabago ang config.yaml. Maginhawa ito, pero nahahati sa dalawang source of truth ang configuration. Piliin kung alin ang authoritative at isulat ang desisyong iyon sa tabi ng config.
Ang dahilan kung bakit hindi dapat nasa config file ang mga key ay siya ring dahilan kung bakit hindi dapat mapunta ang mga ito sa tools na ibinibigay mo sa isang agent. Tinalakay sa Pag-iwas na mapunta ang provider secrets sa AI agents ang pattern na iyon, at sa env files at secrets sa Docker Compose naman ang mechanics nito.
I-start ito at i-monitor ang unang boot:
docker compose up -d
docker compose logs -f litellmTiyaking aktuwal na gumagana ito
May dalawang probe na walang authentication at isang probe na may authentication. Magkakaiba ang dahilan ng kanilang failure.
curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readinessHindi nangangailangan ng authentication ang /health/liveliness at sumasagot ito ng "I'm alive!" habang tumatakbo ang process. Hindi rin nangangailangan ng authentication ang /health/readiness. Nagbabalik ito ng JSON object na may "status": "healthy" at field na db, o 503 kapag hindi maabot ang database. Ituro ang monitoring sa readiness, dahil mananatiling green ang liveliness sa isang gateway na hindi makahanap ng kahit isang virtual key.
Ang authenticated check ang kumokonekta sa mga provider:
curl -s http://127.0.0.1:4000/health \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"Sumasagot ito gamit ang mga array na healthy_endpoints at unhealthy_endpoints. Kapag may model sa unhealthy_endpoints na may authentication error, nangangahulugan itong mali o nawawala ang provider key sa .env. Ito ang failure na kailangan mong mahanap ngayon. Dahil naka-set ang background_health_checks: true, awtomatikong pinapatakbo ng proxy ang mga probe na ito bawat health_check_interval segundo, at ibinabalik ng /health ang pinakahuling resulta. Kaya kapag nag-poll dito, hindi ito nagpapadala ng test request sa iyong mga provider sa bawat pagkakataon.
Virtual keys at budget kada key
Bawat application ay may sariling key na ginawa gamit ang 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
}'May key field ang response na nagsisimula sa sk-. Ang string na iyon ang natatanggap ng application, at iyon lamang ang bagay na kailanman nitong natatanggap.
- Ang
modelsay allowlist ng mga request na maaaring gawin ng key na ito. Ang key sa itaas ay maaaring humiling ngbulkat wala nang iba. - Ang
max_budget: 5kasama angbudget_duration: "30d"ay limang US dollars bawat calendar month. Nire-reset ng LiteLLM ang30dbudget sa unang araw ng bawat buwan pagsapit ng midnight, sa UTC maliban kung itakda mo angtimezonesa ilalim nglitellm_settings. Hindi ito batay sa rolling 30 days. Kapag nakagastos na ang key ng limang dolyar, hihinto itong gumana hanggang sa susunod na unang araw ng buwan. - Nililimitahan ng
rpm_limitattpm_limitang requests per minute at tokens per minute para sa key na ito lamang. - Ang
key_aliasang makikilala mo sa spend log pagkalipas ng anim na linggo. Palagi itong itakda.
Kapag naubos na ang budget, mabibigo ang call at magbabalik ito ng error na may type na budget_exceeded at message na ganito ang anyo:
Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>Depende sa release ang status code. Sa naka-pin na v1.95.0, HTTP 429 ito. Simula sa v1.104.0, ang default ay HTTP 422, at ibinabalik ng pagtatakda ng budget_exceeded_status_code: 429 sa ilalim ng litellm_settings ang dating code. Ang tunay na rpm_limit at tpm_limit hits ay nagbabalik pa rin ng 429 sa alinmang release. Suriin kung alin ang natatanggap mo pagkatapos ng bawat upgrade.
Ang status code ang dahilan kung bakit nakalilito ito, dahil wala sa dalawang code ang nagsasabing "budget". Iniuulat ng client library ang 429 bilang rate limit at maaaring i-retry ito nang may backoff laban sa budget na hindi babalik hanggang sa reset. Iniuulat naman nito ang 422 bilang request na hindi ma-process. I-log ang response body kasabay ng status code. Kung hindi, magmumukhang ibang problema ang pagkaubos ng budget sa bawat pagkakataon.
I-inspect at baguhin ang mga key gamit ang kaparehong management API:
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}'Mananatiling umiiral ang budget na ipinapatupad sa gateway kahit ang mismong agent ang may problema. Kaya ito ang backbone ng cost control para sa AI agents sa isang VPS.
Magpadala ng maramihang gawain sa murang model
Ituro ang client sa gateway. Gamitin ang Base URL, key, at 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."}]
}'Pareho ang paraan sa anumang OpenAI client library, bagama't nagkakaiba ang mga pangalan ng option depende sa language. Sa Python client, itakda ang base_url sa https://gateway.example.com/v1 at ang api_key sa virtual key. Sa JavaScript at TypeScript client, ang parehong dalawang option ay baseURL at apiKey.
Awtomatikong inilalapat ang routing policy mula sa config.yaml nang hindi ito kailangang malaman ng caller. Ipinapadala sa murang model ang request para sa bulk. Kung mabigo ang tawag matapos ang mga retry nito, ire-retry ang request gamit ang strong. Kung masyadong mahaba ang prompt para sa bulk, ipinapadala ito ng context_window_fallbacks sa strong sa halip na magbalik ng error. Ang maramihang gawain gaya ng classification pass o pagbubuod ng backlog ay default na tumatakbo sa murang model, at ang mahihirap na request lamang ang mas magastos.
Dito rin kapaki-pakinabang ang gateway para sa mga agent na gumagamit ng tools. Maaaring ituro ng MCP (model context protocol) server sa parehong VPS at ng agent na kumokontrol dito ang parehong endpoint, kaya maaaring palitan ang model sa likod ng mga ito nang hindi muling nagde-deploy ng alinman.
Paano mo malalaman kung nagkaroon ng fallback?
Ito ang failure mode na nagdudulot ng gastos dahil walang mukhang sira. Ang matagumpay na fallback ay nagbabalik ng HTTP 200 na may karaniwang response body. Maaaring down ang murang model mo nang isang araw, habang tahimik na sine-serve ng mas mahal na model ang bawat call. Ang unang ebidensiya ay ang invoice.
Makikita ang ebidensiya sa response headers. Hingin ang mga ito:
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-groupang pangalan ng model kung saan ni-route ang request, gaya ngbulk.x-litellm-model-idang ID ng deployment na sumagot; maaari mo itong hanapin gamit ang/v1/model/info?litellm_model_id=.... Kapag hindi kabilang ang ID na iyon sa iyongbulkdeployments, nagkaroon ng fallback.- Binibilang ito ng
x-litellm-attempted-fallbacksatx-litellm-attempted-retries. Sa isang healthy na call, walang lalampas sa 0 sa mga ito. x-litellm-response-costang halaga ng isang call na iyon sa US dollars.x-litellm-call-idang identifier na ginagamit mo upang mahanap ang parehong call sa iyong logs.
I-record ang x-litellm-attempted-fallbacks sa bawat request at maglagay ng alert kapag mas mataas ito sa 0. Ang iisang numerong iyon ang naghihiwalay sa routing policy na gumagana sa routing policy na tahimik nang naging “palaging gamitin ang mas mahal na model.”
Ang kumpletong bersyon nito ay tracing, at kailangan nito ng sarili nitong setup: self-hosted Langfuse para sa tracing ng agent calls. Kasama sa LiteLLM ang callback, kaya dalawang linya lang at credentials ang kailangan para mai-configure ito.
litellm_settings:
success_callback: ["langfuse"]
failure_callback: ["langfuse"]LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.comPara sa Langfuse v3 at mas bago, inirerekomenda na ngayon ng Langfuse page ng LiteLLM ang langfuse_otel preset nito; documented pa rin ang langfuse callback sa itaas. I-set din ang failure_callback pati ang success_callback. Kapag nilaktawan mo ito, ang tanging traces na mase-save mo ay ang mga request na walang naging problema. Hiwalay sa mga ito, nagsusulat ang LiteLLM ng spend row para sa bawat request sa Postgres, at binabasa ng Admin UI sa /ui ang table na iyon. Lumalaki ito kasabay ng traffic, kaya i-monitor ito kapag maliit ang disk.
Ilagay ang gateway sa likod ng isang reverse proxy
Walang dapat na makarating sa port 4000 mula sa labas ng server. I-terminate ang TLS sa nginx o Caddy at i-forward ito sa loopback address.
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;
}Dalawa sa mga linyang ito ang madalas makalimutan ng mga tao. Mahalaga ang proxy_buffering off dahil ang streaming completion ay serye ng server-sent events, at kapag naka-enable ang buffering, kinokolekta ng nginx ang mga chunk sa buffers bago ito i-forward, na nagiging sanhi ng pagkaantala ng pagdating nito sa client. Mahalaga ang proxy_read_timeout 600s dahil ang default na 60 segundo ng nginx ay ang pinakamahabang oras na naghihintay ito sa pagitan ng dalawang read mula sa gateway, hindi ito limitasyon para sa buong response. Ang isang non-streamed completion ay walang ipinapadala hangga't hindi tapos ang generation, kaya kung matagal ito, lalampas ito sa 60 segundo nang walang natatanggap na byte, at makakatanggap ang client ng 504 habang nire-record ng error log ang upstream timed out (110: Connection timed out) while reading response header from upstream. Ang isang streamed completion na patuloy na nagpapadala ng mga chunk ay maaaring tumagal nang higit sa 60 segundo; magti-trigger lamang ang timeout kung mananatiling tahimik ang model sa loob ng ganoong katagal na panahon.
Para sa certificate, ang Certbot na may Let's Encrypt sa nginx ang pinakamabilis na paraan. Kung ang server ay nagpapatakbo na ng ilang containers, ang Traefik sa harap ng maraming Compose apps ang humahawak sa routing at certificates sa iisang lugar.
Ang gateway ay isa na ngayong single point of failure
Maging tapat sa kung ano ang iyong binuo. Ang bawat application na pagmamay-ari mo ay nakadepende na ngayon sa isang container sa isang VPS. Habang ito ay down, walang makakatawag sa anumang model, kabilang ang mga provider na maayos naman ang takbo. Apat na bagay ang dapat tandaan mula rito.
- Ang maling config ay magpapabagsak sa lahat nang sabay-sabay. Ang
restart: unless-stoppeday nagre-restart ng crash, at nirere-restart nito ang container na hindi makapag-parse ng config.yaml nang paulit-ulit. Basahin angdocker compose logs litellmpagkatapos ng bawat pagbabago sa config, at gumawa lamang ng mga pagbabago kung may oras kang bantayan ang mga ito. - Ang Postgres ay nasa request path kapag may cache miss. Ginagamit ito ng virtual key lookup kapag ang key ay wala sa cache; ang spend recording ay tumatakbo nang asynchronously pagkatapos ng response. Ang
/health/readinessna nagbabalik ng 503 ay ang iyong babala na ang gateway ay tumatakbo pero hindi magawa ang alinman sa dalawa. - Gamitin muna ang mga core, bago magdagdag ng mga instance. Ang production guidance ng project na isang worker bawat instance (
--num_workers 1) ay para sa Kubernetes o iba pang pod autoscaler na nagdaragdag ng mga instance para sa iyo. Para sa isang single VM o bare container na gaya nito, kabaligtaran ang payo: itakda ang worker count ayon sa vCPU count ng machine. Sa 1 vCPU box sa itaas, ito ay--num_workers 1pa rin; sa mas malaking box, itaas ito, at tandaan na ang bawat worker ay may sariling memory. Ang pangalawang gateway sa likod ng isang load balancer ang magtatanggal sa single container bilang isyu. Hindi nito tinatanggal ang database. - I-back up ang mga bagay na hindi mo na maibabalik. Ito ay ang
config.yamlat.env, kasama ang isangpg_dumpng database. Ang pagkawala ngLITELLM_SALT_KEYay magpapawalang-bisa sa mga encrypted provider credential sa loob ng dump na iyon, kaya ang env file at ang dump ay dapat kasama sa iisang backup job: restic backups sa off-box storage.
Ang pag-upgrade ay ang pag-edit ng image tag at pagtakbo ng docker compose up -d. Ang LiteLLM ay nagpapatakbo ng prisma migrate deploy sa startup bilang default, kaya ang bagong container ang magma-migrate ng database schema sa unang boot nito. Kumuha ng dump bago mo palitan ang tag, dahil ang pagbabalik sa lumang image ay hindi mag-a-undo ng migration na tumakbo na.
Basahin ang release notes ng bawat version na lalakpasan mo, hindi lang ang version na iyong pupuntahan. Ang paglipat mula v1.95.0 patungong v1.104.0 o mas bago ay may ilang breaking changes: ang budget status code sa itaas, isang proxy na tumatangging mag-start kapag may unset, empty, o publicly known master key, at isang proxy na nag-e-exit kapag nabigo ang database setup sa startup, na sa ilalim ng restart: unless-stopped ay lalabas bilang restart loop. Kung galing ka sa v1.102.x o mas maaga, ang mga note ng v1.104.0 ay humihiling din na ikaw mismo ang gumawa ng dalawang LiteLLM_SpendLogs index.
FAQ
Nagdaragdag ba ang LiteLLM ng kapansin-pansing latency sa bawat call?
Naglalathala ang proyekto ng 8 ms sa 95th percentile sa 1000 requests bawat segundo, ayon sa README nito noong November 2026. Ituring ito bilang vendor figure. Ang aktuwal na may pinakamalaking epekto sa latency ay ang network distance sa pagitan ng iyong mga application at gateway, dahil nagdagdag ka ng isang round trip sa bawat call. Patakbuhin ang gateway sa parehong region ng mga application na tumatawag dito. Pagkatapos, sukatin ang sarili mong overhead gamit ang x-litellm-overhead-duration-ms header sa isang aktuwal na response.
Bakit tumigil ang streaming matapos kong ilagay ang nginx sa unahan?
Dahil bina-buffer ng nginx ang mga upstream response bilang default, at ang streaming completion ay serye ng server-sent events. Kapag naka-on ang proxy_buffering, kinokolekta ng nginx ang mga chunk sa buffers bago ipasa ang mga ito, kaya nade-delay ang paghahatid sa client. Itakda ang proxy_buffering off; sa location block. Itaas din ang proxy_read_timeout sa parehong block. Bilang default, sumusuko ang nginx matapos ang 60 segundo na walang data mula sa gateway. Madaling umabot dito ang isang matagal na non-streamed generation, kaya nakakatanggap ang client ng 504.
Ano ang nangyayari kapag naubos ang budget ng isang virtual key?
Nabibigo ang call na may error na type budget_exceeded at mensaheng nasa anyong Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>. Sa pinned v1.95.0, HTTP 429 ang status. Mula sa v1.104.0, HTTP 422 na ang default. Wala sa dalawang code ang nagsasabing budget ang dahilan. Ito ang karaniwang nakalilito: iniuulat ng isang client library ang 429 bilang rate limit at maaaring i-retry ito, kaya rate throttling ang sinusubukan ng mga tao sa halip na basahin ang mensahe. I-log ang response body kasabay ng status code. Kumpirmahin ang aktuwal na position ng key gamit ang /key/info?key=sk-... laban sa master key. Itaas ang ceiling gamit ang /key/update kung masyadong mababa ang itinakdang budget.
Maaari bang mag-route ang gateway sa local model pati sa hosted models?
Oo. Isa itong karagdagang entry sa model_list. Gamitin ang ollama_chat/ prefix kasama ang api_base, halimbawa model: ollama_chat/llama3.1 kasabay ng api_base: http://ollama:11434. Sa default networking ng Compose, ang localhost sa loob ng isang container ay nangangahulugan ng container na iyon. Kaya gamitin ang Compose service name o address ng host sa Docker network, at huwag gamitin ang 127.0.0.1. Ang host networking, kung saan ibinabahagi ng container ang network stack ng host, ang eksepsiyon. Hiwalay na gawain ang pag-stand up ng local model. Tingnan ang pagho-host ng LLM gamit ang Ollama sa isang VPS.