vLLM LoRA adapter 띄우기

vLLM을 이용하여 LoRA Adapter 모델 서빙하기

최근 업무를 진행하다가 vLLM을 이용해 LoRA Adapter 모델을 서빙해야 했던 상황이 있었다. 그런데 팀원이 base 모델 없이 LoRA Adapter의 경로만 전달해서 처음에는 약간 혼란스러웠다.

LoRA Adapter를 vLLM에서 사용하기 위해서는 Base Model과 LoRA Adapter 모델 두 가지를 모두 명시적으로 제공해줘야 한다.

공식 vLLM 문서에서 관련된 내용을 찾긴 했지만, 실제 구현에 대한 레퍼런스가 부족해서 시행착오 끝에 성공한 내용을 공유하고자 한다.

평소에는 주로 Kubernetes 환경에서 yaml을 통해 모델을 서빙했었는데, 이번 사례는 Docker 환경에서 작업을 진행했기 때문에 Docker 명령어 기반으로 설명한다.

작업 환경

• GPU: NVIDIA TITAN RTX
• Driver Version: 530.30.02
• CUDA Version: 12.1

기본적인 vLLM Docker 실행 명령어

기본적인 vLLM 서빙을 위한 Docker 명령어는 다음과 같다.

docker run --gpus 1 \\  # GPU 사용 개수 설정
  -v ~/.cache/huggingface:/root/.cache/huggingface \\  # 로컬 Huggingface 모델 캐시 디렉토리를 컨테이너 내로 마운트
  -e "HUGGING_FACE_HUB_TOKEN=YOUR_HF_TOKEN" \\  # Huggingface API 토큰 환경 변수 설정
  -e HF_HUB_ENABLE_HF_TRANSFER=false \\  # 허깅페이스 파일 전송 가속 기능 비활성화
  -p 8282:8000 \\  # 컨테이너의 8000 포트를 호스트의 8282 포트로 매핑
  --ipc=host \\  # IPC 공유로 성능 최적화
  vllm/vllm-openai:latest \\  # vLLM 공식 도커 이미지
  --model "Qwen/Qwen2.5-Coder-7B-Instruct" \\  # 사용할 기본 모델 설정
  --dtype half  # 연산 데이터 타입을 FP16으로 설정하여 성능 향상

LoRA Adapter를 사용하는 경우

LoRA Adapter를 적용하려면 아래와 같은 추가 파라미터가 필요하다.

• -enable-lora: LoRA 기능 활성화
• -lora-modules: LoRA 모듈에 대한 설정을 JSON 형태로 명시한다.

예시 명령어는 다음과 같다.

docker run --gpus 1 \\  # GPU 1개 사용
  -v ~/.cache/huggingface:/root/.cache/huggingface \\  # Huggingface 캐시 마운트
  -e "HUGGING_FACE_HUB_TOKEN=YOUR_HF_TOKEN" \\  # Huggingface 허브 API 인증 토큰
  -e HF_HUB_ENABLE_HF_TRANSFER=false \\  # Huggingface 전송 최적화 기능 끄기
  -p 8282:8000 \\  # 호스트와 컨테이너 포트 매핑
  --ipc=host \\  # IPC 공유로 컨테이너 내 성능 향상
  vllm/vllm-openai:latest \\  # vLLM 공식 이미지
  --enable-lora \\  # LoRA 기능 활성화
  --model "Qwen/Qwen2.5-Coder-7B-Instruct" \\  # LoRA Adapter를 위한 Base 모델 지정
  --dtype half \\  # 연산을 FP16으로 처리
  --lora-modules '{"name": "tmp", "path": "AIDXteam/NextGen_Code_7B", "base_model_name": "Qwen/Qwen2.5-Coder-7B-Instruct"}'  # LoRA 모듈 설정(JSON 형태로 이름, 경로, base 모델 지정)

여기서 base_model_name은 반드시 LoRA Adapter가 호환되는 Base Model 이름과 정확히 일치해야 한다.

참고 사항

LoRA Adapter 개념은 기본적으로 Base Model 위에 Adapter를 추가하여 경량화된 파라미터로 미세조정을 수행하는 방식이다. 따라서 반드시 Base Model이 구동된 상태에서 Adapter를 적용하는 형태로 서빙해야 한다.

이외에도 LoRA Adapter와 Base Model을 결합하여 단일 모델로 Hugging Face에 업로드하는 방법도 존재한다.