본문 바로가기
삵
AI

LiteLLM으로 여러 LLM을 한 창구로 묶기

sstdio.h·2026년 11월 21일·조회 0

서비스 코드 여기저기에 OpenAI 키, Anthropic 키, Bedrock 자격증명이 흩어져 있으면 모델 하나 갈아끼우는 일조차 배포 거리가 된다. 팀이 둘만 돼도 누가 어떤 모델을 얼마나 썼는지 월말에 청구서를 열어서야 알게 된다. LiteLLM 프록시는 그 중간에 창구 하나를 세워서, 뒤에 어떤 공급자가 붙어 있든 앞에서는 전부 OpenAI 호환 API로 보이게 만든다.

정리하자면, config.yaml에 모델 목록을 선언해 LiteLLM 프록시를 http://0.0.0.0:4000에 띄우면 OpenAI, Claude, Bedrock, Ollama가 전부 /chat/completions 한 경로로 들어온다. 여기에 가상 키(virtual key)를 발급해 팀별로 쓸 모델과 예산을 묶고, 요청마다 PostgreSQL에 사용량이 쌓인다. 애플리케이션 코드는 base_url만 이 프록시로 바꾸면 되고 나머지는 건드릴 게 없다.

여기서 가상 키라는 말이 낯설 수 있다. 프록시가 자체적으로 발급하는 sk-로 시작하는 토큰인데, 실제 공급자 키를 감춘 채 "이 키는 gpt-4o-mini와 claude만 쓸 수 있고 월 한도 50달러"처럼 권한과 예산을 묶어 둔 꼬리표다. 이 키로 들어온 요청은 프록시 뒤에 숨겨 둔 진짜 공급자 키로 바꿔치기돼 나간다.

1. 설치와 첫 기동

LiteLLM 프록시는 파이썬 패키지다. 가상 키와 예산 기능까지 쓰려면 proxy 엑스트라가 필요하다.

$ python3 -m venv .venv && source .venv/bin/activate
$ pip install 'litellm[proxy]'

$ litellm --version
LiteLLM: Current Version = 1.5x.x

버전 번호는 설치 시점에 따라 다르다. 공급자 키는 설정 파일에 직접 박지 말고 환경변수로 둔다. os.environ/이름 구문으로 참조하기 때문이다.

$ export OPENAI_API_KEY=sk-...
$ export ANTHROPIC_API_KEY=sk-ant-...
$ export AWS_ACCESS_KEY_ID=...
$ export AWS_SECRET_ACCESS_KEY=...
$ export LITELLM_MASTER_KEY=sk-master-$(openssl rand -hex 16)

LITELLM_MASTER_KEY는 프록시 관리자 자격증명이다. 반드시 sk-로 시작해야 하고, 이 키로 가상 키를 발급하거나 사용량을 조회한다. 밖으로 새면 전부 뚫리니 서버 환경변수로만 둔다.

2. 네 공급자를 config.yaml에 모으기

설정의 핵심은 model_list다. 각 항목은 호출자가 쓸 이름인 model_name과, 실제로 어디로 보낼지 적는 litellm_params.model 한 쌍으로 이뤄진다. 공급자는 model 문자열의 접두사로 구분한다.

model_list:
  # OpenAI
  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

  # Anthropic 직접 호출
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

  # Bedrock 위의 Claude (같은 model_name으로 폴백에 쓸 것)
  - model_name: claude-sonnet
    litellm_params:
      model: bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0
      aws_region_name: us-east-1

  # Ollama 로컬
  - model_name: llama31-local
    litellm_params:
      model: ollama_chat/llama3.1
      api_base: http://localhost:11434

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

litellm_settings:
  drop_params: true

Ollama는 ollama_chat/ 접두사를 권장한다. ollama/는 구형 /api/generate로 가고, ollama_chat/는 /api/chat으로 가서 역할 기반 대화 응답이 더 안정적이다. 처음에 ollama/로 붙였다가 멀티턴 응답이 어긋나길래 ollama_chat/로 바꾸면 깔끔해진다.

위에서 claude-sonnet이라는 이름을 두 번 선언한 점이 눈에 띌 것이다. 같은 model_name을 여러 litellm_params에 걸면 LiteLLM이 그 이름을 하나의 배포 그룹으로 보고 요청을 분산하거나 폴백 대상으로 삼는다. 여기서는 Anthropic 직접 호출과 Bedrock 경유를 한 그룹으로 묶어 뒀다.

이제 프록시를 띄운다.

$ litellm --config config.yaml

#------------------------------------------------------------#
#   LiteLLM: Proxy initialized with Config, Set models:
#   gpt-4o-mini
#   claude-sonnet
#   llama31-local
#------------------------------------------------------------#

INFO:     Uvicorn running on http://0.0.0.0:4000 (Press CTRL+C to quit)

