hallu-lab 0.1.0

로컬 LLM(Ollama)로 할루시네이션과 컨텍스트 정보 소실을 실습하는 교육용 패키지

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

로컬 LLM(Ollama)을 사용해 다음 두 가지 현상을 직접 관찰하는 교육용 파이썬 패키지입니다.

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

---

1. 사전 준비

# (1) Ollama 설치  →  https://ollama.com/download
# (2) 가벼운 모델 내려받기 (3B 권장: 노트북에서도 무난)
ollama pull llama3.2

# (3) 이 패키지 설치 (code 디렉토리에서)
pip install -e .
#   주피터까지 함께:  pip install -e ".[notebook]"

설치 후 Ollama 서버가 떠 있는지 확인:

from hallu_lab import OllamaClient
client = OllamaClient(model="llama3.2")
print(client.is_available())   # True 면 준비 완료

---

2. 빠른 사용 (주피터)

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

client = OllamaClient(model="llama3.2", 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=400))

자세한 단계별 실습은 examples/demo.py 를 참고하세요.

---

3. 패키지 구조

파일	역할
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로 온도가 높을수록 답이 흔들리는 것을 관찰.
• 길이 효과: length_sweep에서 num_ctx를 작게(예: 512) 주면 컨텍스트 창을 넘쳐 정보가 잘리는 현상을 더 극적으로 재현.
• 위치 효과: position_sweep에서 보통 중앙(50%)에서 성공률이 가장 낮음.