rad-convert는 Hugging Face 체크포인트(.gguf, .safetensors, 인덱스, 디렉터리)를 받아 .rad 컨테이너 하나를 만든다. 입력 텐서는 아키텍처 플러그인이 그래프의 가중치로 매핑하고, 모든 op가 해석되고, 각 커널에 "이 가중치 인코딩을 읽을 수 있나"가 물어보진 뒤, 각 가중치를 인코딩의 평면으로 한 번 쓴다. 토크나이저와 채팅 템플릿도 같이 들어간다. Docker 안에서는 --entrypoint rad-convert로, 이미지 안 레시피는 /opt/radiance/share/radiance/recipes/에 있다.

rad-convert 개요

rad-convert /srv/models/Qwen/Qwen3.8-27B-FP8 -o /srv/models/rad/q38-27b-fp8.rad --home $RADIANCE_HOME

레시피가 없으면 모든 가중치가 체크포인트의 인코딩을 그대로 유지한다 — bf16이나 블록 fp8 체크포인트를 자기 정밀도로 서빙할 때는 레시피가 필요 없다. 4비트 expert처럼 양자화가 필요하면 레시피가 무엇과 어떻게를 정한다. 변환 후 양자화된 가중치는 전부 원본과 비교되어 가장 나쁜 것들이 인쇄된다.

인자가 헷갈리면 쓰기 전에 계획을 보는 게 싸다: --plan은 아무것도 쓰지 않고 계획만 출력한다.

레시피: 무엇이 어떻게 양자화되는가

레시피는 PATTERN QUANTISER OPTIONS 줄의 덩어리다. 가중치 이름 패턴에서 첫 일치로 결정된다. Flash-Next 레시피 일부:

# data/recipes/qwen4exp-w4.recipe (발췌)
blk.*.ffn_*_exps.*.weight   rtn  codes=i4 group=128 scale=bf16 transform=fwht128
blk.*.attn_qg.weight        rtn  codes=fp8_e4m3 block=128x128 scale=bf16
output.weight               rtn  codes=fp8_e4m3 block=128x128 scale=bf16

rtn은 round-to-nearest, group/block은 스케일 간격, transform은 Hadamard 회전이다. 양자화기는 플러그인이므로 커스텀 양자화도 레시피로 들어온다(IQR, GPTQ 등). 보정(GPTQ)이 필요한 레시피는 $CALIB처럼 환경변수에서 디렉터리를 펼쳐 받는다 — 예: CALIB=DIR rad-convert ... --recipe qwen4exp-w4nl64-i8-hc8m.recipe. 어떤 값을 담아야 하는지는 레시피 헤더와 MOE-W4.md에 적혀 있다.

실전 변환 명령

README와 GUIDE §3.2에서 범주별로 뽑은 예들이다.

# bf16 그대로: 레시피 불필요 (체크포인트의 가중치·토크나이저·채팅 템플릿 사용)
build/bin/rad-convert /srv/models/hf/XHToken-Spark-X2.6-4B -o spark-x2.6-4b-bf16.rad --max-ctx 4096

# bf16 체크포인트를 블록 fp8로: 레시피가 linear를 쓰고 --set이 포맷을 선언해 fp8 플러그인을 고른다
build/bin/rad-convert /srv/models/hf/Qwen/Qwen3.8-27B -o qwen3.8-27b-bf16.rad \
    --recipe data/recipes/q38-27b-bf16.recipe

# Gemma 4 31B: GPTQ 양자화 + 어시스턴트 헤더를 MTP drafter로
build/bin/rad-convert /srv/models/hf/google/gemma-4-31B-it -o gemma4-31b-w4a8.rad \
    --recipe data/recipes/gemma4-31b-dense-bf16-w4a8.recipe \
    --set quantization_config.quant_method=compressed-tensors \
    --draft-model /srv/models/hf/google/gemma-4-31B-it-assistant

