ARahim3/mlx-dspark

mlx‑dspark란?

mlx‑dspark는 Apple 실리콘 Mac에서 추측 디코딩——텍스트 생성을 가속하는 기술——을 실행할 수 있게 해 주는 Python 패키지(그리고 macOS 앱)입니다. 원래 DeepSeek(DSpark)와 z‑lab(DFlash)이 공개한 두 가지 “드래프트 생성” 엔진을 탑재하고 있습니다. 두 엔진 모두 무손실입니다. 즉, 미리 여러 토큰을 제안한 뒤 실제 모델이 각 토큰을 검증하므로 최종 출력은 일반 디코딩과 완전히 동일하며, 단지 더 빠를 뿐입니다.

작동 방식

• 추측 디코딩: 빠른 “드래프터”가 짧은 토큰 시퀀스를 예측합니다. 그런 다음 전체 모델이 그 토큰들을 확인하여 모두 일치하면 블록 전체가 수락되고, 그렇지 않으면 일반 디코딩으로 폴백합니다. 드래프터는 저렴하기 때문에 전체 처리량이 2‑5배 더 높아질 수 있습니다.
• 두 드래프터 계열:
  • DSpark——DeepSeek의 DeepSpec 코드베이스에서 온 반자기회귀 드래프터.
  • DFlash——z‑lab의 블록 확산 드래프터.
• 이 패키지는 로드한 모델에 가장 적합한 드래프터를 자동으로 선택하며, 특정 드래프터를 강제할 수도 있습니다.
• 처음 사용할 때 Mac의 성능을 측정하고 최적의 드래프트 크기(--max-draft auto)를 선택합니다.

할 수 있는 일

1. CLI 생성——mlx-dspark generate --model <repo> --prompt "…".
2. 로컬 OpenAI 호환 서버——mlx-dspark serve …는 OpenAI(또는 Anthropic) API를 사용하는 모든 클라이언트(Ollama, Open WebUI, SillyTavern 등)와 작동하는 HTTP API를 제공합니다.
3. macOS GUI 앱——채팅, 모델 관리, 실시간 텔레메트리, 코딩 지원 에이전트의 원클릭 설정을 위한 클릭형 인터페이스.
4. Claude Code 및 Codex와의 통합——이 서버는 Anthropic의 Claude Code 또는 OpenAI의 Codex API의 백엔드로 사용할 수 있습니다.

지원 모델

README에는 드래프터가 사전 등록되어 있고 속도 향상이 측정된 모델 표가 있습니다. 예:

• Gemma‑4 12B(8‑bit)——최대 4.24× 빠름.
• Qwen‑3.8‑27B(8‑bit, DFlash 2)——최대 4.22×.
• MiniCPM5‑2B——최대 4.21×.
• LFM2.5‑1.2B——최대 3.83×.
• 그 외 다수(Qwen, Ornith, Nemotron, Bonsai 등). 표에 없는 모델도 “드래프터 없는” 조회 모드(--mode auto)로 실행할 수 있습니다.

설치 및 요구 사항

• Apple Silicon에서 Python ≥ 3.10.
• pip install mlx-dspark(MLX 런타임 ≥ 0.32를 자동으로 설치).
• 선택적으로 Homebrew Cask를 통해 GUI를 설치하거나 releases 페이지에서 DMG를 다운로드.
• 추가 서버 프레임워크 불필요——HTTP API는 Python 표준 라이브러리 위에 구축되어 있습니다.

주요 명령줄 플래그(가장 많이 사용됨)

Flag	Purpose
--model <repo>	대상 모델의 HF repo 또는 로컬 경로.
`--mode auto	dspark
--max-draft auto	도구가 Mac에 맞게 드래프트 길이를 자동 조정.
--max-batch N	최대 N개의 동시 요청을 배치 처리(약 2.5배 총 처리량).
--kv-bits 8	KV 캐시를 양자화하여 긴 컨텍스트의 메모리 절약.
--api-key <key>	localhost 외부로 서버를 노출할 경우 간단한 인증.
--trust‑remote‑code	사용자 정의 Python 코드가 포함된 체크포인트 로드를 허용.

왜 중요한가

추측 디코딩은 소비자용 LLM을 단일 Mac에서 답변 품질을 희생하지 않고 눈에 띄게 더 빠르게 실행할 수 있게 하는 최첨단 기술입니다. 표준 OpenAI／Anthropic API를 제공함으로써 mlx‑dspark는 이러한 로컬 모델을 기존 도구와 에이전트에 쉽게 연결할 수 있게 하며, 모든 것을 온디바이스와 비공개로 유지합니다.

---

위의 모든 세부 사항은 저장소의 README에서 직접 가져온 것이며, 외부 정보는 추가되지 않았습니다.