콘텐츠로 이동

RBLN vLLM: RBLN NPU용 vLLM 플러그인

RBLN vLLM(vllm-rbln)은 vLLM용 하드웨어 플러그인입니다. 리벨리온 NPU에서 LLM 추론과 서빙을 수행합니다.

설치 방법

RBLN vLLM을 설치하기 이전에 반드시 rebel-compiler 최신 버전을 설치해야 합니다.

1
2
3
$ pip install \
  --extra-index-url https://pypi.rbln.ai/simple \
  rebel-compiler==0.12.0

RBLN vLLM은 PyPI에서 설치하거나 소스 코드를 직접 빌드하여 설치하는 두 가지 방법을 제공합니다.

최신 버전 및 변경 사항에 대한 자세한 내용은 릴리즈 노트에서 확인할 수 있습니다.

PyPI 설치

다음은 pip를 통해 최신 릴리즈를 설치하는 명령어입니다.

1
2
3
4
$ pip install \
  --extra-index-url https://wheels.vllm.ai/0.30.0/cpu \
  --extra-index-url https://download.pytorch.org/whl/cpu \
  vllm-rbln==0.12.0

소스 코드 설치

1. vllm과 vllm-rbln 저장소 클론

필요한 vllm 버전은 vllm-rbln의 버전과 다를 수 있습니다.

1
2
$ git clone -b vv0.30.0 --single-branch https://github.com/vllm-project/vllm.git
$ git clone https://github.com/RBLN-SW/vllm-rbln.git

2. vllm 설치

RBLN NPU용 vLLM을 빌드할 때 VLLM_TARGET_DEVICE=empty를 설정해야 합니다.

1
2
3
$ cd vllm/
$ VLLM_TARGET_DEVICE=empty pip install -e .
$ cd ..

3. vllm-rbln 설치

1
2
3
$ cd vllm-rbln
$ pip install -e .
$ cd ..

기능별 추가 패키지

사용할 기능에 필요한 의존성을 추가로 설치해야 합니다.

KV 캐시 오프로딩 및 Disaggregated Prefill / Decode

kv_connectors extra는 KV 캐시 오프로딩과 Disaggregated Prefill / Decode에 필요한 nixl-rbln, lmcache-rbln을 설치합니다. 기본 설치에는 포함되지 않습니다.

1
2
3
4
5
$ pip install \
  --extra-index-url https://pypi.rbln.ai/simple \
  --extra-index-url https://wheels.vllm.ai/0.30.0/cpu \
  --extra-index-url https://download.pytorch.org/whl/cpu \
  "vllm-rbln[kv_connectors]==0.12.0"

소스 코드로 설치하는 경우, vllm-rbln 디렉터리에서 pip install -e '.[kv_connectors]'를 실행합니다.

Disaggregated Encoder

Disaggregated Encoder를 사용하려면 인코더와 PD 인스턴스를 실행하는 Python 환경에 nixl이 필요합니다. vllm-rbln 외에 추가로 설치해야 합니다.

1
$ pip install nixl

음성 인식

audio extra는 Whisper를 비롯해 /v1/audio/transcriptions로 서빙하는 모델에 필요한 오디오 디코더를 설치합니다. 이 의존성이 없으면 서버는 시작되지만 첫 음성 전사 요청이 실패합니다.

1
2
3
4
5
$ pip install \
  --extra-index-url https://pypi.rbln.ai/simple \
  --extra-index-url https://wheels.vllm.ai/0.30.0/cpu \
  --extra-index-url https://download.pytorch.org/whl/cpu \
  "vllm-rbln[audio]==0.12.0"

소스 코드로 설치하는 경우, vllm-rbln 디렉터리에서 pip install -e '.[audio]'를 실행합니다.

아키텍처 디자인

RBLN vLLM은 모델을 두 가지 model implementation, vllm과 transformers 중 하나로 실행합니다. 이 이름은 upstream vLLM --model-impl 옵션의 값입니다. transformers는 이를 제공하는 패키지가 optimum-rbln이라서 optimum이라고도 부릅니다. 두 구현은 모델 코드, 컴파일 방식, worker, 스케줄링, 지원 기능이 다릅니다. 구현별 기능 지원은 Feature Matrix에 정리되어 있습니다.

두 구현 모두 RBLN 컴파일러(rebel-compiler)로 모델을 컴파일하고 그 결과를 캐시하므로, 같은 설정으로 다시 실행하면 재컴파일 없이 캐시를 재사용합니다. 자세한 내용은 Compile Cache에서 확인할 수 있습니다.

항목 vllm transformers(optimum)
모델 구현 출처 vLLM 자체 모델 구현 optimum-rbln
컴파일 엔진 시작 시 엔진 시작 시, 또는 optimum-rbln으로 사전에
멀티 디바이스 TP, PP, EP, DP. 프로세스에 걸쳐 RSD. 단일 프로세스 내부
지원 디바이스 Rebel100™ Rebel100™, ATOM™

vllm

모델 코드를 vLLM 자체 모델 구현에서 가져옵니다. 엔진이 rbln 백엔드의 torch.compile로 엔진 시작 시 컴파일합니다.

