Hướng dẫn thiết lập Coding Agent cục bộ trên macOS với Gemma 4 và MTP

Gần đây, việc mất kết nối Internet đã khiến tôi bị "mắc kẹt" mà không có sự hỗ trợ của các công cụ AI lập trình. Điều này thúc đẩy tôi tìm hiểu tính năng Multi-Token Prediction (MTP) mới của Gemma 4, được quảng cáo là giúp mô hình chạy nhanh gấp đôi. Mục tiêu của tôi là xây dựng một hệ thống coding agent chạy cục bộ (local) đáp ứng đủ các tiêu chí: tốc độ xử lý thực tế tốt trên Mac, tương thích với API chuẩn của OpenAI để dễ dàng tích hợp vào các công cụ khác, và quan trọng nhất là có khả năng xử lý hình ảnh để tôi có thể gửi ảnh chụp màn hình (screenshot) cho agent phân tích.

Video demo hiệu năng Gemma 4

Sau quá trình thử nghiệm và tinh chỉnh, tôi đã thiết lập thành công một hệ thống vận hành mượt mà trên máy Apple M1 Max (64GB unified memory) chạy macOS 15.7.7. Video dưới đây cho thấy agent phản hồi với tốc độ hoàn toàn có thể sử dụng được trong thời gian thực.

Cấu hình hệ thống tối ưu

Để đạt được hiệu năng tốt nhất, bộ đôi phần mềm và mô hình sau đây đã được lựa chọn:

• Runtime: llama.cpp (biên dịch với hỗ trợ Metal trên macOS).
• Mô hình chính: Gemma 4 26B-A4B (định dạng GGUF).
• Mô hình nháp (Draft Model): Q8 MTP (dùng cho speculative decoding).
• Hỗ trợ đa phương tiện: Gemma 4 multimodal projector.
• Coding Agent: Pi (chạy trên terminal).

Mô hình chính gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf có dung lượng khoảng 16GB. Khi kết hợp với MTP draft head và multimodal projector, tổng dung lượng thư mục model khoảng 17GB.

Tăng tốc với MTP Draft Model

Điểm nhấn của bản thiết lập này là việc sử dụng kỹ thuật Multi-Token Prediction (MTP). Ban đầu, khi chạy trực tiếp Gemma 4 qua llama.cpp với tăng tốc Metal, tốc độ tạo token (generation) chỉ đạt 58.2 tokens/giây. Mặc dù con số này vẫn dùng được, nhưng đối với công việc lập trình cần nhiều lần gọi công cụ (tool calls), tốc độ càng nhanh càng tốt.

Sau khi thêm MTP draft model và tinh chỉnh tham số --spec-draft-n-max, tốc độ đã được cải thiện đáng kể. Trên máy M1 Max của tôi, giá trị tối ưu là 3 draft tokens, giúp đẩy tốc độ lên 72.2 tokens/giây.

Thử nghiệm offline với Gemma 4

So sánh cho thấy việc sử dụng MTP draft model giúp tăng tốc độ tạo văn bản lên khoảng 24% mà không làm giảm tốc độ xử lý prompt (prompt processing). Điều này khiến llama.cpp vượt trội hơn so với MLX trong bài kiểm tra cụ thể này, dù MLX được tối ưu hóa riêng cho nền tảng Mac.

Thêm hỗ trợ hình ảnh

Để coding agent Pi có thể hiểu và phân tích ảnh chụp màn hình, tôi cần kích hoạt tính năng đa phương tiện. Llama.cpp server yêu cầu tệp mmproj-BF16.gguf (Gemma 4 multimodal projector) để xử lý phần này.

Trong cấu hình của Pi, điều quan trọng là phải khai báo input bao gồm cả "text" và "image". Nếu chỉ khai báo "text", Pi sẽ không gửi dữ liệu hình ảnh đến mô hình. May mắn thay, việc tải projector này không làm giảm tốc độ xử lý văn bản của hệ thống.

Hướng dẫn cài đặt chi tiết

Dưới đây là các bước tổng quan để thiết lập hệ thống này trên máy Mac của bạn.

1. Cài đặt và biên dịch llama.cpp

Đầu tiên, cài đặt các thư viện cần thiết và clone mã nguồn llama.cpp:

brew install cmake git tmux [email protected]
mkdir -p ~/Developer/ML-Models/Gemma4/repos
cd ~/Developer/ML-Models/Gemma4
git clone https://github.com/ggml-org/llama.cpp repos/llama.cpp
cd repos/llama.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_METAL=ON -DGGML_ACCELERATE=ON
cmake --build build --config Release -j

2. Tải mô hình

Sử dụng huggingface-cli để tải các tệp mô hình cần thiết:

mkdir -p models/unsloth-gemma-4-26B-A4B-it-GGUF
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. Khởi chạy Server

Bạn có thể sử dụng lệnh sau để khởi động server llama.cpp với API tương thích OpenAI (cổng 8080):

repos/llama.cpp/build/bin/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. Cấu hình Pi Agent

Pi cần được cấu hình để nhận diện server local này. Trong tệp ~/.pi/agent/models.json, thêm provider mới:

{
  "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
        }
      ]
    }
  }
}

Bây giờ bạn có thể chạy Pi offline để lập trình hoặc phân tích ảnh:

pi --provider gemma4-local --model gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf

Thử nghiệm với Qwen3.6

Một số gợi ý cho rằng Qwen3.6 35B-A3B là một coding agent xuất sắc hơn Gemma 4. Tôi cũng đã thử nghiệm mô hình này. Tuy nhiên, trên cấu hình của tôi, Qwen3.6 chậm hơn đáng kể, chỉ đạt khoảng 55 tokens/giây so với 72 tokens/giây của Gemma 4.

Thử nghiệm offline với Qwen 3.6

Nếu bạn ưu tiên tốc độ phản hồi khi ngồi chờ agent hoàn thành tác vụ, Gemma 4 kết hợp với MTP draft model là lựa chọn hợp lý hơn tại thời điểm này.

Kết luận

Việc thiết lập một coding agent cục bộ không còn quá phức tạp nhờ vào sự tối ưu hóa của llama.cpp và các mô hình GGUF. Với sự hỗ trợ của MTP draft model, Gemma 4 đã đạt được tốc độ xử lý ấn tượng trên phần cứng Mac, biến nó thành một trợ lý lập trình mạnh mẽ, riêng tư và không phụ thuộc vào Internet.