Hypura – 애플 실리콘용 저장 계층 인식 LLM 추론 스케줄러

• GPU·RAM·NVMe 간 텐서 배치를 최적화해 대형 언어 모델을 실행하는 저장 계층 인식형 추론 스케줄러
• 32GB 맥 미니에서 Mixtral 8x7B(31GB) 모델을 2.2 tok/s, Llama 70B(40GB) 모델을 0.3 tok/s 속도로 실행 가능
• 접근 패턴과 하드웨어 대역폭을 분석해 물리 메모리를 초과하는 모델도 안정적으로 구동, 기존 llama.cpp가 OOM으로 실패하던 모델까지 처리 가능
• MoE 구조의 전문가 라우팅, 뉴런 캐시, 프리패치를 통해 I/O를 최대 75% 절감하고 캐시 적중률 99.5% 달성
• 모델 크기와 하드웨어에 따라 Full-resident, Expert-streaming, Dense FFN-streaming 모드를 자동 선택해 최적 성능 유지
• Ollama 호환 HTTP API를 제공해 OpenClaw 등과 연동 가능하며, SSD는 읽기 전용으로 사용해 수명 저하 없이 NVMe 기반 추론을 지원

개요

• Hypura는 Apple Silicon 환경에서 저장 계층 인식형 LLM 추론 스케줄러로, GPU·RAM·NVMe 간 텐서 배치 최적화를 수행하는 도구
• 접근 패턴, 대역폭 비용, 하드웨어 성능을 기반으로 텐서를 분산 배치해 물리 메모리를 초과하는 대형 모델도 안정적으로 실행 가능
• 32GB Mac Mini에서 Mixtral 8x7B(31GB) 모델을 2.2 tok/s, Llama 70B(40GB) 모델을 0.3 tok/s 속도로 실행 가능
• 동일 환경에서 llama.cpp는 OOM(Out of Memory)으로 실행 불가

문제 배경

• 소비자용 Mac은 빠른 통합 메모리와 NVMe 저장장치를 갖지만, 메모리 용량이 제한적
• 예를 들어 32GB M1 Max는 40GB 모델을 직접 로드할 수 없어 스왑 과다 및 OOM 종료 발생
• Hypura는 모델 구조를 분석해 계층별로 최적 배치를 수행함으로써 이 문제를 해결

모델 구조 기반 계층 배치

• Norms 및 Embeddings: 작지만 매 토큰마다 접근되므로 GPU에 고정
• MoE Expert Routing: 희소성 활용, 토큰당 8개 중 2개 전문가만 활성화
  • 라우터 인터셉션으로 활성 전문가를 식별 후 필요한 부분만 NVMe에서 로드
  • I/O 75% 감소, 뉴런 캐시 99.5% 적중률 확보
  • 공동 활성화 추적(co-activation tracking) 으로 다음 활성 전문가를 예측해 사전 프리패치 수행
• Dense FFN Weights: 모델 크기의 약 60% 차지
  • NVMe에서 동적 풀 버퍼를 통해 스트리밍
  • 프리패치 깊이(prefetch lookahead depth) 는 사용 가능한 메모리에 따라 자동 조정
• 결과적으로 기존 mmap 방식으로는 크래시하던 모델도 실행 가능하며, 메모리에 맞는 모델은 Metal GPU 속도로 오버헤드 없이 동작

작동 방식

• Hypura는 GGUF 파일을 읽고, GPU·RAM·NVMe 대역폭을 프로파일링
• 각 텐서를 다음 세 계층 중 하나에 배치
  • GPU(Metal): Attention, Norm, Embedding 계층
  • RAM: GPU에 적재 불가한 오버플로 계층
  • NVMe: 나머지 계층, F_NOCACHE + pread로 직접 I/O 수행
• 모델 크기와 하드웨어에 따라 자동으로 추론 모드 선택
  • Full-resident: GPU+RAM에 모델 전체 적재, NVMe I/O 없음
  • Expert-streaming: MoE 모델용, 비전문가 텐서만 GPU에 상주, 전문가 텐서는 NVMe 스트리밍
  • Dense FFN-streaming: 비-MoE 대형 모델용, Attention+Norm은 GPU에, FFN은 NVMe 스트리밍
