vLLM HyperAccel: LPU용 vLLM 플러그인¶
문서 상태
소유: LLMOps · 기준: vLLM HyperAccel 0.0.6 (vLLM 0.28.0, PyTorch 2.10.0, Python 3.10) · 최종 확인: 2026-10-15
vLLM HyperAccel(vllm-hyperaccel)은 HyperAccel LPU(LLM Processing Unit)에서 vLLM을 실행하는
하드웨어 플러그인입니다.
vLLM을 포크하지 않았습니다. vLLM의
하드웨어 플러그인 설계(RFC)를 따라 플러그인 인터페이스로
LPU를 붙이므로, 다른 vLLM 플랫폼에서 쓰던 vllm serve 명령과 LLM 클래스를 그대로 씁니다.
설치¶
요구 사항¶
| 구성 요소 | 버전 |
|---|---|
| Python | 3.10 |
| vLLM | 0.28.0 |
| PyTorch | 2.10.0 |
| vLLM HyperAccel | 0.0.6 |
LPU 카드에서 실행하려면 호스트에 HyperAccel 커널 드라이버와 호환 펌웨어가 설치되어 있어야 하고, LPU 장치
파일(/dev/ha0 등)이 보여야 합니다. 드라이버 설치는 빠른 설치에서 다룹니다.
컨테이너¶
vLLM 서빙 이미지에는 Python, PyTorch, vLLM, 플러그인, 그리고 플러그인이 쓰는 SDK 구성 요소가 모두 들어 있습니다. LPU가 꽂힌 서버의 Docker 호스트에서 실행합니다.
하이퍼엑셀이 발급한 계정으로 먼저 docker login public.hyperaccel.net 합니다.
1 2 3 4 5 6 7 8 9 10 11 | |
--device hyperaccel.ai/lpu=all은 CDI로 카드를 넘깁니다. CDI를 쓰지 않는 환경에서는--device /dev/ha0처럼 장치 파일을 직접 넘깁니다.--privileged는 필요하지 않습니다.- Hugging Face 캐시를 연결해 두면 모델을 한 번만 내려받습니다. 접근 권한이 필요한 모델은
-e HF_TOKEN=<토큰>을 함께 넘깁니다. - 쿠버네티스 배포는 쿠버네티스 지원을 참고합니다.
소스 설치¶
플러그인은 hyperaccel-sdk 저장소의 vllm/ 디렉터리에 있고, 같은 저장소의 다른 SDK 패키지(torch_ha, hart,
legato, legato_kernels, torch_legato, lccl, hapti)에 의존합니다. 의존성은
uv로 관리합니다.
1 2 3 4 5 6 7 8 | |
설치 확인¶
1 | |
플러그인은 vLLM의 entry point로 자동 등록되므로 따로 켤 필요가 없습니다(VLLM_PLUGINS=bertha도 필요 없습니다).
vLLM이 시작할 때 로그에 플랫폼 플러그인 bertha가 활성화되었다고 나오면 설치가 끝난 것입니다.
설계 개요¶
플러그인은 vLLM을 다시 구현하지 않습니다. OpenAI 호환 API 서버, LLM 클래스, 토크나이저, 엔진, 요청
스케줄링 등 사용자가 다루는 부분은 모두 업스트림 vLLM입니다. 플러그인은 vLLM이 디바이스에 일을 넘기는
지점부터 LPU를 알아야 하는 부분만 바꿉니다.
1 2 3 4 5 6 7 8 9 10 11 12 | |
vllm_hyperaccel 패키지를 설치하면 vLLM이 스스로 찾는 entry point 세 개가 등록됩니다.
| Entry point | vLLM에 제공하는 것 |
|---|---|
Platform (bertha) |
lpu 디바이스를 설명하고 LPU용 스케줄러, 워커, attention 백엔드, 컴파일러를 고르는 LPUPlatform |
Models (bertha_model) |
vLLM의 Llama, Qwen3, Gemma-4 클래스를 상속해 LPU에서 다른 부분만 바꾼 모델 클래스 |
Ops (bertha_ops) |
linear, embedding, RMSNorm, activation, rotary embedding, fused MoE의 LPU 구현 |
서버가 시작할 때¶
- 설정을 LPU에 맞춥니다.
LPUPlatform이 명령줄로 만든 설정을 검사해 chunked prefill, LPU 코어 수로 정한 스텝당 토큰 예산,bfloat16, 컴파일 실행을 적용합니다. 자세한 값은 설정 가이드에 있습니다. - 워커가 LPU를 잡습니다. vLLM은 엔진 워커마다 프로세스를 하나씩 띄우고,
HAWorker는 자기 프로세스가 쓸 LPU 하나를 고릅니다. - 가중치를 올립니다. vLLM 표준 모델 로더로 원본 Hugging Face 체크포인트를 읽습니다. 각 가중치는 LPU 행렬 유닛이 요구하는 메모리 레이아웃으로 한 번만 할당되며, 다른 형태로 올렸다가 변환하지 않습니다.
- 모델을 컴파일합니다. vLLM이
torch.compile로 모델을 추적하고 attention마다 그래프를 나눕니다. attention 사이의 조각(정규화, projection, feed-forward, residual)은LegatoCompiler가 조각 하나를 LPU 바이너리 하나로 만들고, attention은 전용 HyperAccel attention 커널로 실행합니다. LM head는 모델 러너가 따로 컴파일합니다.
컴파일은 시작할 때 한 번만 일어납니다. 서버가 준비될 때까지 시간이 걸리는 이유이고, 이후 요청은 이 비용을 치르지 않습니다. 가중치를 올리고 남은 디바이스 메모리는 KV 캐시로 예약됩니다.
매 스텝마다¶
- 검증 — 요청을 받기 전에 샘플링 옵션을 확인합니다.
- 스케줄링 —
EVT0Scheduler가 LPU 토큰 예산 안에서 이번 스텝에 실행할 요청과 토큰 수, 그리고 각 요청에 필요한 KV 캐시 페이지를 정합니다. - KV 캐시 매핑 — 새로 스케줄된 토큰의 페이지를 매핑하고 끝난 요청의 페이지를 해제합니다.
- Forward — 컴파일된 조각과 attention 커널이 LPU에서 차례로 실행됩니다.
- Logits — 다음 토큰을 고르는 데 필요한 요청별 마지막 위치만 LM head에 통과시킵니다.
- 샘플링 — greedy와
temperature/top_k/top_p샘플링을 LPU에서 수행하고 토큰 id만 호스트로 돌려보냅니다. LPU 샘플링을 참고합니다. - vLLM으로 반환 — 엔진이 토큰을 디토큰화해 클라이언트로 스트리밍합니다.
설계의 세 가지 원칙¶
- 하드웨어에 묶인 토큰 예산. LPU 코어 하나는 스텝당 최대 32 토큰을 처리합니다. 코어 32개면 스텝당 1,024 토큰을 prefill과 decode가 나눠 씁니다. 예산보다 긴 프롬프트는 여러 스텝에 걸쳐 읽습니다(chunked prefill).
- 요청별로 주소가 매겨지는 KV 캐시. 요청마다 하드웨어 주소 변환 테이블로 접근하는 연속 영역 하나를 주고, 메모리는 요청이 자라는 만큼 페이지 단위로 채웁니다. 컨텍스트와 KV 캐시를 참고합니다.
- 조용히 바꾸지 않고 분명히 실패. LPU에서 실행할 수 없는 설정이나 요청 옵션은 그 이름을 담은 오류로 거절합니다. 다른 계산으로 몰래 대체하지 않습니다.
SDK와의 관계¶
컴파일, LPU 커널, 커널 실행, 디바이스 메모리 관리는 vLLM과 무관한 HyperAccel SDK가 맡습니다. 플러그인은 vLLM의 계약을 SDK 호출로 옮기는 얇은 층이라 새 vLLM 릴리스를 빠르게 따라갈 수 있습니다. 아래 계층은 Torch, Runtime, Compiler에서 다룹니다.
튜토리얼과 기능¶
- 모델 튜토리얼 — 대표 모델로 vLLM HyperAccel을 실행하는 단계별 예제 - Qwen3 8B - Qwen3 30B-A3B (MoE) - Gemma-4 31B - EXAONE-4.5 33B - Llama-2 7B
- 기능 설명 — vLLM HyperAccel의 주요 기능 - 지원 기능 - 컨텍스트와 KV 캐시 - LPU 샘플링 - 여러 LPU 사용하기 - 양자화 - OpenAI 호환 서버 - 프로파일링
- 설정 가이드 — 엔진 인자, 플러그인이 정하는 값, 환경 변수
- 문제 해결
지원 모델¶
vLLM HyperAccel에서 지원하는 모델입니다. 모든 모델은 LPU 하드웨어에서 CPU 기준 결과와 비교해 검증합니다.
텍스트 생성 모델¶
| 아키텍처 | 예제 모델 | 검증된 구성 | 튜토리얼 |
|---|---|---|---|
Qwen3ForCausalLM |
Qwen/Qwen3-8B |
BF16 · 컨텍스트 16K · 동시 요청 · PP(2, 4 LPU) · DP | Qwen3 8B |
Qwen3MoeForCausalLM |
Qwen/Qwen3-30B-A3B |
BF16 · FP8 가중치 · 컨텍스트 2K | Qwen3 MoE |
Gemma4ForConditionalGeneration |
google/gemma-4-31B-it |
BF16 · 컨텍스트 16K · 동시 요청 · sliding-window attention | Gemma-4 |
Exaone4_5_ForConditionalGeneration |
LGAI-EXAONE/EXAONE-4.5-33B |
BF16 · INT4 가중치 · 컨텍스트 4K · 한 번에 요청 하나 | EXAONE-4.5 |
LlamaForCausalLM |
meta-llama/Llama-2-7b-hf |
BF16 (float16 체크포인트를 bfloat16으로 실행) |
Llama-2 |
Gemma-4와 EXAONE-4.5는 멀티모달 체크포인트로 배포되지만, LPU에서는 --language-model-only로 원본 체크포인트를
그대로 텍스트 모델로 서빙합니다. 변환한 체크포인트는 필요하지 않습니다.
양자화 모델¶
| 원본 | 방식 | 변환 | 검증된 구성 | 문서 |
|---|---|---|---|---|
LGAI-EXAONE/EXAONE-4.5-33B-AWQ |
INT4 | vllm serve 첫 실행 때 자동 |
컨텍스트 4K, 한 번에 요청 하나 | 양자화 |
Qwen/Qwen3-8B-AWQ |
INT4 | vllm serve 첫 실행 때 자동 |
입력 64 + 출력 64 토큰, 한 번에 요청 하나 | 양자화 |
Qwen/Qwen3-30B-A3B-GPTQ-Int4 |
INT4 | vllm serve 첫 실행 때 자동 |
입력 64 + 출력 64 토큰, 한 번에 요청 하나 | 양자화 |
Qwen/Qwen3-8B-FP8 |
FP8 | vllm serve 첫 실행 때 자동 |
입력 64 + 출력 64 토큰, 한 번에 요청 하나 | 양자화 |
Qwen/Qwen3-30B-A3B-FP8 |
FP8 | vllm serve 첫 실행 때 자동 |
입력 64 + 출력 64 토큰, 한 번에 요청 하나 | 양자화 |
검증 방식¶
| 모델 | LPU 야간 테스트 | LPU 수시 테스트 |
|---|---|---|
| Qwen3-8B | 동시 요청 3개 | 16K 서빙, 4K / 8K / 16K 장문 컨텍스트, 2 · 4 LPU PP, 2 LPU DP, KV 캐시 선점 |
| Qwen3-30B-A3B | greedy 생성 | 2K 컨텍스트 FP8 |
| Gemma-4 31B | 입력 64 + 출력 64 토큰 | 요청 8 / 16 / 32개에서 KV 캐시 선점, sliding window보다 긴 컨텍스트 |
| EXAONE-4.5 33B | 짧은 프롬프트, 4K 전체 컨텍스트, INT4 | |
| Llama-2 7B | 짧은 프롬프트 |
LPU는 bfloat16으로 계산하므로 판정은 최종 문장 비교가 아니라, LPU가 고른 토큰마다 CPU 기준 모델이 같은
선택을 하는지(근소한 동점 허용)로 합니다.