콘텐츠로 이동

8. 가중치 변환

LPU 커널은 체크포인트의 가중치를 그대로 읽지 않습니다. 가중치는 대상 아키텍처가 정한 바이트 레이아웃으로 변환한 뒤 디바이스 메모리에 올려야 하며, 이 변환을 Weight Converter API가 담당합니다. 이 장은 변환이 필요한 이유, 입력을 준비하는 규약, 변환 결과를 디바이스로 옮기는 흐름을 다룹니다.

Contents

Section Objective
8.1 변환이 필요한 이유 체크포인트 레이아웃과 디바이스 레이아웃의 차이
8.2 사용 경로 직접 호출이 필요한 경우와 아닌 경우
8.3 변환 흐름 크기 조회부터 디바이스 배치까지
8.4 입력 텐서 규약 형상, 데이터 배치, 메타데이터 텐서
8.5 양자화 방식과 아키텍처 방식별 필요 텐서와 아키텍처별 지원 범위
8.6 메모리와 에러 처리 호스트 메모리 사용과 실패 분류

8.1 변환이 필요한 이유

LPU의 행렬 연산 커널은 가중치를 출력 채널 그룹 단위로 묶어 DRAM 라인에 정렬된 형태로 읽습니다. bias, scale, zero-point 같은 양자화 메타데이터도 각 그룹 옆에 정해진 순서로 놓여 있어야 합니다. 그룹 크기, 정렬 단위, 메타데이터 배치는 아키텍처마다 다릅니다.

변환 결과는 해당 아키텍처의 커널만 해석할 수 있는 불투명한 바이트 버퍼입니다. 버퍼 내용을 직접 읽거나 고치지 말고, 다른 아키텍처용으로 변환한 버퍼를 재사용하지 마십시오. 아키텍처를 잘못 지정하면 크기와 위치는 맞아 보이지만 커널이 에러 없이 잘못된 결과를 냅니다.

8.2 사용 경로

대부분의 사용자는 Weight Converter API를 직접 호출하지 않습니다.

사용 환경 변환 경로
vLLM HyperAccel 체크포인트 변환 도구(python -m vllm_hyperaccel.tools.convert_checkpoint)가 양자화된 가중치를 미리 변환해 저장합니다(양자화 참고). 직접 호출할 필요가 없습니다.
PyTorch(torch_ha) torch.ops.lpu.quant_weight_pack()이 PyTorch 텐서를 받아 변환합니다. 대상 아키텍처를 생략하면 현재 디바이스에 맞춰 변환합니다.
런타임 직접 통합 C++ HaWeightConvert() 또는 Python hart.weight_converter.convert()를 호출합니다.

이 장의 나머지는 세 번째 경우, 즉 런타임 API로 직접 통합하는 경우를 기준으로 설명합니다.

8.3 변환 흐름

변환은 디바이스와 무관하게 호스트에서만 수행됩니다. 핸들이나 상태가 없어서 각 호출이 독립적으로 동작합니다.

  1. 입력 텐서 준비 — 가중치와 필요한 메타데이터를 각각 HaWeightTensor로 감쌉니다(입력 텐서 규약 참고).
  2. 크기 조회 — HaWeightGetConvertedSize()로 변환 결과의 바이트 수를 얻습니다.
  3. 변환 — 그 크기 이상의 호스트 버퍼를 할당하고 HaWeightConvert()를 호출합니다. 변환기는 이 버퍼에 직접 기록하며 중간 복사본을 만들지 않습니다.
  4. 디바이스 배치 — 변환된 버퍼를 디바이스 메모리로 복사합니다. 이후 커널은 이 디바이스 버퍼를 가중치 인자로 받습니다.

호스트에서의 가중치 변환과 디바이스 배치

호스트에서 변환한 뒤 디바이스로 복사하는 흐름 (C++ API 기준)

Python의 convert()는 2단계와 3단계를 한 번에 처리하고 결과를 NumPy 배열로 돌려줍니다.

channel_wise_packing은 변환 결과를 DRAM 채널별로 미리 나눠 담을지 정합니다. 결과를 담을 디바이스 텐서의 레이아웃 종류가 이 값과 맞아야 합니다.

