콘텐츠로 이동

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
import torch

pool = torch.ops.lpu.vmm_create_kv_pool(
    num_tokens, num_attn_layers, num_kv_heads, 1, head_dim,
    dtype=torch.bfloat16, device="lpu:0",
)
assert pool.shape == (2, num_tokens, num_attn_layers, num_kv_heads, 1, head_dim)

torch.ops.lpu.vmm_deinit

모든 요청을 반환하고 풀을 놓은 뒤 디바이스의 VMM 상태를 정리합니다.

예제
1
2
3
4
5
import torch

torch.ops.lpu.vmm_unmap_blocks_batch([k, v], live_slots, [], live_tokens)
del pool
torch.ops.lpu.vmm_deinit()

torch.ops.lpu.vmm_init_blocks

예약과 풀 생성 뒤, 풀로 디바이스의 VMM 상태를 만듭니다.

예제
1
2
3
4
5
import torch

torch.ops.lpu.vmm_init_blocks(
    max_num_seqs, 1, num_attn_layers, num_kv_heads, max_model_len, head_dim, 16, pool
)

torch.ops.lpu.vmm_kv_cost_table

요청의 토큰 수별 단위 수를 표로 받아, 요청들이 풀에 들어가는지 확인합니다.

예제
1
2
3
4
5
import torch

costs = torch.ops.lpu.vmm_kv_cost_table(head_dim, torch.bfloat16, max_model_len)
capacity = torch.ops.lpu.vmm_kv_pool_units(head_dim, torch.bfloat16, num_tokens)
fits = sum(costs[n].item() for n in token_counts) <= capacity

torch.ops.lpu.vmm_kv_pool_bytes

메모리 예산 안에서 풀 크기를 정합니다.

예제
1
2
3
4
5
import torch

pool_bytes = torch.ops.lpu.vmm_kv_pool_bytes(
    head_dim, torch.bfloat16, num_attn_layers, num_kv_heads, budget_bytes,
)

torch.ops.lpu.vmm_kv_pool_units

풀이 담는 단위 수를 구합니다. 예제는 vmm_kv_cost_table을 보십시오.


torch.ops.lpu.vmm_map_blocks

요청 하나의 토큰을 늘립니다. 인자 길이가 토큰 수를 뜻합니다.

예제
1
2
3
4
import torch

# 슬롯 3이 토큰 10개에서 12개로 자람
torch.ops.lpu.vmm_map_blocks([k, v], 3, [0] * 10, pool, [0, 0])

torch.ops.lpu.vmm_map_blocks_batch

스케줄러 스텝 하나의 매핑을 한 번에 처리합니다.

예제
1
2
3
4
import torch

# 슬롯 3은 10→12 토큰, 슬롯 7은 새 요청 5 토큰
torch.ops.lpu.vmm_map_blocks_batch([k, v], [3, 7], [], [10, 0], pool, [0] * 7, [2, 5])

torch.ops.lpu.vmm_reserve

KEY와 VALUE 주소 텐서를 각각 만듭니다. 물리 메모리는 붙지 않습니다.

예제
1
2
3
4
5
6
7
8
import torch

k = torch.ops.lpu.vmm_reserve(
    1024, num_attn_layers, num_kv_heads, max_model_len, head_dim, "key", torch.bfloat16
)
v = torch.ops.lpu.vmm_reserve(
    1024, num_attn_layers, num_kv_heads, max_model_len, head_dim, "value", torch.bfloat16
)

torch.ops.lpu.vmm_unmap_blocks

요청 하나의 페이지를 반환합니다. block_ids의 길이가 토큰 수입니다.

예제
1
2
3
4
import torch

# 슬롯 3의 토큰 12개 반환
torch.ops.lpu.vmm_unmap_blocks([k, v], 3, [0] * 12)

torch.ops.lpu.vmm_unmap_blocks_batch

끝난 요청의 페이지를 한 번에 반환합니다.

예제
1
2
3
4
import torch

# 슬롯 5(토큰 300개)와 슬롯 9(토큰 40개) 반환
torch.ops.lpu.vmm_unmap_blocks_batch([k, v], [5, 9], [], [300, 40])

함께 보기