콘텐츠로 이동

설정 가이드

문서 상태

소유: 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
vllm serve Qwen/Qwen3-8B \
  --max-model-len 16384 \
  --dtype bfloat16 \
  --no-enable-prefix-caching \
  --no-async-scheduling
1
2
3
4
5
6
7
8
9
from vllm import LLM

llm = LLM(
    model="Qwen/Qwen3-8B",
    max_model_len=16384,
    dtype="bfloat16",
    enable_prefix_caching=False,
    async_scheduling=False,
)

플러그인이 정하는 값

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
export HA_TOOLCHAIN=1
export BERTHA_ATTN_BACKEND="hyperaccel"

플러그인 동작

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가 기본값입니다

다음