Hướng dẫn AI

Chạy mô hình AI cục bộ nhanh trên Apple Silicon với Splash

Tìm hiểu cách cài đặt Splash trên máy Mac được hỗ trợ, khởi chạy máy chủ mô hình, gọi API tương thích OpenAI, kết nối tác nhân lập trình, quản lý bộ nhớ và giới hạn ngữ cảnh, bật xác thực cũng như tối ưu quy trình suy luận cục bộ nâng cao.

19 tháng 9, 2026Thời gian đọc khoảng 20 phút

Chạy mô hình AI cục bộ nhanh trên Apple Silicon với Splash

Splash là gì?

Splash là một công cụ suy luận cục bộ được thiết kế riêng cho Apple silicon. Công cụ này cung cấp các mô hình ngôn ngữ đã được tối ưu hóa cho các tác nhân lập trình và ứng dụng hỗ trợ API OpenAI hoặc Anthropic. Máy chủ chạy cục bộ trên một máy Mac và cung cấp API tại 127.0.0.1:8000.

Khác với công cụ suy luận đa năng, Splash chuyên biệt hóa các kernel, mô hình nháp cho giải mã suy đoán, bố cục trọng số và kế hoạch bộ nhớ cho từng mô hình được hỗ trợ. Các gói mô hình đã sẵn sàng để chạy, vì vậy bạn không cần Xcode, bộ công cụ biên dịch hoặc tinh chỉnh riêng cho từng mô hình.

Tính năng chính

Suy luận cục bộ trên Apple silicon: Splash chạy mô hình trực tiếp trên máy Mac được hỗ trợ.
Tương thích với OpenAI: Công cụ cung cấp Chat Completions tại /v1/chat/completions và Responses tại /v1/responses.
Tương thích với Anthropic: Các yêu cầu Anthropic Messages có sẵn tại /v1/messages.
Hỗ trợ yêu cầu nâng cao: API hỗ trợ truyền trực tiếp, gọi công cụ, đầu ra JSON Schema, hình ảnh và PDF nội tuyến.
Tích hợp tác nhân lập trình: Splash bao gồm các lệnh cho OpenCode, Claude, Codex và Hermes.
Tăng tốc theo từng mô hình: Mỗi gói mô hình bao gồm một bản nháp DFlash 2 cho giải mã suy đoán và các kernel Metal được biên dịch sẵn, tinh chỉnh theo đúng kích thước của mô hình.
Lập kế hoạch bộ nhớ tự động: Khi khởi động, Splash tính toán ngữ cảnh, dung lượng bộ nhớ đệm KV và giới hạn batch dựa trên bộ nhớ khả dụng cho Metal.
Kiểm tra prompt: Các endpoint /tokenize và /apply-template trả về ID token hoặc prompt đã kết xuất mà không chạy suy luận.

Yêu cầu hệ thống

Trước khi cài đặt Splash, hãy xác nhận hệ thống của bạn đáp ứng tất cả các yêu cầu sau:

Bộ xử lý Apple M3 hoặc mới hơn
macOS 26.4 trở lên
Homebrew
Ít nhất 36 GB bộ nhớ hợp nhất
Khuyến nghị 48 GB bộ nhớ hợp nhất trở lên

Dung lượng ngữ cảnh có thể sử dụng phụ thuộc vào bộ nhớ khả dụng. Mặc dù các mô hình được hỗ trợ có cửa sổ ngữ cảnh gốc lên đến 256K, toàn bộ cửa sổ có thể không vừa trên mọi máy Mac.

Cài đặt Splash

Cài đặt bản phát hành đóng gói thông qua tap Homebrew của Inco:

brew install incoai/tap/splash

Bạn không cần tạo tệp cấu hình. Splash sử dụng cờ dòng lệnh và biến môi trường cho các tùy chọn thiết lập.

Khởi động máy chủ mô hình

Cung cấp gói Qwen3.8-27B đã được tối ưu hóa bằng lệnh sau:

splash serve --model incoai/Qwen3.8-27B-Splash

Trong lần chạy đầu tiên, Splash tải xuống và xác minh gói mô hình, kiểm tra bộ nhớ khả dụng, tạo kế hoạch bộ nhớ và khởi động máy chủ tại 127.0.0.1:8000. Gói Qwen3.8-27B có dung lượng tải xuống 17.4 GB và bao gồm mô hình mục tiêu 4-bit cùng bản nháp DFlash 2.

Chờ đến khi terminal in Ready. Giữ terminal đó mở trong khi sử dụng mô hình. Sau đó, bạn có thể mở http://127.0.0.1:8000 trong trình duyệt để truy cập trang trò chuyện.

