project-maya

무엇인가

Project Maya는 대형 MoE 언어 모델을 개인 워크스테이션에서 직접 구동하는 로컬 추론 스택이다. C++로 작성된 엔진, 서버, 브라우저 대시보드, OpenAI·Anthropic 호환 API, 양자화 도구를 한 저장소에 묶는다. 대상 모델은 GLM-5.3-Flash(zai-org, MIT 라이선스, 321B 파라미터, 토큰당 약 18B 활성, 최대 1M 토큰 컨텍스트)와 DeepSeek-V4.1-Flash-1017(DeepSeek, MIT 라이선스, 748B 파라미터)이다. 두 모델은 각각 전용 엔진을 가진다. 저장소 분류상 CLI 도구에 속하며, 설치 스크립트와 셸 스크립트를 통해 구동된다. 모델 크기 때문에 통상 데이터센터가 필요한 규모를, 사용자가 이미 보유한 GPU 한 장에서 16장까지, NVIDIA 또는 AMD, Linux 또는 Windows(실험적)에서 실행하는 것을 목표로 한다. 추론 과정에서 데이터가 외부로 나가지 않는다.

어떻게 동작하나

이 도구가 겨냥하는 문제는 모델 가중치가 단일 GPU 메모리에 들어가지 않는다는 점이다. 321B, 748B 규모의 MoE 모델은 VRAM에 전부 적재하는 방식으로는 개인 하드웨어에서 구동할 수 없다. 기존 선택지는 모델을 작은 것으로 바꾸거나, 클라우드 API로 데이터를 내보내거나, 정확도를 크게 희생하는 저비트 양자화를 감수하는 것이었다. Maya는 가중치를 전부 메모리에 올리는 대신 계층적으로 배치한다. 대화에서 가장 많이 쓰이는 전문가(experts)는 GPU에, 그다음은 RAM에, 나머지는 NVMe SSD에 두고 대화가 진행되면서 옮긴다. 즉 저장 매체를 하나의 연속된 계층으로 취급하고, 접근 빈도에 따라 배치를 바꾼다. 여기에 더해 GPU, CPU, RAM, SSD 사양을 측정해 스스로 튜닝한다. 하드웨어마다 다른 메모리 구성에 맞춰 설정을 사람이 계산하지 않아도 되게 만든 것이 설계의 출발점이다.

무엇과 다른가

핵심 메커니즘은 전문가 계층화와 투기적 디코딩이다. MoE 모델은 토큰마다 일부 전문가만 활성화되므로, 자주 쓰이는 전문가를 빠른 매체에 두면 평균 지연이 줄어든다. Maya는 이 배치를 대화 패턴에 따라 갱신한다. 메모리가 얼마든 동작한다는 것이 명시된 특성이며, VRAM과 RAM이 많을수록 빠르고 파일은 NVMe SSD에 두는 것이 권장된다. 정확도 쪽에서는 자체 양자화를 쓴다. GLM-5.3-Flash 양자화는 Z.ai의 FP8 릴리스에서 통계를 뽑아 만들었고, FP8 모델의 제로샷 정확도 중 97.7~99.2%를 유지한다. 각 양자화는 모델의 MTP 블록을 보존하는데, 이 블록이 토큰을 미리 초안(draft)한다. DeepSeek 쪽은 Maya-S가 원본과 같은 다음 토큰을 92.6% 확률로 고른다. GGUFs 사용 시 DSpark 드래프터(8GB, DeepSeek의 FP4 전문가와 8비트 dense 가중치)를 함께 받아 실제로 빨라지는지 측정한 뒤 효과가 있는 경우에만 유지한다.

어떻게 쓰나

구성 요소는 역할별로 분리되어 있다. 모델별 추론 엔진이 있고, DeepSeek-V4.1-Flash-1017은 `maya-ds4`라는 별도 엔진을 쓴다. 서버는 고정된(pinned) 공식 프롬프트 인코더를 사용하며, 수치로 지정하는 추론 예산(reasoning budget)과 ID로 매칭되는 병렬 도구 결과를 다룬다. API 계층은 OpenAI 및 Anthropic 호환 형식을 제공하고 도구 호출을 지원하므로 코딩 에이전트가 그대로 붙을 수 있다. 브라우저 대시보드는 채팅과 실시간 모니터를 제공하며, 모니터는 각 GPU 메모리를 무엇이 채우는지까지 보여준다. 설정에서 컨텍스트 크기와 포트를 바꿀 수 있다. 설치 스크립트 `./setup.sh`가 다운로드, 빌드, 기동을 담당하고, 벤치마크는 `./maya.sh --bench`와 `--report`로 수행한다. 서버는 기본적으로 `http://127.0.0.1:8080`에서 열린다.

전제와 한계

구조적 차이는 메모리 계층을 소프트웨어로 관리한다는 점에 있다. 일반적인 로컬 추론기는 모델 전체를 VRAM에 올리는 것을 전제로 하고, 부족하면 레이어를 GPU 수만큼 나누는 수준에 그친다. Maya는 전문가 단위로 배치를 정하고 SSD를 마지막 계층으로 포함한다. 대신 대가가 따른다. 시작 시 엔진이 여유 RAM을 약 6GB를 남기고 대부분 고정(pin)하므로, 실행 중에는 다른 프로그램이 쓸 RAM이 줄어든다. 첫 응답이 가장 느린데, 캐시가 채워지기 전까지는 전문가를 매체에서 읽어야 하기 때문이다. 여러 요청을 동시에 처리하는 `--parallel`은 반대로 이 구조의 이점을 키운다. 한 GPU에서 여러 요청의 토큰이 함께 모델을 통과하므로 dense 가중치를 한 번만 읽는다. VRAM이 모델을 많이 담을수록 이득이 커진다.

