콘텐츠로 이동

설정 가이드

개요

vLLM RBLN은 upstream vLLM과 동일한 진입점인 LLM(...), vllm serve, EngineArgs를 사용합니다. 대부분의 인자는 vLLM과 동일하게 동작하며, 일부는 RBLN 만의 고유 제약 사항이 적용됩니다.

그리고 RBLN 만의 고유 개념은 다음 두 가지 방식으로 노출됩니다:

  • additional_config 파라미터
  • VLLM_RBLN_* 환경 변수

Engine Arguments

엔진 인자는 upstream vLLM과 동일한 방식으로 설정합니다. 아래 인자들은 RBLN 만의 고유 제약 사항이 있습니다.

block_size (필수)

max_model_len과 함께 attention 모드를 결정합니다:

  • block_size == max_model_len: Naive Attention.
  • max_model_len이 block_size의 배수: Flash Attention.

예외: 풀링 및 인코더-디코더 모델(예: Whisper)에서는 block_size가 max_model_len과 같은 값으로 자동 설정되므로 직접 지정하지 않아도 됩니다. Qwen3 백본 기반 풀링 모델은 Flash Attention을 위해 더 작은 값을 명시할 수 있습니다. 자세한 내용은 Attention 모드를 참고하세요.

max_model_len

기본값: 모델의 최대 시퀀스 길이.

block_size와의 조합에 따라 attention 모드가 결정됩니다(위 참조).

max_num_seqs
기본값: 1.
tensor_parallel_size (고정값 1)

이 vLLM 엔진 인자는 vLLM 레벨의 텐서 병렬을 선택하며, 모델을 여러 워커 프로세스로 분할하고 Rebellions Collective Communications Library (RCCL)로 통신합니다. RBLN NPU 환경에서는 1만 허용하며, 다른 값을 지정하면 에러가 발생합니다. 다중 프로세스 텐서 병렬은 RCCL 연동이 추가되는 향후 릴리스에서 지원될 예정입니다.

단일 프로세스 안에서 여러 NPU 디바이스에 걸쳐 모델을 실행하려면 VLLM_RBLN_NUM_DEVICES_PER_LOCAL_RANK 환경 변수를 사용하세요. RBLN 컴파일러가 해당 디바이스들에 모델을 분할하고 단일 프로세스로 실행하며, 이는 vLLM 레벨의 tensor_parallel_size와는 별개의 메커니즘인 Rebellions Scalable Design(RSD)입니다.

다음은 전체 예시입니다:

1
2
3
4
5
6
7
8
9
from vllm import LLM

llm = LLM(
    model="<huggingface-model-id>",
    block_size=4096,
    max_model_len=32768,
    max_num_seqs=1,
    tensor_parallel_size=1,
)

Additional Configuration Keys

LLM(...)의 additional_config 파라미터로 전달하는 RBLN 전용 키. 일부는 additional_config 최상위에, 일부는 additional_config["rbln_config"] 아래에 위치합니다. rbln_config의 전체 스키마는 optimum-rbln의 RblnModelConfig에서 확인하세요.

prefix_block_size

기본값: 128.

additional_config["prefix_block_size"]로 설정합니다. Automatic Prefix Caching이 활성화된 경우 prefix 캐시 히트 단위를 제어합니다. 값은 prefill_chunk_size의 배수이면서 kvcache_block_size의 약수여야 합니다. 자세한 내용은 Automatic Prefix Caching을 참고하세요.

device

기본값: 0부터 VLLM_RBLN_NUM_DEVICES_PER_LOCAL_RANK - 1까지 디바이스에 자동 매핑됩니다.

각 모델 또는 서브모듈 아래의 additional_config["rbln_config"][...]["device"]로 설정하며, 한 컴파일 모델 안에서 서브모듈별로 다른 디바이스에 배치할 수 있습니다(아래 예시 참조). 디바이스 배치는 런타임에 결정되므로, 동일한 컴파일 산출물을 재컴파일 없이 서로 다른 하드웨어에 배포할 수 있습니다.

decoder_batch_sizes

기본값: max_num_seqs 크기의 디코더 하나만 컴파일됩니다.

additional_config["rbln_config"]["decoder_batch_sizes"]로 설정합니다. 리스트의 각 배치 크기마다 디코더 그래프를 하나씩 컴파일하므로, 런타임에 진행 중인 요청 수를 처리할 수 있는 가장 작은 배치 크기의 디코더가 선택됩니다. 모든 값은 max_num_seqs 이하여야 합니다. 리스트는 내림차순으로 정렬되며, max_num_seqs가 누락되어 있으면 자동으로 추가됩니다. 자세한 내용은 Inference with Dynamic Batch Sizes를 참고하세요.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
from vllm import LLM

llm = LLM(
    ...,
    additional_config={
        "prefix_block_size": 256,
        "rbln_config": {
            "visual": {
                "device": [0],
            },
            "language_model": {
                "device": [1, 2, 3, 4],
            },
        },
    },
)

환경 변수

VLLM_RBLN_ 접두사를 가진 RBLN 전용 환경 변수. 엔진을 실행하는 프로세스에서 설정합니다. upstream vLLM의 환경 변수는 vLLM 환경 변수 문서를 참고하세요.

VLLM_RBLN_NUM_DEVICES_PER_LOCAL_RANK

기본값: 1.

하나의 local rank, 즉 하나의 엔진 프로세스로 묶이는 RBLN NPU 디바이스 수를 지정합니다. RBLN 컴파일러는 이 디바이스들에 모델을 분할하고 단일 프로세스로 실행하며, RBLN은 이 방식을 RSD라고 부릅니다. RSD는 런타임 오버헤드를 줄입니다. 이는 모델을 여러 프로세스로 분할하여 RCCL로 통신하는 vLLM 레벨의 tensor_parallel_size와는 다릅니다. 자세한 내용은 Model Parallelism을 참고하세요.

Note

VLLM_RBLN_TP_SIZE는 이 변수의 이전 이름으로, deprecated되었습니다. VLLM_RBLN_NUM_DEVICES_PER_LOCAL_RANK가 설정되지 않은 경우 fallback으로 계속 인정되지만, 향후 릴리스에서 제거될 예정입니다.

VLLM_RBLN_SAMPLER

기본값: True.

RBLN NPU에서 샘플링을 실행하는 RBLNSampler를 사용합니다. False로 설정하면 upstream vLLM 샘플러로 폴백되어 샘플링이 CPU에서 실행됩니다.

VLLM_RBLN_ENABLE_WARM_UP

기본값: True.

엔진 시작 시 모델 워밍업 단계를 실행해 첫 요청이 일회성 초기화 비용으로 지연되지 않도록 합니다. False로 설정하면 워밍업을 건너뜁니다.