본문으로 건너뛰기

LiteLLM으로 로컬 LLM 게이트웨이 만들기: Ollama 앞에 가상 키·요청 한도·예산을 붙이고 kind에서 직접 확인하기

인증이 없는 Ollama 앞에 LiteLLM을 두고, 사용자별 키·허용 모델·분당 요청 수·예산이 실제로 어떤 응답을 돌려주는지 하나씩 확인했습니다.

로컬 AI 플랫폼 실습 시리즈 목차 · 글 5개
  1. 1편RTX 3060 Ti 8GB로 로컬 LLM 돌리기: Ollama 모델 4개 속도·VRAM·품질 실측
  2. 번외편Ollama 웹 채팅 화면 직접 만들기: HTML 한 장으로 WSL의 로컬 LLM에 연결하고 CORS까지 이해하기
  3. 2편kind 파드에서 클러스터 밖 Ollama 호출하기: selector 없는 Service와 EndpointSlice로 GPU는 밖, 앱은 안에
  4. 3편LiteLLM으로 로컬 LLM 게이트웨이 만들기: Ollama 앞에 가상 키·요청 한도·예산을 붙이고 kind에서 직접 확인하기
  5. 4편LiteLLM 관측하기: Prometheus·Grafana·Tempo로 LLM 호출의 토큰·지연·오류·비용 보고 경보 걸기

Ollama에는 인증이 없어서 클러스터 안 어떤 파드든 모델을 부를 수 있습니다. 그 앞에 LiteLLM을 두면 사용자별 가상 키로만 호출할 수 있고, 키마다 허용 모델·분당 요청 수·예산을 걸 수 있습니다. 실측에서 키 없는 요청은 401, 허용되지 않은 모델은 403, 요청 한도 초과는 429, 예산 초과는 422로 막혔고, 게이트웨이를 거쳐도 짧은 질문은 0.2초 안에 답했습니다. 다만 qwen3가 LiteLLM을 거치면 생각 모드로 동작해 응답이 약 5배 느려지고, 사용자를 만들 때 모델 제한 없는 키가 자동으로 생기는 함정이 있었습니다.

kind 클러스터(노드 3개)에 LiteLLM 1.110.0(Helm 단일형 차트)과 CloudNativePG PostgreSQL을 올리고, WSL에서 GPU로 도는 Ollama(qwen3:8b·gemma3:4b·llama3.1:8b)를 연결한 결과입니다. 사용자 alice·bob은 가상 사용자이고, 비용은 예산 한도를 보여 주기 위한 시연용 가상 단가입니다.

왜 Ollama 앞에 게이트웨이가 필요한가

2편에서 kind 파드가 클러스터 밖(WSL)의 Ollama를 http://ollama.ai.svc:11434로 부르게 만들었습니다. 그때 확인한 문제가 하나 있었습니다. Ollama API에는 인증이 없어서, 클러스터 안의 어떤 파드든 키 없이 모델을 호출할 수 있고 모델 삭제 같은 관리 API도 같은 주소로 열려 있습니다.

여러 사람과 앱이 같은 GPU를 나눠 쓰려면 “누가 부르는지”, “어떤 모델을 쓸 수 있는지”, “얼마나 많이 부르는지”를 정할 수 있어야 합니다. LiteLLM은 여러 모델 서버 앞에서 OpenAI 호환 API(/v1/chat/completions)를 제공하면서, 가상 키·요청 한도·예산·사용량 기록을 맡는 게이트웨이입니다. LiteLLM Virtual Keys

구성

이번 편에서 올린 것 (네임스페이스 ai)

구성 요소 역할 값
LiteLLM 키 확인, 한도 적용, 모델 라우팅, 사용량 기록 Helm 차트 litellm-helm 1.110.0, 이미지 ghcr.io/berriai/litellm:1.110.0
litellm-db 가상 키·사용자·사용량 저장 CloudNativePG Cluster, 인스턴스 1개, 1Gi
master key 관리자 키(키 발급·삭제) 직접 만든 Secret litellm-master-key
Ollama 실제 모델 실행 2편의 ollama.ai.svc:11434

