Apple Silicon with Metal

Apple Silicon에서 MLX를 사용해 SGLang 서빙 런타임을 실행하는 방법을 설명합니다. SGLang Diffusion은 대신 PyTorch MPS를 사용하므로, 관련 내용은 설치 가이드를 참고하세요. 문제가 있으면 이슈를 열어 주세요.

출처: 문서

본문

전제 조건 (Prerequisites)

MLX 런타임은 Apple Silicon + macOS 14 이상, 안정적인 PyTorch 2.13.x, 안정적인 MLX 0.32.0 이상이 필요합니다. srt_mps extra가 PyTorch 2.13.0과 MLX 0.32.0 이상을 설치합니다. 시작 시 안정적인 PyTorch 2.13 패치 릴리스와 더 최신 안정 MLX 릴리스를 수용합니다.

SGLANG_USE_MLX=1로 실행하면 SGLang은 인자 초기화 중 두 프레임워크 버전과 Metal 가용성을 검증하고, 런타임이 호환되지 않으면 모델을 확인·다운로드하기 전에 멈춥니다.

sgl-kernel의 선택적 네이티브 Metal 커널을 빌드하려면 전체 Xcode 애플리케이션의 Metal shader 컴파일러가 필요합니다. 독립 실행형 Xcode Command Line Tools로는 부족해요. Xcode 설치 후 다음으로 선택하세요:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

컴파일러는 xcrun -sdk macosx metal --version으로 검증하세요.

SGLang 설치 (Install SGLang)

아래 방법 중 하나로 SGLang을 설치할 수 있습니다.

소스에서 설치 (Install from Source)

# Use the default branch
git clone https://github.com/sgl-project/sglang.git
cd sglang

# Create and activate a virtual environment
uv venv -p 3.12 sglang-metal
source sglang-metal/bin/activate

# (Optional) Compile sgl-kernel
uv pip install --upgrade pip
uv run python/sglang/kernels/aot/setup_metal.py install

# Install sglang python package along with diffusion support
rm -f python/pyproject.toml && mv python/pyproject_other.toml python/pyproject.toml
uv pip install -e "python[all_mps]"

서빙 엔진 시작 (Launch of the Serving Engine)

다음으로 서버를 시작하세요:

SGLANG_USE_MLX=1 python -m sglang.launch_server \
  --model <MODEL_ID_OR_PATH> \
  --disable-cuda-graph \
  --host 0.0.0.0

핵심 파라미터 설명 (Key Parameters Explained):

SGLANG_USE_MLX=1 - SGLang 런타임 백엔드로 MLX 사용을 활성화 (비활성 시 SGLang은 지원이 적은 torch.mps로 폴백)
--disable-cuda-graph - Apple Metal과 무관한 CUDA graph 사용을 비활성화
--disable-overlap-schedule - MLX의 async_eval()로 달성되는 overlap scheduling 비활성화 (기본적으로 활성/비활성 아님)
SGLANG_MLX_USE_CUSTOM_ROPE=1 - 선택적 커스텀 Metal RoPE 커널 활성화. 기본적으로 비활성이므로 A/B 테스트에 선택하지 않는 한 MLX 백엔드는 표준 RoPE 경로 사용
SGLANG_MLX_FUSE_SWIGLU=1 - fused Swish-Gated Linear Unit 커널 사용 활성화 (기본적으로 비활성)
SGLANG_MLX_CLEAR_CACHE_STEPS=256 - MLX 캐시를 비우기 전 decode 단계 수 설정 (기본 256)

양자화 (Quantization)

MLX 백엔드는 Apple Silicon에서 두 가지 양자화 경로를 지원합니다:

사전 양자화 HF 저장소 (Pre-quantized HF repos). 어떤 mlx-community/<model>-4bit(또는 -8bit) 저장소도 mlx_lm.load(...)를 통해 직접 로드됩니다. 추가 플래그가 필요 없어요.
```
SGLANG_USE_MLX=1 python -m sglang.launch_server \
  --model-path mlx-community/Qwen3-0.6B-4bit \
  --disable-cuda-graph
```
온더플라이 양자화 (On-the-fly quantization). fp16 모델이라면 --quantization mlx_q4 또는 --quantization mlx_q8을 전달해 sglang이 로드 시점에 mlx_lm.utils.quantize_model로 가중치를 양자화하게 합니다(group size 64, mlx-community 기본값). 양자화된 가중치는 프로세스 메모리에 유지되고, 디스크의 모델은 건드리지 않습니다.
```
SGLANG_USE_MLX=1 python -m sglang.launch_server \
  --model-path Qwen/Qwen3-0.6B \
  --quantization mlx_q4 \
  --disable-cuda-graph
```
기대 로그 라인:
```
Quantizing MLX model on-the-fly: bits=4 group_size=64 (preset=mlx_q4)
Quantization complete in 0.13s — active mem: 1.11 GB -> 0.31 GB (71.9% reduction)
```
MLX 백엔드는 모델이 HF 설정에서 이미 양자화된 경우(path 1) --quantization mlx_q4를 조용히 무시하므로, 어떤 경우든 같은 플래그를 안전하게 전달할 수 있습니다.

요청으로 벤치마킹 (Benchmarking with Requests)

sglang.benchmark.one_batch는 스케줄러와 overlap 코드 경로를 거치지 않고 동기 prefill/decode 메서드를 직접 호출합니다.

sglang.benchmark.offline_throughput은 스케줄러와 overlap 코드 경로를 사용하므로 --disable-overlap-schedule 플래그로 overlap 스케줄링을 토글할 수 있습니다.

처리량 테스트 (Throughput Testing)

기본 동기 one-batch 처리량:

SGLANG_USE_MLX=1 python -m sglang.benchmark.one_batch \
  --model-path <MODEL_ID_OR_PATH> \
  --disable-cuda-graph \
  --tp-size 1 \
  --batch-size 1 \
  --input-len 60 \
  --output-len 10

동기 오프라인 처리량:

SGLANG_USE_MLX=1 python -m sglang.benchmark.offline_throughput \
  --model-path <MODEL_ID_OR_PATH> \
  --disable-cuda-graph \
  --num-prompts 1 \
  --disable-overlap-schedule

비동기 오프라인 처리량:

SGLANG_USE_MLX=1 python -m sglang.benchmark.offline_throughput \
  --model-path <MODEL_ID_OR_PATH> \
  --disable-cuda-graph \
  --num-prompts 1

Apple Silicon with Metal