# ParoQuant int4(학습된 회전 유지) + DFlash2 drafter
build/bin/rad-convert /srv/models/hf/z-lab/Qwen3.8-27B-PARO -o qwen3.8-27b-paro-int4.rad \
    --recipe data/recipes/q38-27b-paro-mxfp4-df2.recipe \
    --draft-model /srv/models/hf/z-lab/Qwen3.8-27B-DFlash2

# 단일 파일 SDXL(Illustrious 등): 체크포인트는 safetensors 하나, 토크나이저를 별도로 줌
build/bin/rad-convert /srv/models/hf/OnomaAIResearch/Illustrious-XL-v2.0/Illustrious-XL-v2.0.safetensors \
    -o illustrious-xl-v2.0-bf16.rad --recipe data/recipes/sdxl-bf16.recipe \
    --tokenizer /srv/models/hf/openai/clip-vit-large-patch14/tokenizer.json

이미지·비디오·오디오 모델은 diffusers 파이프라인 디렉터리 전체가 체크포인트다(텍스트 인코더, DiT, VAE/보코더, 토크나이저). GUIDE §3.2에 Qwen-Image, Krea 2, LTX-2.5, MiniMax-Music3, Breeze-TTS-2, drama-3 등의 레시피별 예가 레시피 이름과 함께 있다.

drafter 병합과 재변환 재사용

• drafter 병합: 따로 공개된 drafter 체크포인트(DSpark, DFlash2)는 --draft-model DIR로 컨테이너에 합친다. 서빙 측 --draft-model은 없고 변환 시에만 있다.
• 재변환 재사용: 기존 컨테이너에서 일부만 다시 양자화할 때는 --reuse <old.rad>로 안 바뀐 텐서를 통째로 복사한다. ParoQuant 컨테이너처럼 포맷이 바뀐 경우에도 "(예전 것을 --reuse로) 다시 변환하라"는 안내가 이때다. --in-place는 기존 컨테이너를 확장한다(예: 비전 타워 추가).
• 규칙 우선순위: 커맨드라인의 --quant 패턴이 레시피 규칙보다 앞에 선다. 예: 레시피는 rtn인데 expert만 GPTQ로.

남이 양자화한 릴리스 다루기

타인이 내온 양자화 릴리스는 세 갈래로 처리된다.

1. 그대로 읽기: 엔진의 커널이 그 형태를 읽으면 변환조차 필요 없다(블록 스케일 fp8, Quark MXFP4). 컨테이너 없이 체크포인트 직접 서빙도 가능하다.
2. 자기 숫자로 쓰기: 커널이 4비트 GEMM 등에서 같은 격자를 다른 철자로 읽는 경우(압축 텐서 AWQ/GPTQ, AutoRound), q38-27b-w4a16.recipe처럼 스토어된 격자를 그대로 살려 쓴다.
3. 정확한 역양자화에서 변환: 아무 커널도 읽지 못하는 형태(NVFP4, AutoRound int4 Flash-Next의 int4 블록 projection)는 역양자화 값에서 MXFP4/int8 커널용으로 변환한다.

결과 확인: rad-info와 KL 검사

변환 후 첫 점검은 rad-info다.

rad-info m.rad              # 컨테이너가 기대한 것과 같은가: 모델, 가중치, 토크나이저, drafter
rad-info --plugins          # 현재 검색 경로가 제공하는 플러그인

시작이 거부되면 rad-kbench --home $RADIANCE_HOME --max-cases 1로 커널 정상성을, radiance --model m.rad --debug-graph로 op 해석을 본다(서버가 안 뜰 때의 3종 세트). 변환 품질을 숫자로 보고 싶으면 rad-convert의 KL 모드 — 원본 대비 양자화 이후의 평균 KL과 top-1 이탈을 재준다(GUIDE §TOOLS의 "The KL mode"; README의 모델별 "mean KL" 수치가 여기서 나왔다). Docker 이미지로 변환만 도는 법은 Docker 글에 있다.