가상 키를 쓰려면 PostgreSQL과 sk-로 시작하는 master key가 필요합니다. 이 클러스터에는 k8s-lab 시리즈에서 설치한 CloudNativePG 운영자가 있어 DB를 그것으로 만들었습니다. 실습용이라 인스턴스는 1개이고 이중화는 하지 않았습니다.

DB와 master key 준비

CloudNativePG Cluster를 만들면 운영자가 DB 사용자와 비밀번호를 만들어 litellm-db-app Secret에 username·password 키로 넣고, 쓰기용 Service litellm-db-rw를 만듭니다.

03-litellm-db.yaml (일부)
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: litellm-db
namespace: ai
spec:
instances: 1
bootstrap:
initdb:
database: litellm
owner: litellm
storage:
size: 1Gi

master key는 무작위 값으로 만들어 Secret에만 넣었습니다. 값은 화면이나 기록에 출력하지 않습니다.

03-install.sh (일부)
KEY="sk-$(openssl rand -hex 24)"
kubectl -n ai create secret generic litellm-master-key --from-literal=master-key="$KEY"

설치: 문서와 차트의 설정 이름이 달랐다

LiteLLM Helm 차트는 두 종류입니다. Redis 없이 한 파드로 도는 단일형 oci://ghcr.io/berriai/litellm-helm과, 게이트웨이·백엔드·UI를 나눈 구성요소 분리형(외부 PostgreSQL·Redis 필수)입니다. LiteLLM Deploy 실습에는 단일형을 썼습니다.

그런데 현재 공식 Helm 문서는 분리형 기준이라 database.writer.*, masterKey.secretName 같은 이름을 씁니다. 단일형 차트에 그대로 쓰면 적용되지 않습니다. 실제 값 이름은 차트에서 직접 확인했습니다.

Terminal window
helm show values oci://ghcr.io/berriai/litellm-helm --version 1.110.0 > values.yaml
03-litellm-values.yaml (일부)
masterkeySecretName: litellm-master-key
masterkeySecretKey: master-key
db:
useExisting: true # 차트가 Postgres를 따로 띄우지 않음
deployStandalone: false
endpoint: litellm-db-rw # CNPG 쓰기용 Service
database: litellm
secret:
name: litellm-db-app # CNPG가 만든 접속 Secret
usernameKey: username
passwordKey: password

설치는 1분 33초 걸렸고, DB 마이그레이션 Job이 끝난 뒤 /health/readiness가 {"status":"healthy","db":"connected"}를 돌려줬습니다.

모델에 짧은 이름 붙이기와 fallback

앱은 Ollama 모델 이름 대신 LiteLLM이 정한 이름으로 부릅니다. Ollama 연결은 /api/chat을 쓰는 ollama_chat/ 접두사가 권장됩니다. LiteLLM Ollama

03-litellm-values.yaml (일부)
proxy_config:
model_list:
- model_name: chat
litellm_params:
model: ollama_chat/qwen3:8b
api_base: http://ollama.ai.svc:11434
think: false # 아래 '생각 모드' 절 참고
input_cost_per_token: 0.000001 # 시연용 가상 단가
output_cost_per_token: 0.000002
- model_name: fast
litellm_params:
model: ollama_chat/gemma3:4b
api_base: http://ollama.ai.svc:11434
- model_name: llama
litellm_params:
model: ollama_chat/llama3.1:8b
api_base: http://ollama.ai.svc:11434
litellm_settings:
fallbacks:
- chat: ["fast"]
general_settings:
master_key: os.environ/PROXY_MASTER_KEY

chat이 실패하면 fast로 넘기도록 fallback을 걸었습니다. 1편에서 생각 과정을 끌 수 없었던 qwen3:4b는 목록에서 뺐습니다. 로컬 모델은 실제 비용이 0이라 예산이 줄지 않으므로, 예산 한도를 보여 주려고 토큰당 가상 단가를 붙였습니다. fast·llama에도 같은 단가를 붙였습니다.

LiteLLM 관리 화면 Model Management에 chat(ollama_chat/qwen3:8b), fast(ollama_chat/gemma3:4b), llama(ollama_chat/llama3.1:8b) 세 모델이 Defined in config로 등록되어 있고 비용이 IN $1.00, OUT $2.00으로 표시된 화면
LiteLLM에 등록한 모델 3개

