MacBook Pro에서 GLM-5.3-Flash를 실행하는 방법: 2bit-Lite MLX 플레이북

실행하는 것은 GLM-5.3-Flash를MacBook Pro에서 정확히 하나의 머신을 의미합니다: 128GB M4/M5 Max MacBook Pro를 실행하는2bit-lite빌드우리의 MLX 변환의, macOS 유선 메모리 한도를 올린 상태로. MacBook Pro가 128GB 미만인 경우 — 36GB M4 Pro, 48GB M4 Max — 이 플레이북은 당신을 위한 것이 아닙니다. 마지막 섹션으로 건너뛰어 호스팅된 z-ai/glm-5.3-flash API를 대신 사용하세요. GLM-5.3-Flash (가중치는 zai-org/GLM-5.3-Flash에 있습니다)는 Z.ai의 3,200억 파라미터 MoE(Mixture-of-Experts) 모델로, 토큰당 180억 개의 활성 파라미터를 가집니다. 2026년 8월 26일에 출시된 최초의 네이티브 멀티모달 GLM-5이며, 우리 MLX 포트의 가장 작은 빌드에도 약 102GB의 가중치와 약 112GB의 메모리가 필요합니다. 이것이 전체 시장이며, 우리는 이를 완화하려 하지 않습니다.

이 문서는 출시 기사가 아닌 자사 문서입니다. 아래의 가중치는 OrcaRouter 자체 빌드(orcarouter/GLM-5.3-Flash-MLX, MIT)이며, 당사의 캘리브레이션 없는 OrcaSAQ 양자화 방식으로 제작되었습니다. 8월 26일에 출시했지만, 다음 날 공개적으로 방향을 수정했습니다. 원래 양자화 범위로는 대부분의 사람들이 MacBook Pro에서 실용적으로 사용할 수 없었기 때문입니다. 일반 2비트 빌드는 여전히 약 160GB가 필요했으며, 이는 어떤 노트북에도 없는 용량입니다. 8월 27일에 가장 작은 변형을 2bit-lite로 재구축했으며, 이는 128GB MacBook Pro에 맞추기 위한 것이었습니다. 이 글은 그 선택이 가져다주는 이점과 비용에 대한 솔직한 설명입니다. 모든 숫자는 현장 노트로 아래에 표시되어 있으며, 단일 H200 검증 실행에서 측정되었습니다. 여기에는 벤더 벤치마크가 없습니다. 커뮤니티 관행을 따르는 부분(wired-memory 명령, mlx-vlm 버전 관리)은 그렇게 표시해 두었습니다.

어떤 빌드가 어떤 Mac에 맞는지 (다운로드하기 전에 이 글을 읽어보세요)

리포지토리의 다섯 빌드는 각각 최소 RAM 수치에 해당합니다. MacBook Pro에서는 '어떤 빌드'에 대한 답은 정확히 하나입니다. 2bit-lite보다 높은 모든 것은 Mac Studio 이야기입니다:

• 6비트 — 가중치 ~296GB / RAM ~320GB / 거의 무손실. 512GB Mac Studio만 해당.

• 4-bit — ~204 GB / ~224 GB / 저희가 권장하는 기본값. Mac Studio 256 GB. 이것이 리포지토리 루트가 미러링하는 내용입니다.

• 3비트 — 약 184 GB / 약 200 GB. Mac Studio 256 GB.

• 2-bit — ~145 GB / ~160 GB. Mac Studio 192 GB. 이것은 우리가 출시 첫날 제공한 가장 작은 빌드였으며, 바로 그것이 놓친 부분이었습니다.

• 2bit-lite — ~102GB / ~112GB. 128GB 장비에 맞는 유일한 빌드 — 128GB M4/M5 Max MacBook Pro, 또는 128GB Mac Studio나 Mac mini. 모든 128GB Apple Silicon 노트북(M3 Max 이상)도 마찬가지이며, 다만 더 느릴 뿐입니다.

