PrismML-Eng/Bonsai-demo 딥다이브
— 27B 모델을 3.9GB로 접어 아이폰에 넣는 1비트 압축 실험실

1프로젝트 한 줄 요약

2왜 주목받는가 — "4비트"는 4비트가 아니었다

① 백서의 폭로: 라벨과 실측이 다르다

로컬 LLM을 써본 사람이라면 Q4_K_M, IQ2_XXS 같은 이름을 봤을 것이다. 이름만 보면 각각 4비트, 2비트 같다. Bonsai 백서가 실제로 재본 값은 이렇다.

② 벤치마크: 크기는 2/3인데 점수는 더 높다

백서 Table 10 기준(EvalScope + vLLM, H100, 15개 벤치마크 평균, thinking 모드).

읽는 법: IQ2_XXS는 9.4GB를 쓰고 72.73점, Ternary Bonsai는 5.9GB를 쓰고 80.49점이다. 용량은 37% 적은데 점수는 7.8점 높다. 이게 이 프로젝트가 화제가 된 실질적 근거다.

단 정직하게 읽자면 Q4_K_XL(17.6GB, 99.9%)이 여전히 품질 챔피언이다. Bonsai가 이기는 영역은 "17GB는 도저히 못 올리는 기기" — 즉 폰, 저사양 노트북, 임베디드다. 백서 스스로도 무손실이 아니다라고 명시한다.

③ BitNet과의 결정적 차이: 재학습이 필요 없다

1비트 LLM 얘기가 나오면 늘 등장하는 게 마이크로소프트의 BitNet(b1.58)이다. 백서는 이 차이를 정면으로 다룬다.

백서는 Qwen3.6-27B뿐 아니라 Gemma-4-31B 계열에도 같은 방법을 적용해 유사한 패턴을 재현했다고 보고한다. "특정 모델의 우연이 아니라 방법론 자체의 성질"이라는 교차검증인 셈이다.

④ 그런데 왜 "demo" 레포가 뜨는가

모델 가중치는 HuggingFace에 있고 커널 코드는 llama.cpp/MLX 포크에 있다. 그럼 이 저장소에 남는 건 스크립트뿐인데, 왜 여기가 별을 모을까? 답은 여기가 유일한 정문(front door)이기 때문이다.

• 백서 PDF 3종이 이 저장소에 직접 들어 있다 (27B / 1-bit 8B / ternary 8B)
• ternary(Q2_0) CUDA 커널은 아직 llama.cpp 본류에 병합 중이라, PrismML 포크 바이너리를 받으려면 이 스크립트가 필요하다
• 커뮤니티가 자기 하드웨어 벤치마크를 PR로 올리는 창구(community-benchmarks/)도 여기다

3기술 스택 전체 지도

언어 구성이 특이하다

AI 프로젝트인데 Python이 3%밖에 안 된다. Shell 65% + PowerShell 32%가 본체다. 이유는 명확하다 — 이 저장소는 모델을 만들지 않고 설치하고 실행하기 때문이다. 무거운 연산은 전부 C++(llama.cpp)와 Metal/CUDA 커널이 한다.

백엔드 · 추론 엔진

Python 계층 — venv를 셋으로 쪼갠 이유

이 프로젝트는 파이썬 가상환경을 3개 만든다. 처음 보면 과해 보이지만 이유가 있다.

패키지 매니저 · 빌드

패키지 매니저로 uv(Astral, Rust로 짠 초고속 pip 대체재)를 쓴다. uv venv, uv sync, uv pip install 조합이며 uv.lock으로 버전을 못 박는다. 파이썬 요구는 >=3.11.

소스 빌드도 플랫폼별 스크립트가 따로 있다: build_mac.sh, build_cpu_linux.sh, build_cuda_linux.sh, build_cuda_windows.ps1.

인프라 · CI

4아키텍처 심화 분석

전체 시스템 구조도

핵심 ① 모델 선택은 환경변수 두 개의 조합

BONSAI_FAMILY(ternary / bonsai / all)와 BONSAI_MODEL(27B / 8B / 4B / 1.7B / all)의 곱으로 경로와 파일 패턴이 결정된다. scripts/common.sh에 중첩 case문으로 사전 계산해두고 모든 스크립트가 이 함수를 재사용한다.

# scripts/common.sh — 실제 코드
case "$BONSAI_MODEL" in
    27B|8B|4B|1.7B)
        case "$BONSAI_FAMILY" in
            ternary)
                GGUF_MODEL_DIR="models/ternary-gguf/${BONSAI_MODEL}"
                MLX_MODEL_DIR="models/Ternary-Bonsai-${BONSAI_MODEL}-mlx-2bit"
                GGUF_QUANT_PATTERN="*-Q2_0.gguf"
                BONSAI_DISPLAY="Ternary-Bonsai-${BONSAI_MODEL}"
                ;;
        esac
        ;;
esac

핵심 ② 다운로드 — 필요한 파일만 골라 받기

download_models.sh는 huggingface_hub.snapshot_download()를 파이썬 인라인으로 호출하되, allow_patterns로 필터를 건다.