관리 화면의 비용 칸은 100만 토큰당 가격이라, 설정한 토큰당 0.000001·0.000002가 IN $1.00·OUT $2.00으로 보입니다.

함정 1: LiteLLM을 거치면 qwen3가 생각 모드로 돈다

처음에는 think: false 없이 설치했습니다. 1편의 요약 작업과 같은 질문을 보내자 결과가 크게 달랐습니다.

같은 요약 작업, qwen3:8b

경로 응답 시간 출력 토큰 생각 과정
Ollama 직접(think false) 1.39~1.47초 - 없음
LiteLLM 경유(설정 전) 6.6~6.8초 404 있음(reasoning_content)

LiteLLM이 Ollama에 생각 여부를 넘기지 않아 qwen3의 기본 동작(생각 켬)이 된 것입니다. 요청마다 think: false나 reasoning_effort: "none"을 넣으면 꺼졌고, 짧은 질문이 2.6초에서 0.2초로 줄었습니다. 하지만 채팅 화면 같은 클라이언트가 매번 이 값을 넣어 주지는 않으므로 모델 설정(litellm_params.think: false)에서 껐습니다.

설정에서 끈 뒤에는 요청에 reasoning_effort: "low"를 넣어도 다시 켜지지 않았습니다. 생각 모드가 필요한 사용자가 있다면 생각을 켠 모델 이름을 따로 하나 더 만드는 편이 낫습니다.

사용자와 가상 키 만들기 (함정 2: 자동 생성 키)

가상 사용자 alice와 bob을 만들고 키를 발급했습니다. alice는 chat·fast를 분당 3번까지, bob은 fast만 예산 0.001(가상 단가)까지 쓰게 했습니다.

Terminal window
# master key로 호출
curl -s -H "Authorization: Bearer $MASTER_KEY" -H 'Content-Type: application/json' \
http://litellm.ai.svc:4000/user/new \
-d '{"user_id":"alice","auto_create_key":false}'
curl -s -H "Authorization: Bearer $MASTER_KEY" -H 'Content-Type: application/json' \
http://litellm.ai.svc:4000/key/generate \
-d '{"user_id":"alice","key_alias":"alice-key","models":["chat","fast"],"rpm_limit":3}'
curl -s -H "Authorization: Bearer $MASTER_KEY" -H 'Content-Type: application/json' \
http://litellm.ai.svc:4000/key/generate \
-d '{"user_id":"bob","key_alias":"bob-key","models":["fast"],"max_budget":0.001}'

위 명령의 "auto_create_key":false가 중요합니다. 처음에는 이 값 없이 /user/new를 불렀는데, 응답에 모델 제한이 없는 키가 하나 자동으로 들어 있었습니다. 이 자동 키로 chat과 llama를 모두 호출할 수 있었습니다. 사용자마다 따로 제한을 건 키를 발급해도, 자동 키가 남아 있으면 제한을 우회할 수 있습니다.

LiteLLM Virtual Keys 목록. bob-load, alice-load, prometheus-metrics, bob-key, alice-key 등 키별 사용자, 사용 금액과 예산, 허용 모델이 보이고, 별칭 없이 All Proxy Models로 표시된 자동 생성 키 3개가 있으며 키 값 끝자리는 가림
Virtual Keys 목록 (키 끝자리 가림)

관리 화면의 Virtual Keys 목록에서도 별칭이 -이고 모델이 “All Proxy Models”인 키 3개가 보입니다. 이것이 /user/new가 자동으로 만든 키입니다. 화면의 bob 키 예산은 “of $0”으로 보이는데, 0.001 같은 작은 값이 화면에서 반올림된 것으로 보이며 실제 차단은 0.001에서 동작했습니다. 목록에 있는 -load 키와 prometheus-metrics 키는 4편에서 만든 키입니다.

한도별 실제 응답

확인용 파드에서 각 경우를 호출해 상태 코드와 오류 본문을 기록했습니다.

한도별 응답 (가상 사용자)