그 설치 단계에 숨은 함정: README의 기본 다운로드 명령은 4비트 빌드(~204GB)를 받아오는데, 이는 256GB 머신에는 적합한 기본값이지만 노트북에서는 쓸모가 없습니다. MacBook Pro에서 기본 명령을 따르면 메모리 할당에 실패하는 모델을 받게 됩니다. 2bit-lite 경로는 명시적인 --include가 필요하며, 아래에서 다룹니다.

위의 계산이 적용되기도 전에 부딪히게 될 엄격한 상한선이 하나 더 있습니다. macOS는 프로세스가 128GB Mac의 통합 메모리를 모두 차지하는 것을 허용하지 않습니다. 기본 GPU 사용 가능 상한선은 대략 91–96GB입니다(커뮤니티에서 리버스 엔지니어링되었으며 대규모 모델 MLX 설정에 대한 여러 글에서 확인되었습니다). 이는 가중치만으로도 약 102GB보다 낮은 수치이므로 wired-memory limit을 올리기 전에는 2bit-lite조차 로드되지 않습니다. 이 단계는 필수이며, 4장에서 다룹니다.

mlx-vlm을 설치하세요 — 그리고 오직 mlx-vlm만.

GLM-5.3-Flash는 비전-언어 모델이므로 mlx-vlm에서 실행되며, mlx-lm이 아닙니다. 이것은 사람들이 가장 흔히 막히는 지점이므로 미리 말씀드립니다: mlx-lm은 텍스트 전용 모델용입니다. 멀티모달 모델을 이것으로 실행하면 혼란스러운 로드 오류가 발생합니다. VLM 패키지를 0.6.17 이상 버전으로 설치하세요:

pip install -U "mlx-vlm>=0.6.17"

버전 핀은 장식이 아닙니다.glm5_next뒤에 있는 하이브리드 희소+선형 어텐션 아키텍처GLM-5.3-Flash모델이 출시된 날(2026년 8월 26일)에 mlx-vlm에 들어왔으며, 그보다 오래된 버전은 config를 인식하지 못합니다. 이 아키텍처가 중요한 이유가 하나 더 있습니다. 이것은 완전히 새로운 토폴로지이며, 초기 포트에는 자연스러운 출력으로는 드러나지 않는 실제 정확성 버그가 있었습니다. 초기 glm5_next MLX 경로에 대한 커뮤니티 런타임 감사에서 네 가지 버그가 발견되어 수정되었습니다: 모든 FFN 블록에 적용되지 않은 SwiGLU 클램프, 매니폴드 제약 하이퍼커넥션 텐서가 잘못된 dtype으로 캐스팅된 것(이로 인해 어텐션 믹싱 행렬이 조용히 손상됨), 어텐션 정규화의 두 엡실론 불일치, 그리고 참조가 float32를 사용하는 bf16 라우터 로짓. 수정 후 수치는 참조와 약 1e-7 수준으로 일치했습니다. 즉, mlx-vlm을 최신으로 유지하고, 새로운 아키텍처 포트의 첫 번째 릴리스는 의심스럽게 취급하십시오.

가중치를 다운로드하세요: 제외 플래그와 실제로 필요한 포함 항목을.

저장소 루트는 4비트 빌드를 미러링하며, 다섯 가지 변형 모두 하위 폴더로 제공됩니다. 기본 명령은 루트를 다운로드하고 --exclude를 사용하므로 다섯 가지 변형 폴더(합계 약 800GB) 중 어느 것도 함께 다운로드되지 않습니다:

hf download orcarouter/GLM-5.3-Flash-MLX --local-dir ./GLM-5.3-Flash-MLX --exclude "2bit-lite/*" "2-bit/*" "3-bit/*" "4-bit/*" "6-bit/*"

MacBook Pro에서는 그 명령이 잘못되었습니다 — 4비트 루트가 나옵니다. 128GB 노트북의 경우, 다음만 가져오세요 2bit-lite 하위 폴더:

hf download orcarouter/GLM-5.3-Flash-MLX --include "2bit-lite/*" --local-dir ./GLM-5.3-Flash-MLX