3. OpenAI SDK를 그대로 꽂기

엔드포인트가 OpenAI 호환이라 기존 클라이언트는 base_url만 바꾸면 된다. 모델명 자리에 config.yaml의 model_name을 넣는다.

$ curl http://0.0.0.0:4000/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-master-...' \
  -d '{
    "model": "claude-sonnet",
    "messages": [{"role": "user", "content": "한 줄로 자기소개"}]
  }'

{"id":"chatcmpl-...","object":"chat.completion",
 "model":"claude-sonnet-4-20250514",
 "choices":[{"message":{"role":"assistant",
   "content":"저는 Anthropic이 만든 Claude입니다."}}],
 "usage":{"prompt_tokens":15,"completion_tokens":12,"total_tokens":27}}

파이썬에서도 공식 openai 라이브러리를 쓴다. 모델만 프록시 이름으로 부르면 뒤에서 Bedrock이든 Ollama든 알아서 간다.

from openai import OpenAI

client = OpenAI(
    base_url="http://0.0.0.0:4000",
    api_key="sk-master-...",   # 또는 아래에서 만들 가상 키
)

r = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "ping"}],
)
print(r.choices[0].message.content)

4. 폴백과 라우팅 전략

공급자 한 곳이 429나 5xx를 뱉을 때 자동으로 다른 쪽으로 넘기려면 router_settings에 폴백을 건다. 앞서 claude-sonnet을 Anthropic과 Bedrock 두 벌로 선언해 뒀으니, 그룹 안에서 한쪽이 죽으면 다른 쪽이 받는다. 서로 다른 모델로 넘기는 폴백은 fallbacks에 명시한다.

router_settings:
  routing_strategy: simple-shuffle
  num_retries: 2
  fallbacks:
    - {"claude-sonnet": ["gpt-4o-mini"]}
    - {"gpt-4o-mini": ["llama31-local"]}

routing_strategy는 같은 이름에 배포가 여러 개일 때 고르는 방식이다. simple-shuffle은 가중치 기반 무작위, usage-based-routing은 TPM이 덜 찬 쪽, latency-based-routing은 최근 응답이 빠른 쪽을 고른다. 외부 유료 모델이 흔들릴 때 로컬 Ollama로 떨어뜨려 두면 최소한 응답은 끊기지 않는다.

한 가지 함정이 있다. 예산 검사는 요청이 들어올 때 요청한 모델 기준으로 통과 여부를 보고, 과금은 폴백으로 실제 실행된 모델 기준으로 집계된다. 그래서 폴백이 발동하면 한도 체크와 실제 비용 사이에 틈이 생길 수 있다. 예산을 빡빡하게 걸 생각이면 직접 호출과 폴백 두 경로를 다 돌려 보고 숫자를 확인하는 편이 맞다.

5. PostgreSQL 붙이고 가상 키 발급

가상 키, 팀, 예산, 사용량 로그는 전부 PostgreSQL에 저장된다. 이 기능을 쓰려면 DB가 필수다. DATABASE_URL만 주면 LiteLLM이 기동 때 스키마를 만든다.

$ export DATABASE_URL=postgresql://litellm:pw@localhost:5432/litellm
$ litellm --config config.yaml

# 기동 로그에 Prisma migrate가 테이블을 올린다
LiteLLM_VerificationToken, LiteLLM_SpendLogs, LiteLLM_TeamTable ...

DB가 붙었으면 마스터 키로 가상 키를 발급한다. 이 키는 지정한 모델만 쓸 수 있고, 월 예산과 사용자 꼬리표가 박힌다.

$ curl http://0.0.0.0:4000/key/generate \
  -H 'Authorization: Bearer sk-master-...' \
  -H 'Content-Type: application/json' \
  -d '{
    "models": ["gpt-4o-mini", "claude-sonnet"],
    "max_budget": 50,
    "budget_duration": "30d",
    "user_id": "backend-team"
  }'

{"key":"sk-abc123...","models":["gpt-4o-mini","claude-sonnet"],
 "max_budget":50,"user_id":"backend-team"}

이 sk-abc123...를 애플리케이션에 쥐여 주면 된다. llama31-local은 models 목록에 없으니 이 키로는 호출이 거부된다. 한도를 넘기면 다음 요청부터 ExceededBudget 오류가 떨어진다.

6. 팀 단위로 예산 묶기

사람별 키를 일일이 관리하는 대신 팀을 만들어 예산을 공유하게 하면 운영이 간단해진다. 먼저 팀을 만들고, 발급하는 키를 그 팀에 붙인다.

$ curl http://0.0.0.0:4000/team/new \
  -H 'Authorization: Bearer sk-master-...' \
  -H 'Content-Type: application/json' \
  -d '{"team_alias": "search-squad", "max_budget": 200, "budget_duration": "30d"}'