상황 HTTP 응답 요지(type)
키 없이 호출 401 Malformed API Key passed in. Ensure Key has 'Bearer ' prefix. (auth_error)
잘못된 키 401 Invalid API key provided. (token_not_found_in_db)
bob(fast만 허용)이 chat 호출 403 The requested model 'chat' is not available for this API key (key_model_access_denied)
alice(분당 3회) 4번째 요청 429 Rate limit exceeded ... Limit type: requests. Current limit: 3, Remaining: 0 (throttling_error)
bob(예산 0.001) 4번째 호출 422 Budget has been exceeded! ... Current cost: 0.001036..., Max budget: 0.001 (budget_exceeded)

예산은 호출 전에 지금까지 쓴 금액을 확인합니다. bob은 3번째 호출로 누적 0.001036이 되어 한도를 살짝 넘겼고, 4번째부터 막혔습니다. 마지막 한 번은 한도를 넘겨도 처리되므로, 한도를 딱 맞춰야 한다면 조금 낮게 잡아야 합니다.

429와 422 오류 본문에는 키의 해시값이나 키 끝 4글자가 들어 있어, 오류 메시지를 화면에 그대로 보여 주는 앱이라면 이 부분을 가리는 편이 좋습니다.

사용량 확인

키·사용자별 사용량은 API(/key/info, /user/info, /spend/logs)와 관리 화면(/ui)에서 볼 수 있습니다. 관리 화면은 kubectl -n ai port-forward svc/litellm 4000:4000으로 열고, 아이디 admin과 master key로 로그인했습니다.

LiteLLM 관리 화면 Home의 요약 카드: Spend $0.01, Total Requests 144(85 ok, 59 failed), Total Tokens 8.5K, Avg cost per request $0.0001, Avg latency 6.4s, 59.0% success rate
LiteLLM 관리 화면 Home

위 숫자는 3편과 4편 실습 동안 쌓인 값입니다. 실패 59건에는 일부러 만든 401·403·429와 장애 훈련의 500이 섞여 있고, 평균 지연 6.4초에는 모델을 메모리에 올리는 시간(20초대)이 포함되어 있습니다.

LiteLLM Usage 화면 Overview: 일별 비용 막대 그래프에 chat과 fast가 쌓여 있고, Top models에 chat 76.1%, fast 23.4%, llama 0.5%로 표시
LiteLLM Usage 화면

Usage 화면에서는 모델별 비중을 볼 수 있습니다. 이 기간에는 chat이 76.1%로 가장 많이 쓰였습니다. 지표를 그래프와 경보로 보는 방법은 다음 편에서 다룹니다.

모델을 바꿔 부를 때의 비용

master key로 chat과 fast를 번갈아 불렀습니다.

호출 순서별 응답 시간

순서 모델 응답 시간
1 chat (qwen3:8b) 25.8초
2 chat 0.16초
3 fast (gemma3:4b) 24.1초
4 fast 0.35초
5 chat 26.8초

끝난 뒤 ollama ps에는 qwen3:8b(5,328MiB)만 남아 있었습니다. 이 PC의 VRAM(여유 약 7GB)에는 qwen3:8b와 gemma3:4b가 함께 올라가지 못해, 모델을 바꿀 때마다 내리고 다시 올립니다. 사용자들이 서로 다른 모델을 번갈아 쓰면 매번 20초대 지연이 생기므로, GPU가 작다면 게이트웨이에 공개하는 모델 수를 줄이는 것도 방법입니다.

장애 훈련: Ollama가 멈추면

Ollama 서비스를 멈춘 상태에서 LiteLLM을 호출했습니다.

Ollama 정지 중 결과

확인 결과
LiteLLM /health/readiness healthy, db: connected (Ollama 상태는 반영 안 함)
chat 호출 10.5초 뒤 500. model group 'chat' failed ... Fallback to fast also failed ... LiteLLM Retried: 2 times
fast 호출 4.7초 뒤 500
Ollama 재시작 → 응답 7.1초
재시작 후 chat 200, 20.6초(모델 로딩 포함)

2편에서 Ollama를 직접 불렀을 때는 0.001초 만에 연결 실패가 났지만, LiteLLM은 재시도 2번과 fallback까지 시도하느라 5~10초 뒤에 실패했습니다. 앞단 앱의 시간 제한을 정할 때 이 시간을 고려해야 합니다.

