VMM API¶
paged KV 캐시를 관리하는 torch.ops.lpu.vmm_* 연산입니다. 물리 KV 풀을
만들고, KEY·VALUE 주소를 예약하고, 스케줄러 스텝마다 요청별 페이지를 늘리고 반환합니다. 이
연산들은 런타임 VMM API를 거쳐 HW 페이지를 관리합니다.
처음 쓰는 경우 Paged KV 캐시 장을 먼저 읽으십시오.
**블록**은 KV 캐시를 매핑하는 논리적인 페이지 단위입니다. 런타임은 블록을 HW 페이지 단위로 디바이스 메모리에 배치하며, 일반적으로 블록 하나는 HW 페이지를 하나 이상 묶습니다.
엔지니어링 샘플
현재 디바이스(엔지니어링 샘플)에서는 다음 조건을 따릅니다.
- 풀과 매핑에서는 블록 하나가 토큰 하나입니다(
block_size=1). 주소 예약과vmm_init_blocks에서는 요청 슬롯 행 하나를 블록 하나(block_size= 요청당 최대 토큰 수)로 둡니다. HW 페이지는 요청마다 할당되며, HW 페이지 하나에 여러 토큰이 들어갑니다. - 요청의 블록은 늘어나기만 합니다. 요청이 살아 있는 동안 매핑은 블록을 늘리기만 하며, 해제는 요청(슬롯) 단위로 한 번에 이루어집니다.
- prefix caching은 multi-turn 이어 쓰기로 동작합니다. 새 요청이 이전 요청의 KV 전체로 시작하면(같은
대화의 다음 턴처럼) 그 KV를 이어 씁니다. vLLM 예제는 prefix caching을 끈 설정(
--no-enable-prefix-caching)을 기준으로 합니다. vLLM KV 캐시를 보십시오.
모든 연산은 호출 스레드의 현재 디바이스로 라우팅됩니다. 런타임 호출이 실패하면
RuntimeError가 <연산>: <런타임 진입점> failed: err=<코드> 형태로 발생합니다.
풀¶
| 함수 | 시그니처 | 비고 |
|---|---|---|
torch.ops.lpu.vmm_create_kv_pool |
(int num_blocks, int num_attn_layers, int num_kv_heads, int block_size, int head_dim, *, ScalarType dtype, Device device, str kind="dram_word_interleaved", int page_size=4096) -> Tensor |
KEY와 VALUE를 함께 담는 풀. 형상 [2, N, L, H, block_size, D]. 블록 하나가 토큰 하나이므로 block_size는 1 |
런타임 HaVmmAllocatePool로 풀 메모리를 할당하고, zero_()로
0을 채운 뒤 반환합니다. num_blocks는 풀의 토큰
예산입니다. page_size는 풀 기준 주소의 정렬이며, 기본값 4096을
그대로 두십시오. torch.ops.lpu.empty_with_kind와
같이 FakeTensorMode용 fake 커널이 등록되어 있습니다.
풀 텐서의 수명이 물리 메모리의 수명입니다
마지막 참조가 사라지면 풀 메모리가 해제됩니다. 매핑된 요청이 남아 있는 동안 풀 텐서를 놓지 마십시오.
KV 비용¶
| 함수 | 시그니처 | 비고 |
|---|---|---|
torch.ops.lpu.vmm_kv_pool_bytes |
(int head_dim, ScalarType dtype, int num_layers, int num_kv_heads, int budget_bytes) -> int |
budget_bytes 안에서 풀이 쓸 수 있는 최대 바이트 수 |
torch.ops.lpu.vmm_kv_pool_units |
(int head_dim, ScalarType dtype, int num_blocks) -> int |
토큰 num_blocks개짜리 풀이 담는 단위 수 |
torch.ops.lpu.vmm_kv_cost_table |
(int head_dim, ScalarType dtype, int max_blocks) -> Tensor |
토큰 n개인 요청이 차지하는 단위 수를 n = 0부터 max_blocks까지 담은 CPU int64 텐서 |
스케줄러가 요청이 풀에 들어가는지 계산할 때 씁니다. 요청들의 단위 수 합이 풀의 단위 수 이하이면 모두 들어갑니다. 디바이스를 열지 않아도 호출할 수 있습니다.
주소 예약¶
| 함수 | 시그니처 | 비고 |
|---|---|---|
torch.ops.lpu.vmm_reserve |
(int num_blocks, int num_attn_layers, int num_kv_heads, int block_size, int head_dim, str kind, ScalarType dtype) -> Tensor |
KV 주소 텐서 하나를 만듦. kind는 "key" 또는 "value". 형상 [num_blocks, L, H, block_size, D] |
런타임 HaVmmReserveBlocks를 호출하며, 물리 메모리를 붙이지 않습니다. 상태가 없어 언제든
호출할 수 있고, KEY와 VALUE에 한 번씩 호출합니다. "value" 텐서에는 VALUE 비트가 붙습니다.
dtype은 float16, bfloat16, float8_e4m3fn, float8_e5m2, float4_e2m1fn_x2를 받습니다.
float4_e2m1fn_x2는 마지막 차원이 패킹 계수만큼 줄어듭니다. 요청 슬롯 행마다 블록 하나를 두고
block_size를 요청당 최대 토큰 수로 주는 것이 일반적입니다(vLLM 플러그인은 행 1024개와 block_size = max_model_len을 넘깁니다. vLLM의 --block-size와는 별개이며, 플러그인은 이를 1로 고정합니다). 예약한 주소는 물리 메모리를 갖지 않으므로 따로 해제할 필요가 없습니다.
vmm_reserve에는 fake 커널이 없습니다
FakeTensorMode나 torch.compile 트레이싱 안에서 호출하면 실제 디바이스 호출이
일어납니다. 컴파일된 영역 밖, 엔진 초기화 단계에서 호출하십시오.
초기화와 해제¶
| 함수 | 시그니처 | 비고 |
|---|---|---|
torch.ops.lpu.vmm_init_blocks |
(int num_rows, int max_num_blocks_per_row, int num_attn_layers, int num_kv_heads, int block_size, int head_dim, int elem_size_bits, Tensor? pool=None) -> () |
풀로 디바이스의 VMM 상태를 만듦. pool에는 vmm_create_kv_pool로 만든 풀 텐서를 넘김 |
torch.ops.lpu.vmm_deinit |
() -> () |
VMM 상태를 해제. 풀은 해제하지 않음. 두 번째 호출은 무동작 |
vmm_init_blocks는 런타임 HaVmmInitBlocks를 호출하며, vmm_reserve와 풀 생성 이후에
호출합니다. max_num_blocks_per_row × block_size는 요청당 최대 토큰 수로, 주소 예약의 토큰
깊이와 같아야 합니다(vLLM 플러그인은 1과 max_model_len을 넘깁니다). num_rows는 요청 슬롯 수로, vLLM의 max_num_seqs와 비슷한 개념입니다(요청 슬롯은 현재 최대 1024개).
elem_size_bits는 dtype의 논리 비트 수입니다(float16 16, float8_* 8, float4_e2m1fn_x2 4).
pool은 현재 디바이스의 vmm_create_kv_pool 텐서여야 하며, 한 요청의 KEY·VALUE 페이지를 담을
만큼 커야 합니다. 다시 호출하면 기존 상태를 먼저 정리합니다.
매핑¶
| 함수 | 시그니처 | 비고 |
|---|---|---|
torch.ops.lpu.vmm_map_blocks |
(Tensor[] vmm_tensors, int row_index, int[] cached_block_ids, Tensor pool, int[] new_block_ids, int block_size=1) -> () |
요청 하나의 페이지를 늘림. cached_block_ids·new_block_ids의 길이가 토큰 수 |
torch.ops.lpu.vmm_map_blocks_batch |
(Tensor[] vmm_tensors, int[] row_indices, int[] cached_block_ids, int[] cached_blocks_per_req, Tensor pool, int[] new_block_ids, int[] new_blocks_per_req, int block_size=1) -> () |
스텝마다 쓰는 배치 형태. new_block_ids는 비우거나 길이를 sum(new_blocks_per_req)로 |
torch.ops.lpu.vmm_unmap_blocks |
(Tensor[] vmm_tensors, int row_index, int[] block_ids, int block_size=1, int block_offset=-1) -> () |
요청 하나의 페이지 반환. block_ids의 길이가 토큰 수 |
torch.ops.lpu.vmm_unmap_blocks_batch |
(Tensor[] vmm_tensors, int[] row_indices, int[] block_ids, int[] blocks_per_req, int block_size=1, int[] block_offsets=[]) -> () |
배치 반환. 풀을 받지 않음 |
map/unmap 연산은 런타임 HaVmmMapBlocksBatchFromPool / HaVmmUnmapBlocksBatchFromPool을
호출합니다.
| 인자 | 의미 |
|---|---|
vmm_tensors |
vmm_reserve가 반환한 [key, value] |
row_indices / row_index |
요청 슬롯 행 0–1023. 필수 |
cached_blocks_per_req |
이미 매핑된 토큰 수 |
new_blocks_per_req |
새로 늘릴 토큰 수 |
new_block_ids, cached_block_ids, unmap block_ids |
값은 쓰이지 않음. 단일 연산(vmm_map_blocks, vmm_unmap_blocks)에서는 길이가 토큰 수이고, 배치 연산에서는 길이를 개수의 합과 맞추거나 비워 둠 |
pool |
vmm_create_kv_pool로 만든 풀 텐서를 넘김. 현재 엔지니어링 샘플에서는 페이지가 vmm_init_blocks에 등록한 풀에서 할당됨 |
block_size |
1만 허용 |
unmap blocks_per_req |
요청에 매핑된 토큰 수 전체. 요청 단위로 한 번에 반환 |
unmap block_offsets / block_offset |
쓰이지 않음 |
map은 토큰 수의 차이로 필요한 KEY·VALUE 페이지만 추가합니다. 매 스텝 정확한 "이미 매핑된 토큰 수"를 넘기십시오.
예제¶
torch.ops.lpu.vmm_create_kv_pool¶
KEY와 VALUE를 함께 담는 풀을 만듭니다. 매핑된 요청이 남아 있는 동안 풀 텐서를 유지하십시오.
예제
1 2 3 4 5 6 7 | |
torch.ops.lpu.vmm_deinit¶
모든 요청을 반환하고 풀을 놓은 뒤 디바이스의 VMM 상태를 정리합니다.
예제
1 2 3 4 5 | |
torch.ops.lpu.vmm_init_blocks¶
예약과 풀 생성 뒤, 풀로 디바이스의 VMM 상태를 만듭니다.
예제
1 2 3 4 5 | |
torch.ops.lpu.vmm_kv_cost_table¶
요청의 토큰 수별 단위 수를 표로 받아, 요청들이 풀에 들어가는지 확인합니다.
예제
1 2 3 4 5 | |
torch.ops.lpu.vmm_kv_pool_bytes¶
메모리 예산 안에서 풀 크기를 정합니다.
예제
1 2 3 4 5 | |
torch.ops.lpu.vmm_kv_pool_units¶
풀이 담는 단위 수를 구합니다. 예제는 vmm_kv_cost_table을 보십시오.
torch.ops.lpu.vmm_map_blocks¶
요청 하나의 토큰을 늘립니다. 인자 길이가 토큰 수를 뜻합니다.
예제
1 2 3 4 | |
torch.ops.lpu.vmm_map_blocks_batch¶
스케줄러 스텝 하나의 매핑을 한 번에 처리합니다.
예제
1 2 3 4 | |
torch.ops.lpu.vmm_reserve¶
KEY와 VALUE 주소 텐서를 각각 만듭니다. 물리 메모리는 붙지 않습니다.
예제
1 2 3 4 5 6 7 8 | |
torch.ops.lpu.vmm_unmap_blocks¶
요청 하나의 페이지를 반환합니다. block_ids의 길이가 토큰 수입니다.
예제
1 2 3 4 | |
torch.ops.lpu.vmm_unmap_blocks_batch¶
끝난 요청의 페이지를 한 번에 반환합니다.
예제
1 2 3 4 | |
함께 보기¶
- Paged KV 캐시 — 호출 순서와 vLLM 흐름
- 런타임 메모리 모델 §3.7 —
HaVmm*진입점 - 커스텀 연산
- 디바이스 API
- 환경 변수