carloslfu/slotstream

Run Qwen3.8-Flash-Next (125B MoE, 104 GB at 4-bit) on Macs with a fraction of that RAM by streaming experts from SSD. MLX + Swift, Ollama-compatible API.

slotstream – 48GB RAM을 가진 맥에서 1250억 파라미터 LLM을 실행하기

무엇인가요 – Apple-silicon 맥에서 Qwen‑3.8‑Flash‑Next 4비트 모델(디스크상 약 105GB, 125B 파라미터)을 실행할 수 있게 해주는 네이티브 Swift 명령줄 도구(및 라이브러리)입니다. 대부분의 모델 가중치를 SSD에서 스트리밍하여 작은 RAM 캐시에 저장함으로써, 48GB 맥에서도 캐시가 준비된 후 초당 약 12개 토큰을 생성할 수 있습니다. Python이 필요 없으며, 한 번의 다운로드 후 오프라인으로 작동하며, Ollama 호환 및 OpenAI 호환 HTTP API를 제공합니다.

왜 중요한가요 – 대규모 LLM은 일반적으로 수십 GB의 GPU 메모리가 필요합니다. slotstream는 창의적인 전문가 캐싱과 4비트 정량화를 통해, 소비자 등급의 맥에서도 전체 모델을 RAM에 스왑하지 않고 125B 파라미터 모델을 실행할 수 있음을 보여줍니다.

주요 기능 (README에 설명된 내용)

SSD에서 모델 로딩 – 가중치는 압축된 4비트 형식(약 88GB)으로 저장됩니다. slotstream는 RAM에 고정된 전문가 슬롯 풀을 유지하고, 필요할 때마다 SSD에서 필요한 부분을 가져옵니다.
자동 메모리 계획 – 시작 시 맥의 RAM, Metal 작업 세트 제한, 그리고 RAM의 70% 한도를 기반으로 메모리 목표를 선택합니다. --memory‑gb로 오버라이드할 수 있습니다.
빠른 추론 – 48GB M5 Pro 맥에서는 캐시가 준비된 후 초당 약 12토큰을 생성합니다; 더 작은 기기에서도 작동 가능(8GB RAM에서는 약 3토큰/초, 다만 스왑이 발생할 수 있음).
API 호환성 – 다음과 같은 기능을 제공합니다:
- Open WebUI 및 Ollama CLI와 호환되는 Ollama 스타일 엔드포인트 (/api/chat)
- 어떤 OpenAI SDK에서도 사용 가능한 OpenAI 스타일 엔드포인트 (/v1/chat/completions)
- 이미지 지원(기본64 또는 data-URL 페이로드)과 시각 타워(메모리 계획에 약 0.9GB 추가)
- OpenAI 채팅 스키마 및 fx 에이전트 프레임워크에서 사용하는 Vercel AI SDK 게이트웨이를 통한 도구 호출
CLI 명령어
- slotstream pull – 공개 Hugging Face 미러에서 모델을 다운로드하고 검증합니다(다시 시작 가능, 해시 검증)
- slotstream run --prompt "…" – 터미널에서 한 번만 생성합니다.
- slotstream serve – 클라이언트 통합을 위한 HTTP 서버를 시작합니다.
- slotstream doctor – 다운로드 전 메모리 계획, 추정 속도, 무료 디스크 공간 확인을 표시합니다.
Swift 패키지 – 동일한 엔진은 Package.swift를 통해 Swift 프로젝트에 추가할 수 있으며, 사용자 정의 앱을 위한 Planner 및 WeightStore API를 노출합니다.
예측적 디코딩 – 선택적 1.5GB의 "드래프트 헤드"를 로드하여 메인 모델이 검증하는 토큰을 제안할 수 있으며, 충분한 RAM이 있으면 최대 약 24%의 속도 향상이 가능합니다.
풍부한 문서 – 설치, 클라이언트 설정, 시각, 코딩 에이전트(fx), 헤르메스 도구 호출, 문제 해결, 하드웨어 측정, 설계 세부 사항에 대한 가이드가 포함되어 있습니다.

시스템 요구 사항

