서버 인자

서버 인자 (Server Arguments)

vLLM을 실제 서비스로 운영하려면 OpenAI 호환 서버를 띄우는 게 가장 흔한 방법이에요. 그때 사용하는 명령어가 바로 vllm serve예요. 이 페이지에서는 vllm serve가 받는 CLI 인자와, 설정을 YAML 파일로 관리하는 방법을 설명할게요.

출처: vLLM 공식 문서 — serve_args

vllm serve란?

vllm serve 명령어는 OpenAI 호환 서버를 실행하는 데 사용돼요. 즉, 이 명령 하나로 OpenAI API와 비슷한 형태의 엔드포인트를 로컬에서 띄울 수 있습니다. 그동안 /v1/chat/completions 같은 엔드포인트로 요청을 보내던 코드를 그대로 활용할 수 있죠.

CLI 인자 (CLI Arguments)

vllm serve가 받을 수 있는 전체 옵션 목록은 CLI Reference에서 확인할 수 있어요. 모델 지정, 병렬 처리, 양자화, 스케줄링 등 실질적으로 엔진 인자와 겹치는 옵션이 많으니, 자세한 각 인자의 의미는 엔진 인자 문서가 더 상세하게 다룹니다.

설정 파일 (Configuration file)

명령줄에 인자를 잔뜩 나열하는 건 번거롭고 실수하기 쉬워요. vLLM은 YAML 설정 파일로 CLI 인자를 한꺼번에 불러오는 방법을 지원합니다.

설정 파일을 만들 때 주의할 점은, 인자 이름이 위에서 설명한 "긴 형태(long form)" 여야 한다는 것이에요. 예를 들어 다음과 같은 config.yaml을 생각해 볼게요.

# config.yaml
model: meta-llama/Llama-3.1-8B-Instruct
host: "127.0.0.1"
port: 6379
uvicorn-log-level: "info"

이 설정 파일을 사용하려면 --config 옵션으로 넘기면 됩니다.

vllm serve --config config.yaml

우선순위 (Precedence)

만약 같은 인자가 명령줄과 설정 파일에 동시에 주어지면 어떻게 될까요? 이때는 명령줄의 값이 이깁니다. 전체 우선순위는 다음과 같아요.

명령줄(command line) > 설정 파일(config file) 값 > 기본값(defaults)

예를 들어 vllm serve SOME_MODEL --config config.yaml처럼 실행하면, SOME_MODEL이 config 파일의 model 값보다 우선하게 됩니다. 같은 값을 어느 곳에서 설정해야 할지 고민될 때, 이 우선순위만 기억하면 헷갈리지 않아요.

실무 팁

여러 환경(개발/스테이징/운영)을 운용한다면 설정 파일을 환경별로 분리해 두는 게 좋아요.
비밀번호나 토큰처럼 민감한 값은 설정 파일보다 환경 변수로 분리해서 관리하는 편이 안전합니다.
명령줄과 설정 파일 우선순위가 헷갈릴 땐 "명령줄이 항상 최우선"이라는 원칙만 기억하세요.