설정 가이드¶
문서 상태
소유: LLMOps · 기준: vLLM HyperAccel 0.0.5 · 최종 확인: 2026-10-15
개요¶
vLLM HyperAccel은 업스트림 vLLM과 같은 진입점 — LLM(...), vllm serve, EngineArgs — 을 씁니다. 대부분의
인자는 그대로 동작하고, 일부 인자에 LPU 제약이 붙습니다. 전체 인자는 vllm serve --help로 확인합니다.
LPU 전용 설정은 두 곳에 있습니다.
- 플러그인이 정하는 값 — 엔진 설정을 만들 때 플러그인이 LPU에 맞게 고정합니다
- 환경 변수 —
HA_*,BERTHA_*
엔진 인자¶
아래 인자는 LPU에서 의미가 있거나 제약이 있습니다.
max_model_len (--max-model-len)
- 최대값: 16,384. EXAONE-4.5는 4,096.
- 요청 하나의 최대 컨텍스트입니다. KV는 요청의 현재 컨텍스트까지 64 토큰 단위로 읽고 메모리도 쓴 만큼만 차지하므로, 크게 잡아도 짧은 요청이 느려지지 않습니다. 컨텍스트와 KV 캐시를 참고합니다.
- sliding-window 레이어가 있는 모델은 LPU에 해당 커널이 있으면(Gemma-4) window보다 긴 컨텍스트를 16,384까지
씁니다. 그 밖의 sliding-window 모델은 결과가 정확하도록
max_model_len을 window 크기로 줄이고 경고를 남깁니다.
max_num_seqs (--max-num-seqs)
- 동시 요청 수의 상한입니다. 스케줄러는 여기에 더해 KV 캐시에 들어가는 만큼으로 동시 요청을 제한합니다.
gpu_memory_utilization (--gpu-memory-utilization)
- 플러그인이 쓸 디바이스 메모리 비율이며, KV 캐시 풀의 크기를 정합니다.
pipeline_parallel_size (--pipeline-parallel-size)
- 1, 2, 4. 모델 하나를 LPU 여러 장에 나눕니다. vLLM 기본 multiprocessing executor를 씁니다. 여러 LPU 사용하기를 참고합니다.
data_parallel_size (--data-parallel-size)
- LPU마다 독립 복제본 하나를 둡니다.
tensor_parallel_size (고정 1)
- LPU에서는 1만 받습니다. 여러 LPU는 PP나 DP로 씁니다.
language_model_only (--language-model-only)
- Gemma-4와 EXAONE-4.5에 필요합니다. 멀티모달 체크포인트를 텍스트 모델로 서빙합니다.
chat_template (--chat-template)
- 채팅 템플릿이 없는 모델(예: Llama-2 base)로 Chat Completions API를 쓸 때 필요합니다.
enable_prefix_caching (--no-enable-prefix-caching)
- vLLM은 prefix caching을 기본으로 켭니다. LPU 서빙에서는
--no-enable-prefix-caching으로 끄고 실행합니다.
async_scheduling (--no-async-scheduling)
- 하드웨어 서빙 테스트와 같은 구성으로 실행하려면
--no-async-scheduling을 지정합니다.
권장 실행 예¶
1 2 3 4 5 | |
1 2 3 4 5 6 7 8 9 | |
플러그인이 정하는 값¶
vLLM이 설정을 만들 때 플러그인이 아래 값을 맞춥니다. 사용자가 따로 지정할 필요가 없고, 충돌하는 값을 넘기면 아래처럼 처리합니다.
| 설정 | 값 | 다른 값을 넘기면 |
|---|---|---|
| 디바이스 | lpu |
다른 디바이스는 거절합니다 |
| Chunked prefill | 켬 | 항상 켭니다 |
max_num_batched_tokens |
LPU 코어 수 × 32 (코어 32개면 1,024) | 덮어씁니다 |
| KV 캐시 블록 크기 | 1 |
덮어씁니다. --block-size를 줬으면 경고를 남깁니다 |
| 모델 dtype | bfloat16 |
float16은 경고와 함께 bfloat16으로 바꿉니다 |
enforce_eager |
False |
True는 경고와 함께 되돌립니다. 모델은 항상 컴파일해 실행합니다 |
| 컴파일 | vLLM piecewise 컴파일 + Legato 컴파일러 | BERTHA_DISABLE_PIECEWISE=1로만 끕니다 |
| 스케줄러 | EVT0Scheduler |
플러그인이 지정합니다 |
| 워커 | HAWorker |
플러그인이 지정합니다 |
| 병렬화 | tensor_parallel_size=1, pipeline_parallel_size ∈ |
그 밖의 조합은 거절합니다 |
| 양자화 | compressed-tensors |
체크포인트 설정에서 읽습니다 |
KV 캐시 블록 크기
이전 릴리스는 블록 크기 128을 썼습니다. 지금은 KV 캐시를 한 토큰 단위로 페이징하므로 블록 크기는 1로
고정이고 --block-size는 효과가 없습니다. 기존 실행 명령의 --block-size 1,
--num-gpu-blocks-override는 지워도 됩니다.
환경 변수¶
엔진을 띄우는 프로세스에 설정합니다. 업스트림 vLLM 환경 변수는 vLLM 환경 변수 문서를 참고합니다.
런타임¶
HA_TOOLCHAIN
- 기본값: 설정 안 됨.
1이면 SDK 런타임이 커널 실행에 Legato 툴체인을 씁니다. 플러그인 실행에 필요합니다. 서빙 이미지에는 이미 설정되어 있습니다.
HA_BACKEND
- 기본값: 빌드를 따름.
- SDK 런타임 백엔드.
hw(LPU 카드),sim(기능 시뮬레이터). 쓸 수 있는 백엔드는 빌드할 때HART_BUILD_BACKEND로 정해집니다.
BERTHA_ATTN_BACKEND
- 기본값:
hyperaccel. - attention 백엔드 선택값입니다. HyperAccel 네이티브 백엔드를 씁니다.
1 2 | |
플러그인 동작¶
BERTHA_CORE_NUM
- 기본값:
32. - 사용할 LPU 코어 수. 스텝당 토큰 예산(코어 수 × 32)을 정합니다. 기본값은 모든 코어가 동작하는 칩에 맞습니다.
BERTHA_FUSE_KV_CACHE_WRITE
- 기본값:
1. - 커널이 지원하는 경우 K/V를 만드는 컴파일 조각 안에서 KV 캐시를 씁니다.
0이면 레이어마다 attention 실행 안에서 씁니다.
BERTHA_DISABLE_PIECEWISE
- 기본값:
0. 1이면 piecewise 컴파일을 끄고 모델을 eager로 실행합니다. 디버깅용입니다.
더 이상 필요 없는 변수¶
| 변수 | 상태 |
|---|---|
VLLM_PLUGINS=bertha |
필요 없습니다. 플러그인은 entry point로 자동 로드됩니다 |
BERTHA_CORE_NUM=32 |
필요 없습니다. 32가 기본값입니다 |