fallback도 소용이 없었습니다. chat과 fast가 같은 Ollama 서버를 쓰기 때문입니다. fallback은 다른 서버나 클라우드 모델처럼 다른 백엔드로 넘길 때 의미가 있습니다. 또 readiness가 healthy를 돌려주므로, 쿠버네티스 상태 점검만 보고는 모델이 죽은 것을 알 수 없습니다.

실습 중 만난 운영 함정 두 가지

설치·운영 함정

함정 증상 해결
WSL 자동 종료 열린 WSL 창이나 프로세스가 없으면 WSL이 꺼지고 kind·Ollama도 멈춤. 다시 켜지는 동안 CloudNativePG webhook 시간 초과로 첫 설치 실패 작업하는 동안 WSL 프로세스 하나(sleep infinity 등)를 띄워 둠
helm upgrade --wait 실패 DB 마이그레이션 Job이 끝나고 2분 뒤(ttlSecondsAfterFinished: 120) 지워지면, --wait가 그 Job을 찾다 10분 뒤 UPGRADE FAILED. 배포 자체는 적용됨 --wait를 빼고 kubectl rollout status deploy/litellm으로 확인

무료로 되는 것과 Enterprise 기능

이번에 쓴 가상 키, 키별 허용 모델, 요청 한도, 예산, 사용량 기록은 모두 Enterprise 라이선스 없이 동작했습니다. LiteLLM 문서 기준으로 키 자동 교체, 감사 로그, 키별 모델별 예산, 관리 화면 SSO(5명 초과)는 Enterprise 기능입니다(2026년 11월 기준). LiteLLM Enterprise

핵심 요약

항목 내용
구성 LiteLLM(단일형 차트 1.110.0) + CloudNativePG DB, Ollama는 ollama.ai.svc로 연결
한도 응답 키 없음 401, 허용 안 된 모델 403, 요청 한도 429, 예산 초과 422
생각 모드 LiteLLM 경유 qwen3는 생각 모드(6.7초) → litellm_params.think: false로 끔
자동 키 /user/new는 모델 제한 없는 키를 자동 생성 → auto_create_key: false
모델 전환 8GB GPU에서 chat↔fast 전환마다 24~27초
장애 Ollama 정지 시 readiness는 healthy, 요청은 재시도 후 5~10초 뒤 500

자주 묻는 질문

LiteLLM Helm 문서의 설정 이름이 적용되지 않아요.

현재 문서는 구성요소 분리형 차트 기준입니다. 단일형 litellm-helm 차트는 masterkeySecretName, db.useExisting 같은 다른 이름을 쓰므로 helm show values로 실제 이름을 확인해야 합니다.

예산을 0.001로 걸었는데 왜 조금 넘게 쓰였나요?

LiteLLM은 호출 전에 누적 금액을 확인합니다. 한도 직전에 들어온 호출은 처리되므로 마지막 한 번만큼 넘을 수 있습니다.

로컬 모델인데 비용이 왜 나오나요?

예산 한도를 보여 주려고 모델에 시연용 가상 단가를 지정했기 때문입니다. 단가를 지정하지 않으면 로컬 모델의 비용은 0으로 기록됩니다.

LiteLLM 관리 화면에는 어떻게 로그인하나요?

아이디 admin과 master key로 로그인합니다. master key는 모든 관리 권한을 가진 키라 화면 캡처나 공유에 주의해야 합니다.

작성 방식과 다음 편

이 글의 명령, 응답, 시간은 모두 앞선 편과 같은 PC의 kind 클러스터에서 직접 실행한 결과이고, 설정은 LiteLLM 공식 문서와 차트 값을 기준으로 했습니다. 사용자 alice·bob은 가상 사용자이며 비용은 시연용 가상 단가입니다. 키 값은 기록과 화면에서 가렸고, 실행 기록 정리와 글 작성에 AI 도구를 함께 썼습니다. 다음 편에서는 LiteLLM의 지표와 트레이스를 Prometheus·Grafana·Tempo에 연결해 이번에 본 현상을 그래프와 경보로 확인할 예정입니다.

사진을 누르면 원본 크기