FujitsuResearch/OneCompression

Fujitsu One Compression (OneComp) – 개요

OneComp는 대규모 언어 모델(LLM)을 압축하여 정확도 손실을 최소화하면서 GPU(또는 CPU/MPS 장치) 메모리에 맞게 줄여주는 Python 라이브러리입니다. 다음과 같은 단일 명령으로 실행할 수 있습니다:

onecomp meta-llama/Llama-2-7b-hf

또는 Python에서 Runner.auto_run()을 통해 실행합니다. 이 도구는 자동으로 다음을 수행합니다:

VRAM 용량을 감지합니다.
적합한 레이어별 비트 폭(예: 4-bit, 3-bit, sub-1-bit)을 선택합니다.
정교한 학습 후 양자화 기술을 사용하여 모델을 양자화합니다.
양자화된 모델을 평가하고 결과를 디스크에 저장합니다.

핵심 기능 (README 설명 기준)

기능	설명
Quantization Error Propagation (QEP)	표준 학습 후 양자화 이후, QEP는 양자화 오차를 네트워크 전체로 전파하여 후속 레이어에서 보상하도록 함으로써 정확도를 향상시킵니다.
Layer-Projected Coordinate Descent (LPCD)	완화된 최적화 문제를 해결하고 해를 각 레이어의 양자화기에 투영하여 임의의 하위 모듈을 양자화할 수 있는 유연한 PTQ 프레임워크입니다.
AutoBit	비트 폭 할당을 정수 선형 계획법으로 공식화하여 VRAM 예산에 맞춰 최적의 레이어별 비트를 자동으로 선택하는 혼합 정밀도 양자화입니다.
JointQ	가중치 양자화와 스케일링 계수를 동시에 최적화하며, 그룹화 양자화(예: groupsize = 128인 4-bit)를 지원합니다.
MDBF (Multi-Envelope Double Binary Factorization)	각 가중치 행렬을 부호 있는 이진 행렬과 FP16 "엔벨로프"의 합으로 표현하는 강력한 이진 인자 양자화기로, ADMM/그래디언트 미세 조정을 통해 sub-1-bit 압축을 가능하게 합니다.
Block-wise PTQ	FP16 교사 모델에 대해 블록 단위로 증류를 수행하여 중간 표현 오차를 줄입니다.
LoRA SFT Post-Process	LoRA 어댑터를 사용하여 양자화된 모델을 미세 조정함으로써 정확도를 복구하거나 도메인 지식을 추가합니다.
Rotation Preprocessing	양자화 전에 회전 행렬(SpinQuant/OstQuant)을 학습하여 오차를 줄입니다. 회전은 로드 시 가중치에 적용됩니다.
vLLM Plugin Integration	내장 플러그인을 통해 고성능 vLLM 추론 엔진으로 양자화된 모델을 서비스할 수 있으며, Open WebUI와 결합하여 로컬 ChatGPT 스타일 UI를 구현할 수 있습니다.
GGUF Export & Hugging Face Hub	모델을 GGUF v3 형식(llama.cpp/Ollama용)으로 변환하고, 양자화 레시피가 포함된 모델 카드를 작성하여 Hugging Face Hub에 푸시할 수 있습니다.
Web Dashboard (HPC)	HPC 클러스터에서 양자화 작업을 시작하고, 진행 상황을 모니터링하며, 채팅 추론을 테스트하기 위한 브라우저 기반 UI입니다.

지원 모델 제품군

이 라이브러리는 Llama (1-3), Qwen3 (최대 32B), Gemma (2-4), GPT-OSS (20B & 120B), Qwen3.6 (최대 35B)에서 테스트되었습니다. 기타 Hugging Face 호환 모델도 작동할 수 있으나 공식적으로 검증되지는 않았습니다.

설치 및 사용법

최종 사용자 – PyTorch(CPU, CUDA 또는 macOS MPS)를 설치한 후 pip install onecomp를 실행합니다. 다중 GPU DeepSpeed 지원을 위해 distributed 옵션을 추가하세요.
개발자 – 저장소에서는 재현 가능한 환경을 만들기 위해 Rust 기반의 uv 도구를 권장하며, CUDA 버전, vLLM, 시각화, 문서 등을 위한 추가 옵션이 제공됩니다.
실행 – CLI(onecomp <model-id>) 또는 Python API(Runner.auto_run)가 보정 데이터 로드부터 양자화 체크포인트 저장까지 모든 과정을 처리합니다.

문서 및 리소스

전체 문서: https://FujitsuResearch.github.io/OneCompression/
튜토리얼 노트북(Jupyter/Colab)에서 RTN 시각화, Runner.auto_run, vLLM 채팅 추론을 안내합니다.
예제 스크립트는 모든 기능(GPTQ, QEP, LPCD, AutoBit, LoRA SFT, vLLM serving 등)을 다룹니다.
학술 참조: QEP에 관한 NeurIPS 2025 논문 및 LPCD에 관한 arXiv 2025 논문.

대상 사용자

LLM의 저비트 양자화 방법을 평가해야 하는 연구원.
단일 GPU 또는 CPU/MPS 장치에서 대규모 모델을 실행하려는 엔지니어.
vLLM과 웹 UI를 사용하여 로컬에 양자화된 모델을 배포하려는 모든 사용자.

결론: OneComp는 대규모 언어 모델의 학습 후 양자화를 위한 진정한 프로덕션급 툴킷으로, 고급 알고리즘과 주요 추론 스택과의 원활한 통합을 제공합니다.