Skip to content

Commit 26dfeab

Browse files
unamedkrclaude
unamedkr
and
claude
committed
Update all docs: inference engine, Q8, 14 tok/s, Qwen3.5 results
README.md (en): - Lead: "LLM inference engine" (not just library) - Results: 14 tok/s CPU, 17x PyTorch, Q8 533MB, KV 7.5x - Run It: tq_run example with actual output - What Makes It Fast: engine architecture, integer attention, Q8 - Real Model Validation: 1+1=2, Paris, Tokyo, logits cosine 0.999 - CLI Reference: tq_run flags + Python CLI README.ko.md: Korean mirror docs/announcement_en.md + announcement_ko.md: - Updated with inference engine messaging CHANGELOG.md: - v0.8 inference engine highlights at top Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 1932231 commit 26dfeab

5 files changed

Lines changed: 273 additions & 253 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,17 @@
44

55
### Highlights
66

7+
- **Self-contained inference engine** — loads Qwen3.5-0.8B, generates text at 14 tok/s on CPU
8+
- **17x faster than PyTorch CPU**, 1.4x faster than PyTorch on Apple GPU
9+
- **Q8 weight quantization** — 4x memory reduction (2.1 GB → 533 MB), `-q` flag
10+
- **Streaming BF16** — embed/lm_head kept as mmap'd BF16, saves ~1 GB
11+
- **Multi-threaded matmul** — 4-thread pthread, 1.56x speedup
12+
- **DeltaNet + Self-Attention** — full Qwen3.5 hybrid architecture in C
13+
- **HuggingFace BPE tokenizer** — 248K vocab, encode/decode
14+
- **KV cache quantized in inference** — Q4 keys, integer Q4×Q8 attention
15+
16+
### v0.8 Inference Engine
17+
718
- **Integer-domain attention**: 2.9-4.8x faster than FP32 on Apple Silicon (ARM NEON `vdotq_s32`)
819
- **Real model validated**: Qwen3.5-0.8B KV cache, cosine 0.994 (A+)
920
- **8 quantization types** including mixed precision outlier and RHT pre-rotation

‎README.ko.md‎

Lines changed: 103 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -2,149 +2,170 @@
22

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

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

7-
동일 하드웨어에서 **3배 긴 컨텍스트** — 또는 동일 비용으로 **3배 많은 사용자**.
7+
모델 로드, 텍스트 생성, KV 캐시 압축 — 하나의 바이너리, Python 불필요.
88