• 풀 버퍼 크기, 프리패치 깊이, 메모리 예산은 하드웨어 프로파일에 따라 자동 계산

성능

• 테스트 환경: M1 Max, 32GB 통합 메모리, NVMe 5.1GB/s
• 주요 벤치마크 결과
  • Qwen 2.5 14B Q4_K_M (8.4GB): GPU 완전 적재, 21 tok/s
  • Mixtral 8x7B Q5_K_M (30.9GB): Expert-streaming 모드, 2.2 tok/s, 99.5% 캐시 적중률
  • Llama 3.3 70B Q4_K_M (39.6GB): Dense FFN-streaming 모드, 0.3 tok/s, 24슬롯 풀, 7계층 프리패치
• 메모리에 맞는 모델은 오버헤드 0, 초과 모델은 Hypura 덕분에 실행 가능 상태 유지

설치 및 실행

• Rust 1.75+ 및 CMake 필요
• 설치 절차 git clone --recurse-submodules https://github.com/hypura/hypura.git cd hypura cargo build --release
• 실행 예시 hypura profile hypura run ./model.gguf --prompt "Hello, world" hypura run ./model.gguf --interactive hypura bench ./model.gguf hypura inspect ./model.gguf
• 미검증 모델은 --max-tokens 10으로 테스트 권장

Ollama 호환 서버

• Hypura는 Ollama 호환 HTTP API를 제공해 OpenClaw 등 Ollama 기반 도구와 완전 호환 hypura serve ./model.gguf Endpoint: http://127.0.0.1:8080 API: /api/generate, /api/chat, /api/tags
• 주요 엔드포인트
  Endpoint 기능

  GET /	상태 확인
  GET /api/tags	로드된 모델 목록
  GET /api/version	서버 버전
  POST /api/show	모델 메타데이터
  POST /api/generate	텍스트 생성
  POST /api/chat	대화형 생성

• OpenClaw 연동은 ~/.openclaw/openclaw.json에서 Ollama base URL을 Hypura로 지정
• 서버 옵션 hypura serve [OPTIONS] --host 기본값 127.0.0.1 --port 기본값 8080 --context 기본값 4096

아키텍처

• Cargo workspace 구조로, 두 개의 crate로 구성
  • hypura: 메인 바이너리 및 라이브러리
  • hypura-sys: llama.cpp FFI 바인딩 (CMake 빌드)
• 주요 모듈
  모듈 역할

  scheduler/placement.rs	GPU/RAM/NVMe 간 텐서 배치 최적화
  compute/inference.rs	추론 엔진 및 서버용 로드/생성 함수
  compute/nvme_backend.rs	NVMe 스트리밍, 뉴런 캐시, 평가 콜백
  server/routes.rs	Ollama 호환 HTTP 핸들러
  profiler/	하드웨어 프로파일링
  cli/bench.rs	벤치마크 도구
  model/tensor_role.rs	텐서 역할 분류

FAQ

• SSD 수명 문제 없음

  • Hypura는 SSD에서 읽기만 수행, 쓰기 없음
  • NVMe I/O는 pread() + F_NOCACHE로 읽기 전용 수행
  • SSD는 콜드 스토리지 역할만 하며, 연산은 RAM/GPU에서 수행
  • 쓰기 발생은 벤치마크 결과 JSON, 통계 파일 등 KB 단위의 미미한 수준

안전 지침

• 모델이 RAM 한계(–4GB 여유) 초과 시 bench --baseline 차단
• 미검증 모델은 --max-tokens 10으로 테스트
• 테스트 모델은 ./test-models/ 디렉터리에 저장

라이선스

• MIT License

윤리적 고지

• 저장소의 코드는 작성자가 직접 작성한 것이 아님
• LLM을 활용한 지시 기반 코드 생성 실험으로 제작
• NVMe 기반 추론의 활용 가능성을 탐구하기 위한 프로젝트임