Skip to content

Commit 3b8e04c

Browse files
unamedkrclaude
unamedkr
and
claude
committed
Add v1.4 PRD + WBS: community trust, killer demo, accessibility
Strategy based on Reddit/HN community feedback: Phase 1: H2H benchmark vs llama.cpp + upstream PR Phase 2: Book-in-a-Chat demo + WASM improvements Phase 3: pip install quantcpp + Windows binary + model CI Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 60531d6 commit 3b8e04c

2 files changed

Lines changed: 276 additions & 0 deletions

File tree

‎docs/plan/prd/prd_v1.4.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# PRD v1.4 — Community Trust & Killer Demo
2+
3+
## Background
4+
5+
v1.3까지 기술적 완성도 99.2%, 234 stars. Reddit/HN 커뮤니티 노출에서 핵심 피드백:
6+
7+
1. **비교가 공정하지 않다** (audioen) — llama.cpp Q8K+Q5V와 비교해야 함
8+
2. **말로 하지 말고 보여줘** (hauhau901, MelodicRecognition7) — 데모/벤치마크로 증명
9+
3. **속도가 느리다** (Emotional-Breath-838) — 속도 열세가 첫인상을 지배
10+
4. **킬러 유즈케이스가 없다** (putrasherni) — "7x longer context"가 수치지 경험이 아님
11+
5. **접근 장벽이 높다** (MimosaTen, Languages_Learner) — C 빌드가 진입 장벽
12+
13+
## Goal
14+
15+
**"직접 써봐"가 가능한 환경** — 수치 증명에서 체험 증명으로 전환.
16+
17+
## Target Metrics
18+
19+
| Metric | Current | Target | 의미 |
20+
|--------|---------|--------|------|
21+
| GitHub Stars | 234 | **500+** | 1차 마일스톤 |
22+
| "직접 돌려봤다" 리포트 | 0 | **10+** | 실사용자 확보 |
23+
| llama.cpp H2H 벤치마크 | 부정확 | **재현 가능** | 기술적 신뢰 확보 |
24+
| pip install 지원 | 없음 | **동작** | Python 유저 접근 |
25+
| 킬러 데모 | 없음 | **Book-in-a-Chat** | 바이럴 콘텐츠 |
26+
27+
## Scope
28+
29+
### Phase 1: 신뢰 확보 (P0)
30+
31+
**1.1 Head-to-head 벤치마크 자동화**
32+
33+
llama.cpp 최신 빌드와 동일 조건 비교. 재현 가능한 스크립트.
34+
35+
- 모델: SmolLM2 1.7B Q8_0
36+
- 하드웨어: M1 Pro 16GB, 8 threads
37+
- 설정:
38+
- llama.cpp: FP16 KV / Q8_0 K + Q5_0 V / Q4_0 K+V
39+
- quant.cpp: FP16 / uniform_4b K + Q4 V / delta_3b K + Q4 V
40+
- 측정: PPL (WikiText-2 4K tokens), max context, tok/s, peak memory
41+
- 출력: bench/head_to_head/ 에 스크립트 + CSV + README
42+
43+
**1.2 llama.cpp delta compression PR**
44+
45+
delta KV compression을 llama.cpp에 upstream PR 제출.
46+
- ggml type 등록 (GGML_TYPE_TQ_DELTA_3B)
47+
- kv_cache.cpp에 delta encode/decode 경로 추가
48+
- 벤치마크 포함 PR description 작성
49+
50+
### Phase 2: 킬러 데모 (P0)
51+
52+
**2.1 Book-in-a-Chat 데모**
53+
54+
소설 한 권을 컨텍스트에 넣고 대화하는 시연.
55+
- 데이터: Alice's Adventures in Wonderland (27K tokens, public domain)
56+
- 비교: llama.cpp FP16 KV (OOM at ~50K) vs quant.cpp (전체 로드 + Q&A)
57+
- 출력 형태:
58+
- CLI 세션 로그 (README에 포함)
59+
- 30초 asciinema 녹화 (GIF 변환)
60+
- bench/demo/book_chat.sh 재현 스크립트
61+
- 핵심 질문: "7장에서 체셔 고양이가 뭐라고 했어?" → 정확한 인용 응답
62+
63+
**2.2 WASM 라이브 데모 개선**
64+
65+
GitHub Pages 데모를 실사용 가능 수준으로 개선.
66+
- 모델 자동 다운로드 (SmolLM2 135M, 270MB)
67+
- KV 압축 ON/OFF 토글 + 메모리 사용량 실시간 표시
68+
- URL: quantumaikr.github.io/quant.cpp/
69+
70+
### Phase 3: 접근성 (P1)
71+
72+
**3.1 pip install quantcpp**
73+
74+
Python 패키지로 빌드 없이 사용 가능.
75+
- cffi 또는 ctypes 기반 (외부 빌드 도구 최소화)
76+
- `from quantcpp import Model; m = Model("model.gguf"); print(m.ask("hello"))`
77+
- PyPI 배포, pip install quantcpp 한 줄
78+
- macOS (ARM64), Linux (x86_64) wheel 사전 빌드
79+
80+
**3.2 Windows 프리빌트 바이너리**
81+
82+
GitHub Releases에 Windows x64 바이너리 포함.
83+
- MSVC Release build (quant.exe + quant-server.exe)
84+
- GitHub Actions CI에서 자동 빌드
85+
- Languages_Learner 피드백 직접 대응
86+
87+
**3.3 모델 호환성 CI 매트릭스**
88+
89+
GitHub Actions에서 주요 모델 자동 테스트.
90+
- SmolLM2 135M (빠른 CI용), Llama 3.2 1B, Qwen3.5 0.8B
91+
- 테스트: 로드 + 10토큰 생성 + PPL 5개 (smoke test)
92+
- README에 "Verified Models" 배지 자동 업데이트
93+
94+
## Non-Goals
95+
96+
- GPU 속도 경쟁 (v1.3에서 별도 진행)
97+
- 70B+ 모델 지원 (메모리 제약)
98+
- 학습/파인튜닝 기능
99+
- vLLM 완전 통합 (별도 마일스톤)
100+
101+
## Success Criteria
102+
103+
1. bench/head_to_head/ 벤치마크가 llama.cpp 최신과 공정하게 비교
104+
2. Book-in-a-Chat 데모가 README 최상단에서 30초 안에 임팩트 전달
105+
3. pip install quantcpp가 macOS/Linux에서 동작
106+
4. GitHub Stars 500 도달

