macOS에서 Gemma 4와 llama.cpp를 사용하여 로컬 코딩 에이전트 설정하기

llama.cpp와 Gemma 4 26B 및 **Multi-Token Prediction (MTP)**를 결합하면 macOS에서 사용 가능한 실시간 성능을 구현하는 로컬 코딩 에이전트 설정을 구축할 수 있습니다. 64GB 통합 메모리를 갖춘 Apple M1 Max에서 이 구성은 생성 속도를 초당 58.2개에서 72.2개 토큰으로 증가시켜, 에이전트 도구 호출 및 코딩 작업에 대한 반응성 높은 경험을 제공합니다.

llama.cpp를 이용한 고성능 로컬 추론

macOS 사용자에게 Metal 가속을 사용하여 빌드된 llama.cpp는 일반적으로 특정 구성에서 MLX-LM보다 뛰어난 성능을을 보여줍니다. 두 가지를 비교하는 벤치마크에서, MTP를 사용하는 llama.cpp는 72.2 tok/s에 도달한 반면, 다양한 MLX-LM 4-bit 구현체는 38.1에서 45.8 tok/s 범위에 머물렀습니다.

Multi-Token Prediction (MTP)의 역할

Multi-Token Prediction (MTP)은 추측적 초안 모델(speculative draft model)을 사용하여 여러 토큰을 한 번에 예측하여, 정확도를 희생하지 않고 생성 처리량을 크게 증가시킵니다.

M1 Max에서 --spec-draft-n-max 파라미터를 다양한 값으로 테스트한 결과, 3이 최적의 값으로 나타났으며 72.2 tok/s를 기록했습니다. 성능은 초안 토큰이 3개일 때 정점에 도달했으며, 값이 6을 향해 증가함에 따라 감소하기 시작했습니다.

--spec-draft-n-max Prompt tok/s Generation tok/s
1 295.5 68.4
2 299.1 72.0
3 295.6 72.2
4 297.3 70.7
5 297.9 63.7
6 296.3 61.2

멀티모달 기능 및 이미지 지원

코딩 에이전트가 스크린샷이나 UI 이미지를 처리할 수 있도록 하려면 멀티모달 프로젝터(multimodal projector)가 필요합니다. Gemma 4 12B 모델은 네이티브 멀티모달이지만, 26B 버전은 llama.cpp에서 --mmproj 플래그를 통해 로드되는 mmproj-BF16.gguf 프로젝터를 필요로 합니다.

멀티모달 프로젝터를 추가해도 텍스트 생성 속도에 측정 가능한 저하가 발생하지 않으며, 72.2 tok/s 벤치마크를 유지합니다.

단계별 설치 가이드

1. llama.cpp 설치

필요한 종속성을 설치하고 Metal 및 Accelerate 지원을 포함하여 llama.cpp를 빌드합니다:

brew install cmake git tmux python@3.11

# Clone and build
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DGGML_METAL=ON \
  -DGGML_ACCELERATE=ON

cmake --build build --config Release -j

2. 모델 파일 다운로드

huggingface-cli를 사용하여 메인 모델, MTP 초안 모델, 그리고 멀티모달 프로젝터를 다운로드합니다:

pip install -U huggingface_hub hf_xet

# Download Gemma 4 26B-A4B
huggingface-cli download unsloth/gemma-4-26B-A4B-it-GGUF \
  gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  mmproj-BF16.gguf \
  MTP/gemma-4-26B-A4B-it-Q8_0-MTP.gguf \
  --local-dir models/unsloth-gemma-4-26B-A4B-it-GGUF

3. 로컬 서버 시작

llama-server를 실행하여 http://127.0.0.1:8080/v1에서 OpenAI-compatible endpoint를 생성합니다:

./llama-server \
  -m models/unsloth-gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  --model-draft models/unsloth-gemma-4-26B-A4B-it-GGUF/MTP/gemma-4-26B-A4B-it-Q8_0-MTP.gguf \
  --mmproj models/unsloth-gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf \
  --spec-type draft-mtp \
  --spec-draft-n-max 3 \
  -ngl 999 \
  -fa on \
  -c 65536 \
  --parallel 1 \
  --host 127.0.0.1 \
  --port 8080

4. Pi 코딩 에이전트 구성

Pi가 llama.cpp 서버와 통신할 수 있도록 ~/.pi/agent/models.json에 로컬 프로바이더를 추가합니다. 멀티모달 지원을 활성화하기 위해 input 필드에 text와 image를 모두 포함해야 합니다:

{
  "providers": {
    "gemma4-local": {
      "name": "Gemma 4 Local",
      "baseUrl": "http://127.0.0.1:8080/v1",
      "api": "openai-completions",
      "apiKey": "local",
      "authHeader": false,
      "models": [
        {
          "id": "gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf",
          "name": "Gemma 4 26B-A4B Q4 + MTP",
          "input": ["text", "image"],
          "contextWindow": 65536,
          "maxTokens": 8192
        }
      ]
    }
  }
}

대안 모델: Qwen 3.6

Gemma 4가 더 빠르지만, 일부 사용자들은 품질 측면에서 Qwen 3.6 35B-A3B를 더 우수한 코딩 에이전트로 제안합니다. 하지만 이는 속도의 희생을 수반합니다. 벤치마크에 따르면 Gemma 4의 72 tok/s에 비해 약 55 tok/s로 생성합니다. 순수 속도보다 정확도를 우선시하는 사용자라면, 유사한 llama.cpp 설정을 사용하여 Qwen 3.6를 사용할 수 있는 실행 가능한 대안이 됩니다.

커뮤니티 인사이트 및 반론

개발자들 사이의 논의는 몇 가지 트레이드오프와 대안 도구구들을 강조했습니다:

  • 벤치마크 정확도: 일부 사용자들은 짧은 벤치마크(예: 128 토큰)가 MTP 속도 향상을 과장할 수 있다고 지적했습니다. 응답의 시작 부분에서 수락률(acceptance rates)이 종종 더 높기 때문입니다.
  • simplified tooling: 여러 기여자는 Ollama, LM Studio, 또는 oMLX와 같은 도구들이 llama.cpp를 소스에서 빌드하는 것보다 더 간소화된 설정 과정을 제공한다고 제안했습니다.
  • Model Quality vs. Speed: 반복적으로 제어기된 비판은 토큰 생성 속도는 모델이

Sources