그것은 ~102GB 다운로드이며 완전히 독립적입니다 — 2bit-lite/ 폴더에는 자체 config.json이 들어 있으므로 생성기를 바로 그 폴더에 지정하면 됩니다. 만약 hf가 PATH에 없다면 설치하세요: pip install -U huggingface_hub. 시작하기 전에 ~110GB의 여유 디스크 공간이 있는지, 그리고 Mac의 저장 공간이 마지막으로 남은 100GB뿐이 아닌지 확인하세요. MLX는 가중치를 메모리 매핑하며, SSD가 거의 가득 찬 상태에서는 이러한 설정이 다운로드 중간에 죽곤 합니다.

wired-memory 한도 높이기 — 모두가 잊어버리는 단계

이것은 128GB MacBook Pro에서 성패를 결정짓는 단계이며, README 카드는 명령어를 자세히 설명하는 대신 여러분이 그것을 알고 있다고 가정합니다. 128GB Mac의 기본 Metal 작업 세트 상한은 대략 91–96GB이며, 이는 2bit-lite 가중치의 약 102GB보다 낮습니다. 따라서 이 단계 없이는 모델이 할당에 실패하고 로드가 중단됩니다. 커뮤니티 표준 해결책은 GPU 고정 메모리 상한을 메가바이트 단위로 높이는 sysctl입니다:

sudo sysctl iogpu.wired_limit_mb=114688

그러면 약 112GB 상한선이 설정되어 약 14GB가 OS 예비 영역으로 남습니다. 128GB 머신에서는 커뮤니티에서 실제 사용하는 값이 ~114688(112GB)부터 ~122880(120GB)까지 다양합니다. 최대치로 설정하지 마세요. macOS에는 여유 공간이 필요하며, 그렇지 않으면 메모리 압력이 높을 때 window-server 버벅임과 시스템 끊김 현상이 발생합니다. 설정한 후 모델을 로드하고 Activity Monitor를 확인하세요. 메모리 압력이 노란색으로 표시되면 숫자를 낮추세요.

실용적인 참고 사항 두 가지입니다. 둘 다 저희 현장 기록이 아니라 커뮤니티 관행에서 나온 것입니다. 첫째, sysctl은 재부팅 시 초기화되고 설정한 터미널 세션에만 적용됩니다. 따라서 다시 실행하거나 LaunchAgent로 스크립트화할 계획을 세우세요. 재부팅 후 잊어버리면 전형적인 '어제는 됐는데' 실패가 발생합니다. 둘째, MLX는 또한 프로세스 내부 노브(knob), 즉 mlx.core.metal.set_wired_limit(bytes)를 macOS 15.0 이상에서 제공합니다. 이 값은 sysctl 상한보다 낮아야 하며, 노트북 환경에서 스크립트를 작성하는 경우 더 이식성이 높은 옵션입니다. 어떤 방법을 사용하든 효과는 동일합니다. 이 설정이 없으면 여기의 어떤 것도 실행되지 않습니다.

실행하세요: 텍스트, 이미지, 그리고 Python API

가중치가 준비되고 제한이 올라간 상태에서, 생성은 단 하나의 명령으로 가능합니다. 텍스트:

python -m mlx_vlm.generate --model ./GLM-5.3-Flash-MLX/2bit-lite --prompt "양자 얽힘을 한 문장으로 설명하세요." --max-tokens 256

이미지 입력은 --image 플래그와 함께 동일한 방식으로 작동합니다 — 비전 타워가 OrcaSAQ 레이아웃에서 더 높은 정밀도를 유지하기 때문에, 멀티모달 모델이 노트북에서 진가를 발휘하는 부분이 바로 여기입니다:

python -m mlx_vlm.generate --model ./GLM-5.3-Flash-MLX/2bit-lite --image photo.jpg --prompt "이 이미지를 설명하세요." --max-tokens 256

스크립트의 경우, Python API는 mlx-vlm 사용자가 알고 있는 것과 동일한 형태입니다:

from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template model, processor = load("./GLM-5.3-Flash-MLX/2bit-lite") prompt = apply_chat_template(processor, model.config, "이 이미지를 설명하세요.", num_images=1) print(generate(model, processor, prompt, ["photo.jpg"], max_tokens=256, verbose=True))