# 27B ternary를 받을 때의 패턴 (개념 요약)
allow_patterns = [
    "*-Q2_0.gguf",          # 본체 (ternary 가중치)
    "*mmproj*.gguf",        # 비전 프로젝터 (멀티모달용)
    "*dspark-Q4_1*.gguf",   # 투기적 디코딩용 초안 모델
]

이 필터가 없으면 저장소에 함께 올라간 F16 참조본(47GB짜리)까지 딸려온다. 27B에서만 mmproj와 dspark를 추가로 받는데, 작은 모델들은 비전 타워가 없기 때문이다.

핵심 ③ 바이너리 — 내 GPU를 알아서 찾아낸다

download_binaries.sh가 하는 하드웨어 감지 순서:

맞는 tar.gz를 curl 또는 wget으로 받아 풀고, macOS라면 Gatekeeper 격리 속성 제거(xattr -cr) + 임시 서명(codesign -s -)까지 자동 처리한 뒤 --version으로 스모크 테스트한다. Mac에서 남이 만든 바이너리를 돌릴 때 겪는 "손상되었기 때문에 열 수 없습니다" 문제를 스크립트가 대신 풀어주는 것이다.

핵심 ④ 서버 기동 커맨드 해부

start_llama_server.sh가 최종적으로 조립하는 명령이다. 로컬 LLM 서버 운용의 교과서라 한 줄씩 볼 값어치가 있다.

exec "$BIN" -m "$MODEL" --host "$HOST" --port "$PORT" -ngl "$NGL" -fa on -c "$_ctx" \
    --temp 0.7 --top-p 0.95 --top-k 20 --min-p 0 \
    --jinja \
    ${MMPROJ:+--mmproj "$MMPROJ"} \
    ${_imt:+--image-max-tokens "$_imt"} \
    ${MD:+-md "$MD"} $_spec_flags \
    $_kv_args ${KV_BIAS:+--kv-mean-center "$KV_BIAS"} \
    --webui-config-file "$_webui_cfg" \
    "$@"

핵심 ⑤ 하이브리드 어텐션이라는 숨은 난관

백서 Section 5의 주장 중 기술적으로 가장 무거운 부분이다. 베이스가 된 Qwen3.6-27B는 표준 트랜스포머가 아니다.

문제는 기존의 저비트 커널들이 표준 어텐션을 가정하고 짜여 있다는 것이다. 그래서 PrismML은 이 하이브리드 구조에 맞는 1비트/2비트 커널을 CUDA와 MLX 양쪽에 새로 작성해야 했다. "모델만 압축하면 끝"이 아니라 런타임 커널까지 함께 만들어야 실제로 돌아간다는 게 이 분야의 현실이다.

핵심 ⑥ 에이전트 도구의 보안 설계

Open WebUI 데모에 심는 도구 4종(weather, web_fetch, sql, code_interpreter) 중 두 개가 특히 잘 짜여 있다.

# scripts/openwebui/tool_web_fetch.py — SSRF 방어
def _is_public_ip(ip_str: str) -> bool:
    try:
        ip = ipaddress.ip_address(ip_str)
    except ValueError:
        return False
    # is_global rejects loopback, private LAN, link-local (169.254/16 -> cloud
    # metadata), CGNAT (100.64/10), reserved, multicast and unspecified.
    return ip.is_global

# scripts/openwebui/tool_sql.py — 읽기 전용 3중 잠금
stripped = _without_leading_comments(sql).strip().rstrip(";").strip()
if ";" in stripped:
    return "Only a single SQL statement is allowed."     # ① 다중문 차단
if not re.match(r"(?is)^(select|with)\b", stripped):
    return "Only read-only SELECT / WITH queries are allowed."  # ② 동사 화이트리스트
...
with sqlite3.connect(f"file:{DB_PATH}?mode=ro", uri=True, timeout=10) as conn:
    conn.execute("PRAGMA query_only = ON")               # ③ DB 레벨 강제

주목할 점은 정규식만 믿지 않는다는 것. 문자열 검사(①②)를 통과해도 SQLite 연결 자체를 mode=ro로 열고 PRAGMA query_only까지 건다. 앞의 방어가 뚫려도 DB가 쓰기를 거부한다.

핵심 ⑦ 데모 데이터에 심어둔 "사건"

make_demo_db.py는 가짜 B2B 매출 SQLite DB를 random.seed(1337)로 결정론적으로 생성한다. 그런데 코드 주석에 스토리가 하드코딩되어 있다.

5디렉토리 구조 해부

6학습 포인트 — 기술별 배울 것

7하드웨어 · 시스템 요구사항

메모리 요구량 (27B 기준, 텍스트 전용, FP16 KV)

BONSAI_KV4=1로 4비트 KV 캐시를 켜면 100K 컨텍스트에서 ternary가 13.7GB → 9.2GB로 줄어든다.

기기별 현실적 판단

커뮤니티 실측 속도

OS · 백엔드 지원 매트릭스

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크 · 한계와 주의사항

이 프로젝트의 한계 (백서가 직접 인정한 것)

보안상 반드시 지킬 것

정보 검증에 관한 메모