여러 디바이스를 사용할 때는 vLLM의 병렬화 메커니즘인 tensor parallelism(TP), pipeline parallelism(PP), expert parallelism(EP), data parallelism(DP)을 사용합니다. 자세한 내용은 모델 병렬화에서 확인할 수 있습니다.

transformers(optimum)

모델 코드를 optimum-rbln에서 가져옵니다. optimum-rbln은 지원하는 아키텍처마다 RBLN 모델 클래스(예: RBLNLlamaForCausalLM)를 제공합니다.

model에는 HuggingFace model ID를 지정하거나, optimum-rbln으로 따로 컴파일한 모델이 들어 있는 디렉터리 경로를 지정합니다. model ID를 지정하면 RBLN vLLM이 엔진 시작 시 컴파일하고, 디렉터리 경로를 지정하면 컴파일된 모델을 불러옵니다.

여러 디바이스를 사용할 때는 Rebellions Scalable Design(RSD)을 사용합니다. vLLM 수준의 모델 분할에 기대지 않고 RBLN 컴파일러가 모델을 여러 디바이스에 분할합니다.

model implementation 선택

vLLM의 --model-impl 옵션(LLM()에서는 model_impl 인자)으로 사용할 구현을 선택합니다.

값 동작
auto(기본값) 모델의 아키텍처를 optimum-rbln이 지원하면 transformers 구현을, 그렇지 않으면 vllm 구현을 사용합니다.
vllm vllm 구현을 사용합니다.
transformers(별칭: optimum) transformers(optimum) 구현을 사용합니다.

vllm serve --help에는 upstream vLLM의 --model-impl 설명이 출력되는데, RBLN vLLM에서의 동작과 일부 다릅니다. 특히 RBLN vLLM의 auto는 transformers를 우선하고, upstream의 auto는 vllm을 우선합니다.

RBLN 전용 옵션은 --rbln-* 접두사를 사용합니다. 각 옵션은 하나의 model implementation에만 적용되며, 선택한 구현에 해당하지 않는 옵션은 엔진 설정을 만드는 단계에서 거부됩니다.

--rbln-* 옵션이 대체한 환경 변수는 deprecated입니다. 해당 VLLM_RBLN_* 변수와 각각의 대체 옵션은 설정 가이드에서 확인할 수 있습니다.

지원 디바이스

vllm model implementation은 Rebel100™에서만 동작합니다. ATOM™ 호스트에서는 --model-impl vllm으로 직접 선택했든 auto가 vllm으로 결정했든, 엔진이 디바이스 이름을 담은 에러를 냅니다. 따라서 ATOM™에서 서빙하려면 transformers(optimum) 구현이 지원하는 아키텍처여야 합니다.

주요 기능

다양한 실행 모드와 서버 기능 등 RBLN vLLM이 제공하는 핵심 기능들을 설명합니다.

지원하는 아키텍처

아래 표는 RBLN vLLM이 지원하는 아키텍처를 model implementation별로 정리한 것입니다. Architecture는 체크포인트의 config.json에 기록된 이름입니다.

vllm implementation 아키텍처

vllm model implementation, 즉 --model-impl vllm으로 실행하는 아키텍처입니다.

Architecture Recipe
GptOssForCausalLM gpt-oss-120b
MiniMaxM2ForCausalLM MiniMax-M2.7
DeepseekV32ForCausalLM DeepSeek-V3.2
AXK2ForCausalLM A.X-K2

transformers(optimum) implementation 아키텍처

각 표는 디바이스 계열별로 나뉩니다. Rebel100™ 탭은 Rebel100™에서 검증된 아키텍처를, ATOM™ 탭은 이 구현이 지원하는 전체 아키텍처를 보여줍니다.

Decoder-only Models

Architecture RBLN Model Class Recipe
LlamaForCausalLM RBLNLlamaForCausalLM Llama-3.1-8B-Instruct
GemmaForCausalLM RBLNGemmaForCausalLM gemma-7b-it
Gemma2ForCausalLM RBLNGemma2ForCausalLM gemma-2-9b-it
PhiForCausalLM RBLNPhiForCausalLM phi-2
OPTForCausalLM RBLNOPTForCausalLM opt-6.7b
GPT2LMHeadModel RBLNGPT2LMHeadModel gpt2
MistralForCausalLM RBLNMistralForCausalLM Mistral-7B-Instruct-v0.3
ExaoneForCausalLM RBLNExaoneForCausalLM EXAONE-3.5-7.8B-Instruct
Qwen2ForCausalLM RBLNQwen2ForCausalLM Qwen2.5-7B-Instruct
Qwen3ForCausalLM RBLNQwen3ForCausalLM Qwen3-8B
GptOssForCausalLM RBLNGptOssForCausalLM gpt-oss-20b
Architecture RBLN Model Class Recipe
LlamaForCausalLM RBLNLlamaForCausalLM Llama-3.1-8B-Instruct
GemmaForCausalLM RBLNGemmaForCausalLM gemma-7b-it
Gemma2ForCausalLM RBLNGemma2ForCausalLM gemma-2-9b-it
PhiForCausalLM RBLNPhiForCausalLM phi-2
OPTForCausalLM RBLNOPTForCausalLM opt-6.7b
GPT2LMHeadModel RBLNGPT2LMHeadModel gpt2
MistralForCausalLM RBLNMistralForCausalLM Mistral-7B-Instruct-v0.3
ExaoneForCausalLM RBLNExaoneForCausalLM EXAONE-3.5-7.8B-Instruct
Qwen2ForCausalLM RBLNQwen2ForCausalLM Qwen2.5-7B-Instruct
Qwen3ForCausalLM RBLNQwen3ForCausalLM Qwen3-8B
Qwen3MoeForCausalLM RBLNQwen3MoeForCausalLM Qwen3-30B-A3B
GptOssForCausalLM RBLNGptOssForCausalLM gpt-oss-20b

