카드는 준비됐고 빌드도 됐으니, 이제 모델을 올려본다. radiance에서 서빙은 radiance --model <무언가> --port 8000 한 줄이고, <무언가>가 무엇이 될 수 있는지가 이 글의 내용이다.

컨테이너와 체크포인트 받기

README의 모델 표에 있는 다운로드 링크는 전부 .rad 컨테이너 파일 하나를 가리킨다. 각 저장소에는 그 파일을 만든 레시피와 정확한 명령도 함께 있다.받는 쪽에서 필요한 건 이어받기 되는 curl 한 줄뿐이다.

mkdir -p /srv/models/rad && cd /srv/models/rad
curl -LC - -O https://huggingface.co/StillDeadcode/minicpm5-2b-fp8/resolve/main/minicpm5-2b-fp8.rad

공개 체크포인트를 그대로 받는 일은 scripts/hfget.sh가 한다. curl과 jq만 필요로 하고, 다시 실행하면 이어서 받으며, LFS 파일은 sha256을 실제 계산해 검증한 뒤에만 보관한다. 게이트된 저장소는 HF_TOKEN으로 인증한다.

scripts/hfget.sh Qwen/Qwen3.8-Flash-Next /srv/models/ckpt

--model에 저장소 ID를 주면

--model은 vLLM처럼 Hugging Face 저장소 ID도 받는다.

radiance --model StillDeadcode/minicpm5-2b-fp8 --port 8000

서버는 시작 전 같은 다운로더(libexec/radiance/hfget.sh)로 ~/.cache/radiance/hf(또는 --download-dir)에 저장소를 받고, 그 안의 .rad 하나를 서빙한다. 저장소에 컨테이너가 여러 개면 거부하고 파일명을 알려준다. 매 시작마다 hub를 확인해 바뀐 것을 받고, hub에 못 닿는 시작은 이전에 받아둔 사본으로 서빙한다. 주의할 점 두 가지 — 저장소 ID는 기본 main을 따라가므로 재시작이 아무도 검토하지 않은 가중치를 가져올 수 있다. 운영에서는 파일을 직접 지정하거나 리비전을 지정한다. 그리고 경로가 이미 존재하면 경로로 취급하고, .rad, .safetensors, .gguf, .json으로 끝나는 이름은 조회하지 않는다.

블록 스케일 fp8처럼 엔진이 그 정밀도로 서빙할 수 있는 체크포인트는 컨테이너 없이 디렉터리 그대로도 된다.

radiance --model /srv/models/hf/Qwen/Qwen3.8-27B-FP8

최소 실행

radiance --model /srv/models/rad/flashnext-w4.rad

이 한 줄이면 카드를 찾아(--gpu-headroom-mib 기본 96MiB 제외) 가중치와 KV 캐시에 예산을 나눠 배정하고, http://0.0.0.0:8000에서 서빙한다. 모든 예산은 무엇이라도 할당하기 전에 로그에 인쇄된다 — radiance에는 침묵하는 자동 최적화가 없다(설계 글 참고). --port, --host로 바인딩을 바꾼다.

기동 로그에서 시작 직전에 찍리는 STARTUP REPORT는 문제 신고 시 붙이는 블록이다. 설정값과 그 출처, 하드웨어 재측정, 경고와 해법이 들어 있다(운영 글 참고).

계획 확인: debug-graph, debug-selection, debug-placement

새 컨테이너나 새 커널 라이브러리를 붙였을 때, 서빙 전에 계획만 보는 플래그가 셋 있다.

radiance --model m.rad --debug-graph        # 선언된 그래프: 모든 op, 해석된 커널, 그 이유
radiance --model m.rad --debug-selection    # 선택 테이블만
radiance --model m.rad --debug-placement    # 배분 계획만

--debug-graph는 서빙하지 않고 끝난다. 참고 구현(libref)으로 해석된 op가 있으면 시작 거부 메시지를 미리 여기서 볼 수 있다. --api-key를 붙여도 이 플래그들에는 영향 없다.

모델별 서빙 플래그

README에는 compose 파일과 같은 서빙 플래그 표가 실려 있다. R9700 두 장 기준의 일부다.

모델	플래그
Qwen3.8-Flash-Next	--tp 2 --tp-wire wht6 --max-num-seqs 8 --max-model-len 200000 --placement expert_tiered --host-pool-mib 12288 --gpu-headroom-mib 96 --kv-cache-dtype fp8 --num-speculative-tokens 3 --max-num-batched-tokens 2048
Qwen3.8-27B FP8·MXFP4, Qwen3.6-35B-A3B	--tp 2 --max-num-seqs 32 --max-model-len 200000 --kv-cache-dtype fp8
MiniCPM5-2B FP8·bf16	--tp 2 --max-num-seqs 32 --max-model-len 131072 --kv-cache-dtype fp8 --gpu-headroom-mib 160 --max-num-batched-tokens 512
Qwen-Image 2.1(+Turbo)	--tp 2 --tp-wire wht6
MiniMax-H3, FastH3	--tp 2 --vision-tower-placement ram
Breeze-TTS-2	--tp 1

눈여겨볼 규칙이 하나 있다. 이 목록의 모델은 모두 한 스텝당 32시퀀스까지 서빙하지만 Flash-Next 계열과 bf16 27B는 8로 제한한다. 하이브리드 모델은 시퀀스마다 자기 순환 상태(delta-net state)를 따로 보유해서, 32개가 어텐션 캐시(와 Flash-Next에선 expert 슬랩)에서 그 메모리를 가져가기 때문이다. 플래그 각각의 의미는 메모리 예산과 롱 컨텍스트에서 풀어 쓴다.

API 키와 대시보드

--api-key KEY를 주면 Authorization: Bearer KEY(또는 X-Api-Key: KEY)를 요구한다. 단 /health, /ping, 대시보드 페이지는 예외다. 키 없이 띄운 서버라도 기계를 들여다보거나 상태를 바꾸는 경로(/diagnostics, LoRA 어댑터 로드, 세션 삭제 등)는 루프백에서만 답한다. 네트워크로 노출하는 서버에 대한 최소 방어선이다.

curl -s localhost:8000/v1/chat/completions -H 'Content-Type: application/json' \
  -d '{"model":"m","messages":[{"role":"user","content":"hi"}],"max_tokens":50}'

브라우저로 http://localhost:8000/를 열면 라이브 대시보드가 열린다. 디코딩 스텝 시간, 처리량, KV 캐시, 초안 채택률이 실시간으로 갱신된다. 다음 글에서는 이 서버가 말하는 HTTP API 전체를 훑는다.