로컬 LLM 구축 방법｜Mac에서 mlx-serve 실행·검증

mlx-serve와 Qwen3-4B-4bit를 Mac에 설치하고, 로컬에서 모델을 실행해 API 응답을 확인했습니다. 아래 소요 시간과 속도는 2026년 11월 5일과 6일에 Apple M1 Max, 64 GB 메모리, macOS 26.6 환경에서 얻은 값입니다. 다른 Mac에서 같은 값이 나온다고 보장하지 않습니다.

사용 조건과 라이선스

사용한 파일은 GitHub Releases v26.11.1의 mlx-serve-bin-macos-arm64.tar.gz입니다. mlx-serve 본체는 MIT 라이선스이고, 함께 포함된 서드파티 구성 요소에는 Apache-2.0과 BSD 고지가 있으며 배포물의 NOTICE 파일에서 확인할 수 있습니다. 모델은 mlx-community/Qwen3-4B-4bit로, 원본 Qwen/Qwen3-4B를 바탕으로 Apache-2.0으로 배포됩니다. 사용하기 전에 내려받은 배포물의 LICENSE·NOTICE와 모델의 라이선스 표기를 확인하세요. 공식 문서에는 DMG와 Homebrew 설치 안내도 있지만, 여기서는 시도하지 않았습니다.

아카이브를 확인하고 실행 파일 찾기

공식 GitHub Releases의 v26.11.1에서 아카이브를 내려받았습니다. ARCHIVE, UNPACK_DIR 두 변수는 실제 저장 위치에 맞게 바꾸세요. 두 경로를 맞춘 상태에서 zsh와 bash 양쪽으로 이 절차를 실행했습니다. SHA-256이 일치하지 않으면 압축을 풀지 않고, 실행 파일이나 버전을 확인하지 못하면 다음 단계로 넘어가지 않습니다. 명령은 실제로 실행한 그대로 실었기 때문에 출력 메시지가 일본어입니다.

ARCHIVE="$HOME/Downloads/mlx-serve-bin-macos-arm64.tar.gz"
UNPACK_DIR="$HOME/Downloads/mlx-serve-v26.11.1"
if ! printf '%s  %s\n' '9acaa7a21b294536c3db9f2683d85079727b4e8db725d34260020499523dc267' "$ARCHIVE" | shasum -a 256 -c -; then
  printf '%s\n' 'SHA-256が一致しません。ここで中止してください。' >&2
elif ! mkdir -p "$UNPACK_DIR" || ! tar -xzf "$ARCHIVE" -C "$UNPACK_DIR"; then
  printf '%s\n' '解凍できませんでした。ここで中止してください。' >&2
else
  BIN="$(find "$UNPACK_DIR" -type f -name mlx-serve -print -quit)"
  if [ -z "$BIN" ] || [ ! -x "$BIN" ]; then
    unset BIN
    printf '%s\n' '実行可能な mlx-serve が見つかりません。' >&2
  elif ! "$BIN" --version; then
    unset BIN
    printf '%s\n' 'バージョンを確認できませんでした。' >&2
  fi
fi

SHA-256은 일치했고, --version의 첫 줄은 mlx-serve 26.11.1 (fast)였습니다. 배포물의 서명 팀 ID는 S77TW432YG(David Dalcu의 Developer ID)였습니다. 위 명령에는 서명 검증이 포함되어 있지 않습니다. BIN에는 압축을 푼 위치에서 찾은 실행 파일 경로가 들어갑니다. 다음 단계도 같은 터미널에서 실행합니다.

모델을 내려받아 실행하기

모델을 내려받으려면 네트워크 연결이 필요합니다. 11월 5일 처음 내려받을 때는 파일 9개, 총 2,173 MB를 받는 데 약 54초가 걸렸습니다. 모델은 ~/.mlx-serve/models/에 저장됩니다. 11월 6일에는 모델이 이미 있어서 pull이 다시 내려받지 않고 진행되었습니다.

if [ -n "${BIN:-}" ] && [ -x "$BIN" ]; then
  "$BIN" pull mlx-community/Qwen3-4B-4bit &&
  "$BIN" --model "$HOME/.mlx-serve/models/mlx-community/Qwen3-4B-4bit" --serve --host 127.0.0.1 --port 11234
else
  printf '%s\n' '先にアーカイブとバージョンを確認してください。' >&2
fi

실행하고 몇 초 안에 Server listening on http://127.0.0.1:11234가 표시되었습니다. 컨텍스트 길이는 남은 메모리에 따라 자동으로 정해지며, 같은 Mac에서도 12,288 토큰일 때와 870 토큰일 때가 있었습니다.