99
[![Build](https://img.shields.io/badge/build-passing-brightgreen)]()
10-
[![Tests](https://img.shields.io/badge/tests-38%2B%20pass-brightgreen)]()
10+
[![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 Validated](https://img.shields.io/badge/Qwen3.5--0.8B-validated-blue)]()
12+
[![Qwen3.5](https://img.shields.io/badge/Qwen3.5--0.8B-14%20tok%2Fs-blue)]()
1313

1414
---
1515

16-
## 한눈에 보는 결과
16+
## 한눈에 보기
1717

18-
| | FP16 (기준) | TurboQuant |
18+
| | PyTorch | TurboQuant.cpp |
1919
|---|---|---|
20-
| **KV 캐시 크기** | 7.00 GB | **0.93 GB** (87% 절약) |
21-
| **Attention 속도** | 1.0x | **2.9-4.8배 빠름** |
22-
| **최대 컨텍스트 (24GB GPU)** | 164K 토큰 | **540K 토큰** |
23-
| **품질 (코사인)** | 1.000 | **0.994** (A+) |
20+
| **CPU 속도** | 0.8 tok/s | **14 tok/s** (17배) |
21+
| **GPU 속도** | 10 tok/s (MPS) | **14 tok/s (CPU만으로!)** |
22+
| **가중치 메모리** | 1.7 GB (BF16) | **533 MB** (Q8, `-q` 플래그) |
23+
| **KV 캐시** | FP16 (전체 크기) | **7.5배 압축** (4-bit) |
24+
| **의존성** | PyTorch + transformers | **0개** (순수 C) |
2425

25-
> Llama-3.2-3B @ 64K 기준. [Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B) 실제 추론으로 검증.
26+
> Qwen3.5-0.8B, Apple Silicon 기준. CPU 엔진이 PyTorch GPU보다 빠름.
2627
2728
---
2829

29-
## 지금 바로 체험 (30초)
30+
## 실행하기
3031

3132
```bash
32-
git clone https://github.com/quantumaikr/TurboQuant.cpp
33-
cd TurboQuant.cpp
33+
git clone https://github.com/quantumaikr/TurboQuant.cpp && cd TurboQuant.cpp
34+
cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)
3435

35-
cmake -B build -DCMAKE_BUILD_TYPE=Release -DTQ_BUILD_TESTS=ON -DTQ_BUILD_BENCH=ON
36-
cmake --build build -j$(sysctl -n hw.ncpu 2>/dev/null || nproc)
37-
38-
# A/B 비교 직접 확인
39-
./build/ab_test
40-
41-
# 실제 LLM 모델별 메모리 절약
42-
./build/demo_real_model
36+
# 텍스트 생성 (14 tok/s, Q8 가중치, 4 스레드)
37+
./build/tq_run model.safetensors -t tokenizer.json -p "What is AI?" -j 4 -q
38+
```
4339

44-
# 속도: 정수 Attention vs FP32
45-
./build/speed_int_vs_float
40+
```
41+
Prompt: What is AI?
42+
---
43+
Artificial intelligence (AI) is a field of computer science that focuses
44+
on creating systems capable of performing tasks that typically require
45+
human intelligence...
46+
---
47+
100 tokens in 7.2s (13.9 tok/s, 4 threads, kv=uniform_4b)
4648
```
4749

4850
### Python
4951

50-
```bash
51-
pip install -e bindings/python
52-
53-
python3 examples/python_quickstart.py
54-
```
55-
5652
```python
5753
from turboquant import TurboQuant
58-
import numpy as np
59-
6054
tq = TurboQuant("cpu")
61-
keys = np.random.randn(512, 128).astype(np.float32) * 0.15
62-
63-
compressed = tq.quantize_keys(keys, TurboQuant.UNIFORM_4B)
64-
print(f"압축: {keys.nbytes:,} → {len(compressed):,} bytes ({keys.nbytes/len(compressed):.1f}x)")
55+
compressed = tq.quantize_keys(keys, TurboQuant.UNIFORM_4B) # 7.5배 압축
56+
scores = tq.attention(query, compressed, seq_len, dim, TurboQuant.UNIFORM_4B)
6557
```
6658

67-
### C
59+
---
6860

69-
```c
70-
#include "turboquant/turboquant.h"
61+
## 왜 빠른가
7162

72-
tq_context_t* ctx;
73-
tq_init(&ctx, TQ_BACKEND_CPU);
63+
### 1. 자체 추론 엔진
7464

75-
// 7.5배 압축, 한 줄
76-
tq_quantize_keys(ctx, keys, n, dim, TQ_TYPE_UNIFORM_4B, out, size);
65+
래퍼가 아닌 순수 C 추론 엔진:
7766

78-
// 압축된 캐시에서 직접 Attention — FP32보다 2.9배 빠름
79-
tq_attention(ctx, query, out, n, dim, TQ_TYPE_UNIFORM_4B, scores);
67+
```
68+
모델 로딩 safetensors (mmap, BF16→FP32 스트리밍)
69+
토크나이저 HuggingFace BPE (248K 어휘)
70+
Forward Pass DeltaNet + Self-Attention (Qwen3.5 하이브리드)
71+
KV 캐시 TurboQuant 양자화 (4-bit, 자동 압축)
72+
Attention 정수 Q4×Q8 (FP32 대비 2.9배 빠름)
73+
가중치 Q8 양자화 (-q 플래그, 메모리 4배 절약)
74+
생성 Top-p 샘플링, 스트리밍 출력
8075
```
8176

82-
---
77+
### 2. 정수 도메인 Attention
78+
79+
양자화 데이터에서 직접 attention 계산 — 역양자화 없음:
8380

84-
## 세 가지 돌파구
81+
```
82+
FP32 attention: 22.8 μs (기준)
83+
Q4×Q8 정수: 7.8 μs (2.9배 빠름, ARM vdotq_s32)
84+
```
8585

86-
### 1. 작을 뿐 아니라 더 빠르다
86+
### 3. Q8 가중치 양자화
8787

88-
대부분의 양자화는 작아지지만 느려집니다. TurboQuant은 정수 도메인에서 직접 계산하여 attention이 **FP32보다 2.9-4.8배 빠릅니다**.
88+
가중치 4배 압축, 품질 손실 무시:
8989

9090
```
91-
FP32: query × key = float dot → 22.8 μs
92-
Q4×Q8: int_query × int_key = int_dot → 7.8 μs (2.9배 빠름)
91+
./build/tq_run model.safetensors -p "1+1=" -q
92+
→ "2" (정확, 2.1 GB 대신 533 MB)
9393
```
9494

95-
### 2. 실제 모델로 검증
95+
---
9696

97-
합성 벤치마크가 아닌 실제 [Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B) KV 캐시:
97+
## 실제 모델 검증
9898

99-
| 타입 | 압축률 | 품질 | 등급 |
100-
|------|--------|------|------|
101-
| **uniform_4b** | 7.5x | 코사인 0.994 | **A+** |
102-
| **mixed_4b8** | 6.4x | 코사인 0.994 | **A+** |
103-
| uniform_2b | 14.2x | 코사인 0.953 | A |
99+
[Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B)로 검증 — 합성이 아닌 실제 추론:
104100

105-
### 3. 커뮤니티 검증 아키텍처
101+
| 테스트 | 결과 |
102+
|--------|------|
103+
| "1+1=" | **2** ✓ |
104+
| "The capital of France is" | **Paris** ✓ |
105+
| "The capital of Japan is" | **Tokyo** ✓ |
106+
| "What is deep learning?" | 정확한 문단 ✓ |
107+
| PyTorch 대비 logits 코사인 | **0.999** |
106108

107-
r/LocalLLaMA 커뮤니티와 llama.cpp Discussion #20969에서 검증된 기법:
109+
### KV 캐시 품질
108110

109-
- **정수 내적** (llama.cpp `vec_dot` 패턴)
110-
- **Random Hadamard Transform** (Qwen3.5에서 MSE 3.9배 감소)
111-
- **K/V 비대칭** 양자화 (Key 4bit + Value 2bit = 9.8배 압축)
112-
- **Mixed Precision** 아웃라이어 탐지 (fp16 + 4bit)
111+
| 타입 | 압축률 | 품질 (코사인) | 등급 |
112+
|------|--------|-------------|------|
113+
| **uniform_4b** | 7.5x | 0.994 | **A+** |
114+
| **mixed_4b8** | 6.4x | 0.994 | **A+** |
115+
| uniform_2b | 14.2x | 0.953 | A |
113116

114117
---
115118

116-
## 얼마나 절약되나?
119+
## CLI 사용법
117120

118-
| 모델 | GPU | FP16 컨텍스트 | TurboQuant | 향상 |
119-
|------|-----|-------------|------------|------|
120-
| Qwen3.5-0.8B | 8GB M2 Air | 87K | **286K** | 3.3x |
121-
| Llama-3.2-1B | 16GB RTX 4060 | 445K | **1,462K** | 3.3x |
122-
| Llama-3.2-3B | 24GB RTX 4090 | 164K | **540K** | 3.3x |
121+
```bash
122+
# 기본 추론
123+
./build/tq_run MODEL -t TOKENIZER -p "프롬프트" -n 100
124+
125+
# 옵션
126+
-j 4 # 스레드 수 (기본: 4)
127+
-q # Q8 가중치 양자화 (메모리 4배 절약)
128+
-k uniform_4b # KV 캐시 타입
129+
-T 0.7 # temperature
130+
-P 0.9 # top-p
131+
--info # 모델 정보 표시
132+
```
133+
134+
### Python CLI
135+
136+
```bash
137+
python3 tools/tq info # 양자화 타입 정보
138+
python3 tools/tq bench # 성능 벤치마크
139+
python3 tools/tq +memory llama-3.2-3b 65536 # 메모리 계산
140+
python3 tools/tq +memory qwen3.5-0.8b 131072 --json # JSON 출력
141+
```
123142

124143
---
125144

126145
## 문서
127146

128147
| 문서 | 설명 |
129148
|------|------|
130-
| **[시작 가이드](docs/getting-started.md)** | **빌드, CLI, Python, C API, llama.cpp — 한 페이지에 모두** |
131-
| [아키텍처](docs/architecture.md) | 4-layer 설계, 타입 시스템, 디스패치 |
132-
| [Qwen3.5 검증](docs/qwen35_validation_results.md) | 실제 모델 A/B 테스트 결과 |
149+
| **[시작 가이드](docs/getting-started.md)** | 빌드, 실행, 통합 |
150+
| [아키텍처](docs/architecture.md) | 엔진 설계, 타입 시스템 |
151+
| [Qwen3.5 검증](docs/qwen35_validation_results.md) | 실제 모델 A/B 결과 |
133152
| [통합 가이드](docs/integration_guide.md) | llama.cpp, vLLM, Python |
134-
| [llama.cpp 플러그인](integrations/llamacpp/README.md) | llama.cpp 통합 단계별 가이드 |
135-
| [포맷 사양](spec/tq_format_v1.md) | 블록 구조, 비트 패킹 |
136-
| [변경 이력](CHANGELOG.md) | 전체 릴리즈 노트 |
153+
| [변경 이력](CHANGELOG.md) | 릴리즈 노트 |
137154

138155
---
139156

140-
## 기술 특징
157+
## 기술 요약
141158

159+
- **자체 추론 엔진** — 모델 로드, 토큰화, forward, 생성을 순수 C로
142160
- **8개 양자화 타입** — Uniform, Mixed Precision, PolarQuant, QJL, TurboQuant
143-
- **정수 도메인 Attention** — Q4×Q8, ARM `vdotq_s32` / x86 VNNI
144-
- **외부 의존성 제로** — 순수 C11/C++17, libc/libm만 사용
145-
- **스레드 안전** — pthread mutex, TSan 검증
146-
- **38+ 테스트** — ASan + UBSan + TSan 클린
147-
- **GPU 대응** — CUDA + Metal 커널 포함
161+
- **Q8 가중치** — 메모리 4배 절약, NEON 최적화 matmul
162+
- **정수 attention** — Q4×Q8, ARM `vdotq_s32`
163+
- **멀티스레드** — pthread matmul, 설정 가능한 스레드 수
164+
- **하이브리드 모델** — DeltaNet (순환) + Self-Attention (Qwen3.5)
165+
- **RHT** — Random Hadamard Transform, MSE 3.9배 감소
166+
- **K/V 비대칭** — 키/값 독립 비트 할당
167+
- **외부 의존성 제로** — 순수 C11, libc/libm만
168+
- **70+ 테스트** — 19 C++ 스위트 + 22 Python, ASan/UBSan/TSan 클린
148169

149170
---
150171

0 commit comments

Comments
 (0)