엔진 인자

엔진 인자 (Engine Arguments)

엔진 인자는 vLLM 엔진의 동작을 제어하는 가장 핵심적인 설정 수단이에요. "엔진"이라고 하면 거창해 보이지만, 쉽게 말해 vLLM이 모델을 어떻게 로드하고 추론을 어떻게 수행할지를 결정하는 스위치들이라고 생각하면 돼요. 이 페이지에서는 엔진 인자가 무엇이고, 어떻게 전달되는지, 그리고 어떤 범주로 나뉘는지를 정리할게요.

출처: vLLM 공식 문서 — engine_args

엔진 인자는 어디에 쓰이나요?

엔진 인자는 사용하는 방식에 따라 두 가지 경로로 들어가요.

• 온라인 서빙(online serving) — vllm serve 명령어의 인자로 전달됩니다.
• 오프라인 추론(offline inference) — LLM 클래스의 인자로 전달됩니다.

즉, 터미널에서 서버를 띄우든 Python 코드로 직접 추론을 하든, 같은 인자 체계가 그대로 적용되는 거예요.

잠깐, 이 인자들은 어디서 정의되나요?

엔진 인자 클래스인 EngineArgs와 AsyncEngineArgs는 사실 vllm.config에 정의된 여러 설정 클래스들을 조합한 것이에요. 개발자 문서가 필요하다면 이 설정 클래스들을 보는 게 좋은데, 그 이유는 타입·기본값·docstring의 **진짜 기준(source of truth)**이 바로 그 클래스들이기 때문이에요. 엔진 인자 클래스는 이 클래스들을 하나로 묶어 CLI/API로 노출하는 얇은 껍질 같은 역할을 하죠.

JSON 형태의 CLI 인자 전달

CLI에서 JSON 구조의 인자를 넘길 때 두 가지 방식은 동일한 결과를 만듭니다.

# 방식 1: 점(dot) 표기법으로 하나씩
--json-arg.key1 value1 --json-arg.key2.key3 value2

# 방식 2: JSON 문자열 통째로
--json-arg '{"key1": "value1", "key2": {"key3": "value2"}}'

추가로, 리스트 요소는 + 기호로 개별 전달할 수 있어요.

# 방식 1: + 로 개별 요소 추가
--json-arg.key4+ value3 --json-arg.key4+='value4,value5'

# 방식 2: JSON 배열로 통째로
--json-arg '{"key4": ["value3", "value4", "value5"]}'

이 두 예시 모두 최종적으로 key4가 ["value3", "value4", "value5"]인 동일한 설정이 됩니다. CLI에서 반복해서 값을 늘려야 할 때 유용하죠.

주요 엔진 인자 살펴보기

엔진 인자는 설정 클래스별로 묶여 있어요. 그중 일부를 살펴보면 이렇습니다.

기본 엔진 인자

ModelConfig — 모델 설정

모델 자체에 대한 설정이에요.

이 외에도 병렬 처리(ParallelConfig), 스케줄러(SchedulerConfig), 캐시(CacheConfig) 등 다양한 설정 클래스가 있으며, 각각 tensor_parallel_size, max_num_seqs, gpu_memory_utilization 같은 중요한 인자를 제공해요. 전체 목록은 공식 문서의 엔진 인자 레퍼런스와 vllm.config 설정 클래스를 참고하세요.

더 알아보기 (Learn more)

• 구성 옵션 (Configuration Options)
• 서브 인자 (Serve Arguments)
• 환경 변수 (Environment Variables)
• 최적화 (Optimization)