배포 자습서: Nginx로 vLLM 로드밸런싱하기

배포 자습서: Nginx로 vLLM 로드밸런싱하기 (Using Nginx)

이 문서는 여러 개의 vLLM 서빙 컨테이너를 띄우고, Nginx를 서버들 사이의 로드밸런서로 사용하는 방법을 보여줘요. 모델 하나를 여러 서버에 분산해 서빙하면 요청이 몰려도 한 서버에 부하가 집중되지 않죠.

Nginx 컨테이너 빌드하기

이 가이드는 vLLM 프로젝트를 clone했고 현재 vllm 루트 디렉터리에 있다고 가정해요.

export vllm_root=`pwd`

Dockerfile.nginx라는 파일을 만들어요:

FROM nginx:latest
RUN rm /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

컨테이너를 빌드해요:

docker build . -f Dockerfile.nginx --tag nginx-lb

간단한 Nginx 설정 파일 만들기

nginx_conf/nginx.conf 파일을 만들어요. 서버는 원하는 만큼 많이 추가할 수 있어요. 아래 예시는 두 개로 시작해요. 더 추가하려면 upstream backend에 server vllmN:8000 max_fails=3 fail_timeout=10000s; 항목을 하나 더 넣으면 돼요.

??? console "Config"

```console
upstream backend {
    least_conn;
    server vllm0:8000 max_fails=3 fail_timeout=10000s;
    server vllm1:8000 max_fails=3 fail_timeout=10000s;
}
server {
    listen 80;
    location / {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

least_conn은 연결 수가 가장 적은 서버로 요청을 보내라는 뜻이에요.

vLLM 컨테이너 빌드하기

cd $vllm_root
docker build -f docker/Dockerfile . --tag vllm

프록시 뒤에 있다면 빌드 명령에 프록시 설정을 넘길 수 있어요:

cd $vllm_root
docker build \
    -f docker/Dockerfile . \
    --tag vllm \
    --build-arg http_proxy=$http_proxy \
    --build-arg https_proxy=$https_proxy

Docker 네트워크 만들기

docker network create vllm_nginx

vLLM 컨테이너 띄우기

주의할 점이 몇 가지 있어요:

  • HuggingFace 모델을 다른 곳에 캐시해 두었다면 아래 hf_cache_dir을 업데이트하세요.
  • 기존 HuggingFace 캐시가 없다면 vllm0을 먼저 시작하고 모델 다운로드와 서버 준비가 끝날 때까지 기다리세요. 그래야 vllm1이 방금 다운로드한 모델을 재사용해서 다시 받지 않아요.
  • 아래 예시는 GPU 백엔드를 가정해요. CPU 백엔드라면 --gpus device=ID를 제거하고, docker run 명령에 VLLM_CPU_KVCACHE_SPACE와 VLLM_CPU_OMP_THREADS_BIND 환경변수를 추가하세요.
  • Llama-2-7b-chat-hf 대신 쓸 모델 이름을 원하는 대로 조정하세요.

??? console "Commands"

```console
mkdir -p ~/.cache/huggingface/hub/
hf_cache_dir=~/.cache/huggingface/
docker run \
    -itd \
    --ipc host \
    --network vllm_nginx \
    --gpus device=0 \
    --shm-size=10.24gb \
    -v $hf_cache_dir:/root/.cache/huggingface/ \
    -p 8081:8000 \
    --name vllm0 vllm \
    --model meta-llama/Llama-2-7b-chat-hf
docker run \
    -itd \
    --ipc host \
    --network vllm_nginx \
    --gpus device=1 \
    --shm-size=10.24gb \
    -v $hf_cache_dir:/root/.cache/huggingface/ \
    -p 8082:8000 \
    --name vllm1 vllm \
    --model meta-llama/Llama-2-7b-chat-hf
```

!!! note 프록시 뒤에 있다면 docker run 명령에 -e http_proxy=$http_proxy -e https_proxy=$https_proxy로 프록시 설정을 넘길 수 있어요.

Nginx 띄우기

docker run \
    -itd \
    -p 8000:80 \
    --network vllm_nginx \
    -v ./nginx_conf/:/etc/nginx/conf.d/ \
    --name nginx-lb nginx-lb:latest

이제 호스트의 8000 포트로 들어온 요청이 Nginx를 거쳐 vllm0·vllm1로 분산돼요.

vLLM 서버가 준비됐는지 확인하기

docker logs vllm0 | grep Uvicorn
docker logs vllm1 | grep Uvicorn

두 출력 모두 다음과 같아야 해요:

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

출처: 공식문서

더 알아보기 (Learn more)