Skip to content

Commit 668f017

Browse files
unamedkrclaude
unamedkr
and
claude
committed
Rewrite README for 47 tok/s achievement showcase
Hero banner with speed comparison, 30-second quick start, architecture diagram, five optimizations table, and journey section. Both EN and KO versions updated. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 4442400 commit 668f017

2 files changed

Lines changed: 252 additions & 233 deletions

File tree

‎README.ko.md‎

Lines changed: 124 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -2,183 +2,197 @@
22

33
![TurboQuant Hero](docs/assets/hero.png)
44

5-
**극한 KV 캐시 압축을 내장한 LLM 추론 엔진. 외부 의존성 없음. 순수 C.**
5+
**순수 C LLM 추론 엔진. 47 tok/s. 외부 의존성 없음.**
66

7-
모델 로드, 텍스트 생성, KV 캐시 압축 — 하나의 바이너리, Python 불필요.
7+
로드 → 생성 → 끝. Python 없이. GPU 없이. 바이너리 하나로.
88

99
[![Build](https://img.shields.io/badge/build-passing-brightgreen)]()
1010
[![Tests](https://img.shields.io/badge/tests-70%2B%20pass-brightgreen)]()
1111
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)]()
12-
[![Qwen3.5](https://img.shields.io/badge/Qwen3.5--0.8B-14%20tok%2Fs-blue)]()
12+
[![Speed](https://img.shields.io/badge/47%20tok%2Fs-Qwen3.5--0.8B-blue)]()
1313

14-
---
15-
16-
## 한눈에 보기
17-
18-
| | PyTorch | TurboQuant.cpp |
19-
|---|---|---|
20-
| **CPU 속도** | 0.8 tok/s | **18 tok/s** (23배) |
21-
| **GPU 속도** | 10 tok/s (MPS) | **18 tok/s (CPU만으로!)** |
22-
| **모델 로딩** | ~3초 | **< 0.3초** (TQM mmap) |
23-
| **가중치 메모리** | 1.7 GB (BF16) | **270 MB** (Q4) |
24-
| **KV 캐시** | FP16 (전체 크기) | **7.5배 압축** (4-bit) |
25-
| **의존성** | PyTorch + transformers | **0개** (순수 C) |
26-
27-
> Qwen3.5-0.8B, Apple Silicon 기준. CPU만으로 PyTorch GPU보다 빠름.
14+
```
15+
PyTorch CPU: 0.8 tok/s
16+
PyTorch GPU: 10 tok/s
17+
TurboQuant CPU: 47 tok/s ← 59배 빠름, GPU 불필요
18+
```
2819

2920
---
3021

31-
## 실행하기
22+
## 30초 빠른 시작
3223

3324
```bash
3425
git clone https://github.com/quantumaikr/TurboQuant.cpp && cd TurboQuant.cpp
3526
cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)
3627

37-
# Step 1: 모델 변환 (1회, 자동 감지)
28+
# 모델 변환 (1회, HuggingFace 캐시 자동 감지)
3829
./build/tq_convert
3930

40-
# Step 2: 추론 (즉시 로딩, 토크나이저 내장)
41-
./build/tq_run model.tqm -p "What is AI?" -j 4
31+
# 실행
32+
./build/tq_run model.tqm -p "What is deep learning?" -j 4
4233
```
4334

4435
```
45-
Prompt: What is AI?
36+
Prompt: What is deep learning?
4637
---
47-
Artificial intelligence (AI) is a field of computer science that focuses
48-
on creating systems capable of performing tasks that typically require
49-
human intelligence...
38+
Deep learning is a field of artificial intelligence and machine learning
39+
that uses artificial neural networks to learn complex patterns...
5040
---
51-
50 tokens in 2.7s (18.3 tok/s, 4 threads, kv=uniform_4b)
52-
```
53-
54-
### Python
55-
56-
```python
57-
from turboquant import TurboQuant
58-
tq = TurboQuant("cpu")
59-
compressed = tq.quantize_keys(keys, TurboQuant.UNIFORM_4B) # 7.5배 압축
60-
scores = tq.attention(query, compressed, seq_len, dim, TurboQuant.UNIFORM_4B)
41+
100 tokens in 2.1s (46.9 tok/s, 4 threads, weights=Q4, kv=uniform_4b)
6142
```
6243

6344
---
6445

65-
## 왜 빠른가
46+
## 왜 TurboQuant인가?
47+
48+
| | PyTorch | TurboQuant.cpp |
49+
|---|---|---|
50+
| **속도** | 0.8 tok/s | **47 tok/s** (59배) |
51+
| **로딩** | 3초 | **0.3초** (mmap) |
52+
| **가중치 메모리** | 1.7 GB | **270 MB** (Q4) |
53+
| **KV 캐시** | 전체 크기 | **7.5배 압축** |
54+
| **의존성** | PyTorch, transformers | **없음** |
55+
| **바이너리** | ~2 GB 설치 | **~1 MB** |
56+
| **품질** | 기준 | **코사인 0.999** (PyTorch 대비) |
6657

67-
### 1. 자체 추론 엔진
58+
---
6859

69-
래퍼가 아닌 순수 C 추론 엔진:
60+
## 구성 요소
7061

7162
```
72-
모델 로딩 safetensors (mmap, BF16→FP32 스트리밍)
73-
토크나이저 HuggingFace BPE (248K 어휘)
74-
Forward Pass DeltaNet + Self-Attention (Qwen3.5 하이브리드)
75-
KV 캐시 TurboQuant 양자화 (4-bit, 자동 압축)
76-
Attention 정수 Q4×Q8 (FP32 대비 2.9배 빠름)
77-
가중치 Q8 양자화 (-q 플래그, 메모리 4배 절약)
78-
생성 Top-p 샘플링, 스트리밍 출력
63+
┌─────────────────────────────────────────────────────┐
64+
│ tq_convert │
65+
│ safetensors → TQM (사전 양자화, mmap 가능) │
66+
├─────────────────────────────────────────────────────┤
67+
│ tq_run │
68+
│ TQM → mmap 로드 → forward → 토큰 스트리밍 │
69+
│ │
70+
│ ┌─── Forward Pass ────────────────────────────┐ │
71+
│ │ DeltaNet (18 레이어, 순환) │ │
72+
│ │ Self-Attention (6 레이어, GQA + RoPE) │ │
73+
│ │ SwiGLU FFN (전체 24 레이어) │ │
74+
│ │ KV 캐시: TurboQuant Q4 양자화 │ │
75+
│ │ Attention: 정수 Q4×Q8 (FP32 대비 2.9배) │ │
76+
│ └─────────────────────────────────────────────┘ │
77+
│ │
78+
│ Q4 가중치 ── NEON matmul ── 멀티스레드 │
79+
└─────────────────────────────────────────────────────┘
7980
```
8081

81-
### 2. 정수 도메인 Attention
82-
83-
양자화 데이터에서 직접 attention 계산 — 역양자화 없음:
82+
### 5가지 최적화
8483

85-
```
86-
FP32 attention: 22.8 μs (기준)
87-
Q4×Q8 정수: 7.8 μs (2.9배 빠름, ARM vdotq_s32)
88-
```
84+
| # | 기법 | 효과 |
85+
|---|------|------|
86+
| 1 | **Q4 가중치** — 4-bit, 8배 작음 | 2배 빠름 |
87+
| 2 | **TQM 포맷** — 사전 양자화 mmap | 10배 빠른 로딩 |
88+
| 3 | **정수 attention** — Q4×Q8, ARM vdotq_s32 | 2.9배 빠름 |
89+
| 4 | **멀티스레드 matmul** — pthread, NEON | 1.6배 빠름 |
90+
| 5 | **스트리밍 BF16** — 임베딩 온디맨드 | 메모리 6배 절약 |
8991

90-
### 3. Q8 가중치 양자화
92+
### 실제 모델 검증
9193

92-
가중치 4배 압축, 품질 손실 무시:
94+
[Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B) — 실제 추론, 합성 아님:
9395

9496
```
95-
./build/tq_run model.safetensors -p "1+1=" -q
96-
→ "2" (정확, 2.1 GB 대신 533 MB)
97+
"1+1=" → "2" ✓
98+
"The capital of France is" → "Paris" ✓
99+
"What is deep learning?" → 정확한 문단 ✓
100+
PyTorch 대비 logits 코사인 → 0.999 ✓
97101
```
98102

99103
---
100104

101-
## 실제 모델 검증
105+
## 시퀀스 길이별 속도
102106

103-
[Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B)로 검증 — 합성이 아닌 실제 추론:
104-
105-
| 테스트 | 결과 |
106-
|--------|------|
107-
| "1+1=" | **2** ✓ |
108-
| "The capital of France is" | **Paris** ✓ |
109-
| "The capital of Japan is" | **Tokyo** ✓ |
110-
| "What is deep learning?" | 정확한 문단 ✓ |
111-
| PyTorch 대비 logits 코사인 | **0.999** |
112-
113-
### KV 캐시 품질
114-
115-
| 타입 | 압축률 | 품질 (코사인) | 등급 |
116-
|------|--------|-------------|------|
117-
| **uniform_4b** | 7.5x | 0.994 | **A+** |
118-
| **mixed_4b8** | 6.4x | 0.994 | **A+** |
119-
| uniform_2b | 14.2x | 0.953 | A |
107+
```
108+
토큰 수 속도 비고
109+
────── ───────── ──────────────────
110+
10 12 tok/s 첫 토큰 지연 포함
111+
30 41 tok/s ← 40 tok/s 돌파
112+
50 44 tok/s
113+
100 47 tok/s ← 정상 속도
114+
200 48 tok/s ← 최대
115+
```
120116

121117
---
122118

123-
## CLI 사용법
119+
## CLI
124120

125121
```bash
126-
# 기본 추론
127-
./build/tq_run MODEL -t TOKENIZER -p "프롬프트" -n 100
128-
129-
# 옵션
130-
-j 4 # 스레드 수 (기본: 4)
131-
-q # Q8 가중치 양자화 (메모리 4배 절약)
132-
-k uniform_4b # KV 캐시 타입
133-
-T 0.7 # temperature
134-
-P 0.9 # top-p
135-
--info # 모델 정보 표시
122+
# 변환 (1회)
123+
./build/tq_convert # 자동 감지
124+
125+
# 추론
126+
./build/tq_run model.tqm -p "Hello" # 토크나이저 내장
127+
./build/tq_run model.tqm -p "Hello" -j 4 -n 200 -T 0.7
128+
129+
# Python CLI
130+
python3 tools/tq info # 양자화 타입
131+
python3 tools/tq +memory llama-3.2-3b 65536
132+
python3 tools/tq_chat.py "What is AI?" # 네이티브 엔진 + KV 분석
136133
```
137134

138-
### Python CLI
135+
### Python API
139136

140-
```bash
141-
python3 tools/tq info # 양자화 타입 정보
142-
python3 tools/tq bench # 성능 벤치마크
143-
python3 tools/tq +memory llama-3.2-3b 65536 # 메모리 계산
144-
python3 tools/tq +memory qwen3.5-0.8b 131072 --json # JSON 출력
137+
```python
138+
from turboquant import TurboQuant
139+
tq = TurboQuant("cpu")
140+
compressed = tq.quantize_keys(keys, TurboQuant.UNIFORM_4B) # 7.5배 압축
141+
scores = tq.attention(query, compressed, seq_len, dim, TurboQuant.UNIFORM_4B)
145142
```
146143

147144
---
148145

149146
## 문서
150147

151-
| 문서 | 설명 |
148+
| 문서 | 내용 |
152149
|------|------|
153-
| **[시작 가이드](docs/getting-started.md)** | 빌드, 실행, 통합 |
154-
| [아키텍처](docs/architecture.md) | 엔진 설계, 타입 시스템 |
155-
| [Qwen3.5 검증](docs/qwen35_validation_results.md) | 실제 모델 A/B 결과 |
150+
| **[시작 가이드](docs/getting-started.md)** | 빌드, 변환, 실행, 통합 |
151+
| [아키텍처](docs/architecture.md) | 엔진 설계, 4-layer 스택 |
152+
| [Qwen3.5 결과](docs/qwen35_validation_results.md) | 실제 모델 A/B 테스트 |
153+
| [변경 이력](CHANGELOG.md) | 전체 버전 히스토리 |
156154
| [통합 가이드](docs/integration_guide.md) | llama.cpp, vLLM, Python |
157-
| [변경 이력](CHANGELOG.md) | 릴리즈 노트 |
158155

159156
---
160157

161-
## 기술 요약
158+
## 기술 상세
162159

163-
- **자체 추론 엔진** — 모델 로드, 토큰화, forward, 생성을 순수 C로
160+
- **8,500줄 이상의 C** — 완전한 추론 엔진, 래퍼 아님
164161
- **8개 양자화 타입** — Uniform, Mixed Precision, PolarQuant, QJL, TurboQuant
165-
- **Q8 가중치** — 메모리 4배 절약, NEON 최적화 matmul
166-
- **정수 attention** — Q4×Q8, ARM `vdotq_s32`
167-
- **멀티스레드** — pthread matmul, 설정 가능한 스레드 수
168-
- **하이브리드 모델** — DeltaNet (순환) + Self-Attention (Qwen3.5)
169-
- **RHT** — Random Hadamard Transform, MSE 3.9배 감소
170-
- **K/V 비대칭** — 키/값 독립 비트 할당
171-
- **외부 의존성 제로** — 순수 C11, libc/libm만
172-
- **70+ 테스트** — 19 C++ 스위트 + 22 Python, ASan/UBSan/TSan 클린
162+
- **TQM 포맷** — 사전 양자화 바이너리, mmap 즉시 로딩
163+
- **DeltaNet + Self-Attention** — Qwen3.5 하이브리드 아키텍처 순수 C
164+
- **BPE 토크나이저** — HuggingFace 호환 (248K 어휘, TQM 내장)
165+
- **Q4×Q8 정수 attention** — ARM vdotq_s32, float 역양자화 없음
166+
- **멀티스레드** — pthread matmul + NEON, 설정 가능
167+
- **반복 방지** — repetition penalty로 퇴화 방지
168+
- **20 테스트 스위트, 70+ 테스트** — ASan + UBSan + TSan 클린
169+
170+
---
171+
172+
## 여정
173+
174+
```
175+
1일차 오전: 빈 디렉토리
176+
1일차 오후: KV 캐시 압축 라이브러리 (8개 타입, A/B 테스트)
177+
1일차 저녁: 완전한 추론 엔진 (모델 로드 → 텍스트 생성)
178+
1일차 밤: 47 tok/s, Q4 가중치, TQM 즉시 로딩
179+
180+
C 코드: 8,500줄 이상
181+
테스트: 20개 스위트 (70+ 테스트)
182+
커밋: 52개
183+
속도: 0.8 → 47 tok/s (59배 개선)
184+
```
173185

174186
---
175187

176188
## 참고 논문
177189

178-
- **TurboQuant** — [arXiv:2504.19874](https://arxiv.org/abs/2504.19874) (ICLR 2026)
179-
- **QJL** — [arXiv:2406.03482](https://arxiv.org/abs/2406.03482) (AAAI 2025)
180-
- **PolarQuant** — [arXiv:2502.02617](https://arxiv.org/abs/2502.02617) (AISTATS 2026)
190+
- [TurboQuant](https://arxiv.org/abs/2504.19874) (ICLR 2026) — KV 캐시 압축
191+
- [QJL](https://arxiv.org/abs/2406.03482) (AAAI 2025) — 1비트 양자화 JL 변환
192+
- [PolarQuant](https://arxiv.org/abs/2502.02617) (AISTATS 2026) — 극좌표 양자화
193+
194+
아키텍처: [llama.cpp](https://github.com/ggerganov/llama.cpp), [vLLM](https://github.com/vllm-project/vllm), [ONNX](https://github.com/onnx/onnx) 참조.
181195

182196
---
183197

184-
**개발사: [QuantumAI Inc.](https://quantumai.kr)** | [hi@quantumai.kr](mailto:hi@quantumai.kr)
198+
**[QuantumAI Inc.](https://quantumai.kr)** | [hi@quantumai.kr](mailto:hi@quantumai.kr)

0 commit comments

Comments
 (0)