유지하십시오--max-tokens적당히. H200 필드 노트 실행에서 2bit-lite는 대략 10 tok/s를 유지하므로, 1,024-토큰 답변은 이미 2분을 기다리는 셈입니다. 그리고 긴 출력은 KV 예산과 품질 저하가 문제가 되는 지점입니다(아래 참조). 노트북에서는 측정된 수치가 나오기 전까지는 더 빠르지 않고 오히려 더 느릴 것으로 예상해야 합니다.

실제로 받고 있는 품질 (측정된 사다리)

이것이 플레이북의 솔직한 부분이며, 우리는 얼버무리지 않겠습니다. OrcaSAQ는 3비트까지 우아하게 성능이 저하되며, 그 이후에는 비용이 급격히 증가합니다. FP8 기준(혼란도 2.7797)과 비교하면:

• 6-bit — perplexity 2.7864 (+0.24%), top-1 토큰 일치율 97.76%. 광고한 대로 거의 무손실입니다.

• 4-bit — perplexity 2.8620 (+2.96%), top-1 96.13%. 권장 기본값입니다.

• 3-bit — 퍼플렉서티 3.0566 (+9.96%), top-1 92.06%. 과감하지만 사용 가능한 수준.

• 2-bit — perplexity 4.3622 (+56.9%), top-1 86.56%. 실질적인 비용이 따른다.

• 2bit-liteperplexity 6.7018 (+141%), top-1 77.19%. 가장 작은 빌드이며, MacBook Pro에 수용할 수 있는 유일한 빌드입니다.

그것들은 우리 자체 변환 파이프라인에서 측정된 수치입니다. 2bit-lite는 perplexity가 141% 악화되고 top-1 토큰 일치율이 78% 미만입니다. 지금 실행 중인 모델은 눈에 띄게 성능이 저하된 모델이며, 아래의 실패 양상들이 실제로 그러한 저하가 어떻게 나타나는지 보여줍니다. 그것은 훌륭한 데모이자 합리적인 단문 어시스턴트이지만, 전체 정밀도 모델을 대체할 수는 없습니다.

속도에 관해서도, 우리는 여러분께 동일한 정직함을 보여드립니다. 공개된 필드 노트에 따르면 H200은 약 10 tok/s로, 안정적인 멀티 턴과 일상적인 Q&A, 짧은 형식의 텍스트에 적합합니다. 우리는 아직 2bit-lite에 대한 측정된 MacBook Pro 수치가 없으며, 이를 지어내지 않을 것입니다. Apple Silicon 처리량은 메모리 대역폭, 열 특성, 하이브리드 어텐션에 대한 MLX 커널 적용 범위에 따라 달라지는데, 우리는 이 노트북의 이 빌드에 대해 그 어떤 것도 측정하지 않았습니다. 우리가 참고할 수 있는 가장 가까운 공개 Apple Silicon 데이터 포인트는 다른 MLX 런타임에서 512GB Mac의 4비트 GLM-5.3-Flash 빌드에 대한 독립적인 약 450 tok/s 수치입니다. 이는 다른 빌드, 다른 정밀도, 데스크톱 머신이므로 여러분의 수치로 해석하지 마십시오. 느리게 계획하세요. 그렇지 않다면 기분 좋게 놀라게 될 것입니다.

KV cache 및 긴 컨텍스트: 헤드룸에 유의하세요

GLM-5.3-Flash는 1M 토큰 컨텍스트 윈도우를 광고합니다. 그 숫자는 이 하드웨어에서는 무의미하며, 그렇지 않은 척하는 사용법은 오히려 도움이 되지 않습니다. 현장 메모는 한 줄입니다: 런타임에 목표 길이에 맞는 충분한 KV 예산을 할당하세요. 단일 H200에서 2bit-lite는 가중치를 로드한 후 KV 캐시를 위해 약 39GB의 여유 공간을 남깁니다. 128GB MacBook Pro에서는 계산이 더 가혹합니다: ~112GB 상한에서 ~102GB의 가중치를 빼면 macOS 자체 작업 세트를 제외하고 약 26GB가 남습니다. 그리고 하이브리드 선형 어텐션 레이어 덕분에 이 모델의 KV 메모리 사용량은 이 크기의 밀집 모델에 비해 작지만, 여전히 컨텍스트에 따라 선형적으로 증가합니다.

