KV 캐시 블록 추정 트러블슈팅¶

요약¶

증상¶

모델 하나만 사용할 때는 컴파일과 추론 모두 정상적으로 동작하지만, 컴파일된 모델이 NPU 메모리 전체를 차지할 수 있습니다. 이 경우 같은 NPU에 두 번째 모델이나 같은 파이프라인의 다른 submodule을 로드할 수 없고, 이후 batch 크기를 늘릴 여유 공간도 남지 않습니다.

근본 원인¶

kvcache_num_blocks의 기본값은 0이며, 이는 KV 캐시 크기를 컴파일 후에 자동으로 결정한다는 의미입니다. 이때 RBLN Optimum은 NPU DRAM에서 컴파일된 모델 자체가 사용하는 메모리를 뺀 나머지에 최대 블록 수(num_full_blocks, Step 2 참고)가 들어가는지 먼저 확인합니다. 들어가면 최대 블록 수를 그대로 쓰고, 들어가지 않으면 들어가는 가장 큰 블록 pool을 탐색합니다. 최대 블록 수를 넘지는 않지만, 어느 경우든 KV 캐시가 남은 DRAM을 쓸 수 있는 만큼 사용하고 다른 용도의 여유 공간은 따로 남기지 않습니다.

해결¶

KV 캐시 크기를 자동으로 결정할 때 사용할 DRAM 용량을 memory_budget으로 제한합니다. memory_budget은 NPU 1장 단위로 적용되며, 그 NPU가 실제로 내주는 DRAM 용량을 기준으로 해석됩니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from optimum.rbln import RBLNQwen3ForCausalLM

model = RBLNQwen3ForCausalLM.from_pretrained(
    "Qwen/Qwen3-8B",
    export=True,
    rbln_batch_size=8,
    rbln_max_seq_len=40_960,
    rbln_num_devices=1,
    rbln_kvcache_partition_len=8_192,
    rbln_memory_budget=0.3,
    rbln_create_runtimes=False,
)
model.save_pretrained("rbln-Qwen3-8B")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from optimum.rbln import RBLNQwen3ForCausalLM

model = RBLNQwen3ForCausalLM.from_pretrained(
    "Qwen/Qwen3-8B",
    export=True,
    rbln_batch_size=8,
    rbln_max_seq_len=40_960,
    rbln_num_devices=4,
    rbln_kvcache_partition_len=8_192,
    rbln_memory_budget=0.5,
    rbln_create_runtimes=False,
)
model.save_pretrained("rbln-Qwen3-8B")

memory_budget은 세 가지 형태를 받습니다.

memory_budget은 KV 캐시에만 적용되는 값이 아니라 컴파일된 모델이 NPU에 올리는 모든 것에 적용됩니다. 가중치와 workspace를 먼저 차감하고 남은 공간을 KV 캐시가 차지하기 때문에, KV 캐시의 블록 수는 memory_budget보다 더 가파르게 줄어듭니다.

1
2

$ python -c "import json; print(json.load(open('rbln-Qwen3-8B/rbln_config.json'))['kvcache_num_blocks'])"
21

1
2

$ python -c "import json; print(json.load(open('rbln-Qwen3-8B/rbln_config.json'))['kvcache_num_blocks'])"
14

컴파일된 산출물에는 0이 기록되지 않습니다. kvcache_num_blocks를 명시했다면 그 값이, 자동 추정을 했다면 추정된 값이 저장됩니다. eager attention에서 블록 수를 지정하지 않았다면 memory_budget과 관계없이 최대 블록 수가 저장됩니다.

같은 옵션을 컴파일 CLI에서도 쓸 수 있으며, 세 가지 형태가 모두 동작합니다.

1
2
3

optimum-rbln-cli --model-id Qwen/Qwen3-8B --output-dir ./rbln-Qwen3-8B \
  --batch_size 8 --max_seq_len 40960 --num_devices 1 \
  --kvcache_partition_len 8192 --memory-budget 0.3

1
2
3

optimum-rbln-cli --model-id Qwen/Qwen3-8B --output-dir ./rbln-Qwen3-8B \
  --batch_size 8 --max_seq_len 40960 --num_devices 4 \
  --kvcache_partition_len 8192 --memory-budget 0.5

