radiance는 AMD GPU 전용 고성능 추론 서버입니다. C++와 HIP로 구현되었으며, 단순한 언어 모델(LLM)을 넘어 이미지, 비디오, 음성, 음악 생성까지 단일 프로세스 내에서 서빙할 수 있는 통합 환경을 제공합니다.

특히 모델 구조, 커널 라이브러리, 양자화 엔진을 모두 .so 플러그인 형태로 분리한 설계가 특징입니다. 이를 통해 기본 내장 플러그인과 서드파티 플러그인을 동일한 방식으로 빌드하고 로드하여 확장성을 확보했습니다.

본 가이드는 radiance에 체크아웃된 공식 저장소의 README와 docs/ 내 가이드 문서들을 바탕으로, 한국어 사용자를 위해 핵심 내용을 재구성하여 정리한 것입니다.

폭넓은 표준 API 호환성

radiance의 HTTP API는 업계 표준으로 자리 잡은 서버들의 명세를 그대로 따릅니다. 덕분에 기존에 사용하던 클라이언트나 SDK를 수정 없이 그대로 연결해 사용할 수 있습니다.

호환 API	엔드포인트 예시	활용 가능 도구
OpenAI Chat / Completions	/v1/chat/completions, /v1/completions	OpenAI SDK, LangChain 및 대부분의 LLM 도구
OpenAI Responses	/v1/responses	Codex, OpenAI SDK responses 클라이언트
OpenAI Images / Audio / Videos	/v1/images/*, /v1/audio/*, /v1/videos	이미지 생성/편집, 음성 합성/인식, 비디오 생성 작업
Anthropic Messages	/v1/messages	Claude Code, Anthropic SDK
llama-server 네이티브	/completion, /infill, /props	llama.vim, llama.vscode 등 전용 클라이언트
vLLM 스타일	/tokenize, /server_info, /load	vLLM 기반 운영 및 모니터링 도구

또한 http://localhost:8000/에서 제공되는 실시간 대시보드를 통해 디코딩 스텝 시간, 처리량(Throughput), KV 캐시 점유율, 추측 복호화(Speculative Decoding) 채택률 등의 핵심 운영 지표를 즉시 확인할 수 있습니다. /metrics 엔드포인트는 Prometheus 형식의 지표를 vllm: 및 radiance: 패밀리로 나누어 제공하여 정밀한 모니터링을 지원합니다.

단일 컨테이너 모델 포맷 (.rad)

radiance는 모델을 효율적으로 관리하기 위해 두 가지 로드 방식을 지원합니다.

• 직접 로드 (Checkpoint): bf16, f16, f32, 블록 스케일 fp8, Quark MXFP4 등 서버가 직접 해석 가능한 정밀도로 저장된 체크포인트는 디렉터리 경로를 --model 인자로 넘겨 바로 사용할 수 있습니다.
• .rad 컨테이너: 양자화가 필요한 모델은 rad-convert 도구를 통해 .rad 단일 파일로 변환합니다. 이 컨테이너에는 가중치(부호, 스케일, 영점, 회전 등의 인코딩 평면)뿐 아니라 토크나이저, 채팅 템플릿, 메타데이터, 그리고 필요한 경우 초안 헤더(drafter)까지 모두 포함됩니다.

특히 컨테이너 설계 시 특정 커널 라이브러리에 종속되지 않도록 설계되었습니다. 커널 라이브러리가 로드 시점에 데이터를 자신의 레이아웃으로 재배열하므로, 하드웨어 가속 커널을 교체하더라도 모델을 다시 변환할 필요가 없습니다. 자세한 내용은 radiance의 설계에서 확인하시기 바랍니다.

지원 모델 범위

radiance는 광범위한 모델군을 지원합니다. 범주별 대표 모델은 다음과 같습니다.

범주	대표 모델
언어 모델 (Dense / MoE)	Qwen3.8-27B, Qwen3.8-Flash-Next (512 expert MoE), Qwen3.6-35B-A3B, Gemma 4 31B/12B, MiniCPM5-2B, GLM-5.3-Flash, Nemotron 3.5 Bolt
이미지 생성	Qwen-Image 2.1 (+Turbo), FLUX.3 [klein], Krea 2, Anima, Stable Diffusion XL 계열
비디오 생성	MiniMax-H3, FastH3, LTX-2.5 (오디오 포함)
음성 및 음악	Breeze-TTS-2, Fish Audio drama-3 (Voice Cloning), MiniMax-Music3, Qwen3-ASR (음성 인식)
임베딩 및 리랭크	EmbeddingGemma 2, nomic-embed-text-v2-moe, Nemotron 3.5 Embed/Rerank
기타 특수 목적	Unlimited-OCR (문서 파싱), Hunyuan3D-2 (3D Mesh 생성)

모델은 Hugging Face에서 배포되는 .rad 파일을 직접 다운로드하거나, 공개 체크포인트를 직접 변환하여 사용할 수 있습니다. 각 배포처에는 해당 파일을 생성하는 데 사용된 정확한 변환 레시피와 명령어가 포함되어 있습니다.

지원 하드웨어 및 백엔드

기본 제공되는 장치 커널은 AMD RDNA4(gfx1200/gfx1201, libr4d), RDNA3(gfx11xx, libr3d), Strix Halo(gfx1151, libhalo) 아키텍처에 최적화되어 있습니다. 본 문서의 성능 지표와 기본 설정값은 주로 Radeon AI PRO R9700 32GB 카드 2장을 탑재한 환경을 기준으로 작성되었습니다.

GPU가 없는 환경에서도 AVX-512/AVX2 커널(libavx)을 통해 모든 모델을 서빙할 수 있습니다. EmbeddingGemma 2나 Qwen3-ASR, 0.8B~3B 규모의 소형 모델은 일반 데스크톱 CPU에서도 실사용 가능한 속도로 구동됩니다. 27B 이상의 대형 모델은 CPU에서 구동 가능하지만 속도가 매우 느립니다. 그 외 AMD GPU 제품군 역시 엔진 자체는 공통으로 작동하며, 해당 아키텍처용 커널 라이브러리 플러그인만 추가하면 가속 기능을 사용할 수 있습니다.

시작해 보기

가장 빠르게 환경을 구축하는 방법은 Docker를 사용하는 것입니다. 호스트 OS에 Docker와 ROCm 10.1을 지원하는 amdgpu 커널 드라이버만 설치되어 있으면 되며, ROCm 툴킷 전체를 설치할 필요는 없습니다.

docker pull stilldeadcode/radiance
git clone https://codeberg.org/StillDeadcode/radiance.git
cp -r radiance/deploy/compose ~/radiance-compose && cd ~/radiance-compose
cp .env.example .env                         # 모델 경로, API 키 등 설정
docker compose -f minicpm5-2b.yaml up -d     # 모델 설정 파일 선택 후 실행

소스 코드에서 직접 빌드하려면 Linux 환경과 C++20 컴파일러, CMake 3.21+, Ninja가 필요하며, 장치 커널 빌드를 위해 ROCm의 hipcc가 설치되어 있어야 합니다.

git clone https://codeberg.org/StillDeadcode/radiance.git && cd radiance
./build.sh                                   # 구성 및 빌드, 기본 테스트 수행
export RADIANCE_HOME=$PWD/build/radiance_home
build/bin/radiance --model minicpm5-2b-fp8.rad --port 8000

이후의 상세 설정은 rig 준비와 Docker로 빠르게 실행하기 가이드를 참고하시기 바랍니다. radiance는 엔진부터 빌드 도구까지 모두 C++와 CMake, 셸 스크립트로 구현되어 있어 Python 의존성이 전혀 없습니다.