hallu-lab 0.2.0

할루시네이션과 컨텍스트 정보 소실을 실습하는 교육용 패키지 (다운로드 없는 시뮬레이터 + Ollama 지원)

hallu_lab — LLM 할루시네이션 & 컨텍스트 소실 실습

LLM에서 나타나는 두 가지 현상을 직접 관찰하는 교육용 파이썬 패키지입니다.

1. 할루시네이션(환각) — 모델이 모르는 것을 그럴듯하게 지어내는 현상
2. 컨텍스트 정보 소실 — 문맥이 길어지거나 핵심 정보가 가운데 묻히면 놓치는 현상

두 가지 백엔드를 지원합니다.

백엔드	다운로드	설명
sim (기본)	없음	현상을 규칙으로 재현하는 시뮬레이터. 오프라인·즉시 실행. 개념 학습용.
ollama	모델 용량	실제 로컬 LLM. 더 현실적인 잡음 관찰 가능.

---

1. 설치

pip install -e .          # code 디렉토리에서 (시뮬레이터는 외부 의존성 없음)
# 주피터까지:  pip install -e ".[notebook]"

시스템 파이썬이 외부 관리(PEP 668) 상태라 설치가 막히면 가상환경을 쓰세요:

python3 -m virtualenv .venv && .venv/bin/pip install -e . ipykernel
.venv/bin/python -m ipykernel install --user --name hallu-lab --display-name "Python (hallu-lab)"

주피터에서 커널을 Python (hallu-lab) 로 선택하면 됩니다.

---

2. 빠른 사용

from hallu_lab import make_client, run_hallucination_demo, length_sweep, position_sweep, summarize

# 다운로드 없는 시뮬레이터 (기본)
client = make_client("sim", seed=0)

# 실습 A: 할루시네이션 — 가드레일 유무 비교
for r in run_hallucination_demo(client):
    r.show()

# 실습 B-1: 문서가 길어질수록 핵심 정보를 놓치는가 (길이 효과)
summarize(length_sweep(client, filler_sizes=[10, 100, 300, 600]))

# 실습 B-2: 핵심 정보 위치에 따른 차이 (lost-in-the-middle)
summarize(position_sweep(client, n_filler=120))

실제 로컬 LLM으로 바꾸려면 클라이언트 한 줄만 교체:

client = make_client("ollama", model="qwen2.5:0.5b", seed=0)  # 약 400MB
# 사전: pip install "hallu-lab[ollama]"  +  `ollama serve`  +  `ollama pull qwen2.5:0.5b`

단계별 실습은 examples/demo.ipynb 또는 examples/demo.py 참고.

---

3. 패키지 구조

파일	역할
hallu_lab/init.py	make_client() 팩토리 + 공개 API
hallu_lab/simulated.py	다운로드 없는 시뮬레이터 (SimulatedClient)
hallu_lab/client.py	실제 Ollama 호출 래퍼 (OllamaClient)
hallu_lab/datasets.py	허구 질문 / 바늘·채움 텍스트 생성
hallu_lab/hallucination.py	할루시네이션 실습 (run_hallucination_demo, temperature_sweep)
hallu_lab/context_loss.py	컨텍스트 소실 실습 (length_sweep, position_sweep)

---

4. 실습 포인트 (강의용)

• 가드레일 효과: "모르면 모른다고 하라"는 시스템 프롬프트를 줬을 때 할루시네이션이 줄어드는지 비교.
• 온도(temperature): temperature_sweep로 온도 0은 동일, 높을수록 답이 흔들리는 것을 관찰.
• 길이 효과: length_sweep에서 문서가 길어질수록 핵심 정보를 놓침. num_ctx를 작게(예: 512) 주면 창을 넘쳐 잘리는 현상을 더 극적으로 재현.
• 위치 효과: position_sweep에서 보통 중앙(50%)에서 성공률이 가장 낮음 (lost-in-the-middle).

⚠️ 시뮬레이터(sim)는 진짜 신경망이 아니라 현상을 재현하는 규칙 기반 모형입니다. "정답"을 보는 게 아니라 실패 패턴/개념을 관찰하는 용도입니다.