{"team_id":"team-9f...","team_alias":"search-squad","max_budget":200}

$ curl http://0.0.0.0:4000/key/generate \
  -H 'Authorization: Bearer sk-master-...' \
  -H 'Content-Type: application/json' \
  -d '{"team_id": "team-9f...", "models": ["claude-sonnet"]}'

같은 팀에 속한 키들의 지출은 max_budget 한도 안에서 합산된다. 팀 예산 200달러면 팀원 전원이 쓴 금액의 총합으로 센다. 개인 키에도 별도 한도를 걸면 둘 중 먼저 걸리는 쪽에서 막힌다.

7. 누가 얼마 썼는지 확인

요청 하나하나가 LiteLLM_SpendLogs 테이블에 키, 사용자, 팀, 모델, 토큰, 달러 단위 비용으로 쌓인다. 조회는 API로 한다.

# 특정 키의 잔여 예산과 누적 지출
$ curl 'http://0.0.0.0:4000/key/info?key=sk-abc123...' \
  -H 'Authorization: Bearer sk-master-...'

{"info":{"spend":12.47,"max_budget":50,"models":["gpt-4o-mini","claude-sonnet"]}}

# 팀/키 단위로 묶은 집계 리포트
$ curl 'http://0.0.0.0:4000/global/spend/report?group_by=team' \
  -H 'Authorization: Bearer sk-master-...'

# 사용자별 일자별 모델별 상세
$ curl 'http://0.0.0.0:4000/user/daily/activity?user_id=backend-team' \
  -H 'Authorization: Bearer sk-master-...'

/spend/logs는 개별 요청 로그라 양이 많으면 잘려 나오니, 팀별 월 리포트는 /global/spend/report를, 사람별 추이는 /user/daily/activity를 쓰는 게 맞다. UI가 필요하면 프록시 기동 뒤 http://0.0.0.0:4000/ui에서 마스터 키로 로그인하면 같은 수치를 대시보드로 볼 수 있다.

여기까지 세우면 모델을 바꾸는 작업이 config.yaml 한 줄 수정과 재기동으로 끝난다. 다음으로 손댈 만한 곳은 요청/응답을 Langfuse 같은 추적 도구로 흘려보내는 콜백 설정과, Redis를 붙여 여러 프록시 인스턴스가 라우팅 상태와 예산 카운터를 공유하게 만드는 수평 확장 쪽이다.

자주 묻는 질문

가상 키 기능 없이 config.yaml만으로 프록시를 쓸 수 있나

쓸 수 있다. 모델 통합, 라우팅, 폴백은 DATABASE_URL 없이 동작하고 마스터 키로 바로 호출하면 된다. PostgreSQL은 가상 키 발급, 팀, 예산 한도, 사용량 로그 저장에만 필요하다. 사용량 추적과 팀별 예산이 목적이라면 DB를 붙여야 한다.

Claude를 Anthropic 직접 호출과 Bedrock 경유 중 어느 쪽으로 붙여야 하나

둘을 같은 model_name으로 선언해 한 그룹으로 묶는 방식을 권한다. 평소에는 라우팅 전략으로 분산하고, 한쪽이 429나 5xx를 내면 다른 쪽이 받는다. AWS 크레딧이 있거나 데이터 경계를 AWS 안에 두어야 하면 Bedrock을, 최신 모델을 빨리 쓰려면 Anthropic 직접 호출을 우선순위로 둔다.

폴백이 발동하면 예산 한도가 정확히 지켜지나

틈이 생길 수 있다. 예산 검사는 요청 들어올 때 요청한 모델 기준으로 통과를 판정하고, 과금은 폴백으로 실제 실행된 모델 기준으로 집계된다. 한도를 엄격하게 걸 생각이면 직접 호출과 폴백 두 경로를 모두 돌려 지출 로그를 확인한 뒤 운영에 넣는 게 안전하다.

Ollama 접두사는 ollama와 ollama_chat 중 뭘 써야 하나

ollama_chat/를 권한다. ollama/는 구형 /api/generate 엔드포인트로 가고, ollama_chat/는 /api/chat으로 가서 역할 기반 멀티턴 대화 응답이 더 안정적이다. api_base 기본값은 http://localhost:11434이다.

기존 OpenAI SDK 코드를 얼마나 고쳐야 하나

base_url을 프록시 주소(기본 http://0.0.0.0:4000)로, api_key를 가상 키나 마스터 키로 바꾸고 model 자리에 config.yaml의 model_name을 넣는 정도다. 엔드포인트가 OpenAI 호환이라 요청 구조는 그대로 두고 Claude, Bedrock, Ollama를 같은 코드로 호출한다.

관련 글

댓글 0

로그인 후 댓글을 남길 수 있습니다.

아직 댓글이 없습니다.