요구 사항	세부 사항
CPU / GPU	Metal 지원이 있는 Apple Silicon(M-시리즈). macOS 14+ (14, 15, 26에서 테스트됨).
RAM	최소 8GB(강한 스왑 발생). 전체 속도를 위해 추천 48GB.
디스크	압축된 모델(약 88GB)과 바이너리에 대해 약 110GB의 무료 SSD 공간 필요.
기타	Python 필요 없음; 바이너리는 자체 포함된 Swift 실행 파일입니다.

일반적인 워크플로우

설치 – curl -fsSL https://raw.githubusercontent.com/carloslfu/slotstream/main/install.sh | sh (바이너리를 ~/.slotstream/bin에 설치함).
맥 확인 – slotstream doctor로 자동 선택된 메모리 목표와 무료 공간을 확인합니다.
모델 다운로드 – slotstream pull (한 번만, 재시작 가능, 해시 검증).
빠른 테스트 실행 – slotstream run --prompt "왜 하늘은 파란가요?".
앱용 서빙 – slotstream serve를 실행하고 Open WebUI, Ollama, 또는 어떤 OpenAI SDK도 http://localhost:11434에 연결합니다.
옵션 – 시각(--vision on), 예측적 디코딩(--mtp auto), 또는 컨텍스트 길이 조정(--max-context 65536)을 활성화할 수 있습니다.

제한 사항 및 주의사항

모델 전용 지원 – 현재 qwen3.8‑flash‑next:4bit만 구현되어 있으며, 다른 LLM 패밀리는 호환되지 않습니다.
하드웨어 제한 – Apple-silicon과 Metal이 필요하며, Linux/Windows 지원은 아직 없음(미래의 "Sevra" 제품에서 계획됨).
메모리 압박 – 저메모리 맥에서는 시스템이 강하게 스왑할 수 있으며, 생성 속도를 저하시키고 SSD를 손상시킬 수 있습니다.
컨텍스트 창 – 기본 32k 토큰(플래그로 65k까지 늘릴 수 있음). 긴 프롬프트는 여전히 수초에 걸쳐 전채 비용이 발생합니다.
시각 정확도 – 이미지 처리는 작동하지만, 시각적 QA에 대한 벤치마크는 제공하지 않습니다.
병렬 처리 – 한 프로세스당 한 번의 생성만 가능; 여러 사용자는 별도의 프로세스가 필요합니다.

누가 사용할 수 있을까

개발자 – 앞으로 출시될 Sevra 앱과 같은 로컬 우선 AI 어시스턴트를 개발하면서 맥에서 빠르고 오프라인 LLM을 원하는 사람.
연구자 – 소비자 수준 하드웨어에서 Mixture-of-Experts 모델을 실험하는 사람.
파워 유저 – 자체 포함된 바이너리와 Python/conda 환경을 피하고 싶은 사람.
도구 개발 애호가 – Ollama, OpenAI SDK, 또는 fx 에이전트 프레임워크와 통합하고 싶은 사람.

빠른 참조 링크

설치 스크립트 – install.sh
API 문서 – docs/API.md
클라이언트 가이드 – docs/CLIENTS.md
시각 가이드 – docs/API.md#images
코딩 에이전트 가이드 – docs/FX.md
설계 및 메모리 플래너 – PLAN.md
성능 측정 – MEASUREMENTS.md
릴리스 노트 – CHANGELOG.md

결론

slotstream는 SSD에서 가중치를 스트리밍하고 동적 캐시를 관리함으로써, 단일 Apple-silicon 맥에서 125B 파라미터 LLM을 실용적으로 사용할 수 있게 해주는 실제 프로덕션 수준의 추론 엔진입니다. 작고 가벼운 Swift 바이너리로 배포되며, 표준 Ollama/OpenAI 엔드포인트를 제공하고, 이미지 및 도구 호출을 지원하며, 네이티브 macOS 앱에 엔진을 통합할 수 있는 Swift 라이브러리를 제공합니다. 프로젝트는 활발히 유지 보수 중이며, 자세한 문서와 명확한 하드웨어 중심의 성능 모델을 제공합니다.