PacifAIst/Quansloth

---

/ __ \ | | | | | |
| | | |_ _ __ _ _ __ __| | ___ | || |
...

두 번째 Starstruck 메달을 획득했습니다!

이 놀라운 커뮤니티에 진심으로 감사드립니다. 128개의 스타—아름다운 2의 거듭제곱—를 달성한 것은 거대한 이정표입니다. 여러분의 지원, 피드백, 그리고 기여가 코드를 움직이고 이 프로젝트를 계속해서 레벨 업 시키는 연료가 됩니다. 다음 최고 점수(256)를 향해 나아갑시다! 🚀👾

VRAM 장벽 돌파: Google의 TurboQuant (ICLR 2026) 구현을 기반으로 하여, Quansloth는 로컬 LLM 추론(Inference)에 엘리트급 KV 캐시 압축(KV cache compression) 기술을 도입합니다.

Quansloth는 소비자용 하드웨어(예: RTX 3060)에서 대규모 컨텍스트 모델을 네이티브로 실행하는 완전한 프라이빗(Private) 및 에어갭(Air-gapped) AI 서버입니다. 커스텀 Gradio Python 프론트엔드와 고도로 최적화된 llama.cpp CUDA 백엔드를 연결함으로써, Quansloth는 극단적인 메모리 압축을 달성하여 VRAM을 최대 75%까지 절약합니다.

표준 LLM 추론은 긴 문서를 처리할 때 종종 "메모리 장벽(Memory Wall)"에 부딪힙니다. 컨텍스트(Context)가 커짐에 따라 GPU 메모리가 부족해져(OOM, Out of Memory) 시스템이 충돌하게 됩니다.

Quansloth는 다음과 같은 방식으로 이러한 충돌을 방지합니다:

75% 캐시 축소: AI의 "메모리"를 16비트에서 4비트로 압축합니다 (TurboQuant).
저가형 GPU에서 대규모 컨텍스트 실행: 일반적으로 24GB RTX 4090이 필요한 32k+ 토큰 컨텍스트를 6GB RTX 3060에서 실행할 수 있습니다.
하드웨어 수준의 안정성: 당사의 인터페이스는 CUDA 백엔드를 모니터링하여 모델이 GPU의 물리적 한계 내에 머물도록 보장하며, 시스템 중단에 대한 걱정 없이 안정적인 장문 문서 분석을 가능하게 합니다.

📸 인터페이스 미리보기

Windows 10/11: 완전 지원 (WSL2 Ubuntu를 통해). 클릭 한 번으로 실행 가능한 .bat 런처를 제공합니다.
Linux: 완전 지원 (네이티브).
macOS: 기본적으로 공식 지원되지 않음 (백엔드가 NVIDIA CUDA GPU에 최적화되어 있음).

TurboQuant 캐시 압축 (TurboQuant Cache Compression): 6GB GPU에서 메모리 부족 (Out-Of-Memory (OOM)) 충돌 없이 8,192개 이상의 토큰 컨텍스트 (token contexts)를 네이티브로 실행합니다.
실시간 하드웨어 분석 (Live Hardware Analytics): UI가 C++ 엔진 로그를 물리적으로 가로채어 정확한 VRAM 할당량과 절감량을 실시간으로 보고합니다.
컨텍스트 인젝터 (Context Injector): 긴 문서 (PDF, TXT, CSV, MD)를 채팅 스트림에 직접 업로드하여 AI의 메모리 한계를 테스트할 수 있습니다.
이중 라우팅 (Dual-Routing): 로컬 models/ 폴더를 자동 스캔하거나, 사용자 정의 절대 경로를 입력하여 임의의 .gguf 파일을 로드할 수 있습니다.
사이버펑크 UI (Cyberpunk UI): 파워 유저를 위해 구축된 매끄럽고 완전 반응형인 다크 모드 대시보드입니다.

• WSL2 (Ubuntu)를 사용하는 Windows
  또는 최신 드라이버가 설치된 NVIDIA GPU를 사용하는 네이티브 Linux
• Miniconda 또는 Anaconda 설치됨

conda create -n quansloth python=3.10 -y
conda activate quansloth

git clone https://github.com/PacifAIst/Quansloth.git
cd Quansloth

chmod +x install.sh
./install.sh

.gguf 모델 (예: Llama 3 8B)을 다운로드하여 다음 위치에 배치하세요:

models/

• Launch_Quansloth.bat 사용
• 더블 클릭 → WSL, Conda 및 서버 자동 실행

conda activate quansloth
python quansloth_gui.py

대칭형 (Symmetric (Turbo3)) → 전반적으로 가장 우수한 압축 성능
비대칭형 (Asymmetric (Q8/Turbo4)) → Q4_K_M 모델 (예: Qwen)에 더 적합

• 실시간 VRAM 절감량을 확인하기 위해 **하드웨어 통계 (Hardware Stats)**를 모니터링하세요.

라이선스 (License): 이 프로젝트는 Apache 2.0 라이선스 하에 배포됩니다.
핵심 기술 (Core Technology): TheTom(@TheTom)이 개발한 TurboQuant+ 구현을 기반으로 구축되었습니다.
연구 및 알고리즘 (Research & Algorithms): 기반 알고리즘은 Google Research의 연구(arXiv:2504.19874)를 바탕으로 합니다.
CUDA 커널 (CUDA Kernels): CUDA 커널을 포팅해 준 Gabe Ortiz(signalnine)에게 특별히 감사드립니다.

👤 저자
Dr. Manuel Herrador 📧 mherrador@ujaen.es

University of Jaén (UJA) - 스페인

PacifAIst가 로컬 AI 커뮤니티를 위해 ❤️를 담아 만들었습니다.