<p align="center">
<h1 align="center">SpectralQuant</h1>
<p align="center">
<strong>3%로 충분하다: 스펙트럴 구조를 통한 TurboQuant의 압축 한계 돌파</strong>
</p>
<p align="center">
<a href="SpectralQuant_main.pdf"><img src="https://img.shields.io/badge/Paper-PDF-red" alt="Paper PDF"></a>
<a href="SpectralQuant_supplement.pdf"><img src="https://img.shields.io/badge/Supplement-PDF-red" alt="Supplement PDF"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
<img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python 3.10+">
<img src="https://img.shields.io/badge/PyTorch-2.2%2B-orange" alt="PyTorch 2.2+">
</p>
</p>
공식 논문 자료 (NeurIPS 2026 제출):
paper_output/, paper_output_v2/, 및 paper_output_consolidated/에 있는 이전 원고들은 추적 가능성을 위해 보관된 것이며, 현재 논문이 아닙니다.
이 저장소에 대하여
이것이 표준 사설 전체 SpectralQuant 저장소입니다: niashwin/spectralquant-full. 이 저장소는 기존의 공개 릴리스(Dynamis-Labs/spectralquant)와 이후 개발된 확장된 논문 검증 증거 계층을 통합했습니다. 현재 논문은 paper_neurips2026/에 제출된 NeurIPS 2026 관련 자료입니다 (최상위 레벨 편의 복사본: SpectralQuant_main.pdf 및 SpectralQuant_supplement.pdf). 이전 통합 기술 보고서인 paper_output_consolidated/와 원래 NeurIPS 형식 원고인 paper_output/는 역사적 아티팩트로만 보존됩니다.
이 저장소는 2026-05-01에 niashwin/spectralquant-v2에서 niashwin/spectralquant-full로 이름이 변경되었습니다. 이전 이름인 niashwin/spectralquant-v2는 다음 항목들에서 그대로 유지됩니다:
results/v3/modal/ 아래의 아카이브된 JSON repo 필드 (고정 실험 아티팩트);
- Modal 볼륨 이름
spectralquant-v2-results;
- 역사적 파일 시스템 경로 (
paper_output_v2/, docs/spectralquant_v2_technical_spec.md, experiments/sqv2_replay.py);
- JSON 메서드 키
spectralquant_v2 및 증거 카탈로그 식별자 (V1-*, V2-SPEC-*, RUN-*).
이러한 역사적 레이블은 의도적인 추적 가능 앵커(traceability anchors)이며, docs/consolidated_spectralquant_inventory.md와 docs/claims_discipline.md에 문서화되어 있습니다. 통합 저장소에 대한 모든 대외 참조는 niashwin/spectralquant-full을 사용해야 합니다.
개요 (Overview)
SpectralQuant는 대규모 언어 모델(LLM) 추론을 위한 KV 캐시 압축 방식입니다. 이 방식은 보편적인 구조적 속성을 활용하여 TurboQuant (Zandieh et al., ICLR 2026)보다 개선되었는데, 바로 4개의 아키텍처 패밀리 내 6개 모델에 걸쳐 KV 캐시 키 벡터가 헤드 차원(head dimension)의 단지 **3~4%**에 신호를 집중시킨다는 점입니다.
일회성 **15초 보정(calibration)**을 통해 이러한 차원들을 식별하고 나머지 96–97%의 노이즈 차원에 대한 오류 수정을 제거함으로써, SpectralQuant는 더 나은 품질과 더 나은 압축을 동시에 달성합니다.
주요 결과 (Headline Results)
| SpectralQuant | TurboQuant | 개선 정도 (Improvement) |
|---|
| 코사인 유사도 (Cosine similarity) (Qwen 2.5-14B) | 0.9485 | 0.9226 | +2.59 pp |
| ... | | | |
핵심 발견 사항 (Key Findings)
-
범용적인 저랭크 구조(Universal low-rank structure). Qwen (1.5B, 7B, 14B), Llama 3.1-8B, Mistral 7B, Gemma 2-9B 전반에 걸쳐 d_eff/head_dim ≈ 3–4%로 나타나며 — 이 비율은 헤드 차원, 모델 크기 및 아키텍처 계열 전반에서 일정합니다.
-
통계적으로 유의미함 (Statistically significant). Qwen 2.5-1.5B에 대한 10-seed CI 결과: SQ 평균=0.8635 ± 0.0024 vs TQ 평균=0.8409 ± 0.0046, Wilcoxon p=0.031.
-
모든 시퀀스 길이에서 더 빠름 (Faster at all sequence lengths). SQ는 512, 1024, 2048 토큰에서 TQ보다 빠릅니다. 보정 인지 압축(calibration-aware compression)에 대한 지연 시간 페널티가 없습니다.
-
KV 스펙트럼 비대칭성 (KV spectral asymmetry). 키(Keys): d_eff ≈ 4. 값(Values): d_eff ≈ 40–55 (10–15배 더 큼). 이는 저랭크 압축이 값에 대해 실패하는 반면 SpectralQuant가 성공하는 이유를 설명합니다.
빠른 시작 (Quick Start)
git clone https://github.com/dynamis-labs/spectralquant.git
cd spectralquant
pip install -e ".[dev]"
...
전체 재현 (Full Reproduction)
PYTHONPATH=src python experiments/neurips_models_asymmetry.py
PYTHONPATH=src python experiments/neurips_seeds_latency.py
...
요구 사항 (Requirements)
- Python ≥ 3.10
- PyTorch ≥ 2.2.0
- CUDA GPU (실험은 NVIDIA B200에서 실행됨)
랜덤 시드 (Random Seeds)
모든 실험은 기본값으로 seed 42를 사용합니다. 10-seed CI 테스트는 다음 시드를 사용합니다: 42, 123, 7, 2024, 31415, 99, 1337, 8675309, 271828, 314159.
논문 주장 → 코드 → 데이터 (Paper Claims → Code → Data)
논문의 모든 숫자는 이 저장소의 스크립트 및 결과 파일로 추적됩니다.
| 논문 섹션 | 주장/결과 | 스크립트 | 결과 파일 |
|---|
| Abstract | SQ 0.9485 vs TQ 0.9226 on 14B (+2.59 pp) | run_memory_efficiency.py | results/memory_efficiency/all_models.json |
| ... | | | |
Repository Structure (저장소 구조)
spectralquant/
├── src/spectralquant/ 핵심 라이브러리 (9개 모듈)
│ ├── calibration.py 고유 스펙트럼 보정 (Eigenspectral calibration) (PCA, d_eff, κ)
...
Experiment Scripts (실험 스크립트)
| 스크립트 | 설명 | 출력 |
|---|
neurips_models_asymmetry.py | Mistral 7B + Gemma 2-9B + KV 비대칭성 (5개 모델) | results/neurips/neurips_mistral.json, neurips_gemma.json, neurips_kv_asymmetry.json |
| ... | | |
Attribution (출처)
TurboQuant — Zandieh, Daliri, Hadian, and Mirrokni (Google Research / Google DeepMind / NYU).
논문: arXiv:2504.19874, ICLR 2026.
우리는 Anirudh Bharadwaj Vangara가 구현한 커뮤니티 버전을 사용합니다: DevTechJr/turboquant_cutile.
The Price of Meaning — Barman, Starenky, Bodnar, Narasimhan, and Gopinath (Sentra).
논문: arXiv:2603.27116.
SpectralQuant의 고유 스펙트럼 분석은 의미론적 메모리 시스템이 그 표현(representation)에서 보편적인 낮은 계수 구조(universal low-rank structure)를 나타낸다는 이 연구의 관찰에 기반합니다.
Citation (인용)
@article{gopinath2026spectralquant,
title={3% Is All You Need: Breaking {TurboQuant}'s Compression Limit
via Spectral Structure},
...
License (라이선스)
MIT 라이선스. LICENSE 참조.