channel_wise_packing 디바이스 텐서 레이아웃
true (Python 기본값) HaTensorKind::SinglePassInterleaved
false HaTensorKind::DramWordInterleaved

레이아웃 종류는 Types API의 HaTensorKind와 메모리 모델을 참고하십시오.

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

# w: [in_features, out_features] row-major uint8 array
weight = Tensor(w.reshape(-1), Shape(1, 1, in_features, out_features), DataType.UINT8, TensorType.Weight)
per_out = Shape(1, 1, 1, out_features)
scale = Tensor(scale_f32, per_out, DataType.FP32, TensorType.Scale)
wzp = Tensor(wzp_u8, per_out, DataType.UINT8, TensorType.WZP)
ozp = Tensor(ozp_u8, per_out, DataType.UINT8, TensorType.OZP)

cfg = WeightConverterConfig(ArchitectureType.EVT1, QuantType.OutputChannelQuant)
blob = convert(cfg, weight, None, scale, None, wzp, ozp, output_data_type=DataType.UINT8)
# blob: 1-D uint8 array, ready to copy to the device
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
#include "ha_weight_converter.h"

// w: [in_features, out_features] row-major uint8 buffer
HaWeightTensor weight(w, HaWeightShape(1, 1, in_features, out_features), HaWeightDataType::kUint8,
                      HaWeightTensorType::kWeight);
HaWeightShape per_out(1, 1, 1, out_features);
HaWeightTensor scale(scale_f32, per_out, HaWeightDataType::kFp32, HaWeightTensorType::kScale);
HaWeightTensor wzp(wzp_u8, per_out, HaWeightDataType::kUint8, HaWeightTensorType::kWzp);
HaWeightTensor ozp(ozp_u8, per_out, HaWeightDataType::kUint8, HaWeightTensorType::kOzp);

HaWeightConfig cfg{HaWeightArchitectureType::kEvt1, HaWeightQuantType::kOutputChannelQuant};

uint64_t size = 0;
HaWeightGetConvertedSize(&cfg, &weight, nullptr, HaWeightDataType::kUint8, &size);

std::vector<uint8_t> blob(size);
HaError err = HaWeightConvert(&cfg, &weight, nullptr, &scale, nullptr, &wzp, &ozp, HaWeightDataType::kUint8,
                              /*channel_wise_packing=*/true, blob.data(), blob.size());

8.4 입력 텐서 규약

가중치 형상과 데이터 배치

가중치 형상은 HaWeightShape(r, s, c, m)의 4차원으로 기술합니다. c는 입력 채널 수, m은 출력 채널 수입니다. Linear 레이어처럼 2차원인 가중치는 (1, 1, in_features, out_features)로 지정합니다.

변환기는 가중치 데이터를 이 형상의 행 우선(row-major) 연속 버퍼로 읽습니다. 즉 2차원 가중치는 [in_features, out_features] 순서여야 합니다.

체크포인트 가중치는 전치가 필요할 수 있습니다

PyTorch nn.Linear를 비롯한 많은 체크포인트는 가중치를 [out_features, in_features]로 저장합니다. 이 순서 그대로 넘기면 원소 수가 같아서 에러 없이 변환되지만, 결과는 다른 행렬의 레이아웃이 됩니다. 변환 전에 전치하여 연속 버퍼로 만드십시오.

4비트 타입(kUint4, kSint4, kFp4, kMxfp4)은 한 바이트에 두 원소를 담은 패킹 버퍼를 넘깁니다.

메타데이터 텐서

메타데이터 텐서는 가중치의 출력 채널 수 m을 기준으로 형상을 정합니다.

텐서 형상 데이터 타입
bias (1, 1, 1, m) kFp32
scale, WZP (kOutputChannelQuant) (1, 1, 1, m) scale kFp32, WZP는 가중치와 같은 정수 타입
scale, WZP (kInputChannelWiseQuant) (1, 1, groups, m) 위와 같음
OZP (1, 1, 1, m) 출력과 같은 정수 타입(kUint8·kSint8)

groups는 입력 채널 그룹 수로, r * s * c를 input_channel_group_size로 나눠 올림한 값입니다.