광범위한 커뮤니티의 서빙 측 지침도 이 점을 뒷받침합니다: 8K 컨텍스트에서는 잘 로드되는 구성이 128K에서는 메모리가 부족해질 수 있습니다. 노트북에서는 컨텍스트를 짧게 유지하세요 — 수천 토큰의 Q&A나 단일 이미지 정도 — 책 전체를 입력으로 넣으려 하지 마세요. 워크로드가 정말로 긴 컨텍스트를 필요로 하는 순간, 당신은 이 글의 마지막 섹션에서 다루는 상황에 있습니다.

긴 코드 생성은 2bit-lite에서 신뢰할 수 없습니다 (이것을 두 번 읽으세요)

이 섹션은 실패 모드를 숨기는 하우투가 없다면 쓸모없게 될 부분이므로, 별도의 제목을 붙인다. H200 필드 노트는 모호함이 없다. 일상적인 Q&A와 짧은 형식의 텍스트는 잘 나오지만, 긴 코드 생성은 이 정밀도에서는 신뢰할 수 없다. 검증 실행에서 재현된 세 가지 실패 모드는 다음과 같다.

• 반복 루프 — 모델이 진전을 보이지 않고 동일한 줄이나 블록을 반복하기 시작하며, 보통 수백 개의 토큰이 지난 시점에 발생합니다.

• 누락된 글루 코드 — 임포트, 연결, 오류 처리가 조용히 누락되었습니다. 생성된 함수는 단독으로 보면 올바르게 보이지만, 주변 스캐폴딩이 전혀 없기 때문에 실행되지 않습니다.

• 재작성 남발 — 최소한의 편집 대신 모델이 파일의 큰 부분을 재작성하며, 연속된 턴마다 서로 다른 출력을 내놓습니다.

이것들은 2bit-lite에서 재현 가능하며, 그것들은 77% top-1 일치도가 예측하는 바로 그 것들입니다. 랩톱 빌드를 유지하는 실무자들이 실제로 하는 일:

• 사용하세요: 설명, 요약, Q&A, 이미지 이해 — 정말 잘하는 단문 작업입니다.

• 코드를 요청해야 한다면, 한 번에 하나의 작은 함수를 명시적 시그니처와 함께 요청하고, 다음으로 넘어가기 전에 각각을 검증하세요. 전체 파일을 건네주고 기능을 요청하지 마세요.

• 긴 작업 — 전체 모듈, 리팩터링, 긴 에이전트 세션 — 은 전체 정밀도 API로 라우팅하세요. 그것은 임시방편이 아니라 올바른 아키텍처이며, 마지막 섹션입니다.

이 작업을 전혀 수행하지 말아야 할 경우: 대신 z-ai/glm-5.3-flash를 호출하세요.

솔직한 결정 규칙: 128 GB M4/M5 Max MacBook Pro에서 2bit-lite를 실행하는 것은, 320B 멀티모달 모델을 구체적으로 원할 때만입니다.휴대할 수 있는 노트북에서 — 오프라인 Q&A, 개인 문서, 기계 밖으로 나가지 않는 이미지 이해. 그 외 모든 경우에는 API를 선택하세요:

• 128GB 미만의 모든 MacBook Pro — 사용자를 위한 빌드가 없습니다. 로드하지 마시고 API를 사용하세요.

• 긴 코드 생성 또는 긴 컨텍스트 추론 — 2bit-lite는 정확히 이 점에서 확실히 실패합니다. API를 사용하세요.

• 품질에 민감한 작업 — 77.19% top-1 일치율과 +141% 혼란도는 실제 하락이지 반올림 오류가 아닙니다. API를 사용하세요.

• 보장된 처리량 또는 예측 가능한 지연 시간 — 아직 측정된 노트북 수치는 없으며, 현장 기록은 10 tok/s입니다. API를 사용하세요.