Encoder-Decoder Models

Architecture RBLN Model Class Recipe
WhisperForConditionalGeneration RBLNWhisperForConditionalGeneration whisper-large-v3

변경 사항

RBLN vLLM v0.10.1부터 V0는 더 이상 지원되지 않습니다. 이에 따라 encoder–decoder 모델로는 Whisper만 지원되며, 그 외 모든 encoder–decoder 모델에 대한 지원은 제거되었습니다. 자세한 내용은 vLLM V1 사용자 가이드에서 확인할 수 있습니다.

Multimodal Language Models

Architecture RBLN Model Class Recipe
LlavaNextForConditionalGeneration RBLNLlavaNextForConditionalGeneration llava-v1.6-mistral-7b-hf
Qwen2VLForConditionalGeneration RBLNQwen2VLForConditionalGeneration Qwen2-VL-7B-Instruct
Qwen2_5_VLForConditionalGeneration RBLNQwen2_5_VLForConditionalGeneration Qwen2.5-VL-7B-Instruct
Qwen3VLForConditionalGeneration RBLNQwen3VLForConditionalGeneration Qwen3-VL-8B-Instruct
Qwen3_5ForConditionalGeneration RBLNQwen3_5ForConditionalGeneration Qwen3.5-9B, Qwen3.6-27B
Idefics3ForConditionalGeneration RBLNIdefics3ForConditionalGeneration Idefics3-8B-Llama3
Gemma3ForConditionalGeneration RBLNGemma3ForConditionalGeneration gemma-3-12b-it
Gemma4ForConditionalGeneration RBLNGemma4ForConditionalGeneration gemma-4-31B-it
Blip2ForConditionalGeneration RBLNBlip2ForConditionalGeneration blip2-opt-2.7b
PaliGemmaForConditionalGeneration RBLNPaliGemmaForConditionalGeneration paligemma-3b-mix-224
Architecture RBLN Model Class Recipe
LlavaNextForConditionalGeneration RBLNLlavaNextForConditionalGeneration llava-v1.6-mistral-7b-hf
Qwen2VLForConditionalGeneration RBLNQwen2VLForConditionalGeneration Qwen2-VL-7B-Instruct
Qwen2_5_VLForConditionalGeneration RBLNQwen2_5_VLForConditionalGeneration Qwen2.5-VL-7B-Instruct
Qwen3VLForConditionalGeneration RBLNQwen3VLForConditionalGeneration Qwen3-VL-8B-Instruct
Qwen3_5ForConditionalGeneration RBLNQwen3_5ForConditionalGeneration Qwen3.5-9B, Qwen3.6-27B
Idefics3ForConditionalGeneration RBLNIdefics3ForConditionalGeneration Idefics3-8B-Llama3
Gemma3ForConditionalGeneration RBLNGemma3ForConditionalGeneration gemma-3-12b-it
Gemma4ForConditionalGeneration RBLNGemma4ForConditionalGeneration gemma-4-31B-it
LlavaForConditionalGeneration RBLNLlavaForConditionalGeneration llava-1.5-7b-hf
Blip2ForConditionalGeneration RBLNBlip2ForConditionalGeneration blip2-opt-2.7b
PaliGemmaForConditionalGeneration RBLNPaliGemmaForConditionalGeneration paligemma-3b-mix-224
PaliGemmaForConditionalGeneration RBLNPaliGemmaForConditionalGeneration paligemma2-3b-mix-224
Exaone4_5_ForConditionalGeneration RBLNExaone4_5_ForConditionalGeneration EXAONE-4.5-33B

Pooling Models

지원하지 않습니다.

Architecture RBLN Model Class Recipe
BertModel RBLNBertModel bge-base-en-v1.5
XLMRobertaModel RBLNXLMRobertaModel bge-m3
XLMRobertaForSequenceClassification RBLNXLMRobertaForSequenceClassification bge-reranker-v2-m3
RobertaForSequenceClassification RBLNRobertaForSequenceClassification twitter-roberta-base-emotion
Qwen3ForSequenceClassification RBLNQwen3ForCausalLM Qwen3-Reranker-4B
Qwen3Model RBLNQwen3Model Qwen3-Embedding-4B