증상¶

memory_budget을 너무 낮게 설정하면 컴파일이 다음 에러로 실패합니다.

1
2
3

ValueError: Insufficient memory for the required KV cache: only 8 blocks can be allocated,
but at least 9 blocks are required. Consider reducing `max_seq_len` or `batch_size`
(currently 8) to lower the memory requirement.

1
2
3

ValueError: Insufficient memory for the required KV cache: only 3 blocks can be allocated,
but at least 9 blocks are required. Consider reducing `max_seq_len` or `batch_size`
(currently 8) to lower the memory requirement.

근본 원인¶

블록 pool이 일정 크기 아래로 내려가면 시퀀스 하나를 온전히 담을 수 없고 batch의 각 항목에 블록을 하나씩 나눠 줄 수도 없습니다. 따라서 RBLN Optimum은 더 작은 pool로 물러서지 않고 추정 결과를 거부합니다. flash attention에서 하한과 최대 블록 수는 다음 식으로 정해집니다.

1
2

num_min_blocks  =  min(max((max_seq_len / kvcache_block_size), batch_size) + 1, num_full_blocks)
num_full_blocks =  (max_seq_len / kvcache_block_size) × batch_size

+ 1은 시퀀스가 계속 길어지는 동안 블록 테이블의 빈 슬롯을 채우기 위한 여분 블록으로, 두 항 중 어느 쪽이 하한이 되든 항상 필요합니다.

기준 설정에서는 다음과 같습니다.

memory_budget을 낮출 수 있는 폭은 이 두 값의 간격에서 나오고, 그 간격은 batch_size가 벌립니다. batch 항목이 하나 늘 때마다 최대 블록 수는 시퀀스 하나 분량만큼 커지는데, 하한은 두 항 중 큰 쪽만 따라가기 때문입니다. 같은 설정에서 batch_size=1이면 최대 블록 수와 하한이 모두 5블록으로 같아지므로, 최대 블록 수에 못 미치는 값은 어느 것도 통과하지 못합니다.

해결¶

추정치가 하한을 넘길 때까지 memory_budget을 올린 뒤, Step 1처럼 확정된 블록 수를 확인합니다. 하한 때문에 memory_budget을 더 낮출 수 없다면 max_seq_len을 줄여야 합니다. max_seq_len을 낮추면 하한도 함께 내려가므로 시퀀스 하나가 예약하는 양 자체가 줄어듭니다.

증상¶

두 가지 검증 에러 중 하나가 발생합니다.

1

ValueError: memory_budget (1099511627776 bytes) exceeds the target NPU's available DRAM (150323855360 bytes).

1

ValueError: memory_budget (107374182400 bytes) exceeds the target NPU's available DRAM (16877879296 bytes).

1

ValueError: `memory_budget` and an explicit `kvcache_num_blocks` are mutually exclusive. `memory_budget` only guides automatic block estimation, which runs when `kvcache_num_blocks` is unset.

근본 원인¶

바이트로 지정한 값이 대상 NPU가 내주는 DRAM 용량을 넘으면 첫 번째 에러가 발생합니다. 그 용량은 Step 1에서 본 것처럼 Rebel100™에서 150,323,855,360 바이트(140 GiB), ATOM™-Max에서 16,877,879,296 바이트(15.72 GB)입니다. 이보다 큰 값은 장치에 없는 용량을 요구하는 셈이므로 조용히 잘라내지 않고 거부합니다.

두 번째 에러는 자동 추정이 무력화되는 조합을 막습니다. memory_budget은 자동 추정이 쓰는 값이고, 자동 추정은 kvcache_num_blocks가 비어 있을 때만 동작합니다. 두 값을 함께 지정하면 추정을 건너뛰면서 memory_budget이 조용히 무시되므로, 설정 시점에 조합 자체를 거부합니다.

해결¶

산출물을 여러 환경에서 쓸 예정이라면 바이트 수보다 비율로 지정하는 것을 권장합니다. 비율은 컴파일 대상 NPU에 맞춰 해석됩니다. 바이트로 지정한다면 대상 NPU가 내주는 DRAM 용량 아래로 유지해야 합니다.

두 제어 수단 중 하나만 선택합니다.