호스팅 모델은 z-ai/glm-5.3-flash이며, OrcaRouter에서 전체 정밀도로 제공되며, Z.ai의 현재 가격 기준 — 입력 토큰 100만 개당 $0.07, 출력 토큰 100만 개당 $0.25 (이 글을 쓰는 시점 기준)입니다 (출시 기간 가격이며, Z.ai의 공시 가격은 $0.15 / $0.50입니다). 이는 공급업체가 보고한 가격이며, 0% 마크업으로 전달되므로 Z.ai의 가격 인하는 같은 날 저희 쪽에도 반영됩니다. 하나의 API 키로 저희가 라우팅하는 다른 200개 이상의 모델에도 접근할 수 있으며, 자동 장애 조치 덕분에 이 새 모델로 실험하더라도 프로덕션 경로가 단일 공급업체에만 의존하지 않습니다. 102GB를 다운로드하고 첫 콜드 생성을 기다리는 시간 동안, API는 이미 일주일치 질문에 답변을 마쳤으며 — 전체 정밀도로 답변합니다.

로컬 추론은 이유가 로컬일 때 가치가 있습니다 — 프라이버시, 오프라인 작업, 요금 제한 없음, 배터리로 실행되는 데모를 위해서입니다. 다른 어떤 이유로든 비용이나 품질 계산상으로는 가치가 없으며, 128GB 미만의 머신에서는 전혀 가치가 없습니다.

자주 묻는 질문

64GB 또는 96GB Mac에서 GLM-5.3-Flash를 로컬로 실행할 수 있나요? 아니요. 가장 작은 빌드인 2bit-lite는 macOS 오버헤드를 감안하면 최소 약 112GB가 필요하며, 128GB 머신이라도 로드하려면 고정 메모리 한도를 높여야 합니다. Mac이 128GB 미만이라면 로컬 경로는 존재하지 않습니다. 대신 z-ai/glm-5.3-flash를 API를 통해 사용하세요.

mlx-vlm을 설치했는데 모델이 로드되지 않습니다. 무엇이 문제인가요? 일반적인 두 가지 원인은 순서대로 다음과 같습니다. 첫째, 0.6.17 미만 버전입니다. glm5_next 지원 이전 버전이므로 아키텍처를 인식하지 못합니다. 둘째, wired-memory 제한이 올라가지 않은 경우입니다. 128GB Mac의 기본 Metal 상한이 ~91–96GB이므로 ~102GB 빌드는 메모리를 할당할 수 없습니다. 두 가지를 모두 해결하면(패키지 업그레이드, sysctl 실행) 로드됩니다.

로컬 2bit-lite 빌드가 z-ai/glm-5.3-flash API와 같은 모델인가요? 동일한 기본 GLM-5.3-Flash 가중치를 사용하지만 품질은 동일하지 않습니다. 2bit-lite는 FP8 기준 대비 77.19%의 top-1 토큰 일치율을 보이는 2비트 양자화 버전이며, 긴 코드 생성에는 신뢰할 수 없습니다. API는 전체 정밀도를 제공합니다. 두 모델은 짧은 형식의 품질 관용 작업에만 상호 교환 가능합니다.

30초 버전

하나의 머신, 하나의 빌드, 하나의 필수 sysctl. 128GB M4/M5 Max MacBook Pro가 있다면: 설치하세요 mlx-vlm>=0.6.17, 다음만 다운로드하세요: 2bit-lite/ (~102GB), wired-memory 한도를 올리세요: sudo sysctl iogpu.wired_limit_mb=114688, 그리고 실행하세요: mlx_vlm.generate — Q&A, 짧은 텍스트, 이미지용입니다. 이 정밀도에서는 긴 코드 생성이 신뢰할 수 없고, 측정된 노트북 처리량이 아직 없으며, 128GB Mac이 최소 사양이지 표준이 아님을 감수하세요. 이러한 주의 사항 중 하나라도 문제가 된다면 — 또는 Mac이 128GB 미만이라면 — 동일한 모델을 전체 정밀도로 사용하는 것은 z-ai/glm-5.3-flash.

128GB Mac이 아니신가요? z-ai/glm-5.3-flash는 OrcaRouter에서 동일한 모델을 전체 정밀도로 제공합니다 — API 키 하나로 충분하며, 공급자 가격을 0% 마크업으로 그대로 전달하고, 102GB 다운로드가 필요 없습니다.