Nhấn Ctrl+C trong terminal của máy chủ khi muốn dừng Splash.

Sử dụng mô hình thay thế

Splash cũng phát hành gói 20.9 GB chứa mô hình Qwen3.6-35B-A3B 4-bit và bản nháp DFlash 2 tương ứng:

splash serve --model incoai/Qwen3.6-35B-A3B-Splash

Tùy chọn --model có thể trỏ đến một kho lưu trữ owner/repo khác chứa gói Splash hợp lệ. Các checkpoint MLX và Transformers thông thường không tương thích. Đối với kho lưu trữ Hugging Face riêng tư, hãy cung cấp HF_TOKEN phù hợp.

Kết nối tác nhân lập trình

Sau khi máy chủ báo đã sẵn sàng, hãy mở một terminal khác và khởi chạy một trong các tác nhân lập trình đã cài đặt được hỗ trợ:

splash opencode
splash claude
splash codex
splash hermes

Chỉ chạy lệnh tương ứng với tác nhân bạn muốn sử dụng. Tiến trình máy chủ ban đầu phải tiếp tục hoạt động trong khi tác nhân gửi yêu cầu.

Gọi API OpenAI Chat Completions

Ứng dụng có thể gọi Splash như một máy chủ cục bộ tương thích với OpenAI. Yêu cầu sau đề nghị mô hình đang được cung cấp giải thích trong một câu:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "incoai/Qwen3.8-27B-Splash",
    "messages": [
      {
        "role": "user",
        "content": "Explain speculative decoding in one sentence."
      }
    ]
  }'

Thuộc tính model là tùy chọn. Nếu bao gồm thuộc tính này, giá trị phải khớp với gói hiện đang được cung cấp.

Chọn endpoint API phù hợp

Sử dụng /v1/chat/completions cho các ứng dụng khách OpenAI Chat Completions.
Sử dụng /v1/responses cho các ứng dụng khách OpenAI Responses.
Sử dụng /v1/messages cho các ứng dụng khách Anthropic Messages.
Sử dụng /tokenize để lấy ID token mà không chạy mô hình.
Sử dụng /apply-template để kiểm tra prompt đã kết xuất mà không chạy suy luận.

Điều khiển suy luận

Suy luận được bật theo mặc định. Để tắt, hãy thêm "reasoning_effort": "none" vào phần thân yêu cầu. Qwen3.8-27B cũng chấp nhận low, medium và xhigh.

{
  "model": "incoai/Qwen3.8-27B-Splash",
  "reasoning_effort": "none",
  "messages": [
    {
      "role": "user",
      "content": "Summarize speculative decoding."
    }
  ]
}

Việc tắt khả năng suy luận có thể hữu ích khi tác vụ không yêu cầu quá trình suy luận mở rộng. Đối với các tác vụ Qwen3.8-27B được hưởng lợi từ suy luận, hãy chọn mức độ phù hợp dựa trên khối lượng công việc.

Cấu hình giới hạn bộ nhớ và ngữ cảnh

Splash tự động xác định các giá trị mặc định phù hợp, nhưng splash serve cung cấp các cờ tùy chọn để kiểm soát chặt chẽ hơn:

--max-memory 28G đặt mức trần cho các vùng cấp phát Metal.
--max-context 100K giới hạn cửa sổ ngữ cảnh, tối đa theo giới hạn gốc 256K của mô hình.
--max-image-pixels kiểm soát số điểm ảnh tối đa sau khi thay đổi kích thước cho mỗi hình ảnh. Giá trị mặc định là 4,194,304.
--allowed-host cho phép thêm một tên Host HTTP, chẳng hạn tên được proxy sử dụng. Có thể lặp lại tùy chọn này.
--no-webui tắt trang trò chuyện trên trình duyệt.

Ví dụ, lệnh sau giới hạn vùng cấp phát Metal ở 28 GB và ngữ cảnh ở 100K:

splash serve \
  --model incoai/Qwen3.8-27B-Splash \
  --max-memory 28G \
  --max-context 100K

Nếu một mô hình không thể vừa trong bộ nhớ khả dụng, Splash sẽ in thông tin phân bổ ngân sách bộ nhớ rồi dừng thay vì khởi động một máy chủ không thể sử dụng. Giảm yêu cầu về ngữ cảnh hoặc bộ nhớ có thể hữu ích, nhưng trọng số mô hình và trạng thái thời gian chạy bắt buộc vẫn phải vừa trong bộ nhớ.

Bảo vệ API cục bộ

Xác thực bị tắt theo mặc định. Bạn có thể yêu cầu khóa bằng cách đặt SPLASH_API_KEY trong shell dùng để khởi động máy chủ:

export SPLASH_API_KEY='replace-with-your-key'
splash serve --model incoai/Qwen3.8-27B-Splash

Đặt cùng biến môi trường trong shell dùng để khởi chạy tác nhân lập trình do Splash quản lý:

export SPLASH_API_KEY='replace-with-your-key'
splash opencode

Các ứng dụng khách API có thể gửi khóa dưới dạng bearer token hoặc thông qua header x-api-key. Bạn cũng có thể cung cấp khóa trực tiếp bằng tùy chọn máy chủ --api-key. Các probe kiểm tra tình trạng và mức sẵn sàng vẫn công khai.

Mẹo nâng cao

Lập kế hoạch cho bộ nhớ đệm mô hình

Các gói đã tải xuống được lưu trong bộ nhớ đệm Hugging Face. Việc chạy brew upgrade splash giữ nguyên các gói, liên kết mô hình và phiên tác nhân, vì vậy nâng cấp engine không yêu cầu xóa chúng.

Sử dụng danh sách cho phép máy chủ với proxy

Máy chủ liên kết cục bộ với 127.0.0.1:8000. Nếu proxy cục bộ gửi một giá trị Host HTTP khác, hãy thêm tên máy chủ đó bằng --allowed-host. Lặp lại cờ này khi cần chấp nhận nhiều tên máy chủ.

Tắt giao diện web khi chỉ sử dụng API

Nếu Splash chỉ phục vụ ứng dụng hoặc tác nhân, hãy khởi động bằng --no-webui. Tùy chọn này tắt trang trò chuyện nhưng vẫn giữ các endpoint API được hỗ trợ.

Kiểm tra prompt trước khi suy luận

Sử dụng /tokenize khi cần các ID token hoặc /apply-template khi cần kiểm tra prompt đã kết xuất cuối cùng. Vì các endpoint này không chạy mô hình, chúng hữu ích để gỡ lỗi kích thước ngữ cảnh và định dạng prompt.

Thử nghiệm chuyển bộ nhớ đệm sang SSD

Một bản triển khai thử nghiệm trong pull request 3 có thể chuyển KV-cache và trạng thái GDN sang SSD. Hãy xây dựng nhánh đó rồi khởi động máy chủ với --max-cache-disk 8G để bật tính năng này. Tính năng có thể giữ lại các tiền tố có thể tái sử dụng khi RAM bị hạn chế và giảm công việc prefill lặp lại.

Tính năng chuyển bộ nhớ sang SSD đang trong giai đoạn thử nghiệm và không thuộc quy trình đóng gói tiêu chuẩn được mô tả trong phần bắt đầu nhanh.

Tìm hiểu hiệu năng Splash

Splash đạt tốc độ cao bằng cách chuyên biệt hóa hầu hết ngăn xếp suy luận cho từng mô hình. Giải mã suy đoán là đường dẫn giải mã tiêu chuẩn thay vì một chế độ tùy chọn. Bản nháp DFlash 2 dành riêng cho mô hình đề xuất các khối token, sau đó mô hình mục tiêu xác minh chúng song song.

Các kernel Metal hợp nhất được biên dịch cho đúng hình dạng của mô hình và đọc các trọng số được đóng gói đặc biệt, ánh xạ từ ổ đĩa mà không cần sao chép bổ sung. Khi khởi động, Splash cũng tính toán các giới hạn ngữ cảnh, bộ nhớ đệm và batch cho máy hiện tại.

Theo các phép đo của dự án trên M5 Pro với GPU 16 lõi và bộ nhớ 48 GB, Qwen3.8-27B đạt 74 token mỗi giây khi giải mã prompt ngắn và trả về token đầu tiên trong 282 ms khi phát lại ngữ cảnh 32K đã được lưu trong bộ nhớ đệm. Kết quả phụ thuộc vào mô hình, prompt, mức đồng thời, phần cứng và điều kiện bộ nhớ. Bài viết ra mắt Splash trình bày phương pháp đo chuẩn và các so sánh.

Kết luận

Splash cung cấp một cách hợp lý để chạy các mô hình được chọn và tối ưu hóa cao trên Apple silicon thế hệ mới. Cài đặt bằng Homebrew, khởi động gói mô hình Splash tương thích, rồi kết nối qua trình duyệt, tác nhân lập trình được hỗ trợ hoặc API tương thích với OpenAI hay Anthropic. Các giá trị mặc định tự động giúp thiết lập ban đầu đơn giản, trong khi các tùy chọn về bộ nhớ, ngữ cảnh, bảo mật, máy chủ và giao diện hỗ trợ những triển khai được kiểm soát chặt chẽ hơn.