콘텐츠로 이동

Python Weight Converter API

가중치 텐서를 대상 아키텍처가 디바이스 메모리에서 읽는 바이트 레이아웃으로 변환합니다. 의미는 C++ Weight Converter API와 같습니다. C++ 함수와 1:1로 대응하는 모듈 함수로 제공하며, 디버그용 show()만 Python에 더 있습니다. 타입 이름에는 C++의 HaWeight 접두사가 없습니다 (예: HaWeightTensor → Tensor). 핸들이나 상태가 없으므로 호출은 서로 독립적입니다. 입력 규약과 전체 흐름은 가중치 변환 가이드를 참고하십시오.

1
2
3
4
from hart.weight_converter import (
    WeightConverterConfig, get_converted_size, convert, show,
    ArchitectureType, QuantType, DataType, Shape, Tensor, TensorType,
)

함수

함수 시그니처
get_converted_size (cfg: WeightConverterConfig, weight_tensor: Tensor, bias_tensor: Tensor \| None = None, *, output_data_type: DataType) -> int
convert (cfg: WeightConverterConfig, weight_tensor: Tensor, bias_tensor: Tensor \| None = None, scale_tensor: Tensor \| None = None, mx_scale_tensor: Tensor \| None = None, wzp_tensor: Tensor \| None = None, ozp_tensor: Tensor \| None = None, *, output_data_type: DataType, channel_wise_packing: bool = True) -> numpy.ndarray[numpy.uint8]
show (cfg: WeightConverterConfig, converted_data: buffer, weight_tensor: Tensor, bias_tensor: Tensor \| None = None, *, output_data_type: DataType) -> None

convert()는 크기 조회와 버퍼 할당을 함께 처리하고, 변환 결과를 담은 1차원 uint8 NumPy 배열을 반환합니다. 결과 버퍼는 런타임의 호스트 메모리 관리자에서 할당되며 복사 없이 배열로 노출됩니다. 배열이 해제되면 버퍼도 반환됩니다. 미리 크기만 알아야 할 때는 get_converted_size()를 사용하십시오.

output_data_type과 channel_wise_packing은 키워드 인자로만 전달할 수 있습니다. C++에는 기본값이 없지만 Python에서 channel_wise_packing의 기본값은 True입니다.

show()는 변환 결과를 16진 표로 출력하는 디버그용 함수이며, 대응하는 C++ 공개 API는 없습니다. 디버그 빌드에서만 동작하고, 릴리스 빌드에서는 처음 호출할 때 지원하지 않는다는 경고 로그를 한 번 남길 뿐 아무것도 출력하지 않습니다.


WeightConverterConfig

필드 타입 기본값 설명
arch_type ArchitectureType — 대상 아키텍처
quant_type QuantType QuantType.NONE 양자화 방식
input_channel_group_size int 0 입력 채널 그룹 크기. InputChannelWiseQuant에서만 사용

양자화 방식별로 필요한 텐서, 아키텍처별 지원 범위, input_channel_group_size 제약은 C++ API와 같습니다.


Tensor와 Shape

1
2
Tensor(data, shape: Shape, dtype: DataType, tensor_type: TensorType)
Shape(r: int, s: int, c: int, m: int)

Tensor는 1차원 버퍼(bytes, bytearray, 1차원 NumPy 배열 등 버퍼 프로토콜을 지원하는 객체)를 받아 복사본을 보관합니다. 생성 후 원본 버퍼를 수정하거나 해제해도 텐서에는 영향이 없습니다. 복사본은 런타임의 호스트 메모리 관리자에서 할당되므로 HA_HOST_MEM_MAX_BYTES 한도에 포함됩니다. 다차원 배열은 reshape(-1) 등으로 1차원으로 만든 뒤 전달하십시오.

메서드 반환
get_data() 데이터 버퍼
get_shape() Shape
get_data_type() DataType
get_tensor_type() TensorType
get_size() 바이트 크기

Shape의 r, s, c, m은 각각 행, 열, 입력 채널, 출력 채널 수이며 모두 0보다 커야 합니다. 텐서 역할별로 허용되는 데이터 타입은 C++ API의 Tensor를 참고하십시오.


열거형

C++ 열거형과 값이 같고 이름 표기만 다릅니다.

열거형 값
ArchitectureType EVT0, EVT1, Edge
QuantType NONE, OutputChannelQuant, InputChannelWiseQuant, TokenWiseQuant, MXFPQuant
DataType FP32, BF16, FP8, FP4, UINT8, SINT8, UINT4, SINT4, MXFP8, MXFP4
TensorType Weight, Bias, Scale, MXScale, WZP, OZP

에러 처리

변환 함수가 실패하면 RuntimeError가 발생합니다. 메시지에는 C++ API가 반환한 에러 코드 이름이 들어갑니다 (예: weight_converter: HaNotSupported). Tensor 생성 시 인자가 잘못되면 그 자리에서 RuntimeError가 발생합니다.


예제

예제
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import numpy as np
from hart.weight_converter import (
    WeightConverterConfig, convert,
    ArchitectureType, QuantType, DataType, Shape, Tensor, TensorType,
)

shape = Shape(1, 1, in_features, out_features)
weight = Tensor(w_u8.reshape(-1), shape, DataType.UINT8, TensorType.Weight)
scale = Tensor(scale_f32, Shape(1, 1, 1, out_features), DataType.FP32, TensorType.Scale)
wzp = Tensor(wzp_u8, Shape(1, 1, 1, out_features), DataType.UINT8, TensorType.WZP)
ozp = Tensor(ozp_u8, Shape(1, 1, 1, out_features), DataType.UINT8, TensorType.OZP)

cfg = WeightConverterConfig(arch_type=ArchitectureType.EVT1,
                            quant_type=QuantType.OutputChannelQuant)
buf = convert(cfg, weight, None, scale, None, wzp, ozp, output_data_type=DataType.UINT8)