콘텐츠로 이동

Python Memory API

함수 시그니처 비고
mem_alloc (size: int, is_interleaved: bool = False) -> int 디바이스 주소를 반환
mem_alloc_3d (shape: HaShape, is_interleaved: bool = False) -> int
mem_alloc_async (size: int, is_interleaved: bool = False, stream: int = HA_STREAM_DEFAULT) -> int 호스트에서 접근하려면 먼저 동기화 필요
mem_free (ptr: int \| None) -> None None은 무동작
mem_free_async (ptr: int, stream: int = HA_STREAM_DEFAULT) -> None 호출 후 ptr을 사용하지 말 것
mem_cpy (dst: int \| bytes, src: int \| bytes, size: int, direction: HaMemCpyDirection) -> None 완료까지 블로킹
mem_cpy_async (dst: int \| bytes, src: int \| bytes, size: int, direction: HaMemCpyDirection, stream: int = HA_STREAM_DEFAULT) -> None 큐잉만 수행
mem_cpy_nd (dst: int, dst_layout: HaLayout, src: int, src_layout: HaLayout) -> None 방향은 레이아웃 scope에서 유추
mem_cpy_nd_async (dst: int, dst_layout: HaLayout, src: int, src_layout: HaLayout, stream: int = HA_STREAM_DEFAULT) -> None 큐잉만 수행. 호스트 피연산자는 stream_synchronize()까지 유지해야 하며, stream의 디바이스가 디바이스 피연산자를 소유해야 함
mem_load_file_async (file_fd: int, file_off: int, dst: int, len: int, stream: int = HA_STREAM_DEFAULT) -> None 파일 디스크립터에서 디바이스 메모리로 직접 읽음
dump_for_each_channel (start: int, bytes_total: int) -> list[bytes] DRAM 채널당 버퍼 하나, 디인터리브하지 않음
host_mem_alloc (size: int) -> int 호스트 메모리 관리자에서 할당. 64바이트 정렬 주소를 int로 반환. 디바이스 불필요
host_mem_free (ptr: int) -> None host_mem_alloc 할당분 해제(재사용을 위해 풀에 보관). 0은 무동작
host_mem_get_stats () -> dict[str, int] 프로세스 호스트 메모리 통계. 키는 allocated_bytes, peak_allocated_bytes, reserved_bytes, peak_reserved_bytes, alloc_count, free_count
host_mem_reset_peak_stats () -> None 통계의 최대값 두 개를 현재 값으로 초기화
host_mem_trim () -> None 풀에 보관 중인 해제된 호스트 메모리를 OS에 반환
device_mem_get_stats () -> dict[str, int] 현재 디바이스의 메모리 통계. 키는 HaDeviceMemStats의 필드 이름(struct_size, reserved0 제외)
device_mem_reset_peak_stats () -> None 현재 디바이스 통계의 모든 최대값을 현재 값으로 초기화
device_mem_trim () -> None 현재 디바이스 풀에서 할당된 블록이 없는 세그먼트를 드라이버에 반환
build_device_tensor_layout (kind: HaTensorKind, dtype: HaDataType, dims: list[int], strides: list[int] = []) -> HaLayout 먼저 set_device() 필요

호스트 버퍼는 bytes 또는 버퍼 프로토콜을 구현한 객체로 전달하며, 바인딩이 원시 포인터를 추출합니다.

host_mem_alloc()은 크기가 0이거나 HA_HOST_MEM_MAX_BYTES 한도(HaHostMemLimitExceeded) 또는 시스템이 거부하면 RuntimeError를 발생시킵니다. host_mem_free()에 살아 있는 host_mem_alloc() 할당이 아닌 주소를 넘겨도 RuntimeError가 발생합니다. 대응하는 C++ API는 Memory API를 참고하십시오.

device_mem_get_stats()의 키는 total_bytes, free_bytes, releasable_bytes, allocated_bytes, peak_allocated_bytes, reserved_bytes, peak_reserved_bytes, requested_bytes, peak_requested_bytes, cached_free_bytes, active_blocks, peak_active_blocks, segments, peak_segments, device_allocs, device_frees입니다. 바이트 값은 모든 DRAM 채널을 합한 값이며, free_bytes는 드라이버가 보고하는 디바이스 전체의 여유 DRAM입니다. HA_DEVICE_MEM_STATS_PRINT=1이면 표준 에러에도 출력합니다. device_mem_trim()을 호출하기 전에 비동기 해제(mem_free_async())한 메모리는 해당 스트림을 동기화해야 풀로 돌아와 반환 대상이 됩니다. 대응하는 C++ API는 Memory API를 참고하십시오.


예제

build_device_tensor_layout

dims의 의미는 텐서 종류마다 다릅니다. KV 캐시 키는 정확히 5차원입니다.

예제
1
2
3
4
5
6
7
8
9
import hart

