양자화 기여 가이드

SGLang에서 양자화 지원을 추가하거나 리팩터링하는 방법을 설명할게요. AWQ, GPTQ, compressed-tensors, ModelSlim, Quark 같은 weight-only·weight-activation 양자화 방법과 관련 백엔드 커널이 공통으로 쓰는 구조를 중심으로 다뤄요.

출처: 양자화 기여 가이드

설계 목표

양자화 코드에서 양자화 포맷의 의미론과 하드웨어별 실행을 분리해 두는 게 핵심이에요. 그래야 새 포맷을 추가하기 쉽고, 포맷 간에 커널을 재사용할 수 있으며, 플랫폼별 변경을 독립적으로 리뷰할 수 있어요.

양자화 수정에서 제안한 아키텍처를 따라요.

Config: 모델·런타임 양자화 파라미터를 파싱하고, 지원 옵션을 검증하며, 적절한 스킴을 선택해요.
Scheme: Linear·MoE·embedding 등의 모듈 타입에 대한 양자화 가중치 생성, 가중치 로딩, 후처리, 양자화 레이어 배선을 담당해요.
Backend kernel: GPU(CUDA/HIP/XPU), NPU, 또는 다른 백엔드에 대한 하드웨어별 실행, 레이아웃 변환, 커널 선택, 커널 호출을 감싸요.

config 파싱, 가중치 로딩, 백엔드 커널 호출을 하나의 모놀리식 파일에 넣는 건 피하세요. 한 방법이 여러 포맷이나 백엔드를 지원해야 한다면 python/sglang/srt/layers/quantization/<method>/ 아래에 패키지를 만들고, 스킴을 schemes/로 나누세요.

권장 파일 레이아웃

여러 스킴이나 백엔드별 실행 경로를 가진 양자화 방법에서는 이 레이아웃을 쓰세요.

python/sglang/srt/layers/quantization/<method>/
  __init__.py
  <method>.py
  schemes/
    __init__.py
    <method>_scheme.py
    <method>_linear.py
    <method>_moe.py
    <method>_<variant>.py

백엔드 커널은 대상 하드웨어 백엔드 아래에 두세요.

python/sglang/srt/hardware_backend/gpu/quantization/<method>_kernels.py
python/sglang/srt/hardware_backend/npu/quantization/<method>_kernels.py

공유 메서드 선택은 양자화 패키지에 두고, 백엔드 import는 좁게 유지하세요. 그래야 순환 import를 막고, 대상이 아닌 플랫폼이 없는 커널 의존성을 import하지 않게 돼요.

양자화 방법 추가 또는 리팩터링하기

config 엔트리 포인트를 정의하고, 필요하면 python/sglang/srt/layers/quantization/__init__.py를 통해 등록하세요.
get_linear_scheme, get_moe_scheme 같은 명시적 스킴 선택 헬퍼를 추가하세요.
레이어별 가중치 생성과 가중치 로딩을 스킴 클래스로 옮기세요.
GPU(CUDA/HIP/XPU), NPU, 또는 다른 하드웨어 커널 호출을 백엔드 커널 모듈로 옮기세요.
Linear·MoE·embedding·비선형 모듈 처리를 명시적으로 유지하세요. 다른 의미론이 필요한 모듈 타입에 Linear 양자화 방법을 할당하지 마세요.
기존 양자화 체크포인트와 런타임 플래그에 대한 호환성을 유지하세요.
변경이 닿는 config 파싱과 실행 경로를 모두 커버하는 테스트를 추가하세요.

예시는 AWQ와 GPTQ 리팩터를 참고하세요.

PR #21126: AWQ 스킴, 가중치 초기화, 백엔드 커널 호출을 분리해요.
PR #26402: GPTQ에 동일한 스킴/커널 분리를 적용해요.

테스트와 검증

양자화 변경은 정확도와 성능에 모두 영향을 줄 수 있어요. 변경의 영향 범위(blast radius)에 맞는 검증을 포함하세요.

Python-only 구조 변경의 경우:

ruff check <changed-python-files>
git diff --check

양자화 모델 동작의 경우:

건드린 각 양자화 방법에 대해 대표 모델을 최소 하나 실행하세요.
/generate 요청을 보내 출력 경로가 성공하는지 확인하세요.
변경이 수치에 영향을 줄 수 있다면 정확도 스모크 테스트를 돌리세요.
변경이 커널 호출·레이아웃 변환·디스패치에 영향을 준다면 warmup을 고려한 벤치마크 결과를 포함하세요.

백엔드별 변경의 경우:

GPU 변경은 지원되는 GPU 환경(NVIDIA, AMD, Intel)에서 검증하세요.
NPU 변경은 지원되는 Ascend 환경에서 검증하세요.
PR 설명에 정확한 모델, 양자화 플래그, 백엔드 플래그, 하드웨어, 사용한 명령을 포함하세요.

PR 체크리스트

리뷰를 요청하기 전에 PR 설명에 다음이 포함되어 있는지 확인하세요.

변경된 양자화 방법과 백엔드 경로
PR이 따르는 이슈, 설계 제안, 로드맵 항목
기존 체크포인트·플래그에 대한 호환성 참고 사항
모델 출력이 바뀔 수 있는 경우의 정확도 결과
런타임 성능이 바뀔 수 있는 경우의 벤치마크·프로파일링 결과
실행한 정확한 로컬 검사와 모델 실행 테스트

소스 세팅, 포맷팅, 단위 테스트, CI 트리거, 리뷰 절차 세부 사항은 일반 기여 가이드를 사용하세요.

양자화 기여 가이드