‎docs/plan/wbs/wbs_v1.4.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# WBS v1.4 — Community Trust & Killer Demo
2+
3+
기반 문서: [PRD v1.4](../prd/prd_v1.4.md)
4+
5+
---
6+
7+
## Phase 1: 신뢰 확보 (P0)
8+
9+
### 1.1 Head-to-head 벤치마크
10+
11+
- [ ] **1.1.1** llama.cpp 최신 빌드 스크립트
12+
- `bench/head_to_head/setup_llamacpp.sh`
13+
- git clone + cmake build + Metal 활성화
14+
- 특정 커밋 hash 고정 (재현성)
15+
16+
- [ ] **1.1.2** 벤치마크 자동화 스크립트
17+
- `bench/head_to_head/run_benchmark.sh`
18+
- 입력: 모델 경로, 반복 횟수
19+
- 테스트 매트릭스:
20+
- llama.cpp: FP16 KV / Q8_0K+Q5_0V / Q4_0 K+V
21+
- quant.cpp: FP16 / uniform_4b+Q4V / delta_3b+Q4V
22+
- 측정: PPL (4K tokens), max context before OOM, tok/s, peak RSS
23+
- 출력: CSV + JSON + 요약 테이블
24+
25+
- [ ] **1.1.3** 결과 분석 및 README 반영
26+
- `bench/head_to_head/README.md` — 재현 방법 + 결과
27+
- README.md 비교 섹션을 실측 데이터로 교체
28+
- "이 스크립트를 돌려서 직접 확인하세요" 문구 추가
29+
30+
### 1.2 llama.cpp upstream PR 준비
31+
32+
- [ ] **1.2.1** llama.cpp 코드 스타일 분석
33+
- ggml type 등록 패턴 파악 (GGML_TYPE_*)
34+
- kv_cache 양자화 경로 분석 (llama-kv-cache.cpp)
35+
- coding convention: snake_case, indent style, comment style
36+
37+
- [ ] **1.2.2** delta KV compression 패치 작성
38+
- ggml_type 추가: GGML_TYPE_DELTA_Q3
39+
- delta encode: key[t] - reconstruct(key[t-1])
40+
- delta decode: reconstruct + dequantize
41+
- I-frame 매 64 토큰 (FP32 anchor)
42+
- integrations/llamacpp/delta_kv.patch
43+
44+
- [ ] **1.2.3** PR description + 벤치마크 결과 포함
45+
- docs/pr/llamacpp-upstream-pr.md
46+
- 제목, 요약, 벤치마크 테이블, 테스트 방법
47+
48+
---
49+
50+
## Phase 2: 킬러 데모 (P0)
51+
52+
### 2.1 Book-in-a-Chat 데모
53+
54+
- [ ] **2.1.1** 데모 데이터 준비
55+
- `bench/demo/alice.txt` — Alice in Wonderland (Project Gutenberg)
56+
- `bench/demo/prepare_book.py` — 텍스트 정리 + 토큰 수 측정
57+
- 목표: ~27K 토큰 (Llama tokenizer 기준)
58+
59+
- [ ] **2.1.2** 데모 스크립트
60+
- `bench/demo/book_chat.sh`
61+
- Step 1: llama.cpp로 전체 책 로드 시도 → OOM 표시
62+
- Step 2: quant.cpp로 전체 책 로드 (KV 압축) → 성공
63+
- Step 3: 질문 3개 자동 실행:
64+
1. "Chapter 7에서 Mad Hatter가 Alice에게 한 수수께끼는?"
65+
2. "Queen of Hearts의 첫 등장 장면을 인용해줘"
66+
3. "Cheshire Cat이 사라지는 장면을 요약해줘"
67+
- 출력: 정리된 세션 로그
68+
69+
- [ ] **2.1.3** 녹화 및 README 반영
70+
- asciinema 또는 script + GIF 변환
71+
- README.md 최상단 "See it in action" 섹션 추가
72+
- "같은 Mac에서 한쪽은 OOM, 한쪽은 책 전체를 기억한다"
73+
74+
### 2.2 WASM 데모 개선
75+
76+
- [ ] **2.2.1** 모델 자동 다운로드 UI
77+
- index.html에 모델 선택 드롭다운 (SmolLM2 135M 기본)
78+
- fetch()로 HuggingFace에서 직접 다운로드
79+
- 프로그레스 바 표시
80+
81+
- [ ] **2.2.2** KV 압축 토글 + 메모리 표시
82+
- 실시간 메모리 사용량 (WASM heap) 표시
83+
- KV 압축 ON/OFF 토글 → 메모리 차이 시각화
84+
- "Compressed: 12MB / Uncompressed: 48MB" 실시간 표시
85+
86+
- [ ] **2.2.3** GitHub Pages 배포
87+
- .github/workflows/pages.yml
88+
- quantumaikr.github.io/quant.cpp/ 라이브 URL 확인
89+
90+
---
91+
92+
## Phase 3: 접근성 (P1)
93+
94+
### 3.1 pip install quantcpp
95+
96+
- [ ] **3.1.1** Python 패키지 구조
97+
- `bindings/python/quantcpp/__init__.py` — Model, Context 클래스
98+
- `bindings/python/setup.py` — cffi 빌드 설정
99+
- `bindings/python/pyproject.toml` — PEP 517 빌드
100+
101+
- [ ] **3.1.2** C 라이브러리 빌드 통합
102+
- setup.py에서 cmake 자동 호출 → libturboquant.a 빌드
103+
- cffi 또는 ctypes로 .so/.dylib 로드
104+
- fallback: quant.h 단일 헤더 직접 컴파일
105+
106+
- [ ] **3.1.3** API 구현
107+
- `Model(path)` — quant_load() 래핑
108+
- `Model.ask(prompt)` — quant_ask() 래핑
109+
- `Model.generate(prompt, callback)` — 스트리밍
110+
- `Model.config(temperature, top_p, kv_compress)` — 설정
111+
112+
- [ ] **3.1.4** 테스트 및 PyPI 배포
113+
- `tests/test_python.py` — 로드 + 생성 + 해제 테스트
114+
- macOS ARM64, Linux x86_64 wheel 빌드
115+
- `pip install quantcpp` 동작 확인
116+
117+
### 3.2 Windows 프리빌트 바이너리
118+
119+
- [ ] **3.2.1** GitHub Actions Windows CI
120+
- `.github/workflows/release-windows.yml`
121+
- MSVC 2022 Release build
122+
- 출력: quant.exe, quant-server.exe
123+
124+
- [ ] **3.2.2** GitHub Release 자동 첨부
125+
- Release 태그 생성 시 자동 빌드 + 업로드
126+
- README에 "Download Windows binary" 링크 추가
127+
128+
### 3.3 모델 호환성 CI
129+
130+
- [ ] **3.3.1** CI 워크플로 작성
131+
- `.github/workflows/model-compat.yml`
132+
- 모델: SmolLM2 135M Q8_0 (HuggingFace에서 다운로드)
133+
- 테스트: 로드 + 10토큰 생성 + greedy 출력 일치 검증
134+
135+
- [ ] **3.3.2** README 배지 자동 업데이트
136+
- CI 결과를 배지로 표시 (pass/fail)
137+
- "Verified on: SmolLM2 135M, ..." 자동 생성
138+
139+
---
140+
141+
## 완료 기준
142+
143+
| 항목 | 기준 | 검증 방법 |
144+
|------|------|-----------|
145+
| H2H 벤치마크 | 스크립트 1개로 전체 재현 | `bash bench/head_to_head/run_benchmark.sh model.gguf` |
146+
| Book-in-a-Chat | 30초 GIF로 임팩트 전달 | README 최상단 확인 |
147+
| pip install | macOS/Linux에서 설치 → ask() 동작 | `pip install quantcpp && python -c "..."` |
148+
| Windows 바이너리 | Release 페이지에서 다운로드 → 실행 | GitHub Releases 확인 |
149+
| 모델 CI | PR마다 자동 검증 | GitHub Actions 배지 |
150+
151+
---
152+
153+
## 의존성 그래프
154+
155+
```
156+
Phase 1 (신뢰)
157+
1.1 H2H 벤치마크 ──────┐
158+
1.2 llama.cpp PR ──────┤
159+
▼
160+
Phase 2 (데모) README 업데이트
161+
2.1 Book-in-a-Chat ────┤
162+
2.2 WASM 개선 ─────────┘
163+
164+
Phase 3 (접근성) (독립)
165+
3.1 pip install ────── PyPI
166+
3.2 Windows binary ─── GitHub Release
167+
3.3 모델 CI ─────────── GitHub Actions
168+
```
169+
170+
Phase 1과 2는 순차 (벤치마크 결과가 데모와 README에 반영), Phase 3은 독립 병렬 가능.

0 commit comments

Comments
 (0)