hart.set_device(0)  # 플랫폼 상수를 현재 디바이스에서 읽음

layout = hart.build_device_tensor_layout(
    hart.HaTensorKind.KV_CACHE_KEY,
    hart.HaDataType.BFLOAT16,
    [num_blocks, num_layers, num_kv_heads, block_size, head_dim],
)

dump_for_each_channel

DRAM 채널별 원시 바이트. 디버깅용이며 데이터 경로가 아닙니다.

예제
1
2
3
4
import hart

channels = hart.dump_for_each_channel(start, bytes_total)
print([len(c) for c in channels])  # 전체를 동기 전송 -- 데이터 경로가 아님

mem_alloc

디바이스 주소를 int로 돌려줍니다. 호스트 포인터가 아닙니다.

예제
1
2
3
4
5
6
7
import hart

hart.set_device(0)
buf = hart.mem_alloc(1024)                       # DRAM 채널 하나
spread = hart.mem_alloc(1024, is_interleaved=True)  # 채널에 분산

hart.mem_free(buf)

mem_alloc_3d

바이트 수가 아니라 shape으로 크기를 정하는 텐서 할당입니다.

예제
1
2
3
import hart

tensor = hart.mem_alloc_3d(hart.HaShape(width, height, channels), is_interleaved=True)

mem_alloc_async

바로 큐잉에 쓸 수 있지만, 스트림이 그 지점에 닿기 전까지 호스트에서 접근할 수 없습니다.

예제
1
2
3
4
5
6
7
import hart

scratch = hart.mem_alloc_async(size, False, stream)
args = hart.HaLaunchArgs()
args.add_tensor(hart.HaLaunchArgRoute.UNIVERSAL, -1, scratch, [size])
hart.launch_kernel_async_with_binary_path(kernel_path, args, stream)
hart.stream_synchronize(stream)  # 여기서부터 호스트가 읽을 수 있음

mem_cpy

양쪽 모두 디바이스 주소이거나 bytes이고, 어느 쪽이 호스트인지는 direction이 정합니다.

예제
1
2
3
4
5
6
7
import hart

payload = b"\x00" * 1024
hart.mem_cpy(buf, payload, len(payload), hart.HaMemCpyDirection.HostToDevice)

out = bytearray(1024)
hart.mem_cpy(out, buf, len(out), hart.HaMemCpyDirection.DeviceToHost)

mem_cpy_async

반환했다고 복사가 시작된 것은 아닙니다.

예제
1
2
3
4
import hart

hart.mem_cpy_async(buf, payload, len(payload), hart.HaMemCpyDirection.HostToDevice, stream)
hart.stream_synchronize(stream)  # 이 전에 payload를 건드리지 말 것

mem_cpy_nd

방향은 인자가 아니라 레이아웃의 scope에서 나옵니다.

이 API는 브로드캐스트하지 않으므로 두 레이아웃의 rank와 shape이 같아야 합니다. stride 단위는 바이트가 아니라 원소이고, 틀리면 예외 없이 잘못된 주소를 읽습니다.

예제
1
2
3
4
5
6
7
import hart

bf16 = hart.HaDataType.BFLOAT16
dev_layout = hart.HaLayout([rows, cols], scope=hart.HaMemScope.DEVICE, dtype=bf16)
# 열 우선으로 놓인 호스트 버퍼. stride는 원소 단위
host_layout = hart.HaLayout([rows, cols], strides=[1, rows], scope=hart.HaMemScope.HOST, dtype=bf16)
hart.mem_cpy_nd(dev_ptr, dev_layout, host_ptr, host_layout)  # scope로 보아 호스트 -> 디바이스

mem_free

블록은 런타임 풀로 돌아가 이후 할당에 다시 쓰입니다. 해제로 빈 세그먼트가 생겨도 조건에 따라 풀에 보관되므로, 해제만으로는 디바이스 메모리 사용량이 줄지 않을 수 있습니다. 보관된 빈 세그먼트는 device_mem_trim()으로 반환합니다. 조건은 메모리 모델을 참고하십시오.

예제
1
2
3
4
import hart

hart.mem_free(buf)
hart.mem_free(None)  # 무동작이라 정리 경로에 방어가 필요 없음

mem_free_async

해제는 지연되지만 포인터에 대한 권한은 호출 시점에 끝납니다.

동기화 여부와 무관하게 이 호출 이후로는 scratch를 쓸 수 없습니다.

예제
1
2
3
import hart

hart.mem_free_async(scratch, stream)

mem_load_file_async

호스트 버퍼를 거치지 않고 파일 디스크립터에서 디바이스 메모리로 바로 읽습니다.

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

import hart

fd = os.open(weights_path, os.O_RDONLY)
hart.mem_load_file_async(fd, file_offset, dev_weights, length, stream)
hart.stream_synchronize(stream)
os.close(fd)

함께 보기