--host 127.0.0.1은 생략하지 않습니다. 공식 cli.md는 기본값을 0.0.0.0으로, SECURITY.md는 127.0.0.1로 적고 있어 문서끼리 일치하지 않기 때문입니다. 여기서는 LAN에 공개하지 않습니다.

API 응답 확인하기

서버를 켜 둔 채 다른 터미널에서 아래 순서대로 실행하고, HTTP 상태 코드와 저장한 응답을 확인했습니다. x-api-key: local-test는 로컬 요청에 사용한 값입니다. 프롬프트는 실제로 보낸 그대로 일본어이며, 결과마다 번역을 덧붙였습니다.

OpenAI 호환 · 일반 응답

OUT_DIR="$(mktemp -d)"
curl -sS -o "$OUT_DIR/chat.json" -w 'HTTP %{http_code}\n' \
  -H 'Content-Type: application/json' \
  --data-binary @- http://127.0.0.1:11234/v1/chat/completions <<'JSON'
{"model":"mlx-community/Qwen3-4B-4bit","max_tokens":128,"messages":[{"role":"user","content":"ローカルLLMとは何か、3文で説明してください。"}]}
JSON
python3 -m json.tool --no-ensure-ascii "$OUT_DIR/chat.json"

11월 6일 응답은 HTTP 200이었습니다. 65개 토큰을 생성했고 속도는 81.0 tokens/초였습니다. 프롬프트는 로컬 LLM이 무엇인지 세 문장으로 설명해 달라는 내용이었고, 답변은 “ローカルLLMとは、自社や組織のサーバー内に置かれる人工知能モデルのことです。”(로컬 LLM이란 자사나 조직의 서버 안에 두는 인공지능 모델을 말합니다.)로 시작했습니다.

OpenAI 호환 · 스트리밍

curl -sSN -o "$OUT_DIR/stream.sse" -w 'HTTP %{http_code}\n' \
  -H 'Content-Type: application/json' \
  --data-binary @- http://127.0.0.1:11234/v1/chat/completions <<'JSON'
{"model":"mlx-community/Qwen3-4B-4bit","max_tokens":64,"stream":true,"messages":[{"role":"user","content":"日本の首都はどこですか。短く答えてください。"}]}
JSON
grep '^data:' "$OUT_DIR/stream.sse"

HTTP 200이었습니다. data: 줄이 차례로 돌아왔고, 마지막 줄은 data: [DONE]이었습니다. 프롬프트는 일본의 수도를 짧게 답해 달라는 내용이었고, 답은 “東京”(도쿄)였습니다.

Anthropic 호환 · Messages API

curl -sS -o "$OUT_DIR/messages.json" -w 'HTTP %{http_code}\n' \
  -H 'Content-Type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'x-api-key: local-test' \
  --data-binary @- http://127.0.0.1:11234/v1/messages <<'JSON'
{"model":"mlx-community/Qwen3-4B-4bit","max_tokens":64,"messages":[{"role":"user","content":"推論を英語で一語で説明してください。"}]}
JSON
python3 -m json.tool --no-ensure-ascii "$OUT_DIR/messages.json"

HTTP 200이었습니다. 프롬프트는 일본어 ‘推論’(추론)을 영어 한 단어로 설명해 달라는 내용이었고, 답은 “Inference.”, stop_reason은 end_turn이었습니다. 이 Mac에서 관측한 생성 속도는 34~90 tokens/초였습니다. 동시에 실행 중인 작업에 따라 달라지며, 다른 기종의 속도를 나타내는 값이 아닙니다.

오류와 검증하지 않은 사항

SHA-256이 일치하지 않으면 그 배포물은 실행하지 마세요. 11월 6일에는 다른 프로그램이 GPU 메모리를 쓰고 있는 상태에서 같은 요청 3개가 모두 HTTP 400을 반환했습니다. 오류 메시지는 “Prompt (29 tokens) requires ~661MB GPU memory but only ~53MB is available …”였습니다. 이 오류가 나오면 먼저 메모리를 쓰고 있는 프로그램을 닫고 다시 시도하세요. 그 밖의 HTTP 오류는 저장한 응답과 서버 로그를 확인하세요.

네트워크를 끊은 상태에서의 실행, 앱, Homebrew, GGUF는 검증하지 않았습니다. 분석·텔레메트리가 없다는 설명은 공식 FAQ에 적힌 내용이며, 저희가 통신을 측정한 결과가 아닙니다. 평가 방법을 더 깊이 알아보려면 파인튜닝한 어댑터를 출시 전에 확인하는 방법을 참고하세요.

Mac에서 로컬 LLM 구축하기: mlx-serve 설치와 API 검증