TL;DR

이 데모는 1-bit 및 ternary 양자화로 패킹된 Bonsai 계열 모델을 로컬에서 간편하게 설치하고 실행하는 용도로 설계되었다. setup 스크립트가 의존성 설치, 모델과 플랫폼별 바이너리 다운로드, MLX 빌드와 Open WebUI 통합을 자동으로 처리하며 27B는 비전 입력과 네이티브 도구 호출, 최대 262,144 토큰의 긴 문맥을 지원한다. 포맷 호환성 문제는 그룹 크기별 Q2_0 파일과 메인라인 또는 포크된 llama.cpp 바이너리의 조합으로 해결하며 CUDA 백엔드용 사전빌드 포크 바이너리를 포함해 즉시 실행을 보장한다. 트레이드오프는 높은 압축률을 통한 작은 풋프린트와 하드웨어별 호환성 관리가 필요하다는 점이며 실험적 옵션으로 speculative decoding과 4-bit KV cache를 통해 성능과 메모리 절감 조정이 가능하다.

주요 기능

• 로컬에서 Mac(Apple Silicon/Metal), Linux(CUDA/Vulkan/ROCm) 및 Windows 환경으로 27B, 8B, 4B, 1.7B 모델을 실행할 수 있다.
• setup.sh가 의존성 설치, 모델 다운로드, 포크 바이너리 또는 빌드 실행을 자동으로 처리해 초기 설정을 간소화한다.
• 내장 채팅 서버와 Open WebUI 통합으로 이미지 업로드, 도구 호출, 서버사이드 코드 인터프리터 기능을 즉시 시연할 수 있다.
• 모델 패밀리와 크기를 환경변수로 즉시 전환하면서 Ternary(2-bit)와 1-bit 실행 경로를 빠르게 비교할 수 있다.
• 실험적 옵션으로 speculative decoding과 4-bit KV cache를 제공해 지연과 메모리 사용을 조정할 수 있다.

어떻게 동작하는가

이 데모는 설치 스크립트가 시스템 종속성 검사, Python 가상환경 생성, 모델과 플랫폼별 바이너리 다운로드를 순차적으로 수행하는 방식으로 동작한다. 런타임은 llama.cpp와 MLX를 지원하며 Q1_0(1-bit)와 Q2_0(ternary) 같은 양자화 포맷을 적절한 백엔드에서 로드해 추론을 실행한다. CUDA 및 일부 백엔드에서는 포크된 사전빌드 바이너리를 제공하고 CPU/Metal 경로는 메인라인 호환 파일로 실행해 다양한 하드웨어에서 즉시 동작하게 구성되어 있다.

해결 문제

대형 양자화 LLM을 다양한 개인 장비에서 실행하고 에이전트형 도구 호출과 비전 입력을 결합하는 복잡한 초기 설정을 단일 데모로 통합해 간소화한다. 플랫폼별 빌드와 포맷 호환성 문제를 자동화된 스크립트와 미리 빌드된 바이너리로 처리해 사용자 개입을 최소화한다. 결과적으로 로컬 환경에서 긴 문맥과 멀티모달 기능을 갖춘 모델을 빠르게 검증하고 프로토타이핑할 수 있게 한다.

지금 주목받는 이유

최근에 공개된 Bonsai 27B가 비전언어, 긴 문맥, 네이티브 도구 호출을 결합해 로컬 환경에서 고성능 멀티모달 실험을 가능하게 했기 때문에 주목받고 있다.

차별점

• 1-bit과 ternary(2-bit) 양자화 팩을 모두 제공해 극단적 압축과 품질 사이에서 선택할 수 있다.
• 메인라인 llama.cpp 호환 파일과 포크된 그룹-128 Q2_0 파일을 함께 배포해 CUDA 등 일부 백엔드에서 즉시 실행 가능하게 구성했다.
• 27B 비전언어 모델이 262,144 토큰의 초대형 문맥을 지원해 장기 대화와 문서 분석 워크로드를 처리할 수 있다.
• 설치 스크립트가 MLX 빌드, Open WebUI 통합, Jupyter 기반 코드 인터프리터 구성까지 자동으로 수행해 데모 완성도를 높였다.

사용 사례

• 인터넷에 의존하지 않는 로컬 환경에서의 멀티모달 채팅 인터페이스와 이미지 기반 질의응답을 실험할 때 유용하다.
• 에이전트형 도구 호출과 MCP 통합을 통해 외부 지식원과 연동하는 자동화된 워크플로우를 로컬에서 검증할 때 쓰인다.
• 하드웨어별 성능과 메모리 사용량을 비교하거나 대규모 문맥 처리 전략(KV cache 조정 등)을 벤치마킹할 때 활용할 수 있다.

시작하기

리포지토리를 클론한 뒤 기본적으로 ./setup.sh를 실행하면 Ternary-Bonsai-27B이 자동으로 설치된다. 27B 모델의 경우 HuggingFace 접근 토큰을 BONSAI_TOKEN 환경변수로 설정해야 다운로드가 완료된다. 설치가 끝나면 ./scripts/start_llama_server.sh로 로컬 채팅 서버를 띄우거나 ./scripts/run_llama.sh로 단건 프롬프트를 실행해 동작을 확인할 수 있다.

요구사항

• HuggingFace 읽기 토큰은 27B 모델을 다운로드할 때 필요하다.
• 플랫폼별로 Metal(Catalyst), CUDA 또는 Vulkan 같은 GPU 백엔드가 있으면 가속 경로를 활용할 수 있다.
• 시스템 수준의 빌드 도구가 필요하며 macOS는 Xcode CLT, Linux는 build-essential과 CMake가 요구된다.
• 대용량 모델을 다루려면 충분한 RAM 및 GPU VRAM이 필요하며 CUDA 빌드의 경우 VRAM 16GB 이상 권장이다.

벤치마크