Skip to content

Commit aaaebfc

Browse files
unamedkrclaude
unamedkr
and
claude
committed
docs: add project introduction articles (ko/en) for PR
- docs/pr/introducing-quantumrag-ko.md — Korean introduction - docs/pr/introducing-quantumrag-en.md — English introduction - Covers: problem, approach, Triple Index, hallucination prevention, Korean support, measured performance, zero-cost start, 30s demo Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent b041ee3 commit aaaebfc

2 files changed

Lines changed: 248 additions & 0 deletions

File tree

‎docs/pr/introducing-quantumrag-en.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# QuantumRAG — Open-Source RAG Engine That Actually Works
2+
3+
> March 31, 2026 | v0.4.4 | Apache 2.0
4+
5+
## TL;DR
6+
7+
Put documents in. Ask questions. Get cited answers. **No configuration needed.**
8+
9+
```python
10+
from quantumrag import Engine
11+
12+
engine = Engine()
13+
engine.ingest("./docs")
14+
result = engine.query("What are the key findings?")
15+
print(result.answer) # ... [1][2] + Confidence: STRONGLY_SUPPORTED
16+
```
17+
18+
## The Problem
19+
20+
Most RAG systems embed documents into vectors and hope the right chunks come back. When questions are phrased differently, when answers span multiple documents, or when you need exact entity matches — they fail silently.
21+
22+
QuantumRAG takes a different approach: **understand documents deeply at indexing time, so queries are fast and accurate by default.**
23+
24+
## How It Works
25+
26+
### Triple Index Fusion
27+
28+
Three retrieval methods combined via Score-Weighted Reciprocal Rank Fusion — each catches what the others miss:
29+
30+
| Index | What It Finds | Why It Matters |
31+
|-------|--------------|----------------|
32+
| **Original Embedding** | Semantically similar content | Handles paraphrasing |
33+
| **HyPE Embedding** | Content that answers similar questions | Bridges question↔document gap |
34+
| **Contextual BM25** | Exact keyword and entity matches | Precise for names, numbers, IDs |
35+
36+
### Hallucination Prevention
37+
38+
Two-layer defense:
39+
1. **Fact Verifier** (Hard Gate): Cross-checks answers against facts extracted at ingest time. Zero LLM cost.
40+
2. **System Prompt** (Soft Gate): 11 generation rules enforce source-only answers with citations.
41+
42+
### Adaptive Post-Correction
43+
44+
After generation, an automatic correction pipeline runs within a 20-second time budget:
45+
- Retrieval Retry → Self-Correction → Fact Verification → Completeness Check
46+
- Simple queries skip correction entirely (zero overhead on happy path)
47+
48+
## Korean as a First Language
49+
50+
Not a translation — designed from the ground up:
51+
52+
| Feature | Description |
53+
|---------|-------------|
54+
| HWP/HWPX Parsing | Native Korean government document support |
55+
| Kiwi Morphology | Accurate Korean tokenization for BM25 |
56+
| EUC-KR Detection | Automatic legacy encoding conversion |
57+
| Mixed Script | Optimal tokenizer for Korean-English mixed text |
58+
| Auto Language | Detects query language, responds in the same language |
59+
60+
## Measured Performance
61+
62+
105 QA questions across 73 source documents (including 50 noise documents):
63+
64+
- **Combined QA: 75% pass rate** (improved from 29% through 6 measurement-driven iterations)
65+
- **Zero timeouts**
66+
- 176 scenario tests, 831 unit tests, mypy 0 errors
67+
68+
## Zero Cost to Start
69+
70+
- **Embedding**: Microsoft Harrier 270M (local, free, MTEB 66.5, 94 languages)
71+
- **LLM**: Gemini free tier (gemini-3.1-flash-lite-preview)
72+
- **Reranker**: FlashRank (CPU, free)
73+
- **No GPU required**
74+
75+
## Try It in 30 Seconds
76+
77+
```bash
78+
pip install quantumrag
79+
quantumrag demo
80+
# Open http://localhost:8000
81+
```
82+
83+
Or with Docker:
84+
85+
```bash
86+
docker run -e GOOGLE_API_KEY=AIza... -p 8000:8000 quantumrag
87+
```
88+
89+
## Three Ways to Use It
90+
91+
| | What You Do | What Happens |
92+
|---|-------------|-------------|
93+
| **Just use it** | `engine.ingest("./docs")` → `engine.query("...")` | Parser, chunker, index, routing — all auto-selected |
94+
| **Tune it** | Adjust fusion weights, pick models, set domain | Better results for your specific use case |
95+
| **Own it** | Custom parsers, chunkers, retrievers, generators | Every layer is replaceable via plugins |
96+
97+
## Supported Formats
98+
99+
PDF, DOCX, PPTX, XLSX, HWP/HWPX, HTML, Markdown, CSV, TXT
100+
101+
## Web Playground
102+
103+
Built-in interactive UI at `http://localhost:8000`:
104+
- Upload documents (drag & drop) or paste text
105+
- Ask questions with streaming or detailed mode
106+
- Inspect pipeline trace with latency breakdown
107+
- View source citations with relevance scores
108+
109+
## Comparison
110+
111+
| Feature | QuantumRAG | LangChain | LlamaIndex | OpenAI file_search |
112+
|---------|:----------:|:---------:|:----------:|:------------------:|
113+
| Triple Index Fusion | Yes | No | No | No |
114+
| Hallucination Prevention | Yes | No | No | No |
115+
| Korean Native (HWP, Kiwi) | Yes | Plugin | Plugin | No |
116+
| Zero Config to First Answer | Yes | No | No | Partial |
117+
| Zero GPU Required | Yes | Depends | Depends | N/A |
118+
| Open Source | Apache 2.0 | MIT | MIT | No |
119+
120+
## Links
121+
122+
- **GitHub**: https://github.com/quantumaikr/quantumrag
123+
- **PyPI**: `pip install quantumrag`
124+
- **Docs**: [English](../../docs/en/index.md) | [한국어](../../docs/ko/index.md)
125+
- **License**: Apache 2.0
126+
127+
---
128+
129+
*QuantumAI Inc. — hi@quantumai.kr*

