LogitScope로 LLM 불확실성 분석

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

LogitScope는 토큰별 확률분포에서 정보이론 지표를 계산해 LLM의 불확실성, 예측 품질, 대안 선택을 정량적으로 분석하는 Python framework입니다. 모델의 logits를 Softmax 확률로 바꾼 뒤 surprisal, entropy, varentropy, skewentropy, perplexity, probability를 계산하고 결과를 필요할 때 평가해 캐시합니다. HuggingFace causal language model과 호환되며 Python API와 웹 UI에서 토큰별 지표, 상위 후보 토큰, 분포 변화를 확인할 수 있습니다. 이를 활용하면 hallucination이 의심되는 구간 탐지, prompt 비교, Fine-tuning 전후 평가, 배포 중 모델 성능 모니터링을 수행할 수 있습니다.

섹션별 상세

LogitScope는 LLM이 각 위치에서 vocabulary 전체에 배분한 확률 질량을 분석해 출력 뒤의 선택 구조를 수치화합니다. 입력 텍스트를 tokenizer로 토큰화하고 모델 추론으로 다음 토큰의 logits를 얻은 뒤 Softmax 확률분포를 계산합니다. 그 결과를 바탕으로 의미 해석에 의존하지 않고 모델의 확신, 불확실성, 예측 품질을 비교할 수 있어 hallucination 점검과 모델 행동 분석에 활용됩니다.

python

from transformers import AutoModelForCausalLM, AutoTokenizer
from logitscope import LogitScope

# Load model and tokenizer
model = AutoModelForCausalLM.from_pretrained('HuggingFaceTB/SmolLM2-135M-Instruct')
tokenizer = AutoTokenizer.from_pretrained('HuggingFaceTB/SmolLM2-135M-Instruct')

# Initialize LogitScope
scope = LogitScope(tokenizer, model, device='cpu')

# Analyze text
results = scope.measure('The quick brown fox jumps over the lazy dog')

# Access metrics as arrays
print(f"Surprisal: {results.surprisal}")
print(f"Entropy: {results.entropy}")
print(f"Varentropy: {results.varentropy}")

# Iterate over tokens with metrics
# Use repr() to show escape sequences (\
, \\t, etc.) in CLI output
for token in results.iter_tokens(['surprisal', 'entropy', 'perplexity']):
    print(
        f"{repr(token['token']):15s} | "
        f"surprisal={token['surprisal']:.3f} | "
        f"entropy={token['entropy']:.3f} | "
        f"perplexity={token['perplexity']:.3f}"
    )

# Inspect top-k alternatives at specific positions
# repr() makes special characters visible
top_tokens = results.top_k(index=5, k=10)
for token, prob in top_tokens:
    print(f"{repr(token):15s} {prob:.4f}")

HuggingFace causal language model을 불러온 뒤 입력 문장에서 토큰별 정보 지표와 상위 후보 토큰을 계산합니다.

이 framework는 하나의 지표로 불확실성을 판단하지 않고 서로 다른 분포 특성을 나눠 계산합니다. Surprisal은 실제 선택 토큰의 예상 밖 정도를, Entropy는 전체 확률분포의 확산 정도를, Varentropy는 surprisal 분산을, Skewentropy는 분포 비대칭을 나타내며, Perplexity는 시퀀스 전체의 누적 예측 품질을 나타냅니다. 따라서 높은 Entropy와 Varentropy가 함께 나타나는 구간이나 낮은 토큰 확률이 이어지는 구간을 중심으로 생성 과정의 불안정성을 확인할 수 있습니다.

bash

uv pip install -e .

웹 UI 없이 Python API만 사용하는 LogitScope를 editable 방식으로 설치합니다.

bash

uv pip install -e ".[ui]"

대화형 웹 UI에 필요한 선택 의존성까지 포함해 LogitScope를 설치합니다.

LogitScope는 HuggingFace causal language model을 감싸는 LogitScope 객체와 분석 결과를 담는 Results 객체로 구성됩니다. `measure(text)`가 입력 텍스트의 토큰 ID, logits, 확률, log probability를 준비하고, 각 metric 속성은 처음 접근할 때 계산된 뒤 캐시되며 `iter_tokens()`와 `top_k()`가 토큰별 수치와 특정 위치의 상위 후보를 반환합니다. Python 3.11 이상, PyTorch 2.7 이상, Transformers 4.51 이상을 요구하고 CPU, CUDA, Apple Silicon의 MPS를 지원합니다.