각 메타데이터의 의미는 다음과 같습니다.

  • scale은 가중치 scale만이 아니라 가중치 scale × 입력 scale / 출력 scale을 합친 값입니다. 입력이나 출력이 양자화되어 있으면 그 scale까지 반영해 넘기십시오.
  • WZP(weight zero-point)는 가중치가 정수 타입일 때만 의미가 있으며, 가중치와 같은 정밀도로 넘깁니다. FP8·FP4처럼 부동소수점 가중치에는 넘기지 않아도 됩니다.
  • OZP(output zero-point)는 출력이 정수 타입일 때만 필요하며, 출력과 같은 정밀도로 넘깁니다.

메타데이터 버퍼 길이는 검사되지 않습니다

변환기는 메타데이터 텐서의 길이를 선언한 형상으로만 판단하며, 실제 버퍼 크기와 대조하지 않습니다. 버퍼가 형상보다 짧으면 버퍼 끝을 넘어 읽습니다. 형상과 실제 버퍼 길이가 일치하는지 호출 전에 확인하십시오.

출력 데이터 타입

output_data_type은 변환된 가중치를 사용하는 행렬 연산이 내놓을 출력의 데이터 타입입니다. 변환된 가중치의 타입이 아닙니다. 출력으로 쓸 수 있는 타입은 kFp32, kBf16, kFp8, kUint8, kSint8입니다. 양자화 방식이 kNone이 아니고 출력이 정수 타입이면 OZP 텐서가 필요합니다.

8.5 양자화 방식과 아키텍처

양자화 방식 필요한 텐서 Cloud EVT0 Cloud EVT1 Edge EVT0
kNone 가중치 ✅ ✅ ✅
kOutputChannelQuant 가중치, scale, WZP(정수 가중치) ✅ ✅ ✅
kInputChannelWiseQuant 가중치, scale, WZP(정수 가중치) ✅ ✅ ✅
kMxfpQuant 가중치, scale, MX scale ❌ ✅ ✅
kTokenWiseQuant — ❌ ❌ ❌

정수 출력에는 위 표와 별도로 OZP가 필요합니다(입력 텐서 규약 참고). bias는 모든 방식에서 선택 사항입니다.

가중치 타입에 따라 쓰는 양자화 방식이 정해집니다. 16비트(kBf16) 가중치는 양자화 정보 없이 kNone으로 변환하고, 8비트·4비트 가중치는 kOutputChannelQuant 또는 kInputChannelWiseQuant로, MXFP 가중치(kMxfp8·kMxfp4)는 kMxfpQuant로 변환합니다.

kInputChannelWiseQuant의 input_channel_group_size는 128(Cloud EVT0·EVT1) 또는 64(Edge EVT0)의 배수여야 합니다. kMxfpQuant는 이 값을 무시하고 아키텍처가 정한 그룹 크기를 사용합니다.

8.6 메모리와 에러 처리

변환에 쓰이는 호스트 메모리 일부는 런타임의 호스트 메모리 관리자에서 할당되며 HA_HOST_MEM_MAX_BYTES 한도에 포함됩니다.

  • HaWeightTensor::CopyOf()와 Python Tensor가 보관하는 입력 복사본
  • Python convert()가 반환하는 결과 배열

큰 모델을 한 프로세스에서 변환할 때는 사용이 끝난 입력 텐서와 결과 배열을 바로 해제하십시오. 한도에 대해서는 환경 변수를 참고하십시오.

C++ 변환 함수는 다른 런타임 API와 같이 HaError를 반환합니다. Python에서는 같은 실패가 RuntimeError로 나타납니다.

에러 코드 주요 원인
HaInvalidArgument 필수 텐서 누락, 버퍼 크기 부족, input_channel_group_size 제약 위반
HaNotSupported 대상 아키텍처가 지원하지 않는 양자화 방식
HaInternalError 지원하지 않는 데이터 타입 조합 등 그 밖의 변환 실패

HaWeightTensor의 생성자는 예외입니다. 인자가 잘못되면(널 포인터, 0인 차원, 텐서 역할에 맞지 않는 데이터 타입) HaError를 반환하지 않고 std::runtime_error를 던지므로, 텐서는 변환 함수를 호출하기 전에 만들어 두십시오.


다음 단계