설치는 저장소 루트에서 `./setup.sh`를 실행하는 것으로 시작한다. 대화형으로 몇 가지를 묻고, Enter를 누르면 권장 선택이 적용된다. 어떤 양자화를 받을지 묻고 PC에 맞는 것을 추천하며, 모든 다운로드를 시작 전에 보여준다. 빌드는 한 번만 수행하고 20~40분이 걸리며 다운로드 시간은 별도다. 빌드가 끝나면 모델을 바로 기동하고 `http://127.0.0.1:8080`을 열면 된다. Ctrl+C로 멈추고 `./setup.sh`를 다시 실행하면 즉시 재기동한다. Windows에서는 `./setup.sh` 대신 `START-MAYA.bat`을 쓰고 docs/WINDOWS.md를 참고한다. AMD는 docs/AMD_MAYA.md를 따른다. DeepSeek-V4.1-Flash-1017을 쓰려면 `./setup.sh --setup`에서 선택하거나 `./setup.sh --model DeepSeek-V4.1-Flash-1017`로 지정한다. GGUFs 경로에서 비전 타워를 빼려면 `--no-vision`을 붙인다. GPU, 컨텍스트, 이미 가진 모델 폴더, 원격 접근 같은 세부 옵션은 docs/SETUP.md에 정리되어 있다. 설정은 시스템 전역에 아무것도 설치하지 않으며, 빠진 것이 있으면 정확한 명령을 출력한다. 실패하기 쉬운 지점은 시작 직후의 RAM이다. 엔진이 여유 RAM을 약 6GB만 남기고 고정하므로, 다른 프로그램을 함께 띄워 두면 메모리 압박이 생긴다.

모델 자산은 양자화 등급으로 나뉜다. GLM-5.3-Flash용 Maya 자체 양자화는 MAYA-S, MAYA-S24, MAYA-M, MAYA-L 네 가지이며, Z.ai의 FP8 릴리스에서 통계를 뽑아 만들었다. 각 등급은 모델의 MTP 블록을 보존한다. DeepSeek-V4.1-Flash-1017은 README에서 새로 추가된 항목으로 표시되고, 전용 엔진 `maya-ds4`를 쓴다. 업데이트 경로는 두 가지다. 대시보드의 About > Update를 쓰거나, `git pull` 후 `./setup.sh`를 실행한다. 이때 모델은 다시 받지 않는다. 즉 코드와 엔진만 갱신되고 이미 받아 둔 가중치는 그대로 재사용된다. 커뮤니티 양자화도 Maya 위에서 돌아가며, 저장소가 자체 배포하는 것 외의 선택지를 허용한다. 양자화 제작과 측정 방법은 MAYA-S, MAYA-S24, MAYA-M, MAYA-L 문서에, 배포는 Hugging Face에 있다.

README가 제시하는 처리량은 다음과 같다. GLM-5.3-Flash 기준 H100 두 장에서 최대 124 tokens/s, RTX 4090 네 장에서 118, RTX PRO 6000 한 장에서 81, RTX 5090 한 장에서 30+다. 토큰 하나는 단어의 약 3/4에 해당한다. 이 수치는 대부분 `./maya.sh --bench`로 측정되었고, prefill은 8K 토큰 프롬프트 기준이다. 대화가 길어져도 속도가 유지되며, 시작 직후 첫 응답들이 가장 느린데 캐시가 채워지는 동안이기 때문이다. `--parallel`로 여러 요청을 동시에 처리하면 합산 처리량이 늘어난다. V100에서 Maya-S 전문가 대부분을 RAM에서 스트리밍하는 구성은 두 요청 x1.41, 네 요청 x1.35였고, Gorgon Halo(Radeon 8065S, GPU에 160GB)로 모든 전문가를 GPU 메모리에 담는 구성은 두 요청 x1.67, 네 요청 x2.02였다. VRAM이 모델을 많이 담을수록 이득이 커진다. 정확도는 GLM-5.3-Flash 양자화가 FP8 모델 제로샷 정확도의 97.7~99.2%를 유지하고, DeepSeek 쪽 Maya-S는 원본과 같은 다음 토큰을 92.6% 확률로 고른다.

전제 조건이 분명하다. 시작 시 엔진이 여유 RAM을 약 6GB만 남기고 고정하므로, Maya가 도는 동안 다른 프로그램은 쓸 RAM이 줄어든다. 모델 파일은 NVMe SSD에 두는 것이 권장된다. VRAM과 RAM이 많을수록 빠르지만, 메모리가 얼마든 동작한다는 것이 명시된 특성이다. AMD와 Windows 지원은 실험적이다. Strix Halo나 Gorgon Halo를 Windows에서 쓸 때는 OS가 GPU 메모리 몫을 페이지 파일 계산에 넣기 때문에, 모든 전문가를 GPU에 두려면 충분히 큰 페이지 파일이 필요하고 설정이 그 크기를 알려준다. 빌드에 20~40분이 걸린다. 판단 기준은 메모리 계층의 크기로 갈린다. VRAM과 RAM이 커서 전문가 대부분을 GPU에 담을 수 있으면 `--parallel` 이득이 커지고 이 구성이 유리하다. 반대로 단일 GPU에 모델이 들어가지 않지만 NVMe SSD 용량이 충분하면, 모델을 줄이거나 데이터를 외부로 보내지 않고 이 계층 구조로 돌릴 수 있다. 데이터가 기기 밖으로 나가면 안 되는 조건도 이 선택을 뒷받침한다.