bash

python -m logitscope.ui --model HuggingFaceTB/SmolLM2-135M-Instruct --device cpu

지정한 모델과 CPU를 사용해 LogitScope 웹 인터페이스를 실행합니다.

bash

python -m logitscope.ui --model MODEL_NAME --device cuda

CUDA 가속을 사용해 지정한 모델의 실시간 분석 UI를 실행합니다.

웹 UI는 metric별 색상 토큰 시각화, 실행 중 평균 통계, 상위 후보 탐색, 분포 그래프, metric 전환, WebSocket 기반 실시간 스트리밍을 제공합니다. 사용자는 `python -m logitscope.ui` 명령으로 모델과 장치를 지정해 브라우저에서 분석 결과를 확인할 수 있으며, `--port` 옵션으로 포트를 바꿀 수 있습니다. API만 설치할 때와 UI·개발 의존성까지 설치할 때를 구분해 운영 환경과 개발 환경에 맞게 구성할 수 있습니다.

LogitScope의 사용 사례는 모델 개발 전후 비교부터 운영 중 품질 감시까지 이어집니다. Validation set에서 Fine-tuning 전후의 Perplexity와 기대 토큰 확률을 비교하고, 동일한 prompt에 대한 여러 응답의 분포를 비교하며, 배포 후 평균 Entropy와 Perplexity 변화를 추적하는 방식입니다. 또한 prompt 문구, 모델 구조, 학습 절차, 언어와 도메인에 따른 확률분포 차이를 측정해 정확도만으로 놓치는 calibration과 의사결정 패턴을 분석할 수 있습니다.

용어 해설

엔트로피(Entropy): — 확률분포가 여러 토큰에 얼마나 넓게 퍼져 있는지를 나타내는 불확실성 지표입니다. 특정 위치에서 각 토큰의 확률이 비슷하게 분산되면 값이 커지고, 하나의 토큰에 확률이 집중되면 값이 작아집니다. 모델의 확신이 낮은 위치를 찾는 데 사용됩니다.
분산 엔트로피(Varentropy): — 각 후보 토큰의 surprisal 값이 얼마나 넓게 퍼져 있는지를 측정하는 지표입니다. 단순한 평균 불확실성보다 여러 선택지가 서로 다른 수준으로 경쟁하는 분포를 포착합니다. 모델이 뚜렷한 대안들 사이에서 갈등하는 위치를 찾는 데 유용합니다.
놀람도(Surprisal): — 실제로 선택된 토큰의 확률을 음의 로그로 변환한 값으로, 해당 토큰이 문맥에서 얼마나 예상 밖이었는지를 나타냅니다. 토큰 확률이 낮을수록 surprisal은 커집니다. 생성 결과에서 통계적으로 드문 토큰이나 잠재적 오류를 찾는 데 활용됩니다.
혼란도(Perplexity): — 시퀀스 전체에서 토큰 예측이 얼마나 잘 맞았는지를 누적해서 나타내는 지표입니다. 평균 surprisal을 지수화해 계산하며 값이 낮을수록 모델이 입력 시퀀스를 더 자연스럽게 예측했다는 뜻입니다. 모델 비교와 배포 환경의 성능 변화 추적에 사용됩니다.
로짓(Logits): — 언어 모델이 다음 토큰 후보마다 출력하는 Softmax 이전의 점수입니다. LogitScope는 이 원시 점수에 Softmax를 적용해 전체 vocabulary에 대한 확률분포를 만들고, 그 위에서 불확실성과 예측 품질 지표를 계산합니다. 확률 변환 전 모델의 선택 구조를 분석하는 출발점입니다.

기술

Python
PyTorch
Transformers
NumPy
FastAPI
Uvicorn
HuggingFaceTB/SmolLM2-135M-Instruct
CUDA
MPS
uv

활용 사례

Hallucination 의심 구간 탐지
Production monitoring
Fine-tuning 전후 평가
Prompt engineering 비교
Ablation study
Calibration 연구
모델 응답 비교

언급된 리소스

GitHubibm-granite/granite.debug-tools

논문LogitScope: A Framework for Analyzing LLM Uncertainty Through Information Metrics

LogitScope로 LLM 불확실성 분석

TL;DR

섹션별 상세

용어 해설

기술

활용 사례

언급된 리소스

관련 토론

댓글

관련 피드

관련 토론

댓글

관련 피드