Mac에서 Muse Glimmer MLX 설정하기: SGLang 백엔드 가이드

Meta가 2026년 8월 10일 공개 가중치 기반의 밀집형 멀티모달 모델 Muse Glimmer 30B를 출시하자마자, Mac 사용자들은 예상치 못한 오류를 마주했습니다. 기존 MLX 런타임 로더가 새 아키텍처를 아직 인식하지 못해 model type muse_glimmer not supported 오류를 내보낸 것입니다.

현재로서는 SGLang의 MLX 백엔드가 실행 가능한 경로 중 하나입니다. 소스에서 직접 빌드하고 Python 3.11을 사용해야 하며, 환경 변수 하나도 반드시 설정해야 합니다. 구성이 끝나면 코딩 에이전트나 채팅 프런트엔드에서 바로 연결할 수 있는 OpenAI 호환 API 서버를 제공하게 됩니다. 이 글에서는 SGLang의 로드맵 이슈 #19137에 흩어진 설치 절차와 해결 방법을 한 번에 정리합니다.

시작 전 확인할 사양과 준비물

Muse Glimmer 30B는 파라미터 300억 개를 갖춘 밀집형 멀티모달 모델입니다. MLX 4비트 양자화 기준으로 모델 가중치만 약 16~18GB를 차지하며, 32K 토큰 컨텍스트 창의 KV 캐시까지 포함하면 약 18~20GB의 작업 메모리가 필요합니다. SGLang 로드맵은 Metal의 권장 최대 작업 세트 크기를 기준으로 메모리 사용량도 제한합니다(PR #21539). 따라서 실제 한계는 Mac의 전체 통합 메모리보다 낮습니다.

가중치가 공개됐을 당시 r/opencodeCLI의 한 Reddit 사용자는 다음과 같이 언급했습니다.

"통합 메모리가 32GB 이상인 Mac이라면 더 높은 양자화 수준도 실용적일 것입니다."

macOS 13.5 이상(Metal 지원용), Xcode Command Line Tools, Homebrew도 필요합니다. SGLang의 MLX 백엔드는 Python 3.11에서만 검증됐습니다. 로드맵에서도 다른 버전은 문제가 발생하는 것으로 명시하고 있습니다.

1단계: Python 3.11, uv, MLX 설치

Mac에서 SGLang을 준비하려면 Homebrew 패키지 두 개를 설치하고, uv로 관리하는 Python 3.11 가상 환경을 만들어야 합니다.

1. Homebrew 의존성 설치

brew install ffmpeg uv

ffmpeg는 오디오와 멀티모달 처리 파이프라인에 사용합니다. uv는 SGLang 로드맵에서 가상 환경 생성 도구로 권장하는 빠른 Python 패키지 관리자입니다.

1. SGLang 저장소 복제

git clone https://github.com/sgl-project/sglang.git
cd sglang

1. Python 3.11 환경 생성 및 활성화

uv venv -p 3.11 my-venv
source my-venv/bin/activate
python -m pip install --upgrade pip

Python 3.12나 3.13은 사용하지 않는 편이 좋습니다. 로드맵 이슈에 따르면 Python 3.12 이상에서는 Triton 스텁 import가 깨집니다(PR #21551에서 수정됐지만 완전히 검증되지는 않음). MLX 컴파일 체인 역시 3.11 기준으로만 테스트됐습니다.

1. 최신 MLX 런타임 패키지 설치

pip install mlx mlx-lm mlx-vlm --upgrade

로드맵은 오래된 mlx 또는 mlx-lm가 과도한 프로파일링 로그와 아키텍처 감지 실패를 유발할 수 있다고 경고합니다. PR #22162에서는 이 패키지들을 SGLang의 명시적 의존성으로 추가했습니다. Muse Glimmer 같은 멀티모달 모델에는 mlx-vlm도 필요하며, 없으면 실행 시 model type muse_glimmer not supported 오류가 발생합니다.

2단계: 소스에서 SGLang MLX 백엔드 빌드

일반적인 pip install sglang 패키지에는 MLX 지원이 포함되지 않습니다. Apple MPS extras를 사용해 소스에서 직접 빌드해야 합니다.

1. pyproject.toml 교체

cp python/pyproject.toml python/pyproject.toml.bak
cp python/pyproject_other.toml python/pyproject.toml

pyproject_other.toml은 macOS에서 빌드할 수 없는 CUDA 전용 의존성을 제거하고, MPS 호환 대안으로 교체합니다.

1. MPS extras를 포함해 editable 모드로 설치

uv pip install -e "python[all_mps]"

이 과정에서 Metal 커널 스텁을 컴파일하고 Apple Silicon 런타임 경로를 설치합니다. Mac 사양에 따라 빌드에는 몇 분이 걸릴 수 있으며, 특히 sgl-kernel의 Metal 빌드(PR #23449)가 가장 오래 걸립니다.

1. 설치 확인

python -c "import sglang; print(sglang.__version__)"

Triton 오류 없이 import된다면 MPS 경로가 제대로 구성된 것입니다.

3단계: Muse Glimmer MLX 모델 내려받기

MLX Community는 Hugging Face에 Muse Glimmer의 4비트 양자화 빌드를 공개했습니다.

huggingface-cli download mlx-community/Muse-Glimmer-30B-4bit

huggingface-cli가 설치되지 않았다면 먼저 다음 명령을 실행합니다.

pip install huggingface-hub

다운로드 크기는 약 16~17GB입니다. 기본적으로 huggingface-cli download는 모델을 ~/.cache/huggingface/hub/에 저장합니다. SGLang의 --model-path에는 Hugging Face 저장소 ID를 직접 넣을 수 있고, 로컬 캐시 디렉터리를 지정해도 됩니다.

메모리 사용량 빠르게 보기

32GB Mac에서도 모델 자체는 로드할 수 있지만, 큰 컨텍스트 창을 쓸 수 있는 여유는 제한적입니다. 서버는 실행됐는데 첫 번째 긴 프롬프트에서 종료된다면 --context-length를 8192 또는 16384로 낮추세요.

4단계: SGLang 서버 실행

의존성을 설치하고 모델까지 받았다면 실행 명령은 한 줄입니다. 다만 환경 변수 설정은 빠뜨리면 안 됩니다.

SGLANG_USE_MLX=1 python -m sglang.launch_server \
  --model-path mlx-community/Muse-Glimmer-30B-4bit \
  --port 30000 \
  --context-length 32768

명령어 구성 살펴보기

• SGLANG_USE_MLX=1은 PyTorch MPS나 CPU로 폴백하지 않고 네이티브 MLX 실행 백엔드를 활성화합니다. 이 플래그가 없으면 서버가 실행되더라도 속도는 크게 떨어집니다.
• --model-path는 MLX 형식의 4비트 모델을 가리킵니다. SGLang의 PR #25191은 MLX 형식 quantization_config의 자동 감지를 추가했으므로, 별도 플래그 없이 형식을 인식해야 합니다.
• --context-length는 최대 컨텍스트 창을 제한합니다. 메모리가 부족하다면 이 값을 낮추세요. Muse Glimmer는 커뮤니티 테스트 및 Meta 릴리스 노트 기준으로 이론상 최대 262K 토큰을 지원하지만, 통합 메모리를 쓰는 Mac에서는 실용적인 한계가 훨씬 낮습니다.

고급 설정: SGLang은 BF16 가중치에서 --quantization mlx_q4 또는 mlx_q8를 지정해 실행 중 양자화하는 기능도 지원합니다(PR #24907). 사전 제작된 4비트 모델을 불러오는 것보다 시작 시간이 길기 때문에, 양자화 과정을 직접 제어해야 할 때만 사용하는 편이 좋습니다.

5단계: OpenAI 호환 API로 동작 확인

서버가 Server is ready를 출력하면 OpenAI 호환 엔드포인트에 curl 요청을 보내 테스트합니다.

curl http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-glimmer",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain how GQA reduces KV cache size in one sentence."}
    ],
    "max_tokens": 200
  }'

정상적으로 동작하면 완성된 응답이 담긴 JSON 객체가 반환됩니다. SGLang 로드맵의 벤치마크 데이터 기준으로 M5 Pro에서 4비트 모델을 단일 사용자 디코드로 실행할 때 약 17.6토큰/초를 기대할 수 있습니다.

중요: max_tokens는 넉넉하게 200 이상으로 잡으세요. Muse Glimmer는 추론 우선 설계를 사용하므로 chain-of-thought 토큰이 출력 예산의 상당 부분을 차지할 수 있습니다. 응답이 비어 있거나 중간에 잘린 것처럼 보인다면, 답변이 출력되기 전에 추론 과정이 전체 예산을 소진했을 가능성이 높습니다.

MLX 튜닝 환경 변수 정리

SGLang은 공식 환경 변수 레퍼런스에 문서화된 MLX 전용 환경 변수 세 개를 제공합니다. 모두 기본값은 비활성화 또는 보수적인 설정입니다.

튜닝을 활성화한 실행 예시는 다음과 같습니다.

SGLANG_USE_MLX=1 \
SGLANG_MLX_USE_CUSTOM_ROPE=true \
SGLANG_MLX_FUSE_SWIGLU=true \
SGLANG_MLX_CLEAR_CACHE_STEPS=128 \
python -m sglang.launch_server \
  --model-path mlx-community/Muse-Glimmer-30B-4bit \
  --port 30000 \
  --context-length 32768

이 기능들은 로드맵상 실험적 기능입니다. 커널 결합 플래그 중 하나를 활성화한 뒤 충돌이 발생하면 비활성화하고 버그를 보고하세요. MLX 백엔드는 아직 활발히 개발되고 있습니다.

자주 발생하는 오류와 해결 방법

"Model type muse_glimmer not supported" 오류

출시 직후 가장 흔히 보이는 오류입니다. MLX 런타임(mlx-lm 또는 mlx-vlm)이 muse_glimmer 아키텍처 유형을 인식하지 못한다는 뜻입니다. 다음 명령으로 업데이트하세요.

pip install mlx-lm mlx-vlm --upgrade

오류가 계속된다면 SGLang 체크아웃에 Qwen3 dense MLX 지원 PR(#25754)이 포함돼 있는지 확인하세요. 이 PR은 밀집형 트랜스포머 모델의 아키텍처 재작성 지원을 추가했습니다. 필요한 아키텍처 지원을 받으려면 최신 main 브랜치로 git pull해야 할 수 있습니다.

Python 3.12에서 발생하는 Triton 스텁 충돌

SGLang 설정은 Python 3.12 이상과 호환되지 않는 Triton 스텁을 import합니다. 해결 방법은 Python 3.11로 가상 환경을 다시 만드는 것입니다.

deactivate
rm -rf my-venv
uv venv -p 3.11 my-venv
source my-venv/bin/activate
uv pip install -e "python[all_mps]"

PR #21551에서 Triton import 경로를 수정했지만, 완전히 검증된 버전은 여전히 Python 3.11뿐입니다.

서버는 켜지는데 CPU로 실행되는 경우

토큰 생성 속도가 지나치게 느리다면(2토큰/초 미만), SGLANG_USE_MLX=1을 설정하지 않아 SGLang이 CPU로 폴백했을 가능성이 큽니다. 먼저 다음 명령으로 확인하세요.

echo $SGLANG_USE_MLX

아무것도 출력되지 않으면 서버를 실행하기 전에 변수를 export하거나, 실행 명령 앞에 인라인으로 붙여야 합니다.

MLX 메모리 충돌 또는 시스템 재부팅

Metal 권장 작업 세트 크기를 초과하면 서버가 종료되거나, 심한 경우 macOS 전체가 재부팅될 수 있습니다. 로드맵은 이를 완화하기 위해 PR #21539에서 작업 세트 제한을 추가했지만, 큰 컨텍스트 창은 여전히 한도를 넘길 수 있습니다. 다음 방법을 시도해 보세요.

• --context-length를 8192 이하로 낮추기
• SGLANG_MLX_CLEAR_CACHE_STEPS=64로 설정해 캐시를 더 자주 비우기
• BF16 가중치에서 실행 중 양자화하는 대신 4비트 모델 사용하기
• GPU를 많이 사용하는 다른 앱 종료하기. 특히 하드웨어 가속을 쓰는 Safari에 주의

도구 호출 루프 또는 빈 결과

r/LocalLLaMA의 커뮤니티 스레드에서는 Muse Glimmer의 도구 호출 동작이 양자화 수준에 따라 일관되지 않으며, MLX와 GGUF 변형을 테스트한 사용자 모두 도구 호출 루프를 보고했습니다. 이는 MLX에만 국한된 문제는 아니며 여러 런타임에서 나타납니다. 함수 호출을 사용할 때는 max_tokens를 500 이상으로 설정하고, 먼저 단일 호출 워크플로로 테스트하세요. 안정적인 도구 호출이 가장 중요하다면 Qwen 3.6 27B도 고려할 만합니다.

FAQ

SGLang MLX 백엔드는 Muse Glimmer의 speculative decoding을 지원하나요?

아직 지원하지 않습니다. SGLang 로드맵에는 EAGLE speculative decoding이 계획 항목으로 올라와 있지만 MLX 백엔드에는 구현되지 않았습니다. Mac에서는 로드맵 논의의 벤치마크 기준으로 일반적인 자기회귀 디코딩만 가능하며, 속도는 M5 Pro Q4 기준 약 17.6토큰/초입니다.

Mac에서 Muse Glimmer를 돌릴 때 MLX와 GGUF 중 무엇을 써야 하나요?

MLX는 Apple Silicon에 맞춘 네이티브 경로입니다. Metal을 직접 사용하며, 명시적인 CPU-GPU 복사 없이 통합 메모리의 이점을 활용합니다. MLX 런타임이 muse_glimmer 아키텍처를 지원하지 않을 때는 llama.cpp 기반 GGUF가 대안입니다. 주요 선택지는 MLX community의 4비트 빌드와 Hugging Face에서 제공하는 Unsloth GGUF 빌드입니다. MLX는 한 번 동작하기 시작하면 대체로 더 빠른 디코드 속도를 내고, GGUF는 LM Studio와 Ollama 등 폭넓은 도구 호환성을 제공합니다.

서빙 용도로 SGLang MLX는 mlx-lm 또는 Ollama와 어떻게 다른가요?

SGLang은 OpenAI 호환 API 서버와 radix 캐싱, 그리고 앞서 소개한 튜닝 변수를 제공합니다. mlx-lm은 더 단순합니다. 설정 옵션은 적지만 서버 추상화 없이 텍스트를 로드하고 생성할 수 있습니다. r/LocalLLM의 한 Reddit 사용자는 별도 API 계층을 가진 Ollama의 muse-glimmer:30b-mlx 태그를 보고했습니다. OpenCode CLI 같은 코딩 에이전트에 바로 연결할 API가 필요하다면 SGLang이나 Ollama가 현실적인 선택이고, 간단한 일회성 생성이라면 mlx-lm으로 충분합니다.