‎docs/pr/introducing-quantumrag-ko.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# QuantumRAG — 문서를 넣으면 정확한 답이 나오는 오픈소스 RAG 엔진
2+
3+
> 2026년 3월 31일 | v0.4.4 | Apache 2.0
4+
5+
## 한 줄 요약
6+
7+
문서를 넣으세요. 질문하세요. 출처가 달린 정확한 답변을 받으세요. **설정 없이 바로 동작합니다.**
8+
9+
```python
10+
from quantumrag import Engine
11+
12+
engine = Engine()
13+
engine.ingest("./docs")
14+
result = engine.query("주요 발견사항은?")
15+
print(result.answer) # ... [1][2] + Confidence: STRONGLY_SUPPORTED
16+
```
17+
18+
## 왜 만들었나
19+
20+
RAG를 직접 구축해 보면, 생각보다 많은 것이 안 됩니다.
21+
22+
- 질문 표현을 살짝 바꾸면 답을 못 찾음
23+
- 여러 문서에 걸친 답변을 종합하지 못함
24+
- 정확한 수치나 엔티티를 요구하면 조용히 실패
25+
- 한국어 문서(HWP 등)는 제대로 파싱조차 안 됨
26+
27+
대부분의 RAG는 문서를 벡터로 변환한 뒤, 적절한 청크가 돌아오기를 기도합니다. QuantumRAG는 다른 접근을 합니다.
28+
29+
**인덱싱 시점에 문서를 깊이 이해해서, 쿼리가 기본적으로 정확하게 작동합니다.**
30+
31+
## 핵심 기술
32+
33+
### Triple Index Fusion
34+
35+
하나의 검색 방식으로는 한계가 있습니다. 세 가지를 동시에 돌리고 Score-Weighted RRF로 융합합니다:
36+
37+
| 인덱스 | 역할 | 왜 필요한가 |
38+
|--------|------|------------|
39+
| **Original Embedding** | 의미적 유사성 | 패러프레이즈 처리 |
40+
| **HyPE Embedding** | "이 문서로 답할 수 있는 질문" 매칭 | 질문↔문서 격차 해소 |
41+
| **Contextual BM25** | 정확한 키워드/엔티티 매칭 | 수치, 이름 등 정밀 검색 |
42+
43+
### 환각 방지 이중 방벽
44+
45+
1. **Fact Verifier** (Hard Gate): 인제스트 시 추출한 facts와 답변을 교차 검증. LLM 비용 제로.
46+
2. **시스템 프롬프트** (Soft Gate): 11개 한국어 생성 규칙으로 출처 없는 주장을 원천 차단.
47+
48+
### 적응형 후처리 파이프라인
49+
50+
답변 생성 후 자동 교정:
51+
- Retrieval Retry → Self-Correction → Fact Verification → Completeness Check
52+
- 시간 예산(20초) 내에서 동작, 단순 쿼리는 자동 스킵
53+
54+
## 한국어를 모국어로
55+
56+
| 기능 | 설명 |
57+
|------|------|
58+
| HWP/HWPX 파싱 | 정부/관공서 문서 직접 파싱 |
59+
| Kiwi 형태소 분석 | BM25 인덱싱 정확도 향상 |
60+
| EUC-KR 자동 감지 | 레거시 인코딩 자동 변환 |
61+
| 혼합 스크립트 | 한영 혼합 텍스트 최적 토크나이징 |
62+
| 언어 자동 감지 | 영어 질문 → 영어 답변, 한국어 질문 → 한국어 답변 |
63+
64+
## 측정된 성능
65+
66+
105개 QA 질문, 73개 소스 문서(50개 노이즈 포함)에서:
67+
68+
- **Combined QA: 75% pass rate** (29%에서 6회 반복 개선)
69+
- **Timeout: 0%**
70+
- 176개 시나리오 테스트, 831개 유닛 테스트, mypy 0 에러
71+
72+
## 비용: 제로에서 시작
73+
74+
- **임베딩**: Microsoft Harrier 270M (로컬, 무료, MTEB 66.5)
75+
- **LLM**: Gemini 무료 티어 (gemini-3.1-flash-lite-preview)
76+
- **Reranker**: FlashRank (CPU, 무료)
77+
- **GPU 불필요**: CPU만으로 동작
78+
79+
## 30초 체험
80+
81+
```bash
82+
pip install quantumrag
83+
quantumrag demo
84+
# 브라우저에서 http://localhost:8000 접속
85+
```
86+
87+
또는 Docker:
88+
89+
```bash
90+
docker run -e GOOGLE_API_KEY=AIza... -p 8000:8000 quantumrag
91+
```
92+
93+
## 지원 포맷
94+
95+
PDF, DOCX, PPTX, XLSX, HWP/HWPX, HTML, Markdown, CSV, TXT
96+
97+
## 프로젝트 구조
98+
99+
```
100+
quantumrag/
101+
├── core/engine.py # 단일 진입점
102+
├── core/retrieve/fusion.py # Triple Index 퓨전 검색
103+
├── core/generate/ # 생성 + 환각 방지 + 완전성 검사
104+
├── core/pipeline/ # 적응형 후처리 교정
105+
├── api/ # FastAPI + 웹 플레이그라운드
106+
├── cli/ # init, ingest, query, serve, demo
107+
└── korean/ # Kiwi 형태소, EUC-KR 인코딩
108+
```
109+
110+
## 링크
111+
112+
- **GitHub**: https://github.com/quantumaikr/quantumrag
113+
- **PyPI**: `pip install quantumrag`
114+
- **문서**: [한국어](../../docs/ko/index.md) | [English](../../docs/en/index.md)
115+
- **라이선스**: Apache 2.0
116+
117+
---
118+
119+
*QuantumAI Inc. — hi@quantumai.kr*

0 commit comments

Comments
 (0)