본문으로 건너뛰기

[sglang] sgl-kernel Wheel METADATA/WHEEL 태그를 CUDA 파일명과 정렬

PR 링크: sgl-project/sglang#21437 상태: Merged | 변경: +71 / -20

들어가며

Python wheel 패키지에서 파일명의 버전과 내부 METADATA의 Version 필드는 일치해야 합니다. sgl-kernel은 빌드 후 wheel 파일명에 CUDA suffix(예: +cu124)를 추가하는 rename 스크립트를 사용하는데, 기존에는 파일명만 변경하고 내부 메타데이터는 수정하지 않아 pip이 "inconsistent version" 오류를 발생시킬 수 있었습니다.

핵심 코드 분석

1. 기존 방식: 단순 파일명 변경

Before:

intermediate_wheel="${wheel/linux/manylinux2014}"
if [[ $intermediate_wheel =~ -cp([0-9]+)- ]]; then
    cp_version="${BASH_REMATCH[1]}"
fi
if ls /usr/local/ | grep -q "12.4"; then
    new_wheel="${intermediate_wheel/-cp${cp_version}/+cu124-cp${cp_version}}"
fi
mv -- "$wheel" "$new_wheel"

파일명만 sgl_kernel-0.1.0-cp312-...에서 sgl_kernel-0.1.0+cu124-cp312-...로 변경합니다.

2. 개선된 방식: unpack -> patch -> repack

After:

python3 -m wheel unpack "$wheel" --dest "$TMPDIR"
DIST_INFO=$(find "$UNPACKED" -maxdepth 1 -type d -name "*.dist-info")
METADATA_FILE="${DIST_INFO}/METADATA"
WHEEL_META="${DIST_INFO}/WHEEL"

# WHEEL 태그에서 linux_ -> manylinux2014_ 변환
patch_wheel_platform_tags "$WHEEL_META"

# METADATA의 Version 필드에 CUDA suffix 추가
ORIG_VERSION=$(grep '^Version:' "$METADATA_FILE" | head -1 | sed 's/^Version:[[:space:]]*//')
NEW_VERSION="${ORIG_VERSION}${CUDA_SUFFIX}"
sed -i "s/^Version:.*/Version: ${NEW_VERSION}/" "$METADATA_FILE"

# dist-info 디렉토리명도 변경
mv "$DIST_INFO" "${UNPACKED}/${NEW_BASE}"

# RECORD 파일 자동 재생성과 함께 repack
python3 -m wheel pack "$UNPACKED" --dest-dir "$WHEEL_DIR"

wheel unpack -> 메타데이터 수정 -> wheel pack으로 재패킹하면, RECORD 파일(해시 체크섬)이 자동 재생성되어 무결성도 보장됩니다.

3. Platform 태그 수정 함수

patch_wheel_platform_tags() {
    local wheel_file="$1"
    sed -i \
        -e 's/-linux_x86_64$/-manylinux2014_x86_64/' \
        -e 's/-linux_aarch64$/-manylinux2014_aarch64/' \
        "$wheel_file"
}

줄 끝 앵커($)를 사용하여 부분 문자열 매칭(예: manylinux2014_x86_64에서 linux_x86_64가 다시 매칭되는 것)을 방지합니다.

왜 이게 좋은가

  1. pip 호환성: 파일명과 METADATA Version이 일치하여 pip install이 정상 동작합니다.
  2. RECORD 무결성: wheel pack이 자동으로 RECORD를 재생성하여 수동 편집 실수를 방지합니다.
  3. 멱등성: 이미 suffix가 적용된 wheel은 건너뜁니다.

정리

Python 패키징에서 wheel 파일명과 내부 메타데이터의 일관성은 필수입니다. 파일명만 바꾸는 것이 아니라, unpack-patch-repack 패턴으로 모든 메타데이터를 동기화해야 합니다.

참고 자료

⚠️ 알림: 이 분석은 AI가 실제 코드 diff를 기반으로 작성했습니다.

댓글

관련 포스트

PR Analysis 의 다른글