고처리량 워크로드 확장
고처리량 워크로드 확장 (Scale for high-throughput workloads)
큰 프롬프트는 요청이 모델 프로바이더에 도달하기 전에 게이트웨이에 상당한 작업을 안겨줘요. 인증, 예산 검사, 토큰 계산, 지출 추적, 메트릭 수집, 데이터베이스 연결이 모두 요청 처리와 경쟁할 수 있답니다.
이 배포 프로필은 그 작업을 분리하고 요청량과 토큰량으로 게이트웨이를 확장해요. 대규모 프롬프트 벤치마크에서 50K~100K 토큰 프롬프트로 초당 3,000 요청을 33개 게이트웨이 파드로 유지했어요. 테스트 설정과 결과는 전체 벤치마크를 참고하세요.
고처리량 배포 프로필은 아직 개발 중이며 nightly 빌드에서 사용할 수 있어요. 아래 설치 예시는 사용 가능한 가장 이른 버전을 고정해요. 평가에는 최신 nightly를 사용하고, 배포 전에 비프로덕션 환경에서 검증하세요.
출처: 문서
본문
이 프로필을 언제 사용하나요 (When to use this profile)
배포에 다음 특성 중 하나 이상이 있으면 이 프로필을 사용해요.
- 초당 수천 개의 요청
- 수만 개 토큰의 프롬프트
- 파드당 여러 게이트웨이 워커
- 엄격한 데이터베이스 연결 제한
- 장시간 실행되는 스트리밍 요청
새 배포는 Helm으로 배포하고 production 체크리스트로 시작하세요. 외부 Postgres와 Redis를 갖춘 작업 컴포넌트화 배포가 있은 후 이 프로필을 적용하세요.
배포 동작 방식 (How the deployment works)
컴포넌트화 차트는 게이트웨이, 관리 백엔드, Admin UI, 데이터베이스 마이그레이션을 독립적으로 실행해요. 오직 게이트웨이만 추론 트래픽을 처리하므로 각 부분이 다른 구성 요소를 늘리지 않고 확장할 수 있어요.
이 프로필은 게이트웨이를 여섯 가지 방식으로 변경해요.
| 설정 | 하는 일 |
|---|---|
| gateway.numWorkers | 각 게이트웨이 파드에서 4개의 요청 워커 실행 |
| database.connectionPool | 파드의 모든 워커가 작은 PgBouncer 풀을 공유 |
| LITELLM_RUST=1 | 대형 프롬프트 토큰 계산을 Rust 고속 경로로 이동 |
| gateway.metricsServer + gateway.collector | 메트릭 수집과 지출 처리를 요청 워커 밖으로 이동 |
| gateway.hpa | 초당 요청, 초당 토큰, CPU, 메모리로 확장 |
| Keep-alive 및 rollout 설정 | 유휴 기간·확장·업그레이드 중 장기 실행 요청 보호 |
이 설정들은 모두 선택(opt-in)이에요. 차트를 업그레이드해도 프로필이 자동 활성화되지 않아요.
프로필 배포 (Deploy the profile)
먼저 데이터베이스와 마스터 키 Secrets를 만들고, 기존 컴포넌트화 배포에 다음 값을 추가해요.
fullnameOverride: litellm
masterKey:
secretName: litellm-masterkey
secretKey: masterkey
database:
writer:
host: "<postgres-endpoint>"
port: 5432
dbname: litellm
passwordSecret:
name: litellm-db
usernameKey: username
passwordKey: password
connectionPool:
enabled: true
maxDbConnections: 8
maxClientConn: 1000
redis:
host: "<redis-endpoint>"
port: 6379
passwordSecret:
name: litellm-env
passwordKey: REDIS_PASSWORD
gateway:
numWorkers: 4
logLevel: ERROR
extraEnv:
- name: LITELLM_RUST
value: "1"
- name: KEEPALIVE_TIMEOUT
value: "75"
metricsServer:
enabled: true
serviceMonitor:
enabled: true
collector:
enabled: true
resources:
requests:
cpu: "4"
memory: 16Gi
limits:
cpu: "16"
memory: 16Gi
hpa:
enabled: true
minReplicas: 2
maxReplicas: 200
targetCPUUtilizationPercentage: 60
targetMemoryUtilizationPercentage: 80
targetRequestsPerSecond: "83"
targetTokensPerSecond: "6.25M"
behavior:
scaleUp:
stabilizationWindowSeconds: 0
policies:
- type: Percent
value: 100
periodSeconds: 15
- type: Pods
value: 20
periodSeconds: 15
scaleDown:
stabilizationWindowSeconds: 300
policies:
- type: Percent
value: 25
periodSeconds: 60
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 0
maxSurge: 25%
lifecycle:
preStop:
exec:
command: ["sh", "-c", "sleep 10"]
terminationGracePeriodSeconds: 620
startupProbe:
httpGet: { path: /health/readiness, port: http }
failureThreshold: 30
periodSeconds: 10
pdb:
enabled: true
maxUnavailable: 10%
config:
general_settings:
proxy_batch_write_at: 60
use_redis_transaction_buffer: true
allow_requests_on_db_unavailable: true
litellm_settings:
callbacks:
- prometheus
request_timeout: 600
json_logs: true
완전한 프로필을 포함한 가장 이른 nightly를 설치해요.
helm upgrade --install litellm \
oci://ghcr.io/berriai/litellm/chart/litellm \
--version 1.102.0-dev.2 \
-f values.yaml
model_list, ingress, 데이터베이스 읽기 복제본, 기타 환경별 값은 Helm으로 배포 문서에 설명된 대로 추가하세요. fullnameOverride: litellm은 아래 검증 명령에 사용되는 짧은 리소스 이름을 만들어줘요.
요청을 차단하지 않고 큰 프롬프트 계산하기
예산 강제는 요청이 모델 프로바이더로 보내지기 전에 프롬프트 토큰을 계산해요. 50K~100K 토큰 프롬프트의 경우 이것이 게이트웨이 요청 경로에서 가장 큰 CPU 비용이 될 수 있어요.
LITELLM_RUST=1로 설정해 Rust 토큰 계산 고속 경로를 사용해요. 테스트에서 50K, 75K, 100K 토큰 본문의 토큰 계산이 46, 53, 100 ms에서 4.9, 6.8, 10.2 ms로 떨어졌어요. 이것이 프로필에서 가장 큰 단일 개선이었어요.
Rust 경로는 기본적으로 꺼져 있어요. 게이트웨이 이미지에서 Rust 확장이 로드되는 것을 확인한 뒤에만 활성화하세요.
CPU 헤드룸으로 4개 워커 실행하기
벤치마크는 각 파드에서 4개의 게이트웨이 워커를 4 vCPU 요청과 16 vCPU 제한으로 사용했어요. 이는 스케줄링을 예측 가능하게 유지하면서 워커와 Rust 토크나이저 스레드가 전체 파드를 스로틀하지 않고 짧은 CPU 버스트를 쓸 수 있게 해줘요.
700 RPS에서 4 vCPU 제한은 평균 CPU가 그 제한 아래에 있어도 스로틀링을 일으켰어요. 제한을 16으로 올리면 스로틀링이 사라지고 p99 지연 시간이 830 ms에서 670 ms로 줄었어요. 파드당 8개 워커는 지연 시간을 개선하지 못했고 메모리를 50% 더 사용했으므로, 이 트래픽 형태에서는 4개 워커가 테스트된 시작점이에요.
워커 수를 바꾸기 전에 자신의 워크로드를 측정하세요. 프로바이더 지연 시간, 프롬프트 크기, 스트리밍 기간, 활성화된 콜백이 모두 올바른 값에 영향을 줘요.
워커 간 데이터베이스 연결 공유
PgBouncer가 없으면 모든 게이트웨이 워커가 자체 Prisma 연결 풀을 엽니다. 워커나 파드를 추가하면 데이터베이스 연결이 빠르게 배가될 수 있어요.
database.connectionPool.enabled는 각 게이트웨이 파드에서 하나의 PgBouncer 풀을 시작해요. 그 파드의 모든 워커가 동일한 업스트림 연결 예산을 공유해요. 1,000 RPS 테스트에서 Postgres는 1129개 파드 간에 86175개 연결을 유지했고 PgBouncer에서는 대기 클라이언트가 없었어요.
차트 기본값인 파드당 20개의 업스트림 연결부터 시작하세요. 벤치마크는 그 워크로드가 큐를 만들지 않았으므로 8을 사용했어요. 데이터베이스 제한, 게이트웨이 복제본 수, 관찰된 PgBouncer 대기 시간을 바탕으로 값을 선택하세요.
요청 워커 밖으로 백그라운드 작업 이동
두 개의 사이드카가 운영 작업을 추론 트래픽에서 멀리 유지해요. collector는 테스트에서 꼬리 지연 시간을 개선했어요. 700 RPS에서 p99가 1.8초에서 830 ms로 떨어졌어요. 작업이 사이드카로 이동했으므로 총 컴퓨팅은 거의 같았어요. 이것을 컴퓨팅 감소가 아닌 요청 격리로 취급하세요.
메트릭 포트는 가상 키 인증을 사용하지 않아요. 공용 ingress에서는 꺼두세요. Prometheus Operator를 사용할 때는 gateway.serviceMonitor를 활성화하세요.
요청과 토큰으로 확장
CPU만으로는 큰 요청의 갑작스러운 증가에 너무 느리게 반응할 수 있어요. 고처리량 프로필은 HorizontalPodAutoscaler가 한 번에 4개의 신호를 사용하게 해요. HPA는 가장 많은 복제본이 필요한 신호를 따릅니다. 테스트에서 요청률 메트릭이 로드 시작 약 48초 후에 확장을 트리거했어요.
RPS·TPS 대상은 Kubernetes custom metrics API를 통해 litellm_requests_per_second와 litellm_tokens_per_second를 노출하는 Prometheus Adapter가 필요해요. 정확한 어댑터 규칙은 파드당 요청·토큰 확장 문서에 나와 있어요.
Prometheus Adapter를 실행하지 않으면 targetRequestsPerSecond와 targetTokensPerSecond를 제거하세요. HPA는 CPU와 메모리로 계속 확장할 거예요.
RPS·TPS 대상은 측정된 파드에서 선택하세요. 예시 값은 벤치마크 워크로드용 헤드룸을 포함하지만 보편적 한계는 아니에요.
확장 중 장기 요청 유지
KEEPALIVE_TIMEOUT을 로드 밸런서의 유휴 타임아웃보다 높게 설정하세요. 예시는 60초 유휴 타임아웃을 가진 AWS Application Load Balancer용 75초를 사용해요. 이는 게이트웨이가 로드 밸런서가 기대하는 것보다 먼저 연결을 닫는 것을 막아줘요.
rollout 설정은 장기 요청이 끝날 시간을 줘요. 이 값을 최장 허용 요청과 로드 밸런서의 등록 해제(데레지스트레이션) 동작에 맞추세요.
startup probe는 새 4-워커 파드가 Kubernetes가 liveness 검사를 적용하기 전에 로드될 시간을 줘요. allow_requests_on_db_unavailable: true는 일시적인 느린 데이터베이스 헬스 체크가 확장 중 유용한 파드를 제거하지 못하게 해요. 이 가용성 트레이드오프가 데이터베이스 실패 정책과 맞는지 결정하세요.
배포 검증 (Verify the deployment)
각 게이트웨이 파드에는 gateway, metrics, collector 컨테이너가 있어야 해요.
kubectl -n <namespace> get pods -l app.kubernetes.io/component=gateway \
-o custom-columns=POD:.metadata.name,CONTAINERS:.spec.containers[*].name
워커, 연결 풀, Rust, keep-alive 설정을 확인해요.
kubectl -n <namespace> exec deploy/litellm-gateway -c gateway -- \
env | grep -E 'NUM_WORKERS|LITELLM_PGBOUNCER|LITELLM_RUST|KEEPALIVE'
kubectl -n <namespace> exec deploy/litellm-gateway -c gateway -- \
python -c "import litellm.rust_bridge._native; print('rust ok')"
Prometheus 메트릭과 Kubernetes custom metrics API를 확인해요.
kubectl -n <namespace> port-forward svc/litellm-gateway-metrics 4001:4001 &
curl -s localhost:4001/metrics/ | grep -c '^litellm_'
kubectl get --raw \
/apis/custom.metrics.k8s.io/v1beta1/namespaces/<namespace>/pods/*/litellm_requests_per_second
kubectl get --raw \
/apis/custom.metrics.k8s.io/v1beta1/namespaces/<namespace>/pods/*/litellm_tokens_per_second
kubectl -n <namespace> describe hpa litellm-gateway
HPA 출력에는 RPS, TPS, CPU, 메모리가 나열되어야 해요. rollout 직후 새 파드는 첫 요청이 메트릭 시리즈를 만들 때까지 잠시 FailedGetPodsMetric을 보고할 수 있어요.
벤치마크 결과 (Benchmark results)
벤치마크 보고서는 이 프로필의 테스트 조건, 전후 결과, 클라이언트 노출 실패, 변수당 측정을 문서화해요.