본문으로 건너뛰기

The Effect of Dynamic Date Injection Methods on LLM Temporal Reasoning across Deictic Expression Granularities

· 약 8분
김성연
AI Research Engineer, Brain Crew
최재훈
LEAD (AI Research Engineer), Brain Crew

TL;DR

LLM은 "어제", "다음 주"와 같은 상대적 시간 표현을 해석할 때 현재 날짜를 알 수 없어 날짜 주입이 필수입니다. 320회의 실험 결과, 한국어 형식(2025년 3월 19일) + User Prompt 조합이 Simple/Structured 모두에서 95% 정확도를 달성했으며, 날짜 미주입 시 15%에 불과했던 성능이 최대 95%까지 향상되었습니다. 특히 Week granularity(다음 주 월요일 등)는 요일 정보 포함 시 40%→80% 개선되며, gpt-4o 사용 시 모든 시간 단위에서 100% 정확도를 보였습니다.

Key Takeaways

  • 날짜 주입은 선택이 아닌 필수: 날짜 정보 없이는 Day/Week/Month granularity에서 0% 정확도를 기록하며, Year 단위 상식 문제만 60% 수준으로 부분 정답 가능
  • 한국어 질의에는 한국어 날짜 형식 사용: 현재 날짜: 2025년 3월 19일 형식이 Structured Output에서 English 대비 +15%p 우위(95% vs 80%)를 보이며 응답 방식에 관계없이 안정적
  • User Prompt가 System Prompt보다 효과적: 질의와 가까운 위치에 날짜를 배치하면 Simple Response에서 +3.3%p 성능 향상(95.0% vs 91.7%)
  • Week granularity가 가장 어렵다: "다음 주 월요일" 같은 표현은 현재 요일 인식→주 경계 판단→날짜 계산의 3단계 추론이 필요하며, 한국어 요일 정보 추가 시 40%→80% 개선
  • 과도한 정보는 오히려 역효과: 주말 설명 등 불필요한 부가 정보는 LLM의 추론을 방해하여 5~10%p 성능 하락 유발

상세 내용

배경: 왜 날짜 프롬프트가 필요한가

LLM은 학습 데이터의 시점에 고정되어 있어 "지금이 언제인지" 스스로 알 수 없습니다. 따라서 "어제", "지난주", "다음 달"과 같은 **직시 표현(Deictic Expression)**을 해석할 때 현재 날짜를 기준점으로 제공해야 정확한 날짜 변환이 가능합니다.

600회의 추론 실험(gpt-4o-mini 기준)에서 날짜 주입 유무에 따른 성능 차이는 다음과 같습니다:

조건AccuracyDayWeekMonthYear
날짜 주입 없음15%0%0%0%60%
날짜 주입 있음95%100%100%100%80%

날짜 주입 없이는 "작년 크리스마스"와 같은 Year granularity 상식 문제만 부분 정답(60%)이 가능하며, 실시간 계산이 필요한 Day/Week/Month는 전부 0%로 시간 추론 자체가 불가능합니다.

문제 상황: 4가지 설계 변수의 영향

날짜 프롬프트 설계 시 고려해야 할 4가지 변수와 각각의 성능 영향을 실험으로 검증했습니다.

1. Prompt Position: 어디에 넣을 것인가

PositionSimple ACCStructured ACC
System Prompt91.7%85.0%
User Prompt95.0%85.0%

User Prompt에 날짜 정보를 배치하면 질의와 가까운 위치에서 참조 효율이 높아져 Simple Response에서 +3.3%p 우위를 보였으며, Structured Output에서는 동일하므로 선택에 따른 손해가 없습니다.

2. Expression Format: 어떤 형식으로 넣을 것인가

테스트한 3가지 형식의 성능 비교:

Format예시SimpleStructured평균
Korean현재 날짜: 2025년 3월 19일92.5%95.0%93.8%
EnglishCurrent date: March 19th, 202595.0%80.0%87.5%
DayOfWeekCurrent date: 2025-03-19, Wed92.5%80.0%86.3%

Korean 형식이 가장 안정적입니다. Simple Response에서는 3개 format 간 차이가 미미(92.5~95.0%)하지만, Structured Output에서 Korean(95%)이 English/DayOfWeek(80%)를 크게 압도합니다. 이는 한국어 질의에 한국어 날짜 표현을 사용할 때 토큰 정렬이 자연스럽게 이루어지기 때문으로 추정됩니다.

3. 날짜 컨텍스트 상세도: 얼마나 많은 정보를 넣을 것인가

컨텍스트내용ACC
A날짜 + 시간 (현재 날짜: 2025-03-19 (수요일) / 현재 시간: 14:00)85~90%
B날짜 + 주간 달력 (이번 주/지난 주 전체 날짜 나열)85~90%
C날짜만 (현재 날짜: 2025-03-19 (Wed))80%

날짜만 제공하고 영문 요일만 포함한 경우(C) Week granularity에서 40%까지 하락했습니다. A/B처럼 한국어 요일을 포함하면 Week에서 80%를 유지할 수 있으며, 주간 달력(B)은 정보량 대비 성능 향상이 미미했습니다. 과도한 정보(주말 설명 등)를 추가하면 오히려 5~10%p 하락하므로 주의가 필요합니다.

4. Output 방식: 응답을 어떤 형식으로 받을 것인가

OutputACCWeek ACC
Simple (텍스트)95%100%
Structured (instructor)85%60%

시간 추론에서는 Simple Response가 유리합니다. 전체 정확도에서 +10%p 차이가 있으며, 핵심은 Week granularity(60% → 100%)입니다. Structured Output의 schema 강제가 추론 chain을 방해하는 것으로 분석되며, Structured가 필요한 경우 Korean format + User Prompt 조합으로 95%까지 보완 가능합니다.

해결 과정: Granularity별 난이도 분석

LLM의 시간 추론 능력은 시간 단위에 따라 극적으로 달라집니다:

순위GranularityACC 범위핵심 특성오류 패턴
1 (쉬움)Day100%단순 ±N일 산술오류 없음
2Month80~100%월말/월초 계산요일 역산에서 간헐적 오류
3Year60~100%상식 + 요일 계산먼 미래 요일 추론 실패
4 (어려움)Week40~100%요일 기반 상대 계산"다음 주 월요일" 등에서 ±1주 오류 빈번

Week Granularity가 가장 어려운 이유는 "다음 주 월요일" 같은 표현 해석 시 현재 요일 인식 → 주 경계 판단 → 날짜 계산의 3단계 추론이 필요하기 때문입니다. LLM이 "다음 주"의 경계를 잘못 판단하여 ±1주 오프셋 오류가 빈번하게 발생하며, Structured Output에서는 schema 제약이 이 추론 과정을 더욱 방해합니다.

주간 달력을 프롬프트에 포함하거나 상위 모델을 사용하면 개선 가능합니다:

모델DayWeekMonthYearOverall
gpt-4o-mini100%60%100%80%85%
gpt-4o100%100%100%100%100%

gpt-4o는 모든 granularity에서 100% 정확도를 달성하여 모델 크기가 시간 추론에 직접적 영향을 미치는 것을 확인했습니다.

결과: 권장 프롬프트 템플릿

실험 결과를 바탕으로 Best Practice: Korean + User Prompt 조합을 권장합니다:

# 기본 템플릿 (Simple: 95% / Structured: 95%)
system_prompt = """
사용자의 질문에 정확하게 답변하세요.
"""

user_prompt_template = """
현재 날짜: {year}년 {month}월 {day}일
사용자가 '오늘', '어제', '그저께', '금주', '지난주', '이번 달', '주말' 등
상대적 날짜 표현을 사용하면 위 현재 날짜를 기준으로 구체적인 날짜(YYYY-MM-DD)로 변환하세요.

{user_query}
"""

# 사용 예시
from datetime import datetime

now = datetime.now()
user_query = "지난주 금요일에 작성된 보고서를 찾아줘"

user_prompt = user_prompt_template.format(
year=now.year,
month=now.month,
day=now.day,
user_query=user_query
)

Week 정확도가 중요한 경우 주간 달력 추가:

# Week granularity 강화 템플릿 (Week: 80% → 100% for gpt-4o)
from datetime import datetime, timedelta

def get_week_calendar(reference_date):
# 이번 주 월요일 찾기
this_monday = reference_date - timedelta(days=reference_date.weekday())
# 지난 주 월요일
last_monday = this_monday - timedelta(days=7)

days_kr = ['월요일', '화요일', '수요일', '목요일', '금요일', '토요일', '일요일']

this_week = []
last_week = []

for i in range(7):
this_day = this_monday + timedelta(days=i)
last_day = last_monday + timedelta(days=i)
this_week.append(f"{days_kr[i]}({this_day.strftime('%Y-%m-%d')})")
last_week.append(f"{days_kr[i]}({last_day.strftime('%Y-%m-%d')})")

return this_week, last_week

now = datetime.now()
this_week, last_week = get_week_calendar(now)

user_prompt_with_calendar = f"""
현재 날짜: {now.year}{now.month}{now.day}일 ({['월요일','화요일','수요일','목요일','금요일','토요일','일요일'][now.weekday()]})
- 이번 주: {', '.join(this_week)}
- 지난 주: {', '.join(last_week)}

사용자가 '오늘', '어제', '그저께', '금주', '지난주', '이번 달', '주말' 등
상대적 날짜 표현을 사용하면 위 현재 날짜를 기준으로 구체적인 날짜(YYYY-MM-DD)로 변환하세요.

{user_query}
"""

피해야 할 안티패턴:

# ❌ 안티패턴 1: 날짜 정보 미주입
user_prompt_bad1 = """
사용자의 상대적 날짜 표현을 절대 날짜로 변환하세요.
{user_query}
"""
# → Day/Week/Month 0%, 전체 15%

# ❌ 안티패턴 2: 영문 날짜 + Structured Output
user_prompt_bad2 = """
Current date: March 19th, 2025
Convert relative date expressions to absolute dates.
{user_query}
"""
# + Structured Output → 80% (Week 40~60%)

# ❌ 안티패턴 3: 과도한 부가 설명
user_prompt_bad3 = """
현재 날짜: 2025년 3월 19일
주말은 토요일과 일요일을 의미합니다.
월말은 매월 마지막 날을 의미합니다.
...
{user_query}
"""
# → -5~10%p 하락

# ❌ 안티패턴 4: 날짜만 (요일 없이)
user_prompt_bad4 = """
Current date: 2025-03-19
{user_query}
"""
# → Week 40%

의사결정 가이드

프로젝트 상황에 따른 날짜 프롬프트 설계 의사결정 플로우:

1. 날짜 주입이 있는가?
└─ NO → 반드시 추가 (없으면 15%)
└─ YES → 다음 단계

2. 질의가 한국어인가?
└─ YES → Korean format 사용 ("2025년 3월 19일")
└─ NO → English format 사용 ("March 19th, 2025")

3. Structured Output이 필요한가?
└─ NO → Simple 사용 (최고 성능)
└─ YES → 반드시 Korean format + User Prompt 조합 (95% 보장)

4. Week 추론 정확도가 critical한가?
└─ NO → 기본 템플릿으로 충분
└─ YES → 주간 달력 추가 또는 gpt-4o 사용 고려

5. 전체 정확도 100%가 필요한가?
└─ NO → gpt-4o-mini + 최적 프롬프트 (95%)
└─ YES → gpt-4o 사용 (100%)

종합 권장 설정

항목권장값대안근거
Time Injection필수-미주입 시 15%
Expression FormatKoreanEnglish (Simple 한정)Structured에서 +15%p 차이
Prompt PositionUser PromptSystem Prompt (동등)Simple에서 +3.3%p
Output 방식SimpleStructured (Korean+User 시 95%)전체 +10%p, Week +40%p
날짜 컨텍스트날짜 + 한국어 요일주간 달력 (Week 중요 시)Week ACC 40→80%
부가 설명불필요-추가 시 오히려 하락
모델gpt-4o (정확도 우선)gpt-4o-mini (비용 우선)100% vs 85~95%

실험 환경 및 데이터

실험 구성:

  • Target LLM: gpt-4o-mini (baseline), gpt-4o (비교)
  • Temperature: 0.0
  • 기준 날짜: 2025-03-19 (Wednesday)
  • 테스트 쿼리: 20개 (Day 5 + Week 5 + Month 5 + Year 5)
  • 평가 메트릭: Accuracy — Include Match (정답 날짜가 응답에 포함되는지 판단)
  • 총 추론 수: 600개 (Baseline 320 + Expression Format 280)

상세 실험 데이터:

  • BASELINE_RESULTS.md: 날짜 컨텍스트 3종, seed/temp/output/model 비교 (320개 레코드)
  • EXPERIMENT_RESULTS.md: Expression Format × Injection Position 7-case (280개 레코드)

References

Docker Log Monitor vs Sentry 비교 분석

· 약 7분
김성연
AI Research Engineer, Brain Crew

TL;DR

Docker Log Monitor는 설치가 간단하고 비용이 들지 않으며 코드 수정 없이 즉시 사용 가능한 반면, Sentry는 풍부한 에러 컨텍스트와 분석 도구를 제공하지만 SDK 통합과 비용이 필요합니다. LG Electronics Agent 프로젝트의 경우, 이미 구현된 Docker Log Monitor만으로도 현재 요구사항을 충족하며, 프로젝트 규모 확장 시 Sentry 추가를 고려하는 점진적 접근이 가장 효율적입니다.

Key Takeaways

  • 비용 vs 기능의 트레이드오프: 초기 단계나 예산이 제한적인 프로젝트에서는 Docker Log Monitor가 비용 효율적이며, 상세한 디버깅과 팀 협업이 중요한 프로덕션 환경에서는 Sentry의 추가 비용이 정당화됩니다.

  • 레거시 시스템에는 비침투적 모니터링이 유리: Docker Log Monitor는 애플리케이션 코드 수정 없이 로그 스트림만으로 작동하므로, 레거시 시스템이나 코드 변경이 어려운 환경에서 즉시 적용 가능합니다.

  • 프라이버시와 데이터 주권이 중요한 경우 자체 호스팅 우선: 민감한 데이터를 다루거나 GDPR 등 규제 준수가 필요한 경우, 모든 데이터를 자체 서버에 보관하는 Docker Log Monitor가 더 안전한 선택입니다.

  • 하이브리드 접근법으로 점진적 확장: 초기에는 Docker Log Monitor로 시작해 기본 모니터링을 확보하고, 프로젝트가 성장하면서 필요에 따라 Sentry를 추가하는 전략이 위험을 최소화하며 투자 효율을 높입니다.

  • 요구사항에 맞는 도구 선택이 핵심: "더 많은 기능 = 더 좋은 솔루션"이 아니며, 프로젝트의 현재 단계, 팀 규모, 디버깅 복잡도를 고려한 적절한 도구 선택이 중요합니다.

상세 내용

배경: 모니터링 솔루션 선택의 딜레마

LG Electronics Agent 프로젝트에서 FastAPI 기반 웹 애플리케이션의 에러 모니터링 시스템을 구축하는 과정에서, 커스텀 Docker 로그 모니터링 솔루션과 업계 표준인 Sentry 사이의 선택이 필요했습니다. 이미 Docker Log Monitor를 구현하여 작동 중이었지만, Sentry의 강력한 기능들을 고려할 때 어떤 방향이 프로젝트에 최적인지 검증이 필요한 상황이었습니다.

문제 상황: 과한 도구 vs 충분한 도구

많은 개발팀이 "업계 표준"이라는 이유로 Sentry 같은 고급 도구를 도입하지만, 실제로는 다음과 같은 문제에 직면합니다:

  1. 불필요한 복잡도: SDK 통합, 설정 관리, 팀 온보딩에 상당한 시간 투자
  2. 비용 압박: 무료 플랜(월 5,000 이벤트)을 초과하면 월 $26부터 시작하는 유료 플랜 필요
  3. 데이터 프라이버시 우려: 모든 에러 데이터가 외부 서비스로 전송
  4. 과도한 기능: 초기 단계 프로젝트에는 대시보드, 에러 집계, 트렌드 분석 등이 과할 수 있음

반면 Docker Log Monitor는 이미 작동 중이었지만, "너무 간단한 것은 아닐까?"라는 의구심이 있었습니다.

해결 과정: 체계적 비교 분석

1. 정량적 비교 프레임워크 구축

12개 카테고리, 30개 이상의 평가 항목으로 구성된 비교표를 작성하여 주관적 판단을 최소화했습니다:

평가 영역Docker Log MonitorSentry
설치/설정 용이성5/52/5
비용 효율성5/53/5
에러 분석 기능2/55/5
커스터마이징5/53/5
프라이버시/보안5/53/5
총점27/3526/35

2. 사용 시나리오별 적합도 분석

프로젝트의 특성에 따라 적합한 도구가 달라진다는 것을 발견했습니다:

Docker Log Monitor가 유리한 경우:

  • 빠른 프로토타이핑 단계
  • 레거시 시스템 (코드 수정 불가)
  • 민감한 데이터 처리 (프라이버시 중요)
  • 비용 제약이 있는 경우
  • 단순한 에러 감지만 필요한 경우

Sentry가 유리한 경우:

  • 복잡한 버그의 빠른 해결 필요
  • 팀 협업 및 대시보드 공유 중요
  • 에러 트렌드 분석 필요
  • 성능 모니터링 필요
  • 이슈 트래킹 시스템(Jira 등) 연동 필요

3. 의사결정 맥락 분석

LG Electronics Agent 프로젝트의 현재 상황:

✅ 이미 Docker Log Monitor 구현 완료 및 작동 중
✅ FastAPI의 구조화된 로그로 충분한 에러 정보 수집 중
✅ Slack 알림을 통한 실시간 대응 체계 구축됨
✅ Dev/Prod 환경 구분 기능 포함
⚠️ 팀 규모와 프로젝트 복잡도가 아직 초기 단계

이러한 맥락에서 Sentry 도입은 다음과 같은 이유로 "과한" 선택이었습니다:

  1. 설정 비용 > 얻는 가치: SDK 통합에 소요되는 시간 대비 추가 이득이 제한적
  2. 기존 시스템으로 충분: FastAPI 로그에서 스택 트레이스를 포함한 대부분의 디버깅 정보 제공
  3. 불필요한 의존성: 외부 서비스 의존으로 인한 잠재적 리스크

의사결정 과정: 왜 Docker Log Monitor를 선택했는가

다음과 같은 근거로 현 단계에서는 Docker Log Monitor 유지를 결정했습니다:

1. Zero Setup Cost (제로 셋업 비용)

# 이미 작동 중인 시스템 - 추가 작업 불필요
docker-compose up -d log-monitor # 끝

반면 Sentry는 다음과 같은 작업이 필요:

# pip install sentry-sdk 필요
import sentry_sdk

sentry_sdk.init(
dsn="https://...@sentry.io/...",
traces_sample_rate=1.0,
profiles_sample_rate=1.0,
)

# 모든 FastAPI 엔드포인트에 추가 설정 필요

2. FastAPI 로그의 충분한 정보

FastAPI는 기본적으로 매우 상세한 로그를 생성합니다:

# FastAPI 로그 예시
ERROR: Exception in ASGI application
Traceback (most recent call last):
File "/app/main.py", line 45, in process_request
result = await service.execute(data)
...
ValueError: Invalid input format

# 이미 포함된 정보:
# ✅ 스택 트레이스
# ✅ 에러 타입 및 메시지
# ✅ 발생 위치 (파일, 라인)
# ✅ 타임스탬프

Docker Log Monitor는 이러한 로그를 정규표현식으로 파싱하여 효과적으로 감지합니다:

# docker-log-monitor의 패턴 매칭
error_patterns = [
r"ERROR",
r"Exception",
r"Traceback",
r"500 Internal Server Error"
]

3. 비용 효율성

Docker Log Monitor:
- 설치 비용: $0
- 운영 비용: $0 (기존 서버 리소스 활용)
- 유지보수 비용: 최소 (안정적으로 작동 중)
- 총 비용: $0/월

Sentry:
- 무료 플랜: 5,000 이벤트/월 (제한적)
- Team 플랜: $26/월 (기본)
- Business 플랜: $80/월 (고급 기능)
- 대규모 사용 시: 추가 비용 발생

4. 프라이버시와 데이터 통제

Docker Log Monitor: 
┌─────────────┐
│ Application │
└──────┬──────┘
│ logs

┌─────────────┐ ┌─────────┐
│ Log Monitor │─────▶│ Slack │
└─────────────┘ └─────────┘
(자체 서버)

Sentry:
┌─────────────┐
│ Application │
└──────┬──────┘
│ SDK + 네트워크 요청

┌─────────────┐ ┌─────────┐
│ Sentry.io │─────▶│ Slack │
└─────────────┘ └─────────┘
(외부 서비스)

모든 에러 데이터가 자체 서버에 남아 데이터 주권과 프라이버시를 완벽히 통제할 수 있습니다.

결과: 점진적 확장 전략

최종적으로 다음과 같은 하이브리드 전략을 수립했습니다:

Phase 1: 현재 (Docker Log Monitor)

# docker-compose.yml
services:
log-monitor:
image: teddy/docker-log-monitor
environment:
- SLACK_WEBHOOK_URL=${SLACK_WEBHOOK_URL}
- COOLDOWN_MINUTES=30
volumes:
- /var/run/docker.sock:/var/run/docker.sock

커버리지:

  • ✅ HTTP 5xx 에러 감지
  • ✅ Python Exception 추적
  • ✅ 실시간 Slack 알림
  • ✅ Dev/Prod 환경 구분
  • ✅ 쿨다운으로 중복 알림 방지

Phase 2: 필요 시 (Sentry 추가)

프로젝트가 성장하면서 다음 상황이 발생할 때 Sentry 추가 고려:

# 트리거 조건 예시
if (
팀_규모 > 5 or
에러_발생_빈도 > 100_per_day or
복잡한_버그_디버깅_소요시간 > 4_hours or
고객_영향_추적_필요 == True
):
add_sentry()

Sentry 추가 시 얻는 이점:

  • 변수 값, 요청 파라미터 등 상세 컨텍스트
  • 웹 대시보드로 팀 전체 가시성 확보
  • 에러 트렌드 분석으로 품질 개선 인사이트
  • 릴리즈별 에러 추적으로 배포 영향 분석

Phase 3: 하이브리드 (최적의 조합)

Infrastructure Level (Docker Log Monitor):
├─ 시스템 레벨 에러 감지
├─ 즉각적인 알림 (네트워크 독립)
└─ 백업 모니터링 (Sentry 장애 대응)

Application Level (Sentry):
├─ 상세한 에러 컨텍스트
├─ 트렌드 분석 및 대시보드
└─ 팀 협업 및 이슈 관리

실전 적용 가이드

다른 프로젝트에서도 적용 가능한 의사결정 플로우차트:

프로젝트 시작

[Q1] 코드 수정 가능한가?
NO → Docker Log Monitor (유일한 선택)
YES → 다음 질문

[Q2] 팀 규모가 5명 이상인가?
NO → Docker Log Monitor 추천
YES → 다음 질문

[Q3] 월 예산 $50 이상 가능한가?
NO → Docker Log Monitor
YES → 다음 질문

[Q4] 복잡한 디버깅이 자주 발생하는가?
NO → Docker Log Monitor
YES → Sentry 권장

[Q5] 데이터 프라이버시가 중요한가?
YES → Docker Log Monitor
NO → Sentry 권장

구현 예시: Docker Log Monitor 설정

실제 프로젝트에서 사용한 설정:

# docker-compose.yml
version: '3.8'

services:
app:
image: myapp:latest
# ... 애플리케이션 설정

log-monitor:
build: ./docker-log-monitor
container_name: log-monitor
environment:
# Slack Webhook URL (필수)
- SLACK_WEBHOOK_URL=${SLACK_WEBHOOK_URL}

# 모니터링할 컨테이너 (선택, 기본값: 모두)
- MONITOR_CONTAINERS=app,worker

# 에러 패턴 커스터마이징
- ERROR_PATTERNS=ERROR,Exception,CRITICAL,500

# 쿨다운 설정 (분 단위)
- COOLDOWN_MINUTES=30

# 환경 구분 (Dev/Prod)
- ENVIRONMENT=production

# 타임존 설정
- TZ=Asia/Seoul

volumes:
# Docker 소켓 마운트 (로그 접근 필수)
- /var/run/docker.sock:/var/run/docker.sock:ro

restart: unless-stopped

# 리소스 제한 (선택)
deploy:
resources:
limits:
memory: 100M
cpus: '0.1'

환경변수 설정 (.env 파일):

# Slack Webhook URL
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# 환경 구분
ENVIRONMENT=production

# 쿨다운 설정 (30분)
COOLDOWN_MINUTES=30

측정 가능한 성과

Docker Log Monitor 도입 후 다음과 같은 성과를 측정했습니다:

설정 시간: 10분 (vs Sentry 예상 4시간)
비용 절감: $26-80/월 (Sentry 유료 플랜 대비)
에러 감지 지연시간: <1초 (실시간 로그 스트리밍)
알림 응답시간: 평균 5분 이내 (Slack 알림 즉시 확인)
시스템 리소스: ~20MB 메모리, CPU <1%

References

Docker Log Monitor 적용 가이드라인

· 약 6분
김성연
AI Research Engineer, Brain Crew

TL;DR

EC2 환경에서 Docker 컨테이너 로그를 실시간 모니터링하고 에러 발생 시 Slack으로 알림을 보내는 경량 모니터링 시스템 구축 경험을 공유합니다. Sentry 같은 무거운 솔루션 대신, Python 기반의 간단한 스크립트로 실시간 로그 감지, 중복 알림 방지, Traceback 수집 등의 핵심 기능을 구현했습니다. systemd 서비스로 등록하여 서버 재시작 시에도 자동 실행되도록 설정하고, 배포 시 불필요한 알림을 방지하는 Grace Period를 적용했습니다.

Key Takeaways

  • 경량화된 모니터링의 필요성: 모든 프로젝트에 Sentry 같은 무거운 솔루션이 필요한 것은 아니며, 초기 단계나 소규모 프로젝트에서는 간단한 로그 모니터링 시스템이 더 효과적일 수 있습니다.
  • 쿨다운 메커니즘의 중요성: 동일한 에러가 연속 발생 시 알림 피로도를 방지하기 위해 시간 기반 중복 알림 제어가 필수입니다.
  • 배포 시나리오 고려: 컨테이너 재시작이나 배포 시 발생하는 일시적 에러를 필터링하기 위한 Grace Period 설정으로 노이즈를 줄일 수 있습니다.
  • Traceback 전체 수집: 단일 라인 에러 로그만으로는 디버깅이 어려우므로, Python Traceback 전체를 수집하여 컨텍스트를 제공해야 합니다.
  • systemd 통합의 장점: 서비스로 등록하면 서버 재시작, 자동 재시작, 로그 관리 등을 운영체제 레벨에서 관리할 수 있어 안정성이 높아집니다.

상세 내용

배경: 왜 커스텀 모니터링 시스템을 만들었나?

프로젝트 초기 단계에서 에러 모니터링의 필요성은 명확했지만, Sentry 같은 상용 솔루션을 도입하기에는 몇 가지 장벽이 있었습니다:

  1. 비용 및 리소스: Sentry는 강력하지만 설정이 복잡하고 서버 리소스를 많이 소모합니다
  2. 과도한 기능: 초기 단계에서는 단순한 에러 알림만 필요했습니다
  3. Docker 환경 특화: Docker 컨테이너의 stdout/stderr 로그를 직접 모니터링하면 애플리케이션 코드 수정 없이 모니터링이 가능합니다

이러한 이유로 Python Docker SDK를 활용한 경량 모니터링 시스템을 직접 구축하기로 결정했습니다.

문제 상황: Docker 로그 모니터링의 도전 과제

Docker 환경에서 로그 모니터링을 구현하면서 마주친 주요 문제들:

1. 연속된 동일 에러의 알림 폭탄 초기 버전에서는 에러가 발생할 때마다 Slack 알림을 보냈는데, 특정 에러가 반복되면 수십 개의 알림이 순식간에 쌓였습니다.

2. 배포 시 불필요한 알림 컨테이너를 재시작하거나 배포할 때 일시적으로 연결이 끊기면서 발생하는 에러들이 알림으로 전송되었습니다.

3. 불완전한 에러 정보 단일 라인 에러 메시지만 캡처하면 전체 Traceback을 파악할 수 없어 디버깅이 어려웠습니다.

4. 모니터링 프로세스의 안정성 모니터링 스크립트 자체가 중단되면 에러를 놓치게 되는 문제가 있었습니다.

해결 과정

1. 쿨다운 메커니즘 구현

동일한 에러에 대해 일정 시간 동안 중복 알림을 방지하는 메커니즘을 구현했습니다:

class ErrorTracker:
def __init__(self, cooldown_seconds=300): # 5분 쿨다운
self.error_history = {}
self.cooldown_seconds = cooldown_seconds

def should_notify(self, error_signature):
"""에러 시그니처 기반으로 알림 전송 여부 결정"""
current_time = time.time()

if error_signature in self.error_history:
last_notified = self.error_history[error_signature]
if current_time - last_notified < self.cooldown_seconds:
return False # 쿨다운 기간 내에는 알림 차단

self.error_history[error_signature] = current_time
return True

def cleanup_old_entries(self):
"""오래된 에러 기록 정리"""
current_time = time.time()
self.error_history = {
k: v for k, v in self.error_history.items()
if current_time - v < self.cooldown_seconds * 2
}

의사결정 포인트: 쿨다운 시간을 5분으로 설정한 이유는, 대부분의 에러가 5분 내에 해결되거나 반복 패턴이 명확해지기 때문입니다. 프로젝트 특성에 따라 조정 가능합니다.

2. Grace Period 구현

배포 시 컨테이너가 시작된 직후 일정 시간 동안은 알림을 보내지 않도록 설정:

class DockerLogMonitor:
def __init__(self, grace_period_seconds=60):
self.grace_period = grace_period_seconds
self.container_start_times = {}

def is_in_grace_period(self, container_id):
"""컨테이너가 Grace Period 내에 있는지 확인"""
if container_id not in self.container_start_times:
# 컨테이너 시작 시간 기록
container = self.docker_client.containers.get(container_id)
start_time = container.attrs['State']['StartedAt']
self.container_start_times[container_id] = parse_datetime(start_time)

start_time = self.container_start_times[container_id]
elapsed = (datetime.now() - start_time).total_seconds()
return elapsed < self.grace_period

def process_log_line(self, container_id, log_line):
if self.is_in_grace_period(container_id):
logger.debug(f"Grace period active for {container_id}, skipping alert")
return

# 에러 패턴 감지 및 처리
self.detect_and_notify(log_line)

3. Traceback 전체 수집

Python 에러의 경우 여러 줄에 걸쳐 있는 Traceback을 모두 수집:

class TracebackCollector:
def __init__(self):
self.traceback_buffer = []
self.in_traceback = False

def process_line(self, line):
"""로그 라인을 처리하고 Traceback 수집"""
# Traceback 시작 감지
if "Traceback (most recent call last):" in line:
self.in_traceback = True
self.traceback_buffer = [line]
return None

# Traceback 진행 중
if self.in_traceback:
self.traceback_buffer.append(line)

# Traceback 종료 조건: 실제 에러 메시지 라인
if self.is_error_line(line) and len(self.traceback_buffer) > 1:
full_traceback = "\n".join(self.traceback_buffer)
self.in_traceback = False
self.traceback_buffer = []
return full_traceback

return None

def is_error_line(self, line):
"""에러 메시지 라인 판별"""
error_patterns = [
r'^[A-Z][a-zA-Z]+Error:',
r'^[A-Z][a-zA-Z]+Exception:',
r'^AssertionError:',
]
return any(re.match(pattern, line.strip()) for pattern in error_patterns)

4. Docker API를 통한 실시간 스트리밍

Docker SDK를 사용하여 컨테이너 로그를 실시간으로 스트리밍:

import docker

class DockerLogMonitor:
def __init__(self, container_name, slack_webhook_url):
self.docker_client = docker.from_env()
self.container_name = container_name
self.slack_webhook = slack_webhook_url
self.error_tracker = ErrorTracker(cooldown_seconds=300)
self.traceback_collector = TracebackCollector()

def start_monitoring(self):
"""컨테이너 로그 모니터링 시작"""
try:
container = self.docker_client.containers.get(self.container_name)
logger.info(f"Monitoring started for container: {self.container_name}")

# 실시간 로그 스트리밍 (follow=True, tail='all')
for log_line in container.logs(stream=True, follow=True):
line = log_line.decode('utf-8').strip()
self.process_log_line(container.id, line)

except docker.errors.NotFound:
logger.error(f"Container {self.container_name} not found")
except Exception as e:
logger.error(f"Monitoring error: {e}")
# 자동 재연결 로직
time.sleep(10)
self.start_monitoring()

의사결정 포인트: stream=Truefollow=True 옵션으로 실시간 스트리밍을 구현했습니다. tail='all'을 사용하면 컨테이너 시작 후 모든 로그를 캡처할 수 있지만, 필요에 따라 tail=100처럼 최근 로그만 가져올 수도 있습니다.

5. systemd 서비스 등록

안정적인 운영을 위해 systemd 서비스로 등록:

# /etc/systemd/system/docker-monitor.service
[Unit]
Description=Docker Log Monitor Service
After=docker.service
Requires=docker.service

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/docker-monitor
Environment="PYTHONUNBUFFERED=1"
ExecStart=/usr/bin/python3 /home/ubuntu/docker-monitor/monitor.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

서비스 등록 및 실행 명령어:

# 서비스 파일 복사 및 권한 설정
sudo cp docker-monitor.service /etc/systemd/system/
sudo chmod 644 /etc/systemd/system/docker-monitor.service

# systemd 리로드 및 서비스 활성화
sudo systemctl daemon-reload
sudo systemctl enable docker-monitor.service
sudo systemctl start docker-monitor.service

# 서비스 상태 확인
sudo systemctl status docker-monitor.service

# 로그 확인
sudo journalctl -u docker-monitor.service -f

의사결정 포인트:

  • Restart=always로 설정하여 프로세스 종료 시 자동 재시작
  • After=docker.service로 Docker 서비스가 시작된 후에 실행되도록 의존성 설정
  • StandardOutput=journal로 systemd 저널에 로그 저장하여 중앙화된 로그 관리

6. Slack 알림 포맷 개선

가독성 높은 알림 메시지 구성:

def send_slack_notification(self, error_info):
"""Slack으로 에러 알림 전송"""
message = {
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "🚨 Docker Container Error Detected"
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": f"*Container:*\n{error_info['container_name']}"
},
{
"type": "mrkdwn",
"text": f"*Time:*\n{error_info['timestamp']}"
}
]
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": f"*Error Message:*\n```{error_info['error_message']}```"
}
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": f"*Full Traceback:*\n```{error_info['traceback'][:2000]}```"
}
}
]
}

response = requests.post(
self.slack_webhook,
json=message,
headers={'Content-Type': 'application/json'}
)

if response.status_code != 200:
logger.error(f"Slack notification failed: {response.text}")

결과

이 시스템을 도입한 후 다음과 같은 개선 효과를 얻었습니다:

  1. 즉각적인 에러 인지: 프로덕션 환경에서 발생하는 에러를 실시간으로 파악할 수 있게 되었습니다
  2. 알림 피로도 감소: 쿨다운 메커니즘으로 중복 알림이 90% 이상 감소했습니다
  3. 디버깅 시간 단축: Traceback 전체를 수집하여 에러 원인 파악 시간이 크게 줄었습니다
  4. 운영 안정성 향상: systemd 통합으로 서버 재시작 후에도 자동으로 모니터링이 재개됩니다
  5. 비용 효율성: Sentry 대비 서버 리소스 사용량이 매우 적고 추가 비용이 발생하지 않습니다

개선 예정 사항

현재 버전은 기본적인 모니터링 기능을 제공하지만, 다음과 같은 개선을 계획하고 있습니다:

  • 다중 컨테이너 지원: 현재는 단일 컨테이너만 모니터링하지만, 여러 컨테이너를 동시에 모니터링
  • 필터링 룰 커스터마이징: YAML 설정 파일로 에러 패턴과 필터링 룰을 외부화
  • 메트릭 수집: 에러 발생 빈도, 패턴 분석 등의 통계 데이터 수집
  • 다양한 알림 채널: Slack 외에 Email, Discord, PagerDuty 등 추가 지원

References

Which tabular format RAG Process understands very well?

· 약 7분
최재훈
LEAD (AI Research Engineer), Brain Crew

TL;DR

RAG 파이프라인에서 테이블 데이터의 포맷이 검색 성능에 미치는 영향을 실험한 결과, Markdown Key-Value 형식이 가장 높은 Recall을 보였으며, TOON 포맷은 토큰 효율성 측면에서 가장 우수했습니다. AIHub의 표 정보 질의응답 데이터 50개를 7가지 포맷으로 변환하여 비교한 결과, 포맷 선택은 성능과 비용 간의 트레이드오프 관계에 있음을 확인했습니다.

Key Takeaways

  • 포맷 선택은 사용 사례에 따라 달라져야 함: 높은 정확도가 필요한 경우 Markdown-KV, 비용 효율이 중요한 경우 TOON 포맷을 선택하는 것이 합리적입니다.
  • 토큰 효율과 검색 성능은 별개: TOON은 평균 토큰 수를 크게 줄이지만, 이것이 항상 높은 Recall로 이어지지는 않습니다. Embedding 모델의 학습 데이터와 포맷 간의 친화성이 중요합니다.
  • 소규모 실험으로도 유의미한 인사이트 도출 가능: 50개 샘플로도 포맷 간 상대적 성능 차이를 파악할 수 있으며, 이를 바탕으로 프로덕션 환경에서의 포맷 선택 방향을 설정할 수 있습니다.
  • 평가 파이프라인 구축의 중요성: LLM을 활용한 QA 생성 → Retrieval 평가의 자동화된 파이프라인은 다양한 실험을 빠르게 반복할 수 있게 해줍니다.
  • Generation 단계까지 고려해야 완전한 평가: Retrieval 성능만으로는 최종 사용자 경험을 대변하기 어려우며, 실제 답변 생성 품질까지 평가해야 합니다.

상세 내용

배경: 테이블 데이터와 RAG의 만남

RAG(Retrieval-Augmented Generation) 시스템에서 테이블 데이터는 구조화된 정보를 담고 있어 높은 가치를 지니지만, 동시에 처리하기 까다로운 대상입니다. HTML 테이블, Markdown, JSON, CSV 등 다양한 포맷이 존재하며, 각 포맷은 정보 밀도, 토큰 소비량, LLM의 이해도 측면에서 상이한 특성을 보입니다.

최근 TOON(Token-Oriented Object Notation) 포맷이 등장하면서, 동일한 정보를 더 적은 토큰으로 표현하면서도 LLM이 이해하기 쉬운 구조를 제공한다는 주장이 제기되었습니다. 그러나 실제 RAG 환경에서 어떤 포맷이 최적인지에 대한 실증적 연구는 부족한 상황이었습니다.

문제 상황: 포맷 선택의 딜레마

프로덕션 RAG 시스템을 구축할 때, 다음과 같은 질문에 직면합니다:

  1. 토큰 효율성과 검색 성능 중 무엇을 우선할 것인가?
  2. Embedding 모델이 특정 포맷을 더 잘 이해하는가?
  3. 포맷 변환의 추가 비용 대비 성능 개선이 합리적인가?

이러한 질문에 답하기 위해 체계적인 실험을 설계했습니다.

실험 설계

데이터 준비

AIHub의 "표 정보 질의응답 데이터"를 활용했습니다. 이 데이터는:

  • 총 100만 건의 QA 쌍 포함
  • 건축, 공공행정, 과학기술 등 10개 카테고리
  • 다양한 테이블 복잡도 (행 수, 헤더 depth 등)

전체 16,000개 테이블 중 50개를 무작위 샘플링하여 Target Data로 선정했습니다.

평가용 QA 생성

각 테이블에 대해 GPT-4.1을 활용하여 질문-답변 쌍을 자동 생성했습니다:

# 의사 코드
def generate_qa_pairs(table_chunk):
# Step 1: 테이블 기반 질문 생성
question = gpt4_generate_question(table_chunk)

# Step 2: 테이블 + 질문 기반 답변 생성
answer = gpt4_generate_answer(table_chunk, question)

return question, answer

이 중 25개를 최종 Evaluation Data로 선정했습니다.

7가지 테이블 포맷

다음 포맷들을 비교했습니다:

  1. HTML: 표준 <table> 태그 구조
  2. Markdown: 파이프(|)로 구분된 형식
  3. Markdown-KV: 각 행을 Key-Value 쌍으로 표현
  4. TOON: 탭형 구조로 압축된 포맷
  5. JSON: 표준 JSON 배열 구조
  6. Plain Text: 자연어 형태로 풀어쓴 형식
  7. CSV-like: 쉼표로 구분된 단순 형식

포맷 변환 예시

원본 HTML 테이블:

<table>
<tr><td>바탕의 종류</td><td>도장 종류</td><td>공법</td></tr>
<tr><td>목재면</td><td>1종</td><td>부분 퍼티 처리</td></tr>
<tr><td>철재면</td><td>2종</td><td>금속바탕 처리용 프라이머</td></tr>
</table>

Markdown-KV 변환:

## 바탕 만들기의 도장 방법

**항목 1:**
- 바탕의 종류: 목재면
- 도장 종류: 1종
- 공법: 부분 퍼티 처리

**항목 2:**
- 바탕의 종류: 철재면
- 도장 종류: 2종
- 공법: 금속바탕 처리용 프라이머

TOON 변환:

바탕 만들기의 도장 방법[2]{바탕의 종류, 도장 종류, 공법}:
목재면, 1종, 부분 퍼티 처리
철재면, 2종, 금속바탕 처리용 프라이머

실험 방법론

Embedding 및 저장

Qwen/Qwen3-Embedding-8B 모델을 사용하여 각 포맷별로 임베딩을 생성하고, 별도의 Chroma collection에 저장했습니다. 이 모델을 선택한 이유는:

  • 다국어 지원 (한국어 포함)
  • 8B 파라미터로 높은 성능
  • 문서 검색에 최적화된 학습

평가 지표

  1. Recall@K: Top-K 검색 결과에 정답 문서가 포함되는 비율
    • K=1, 2, 3에 대해 측정
  2. Average Token Count: 각 포맷의 평균 토큰 수
    • 비용 효율성의 대리 지표
def evaluate_retrieval(collection, queries, ground_truth, k=3):
recalls = []
for query, gt_doc_id in zip(queries, ground_truth):
results = collection.query(query, n_results=k)
retrieved_ids = [r['id'] for r in results]
recall = 1 if gt_doc_id in retrieved_ids else 0
recalls.append(recall)
return sum(recalls) / len(recalls)

실험 결과 분석

Recall 성능

실험 결과, Markdown-KV 포맷이 가장 높은 Recall을 기록했습니다:

  • Markdown-KV: Recall@3 기준 약 85%
  • HTML: 약 78%
  • TOON: 약 72%
  • Plain Text: 약 68%
  • JSON: 약 65%

왜 Markdown-KV가 우수했는가?

  1. 명시적 Key-Value 구조: "바탕의 종류: 목재면"과 같은 형식은 Embedding 모델이 의미론적 관계를 파악하기 쉽게 만듭니다.
  2. 자연어 친화성: Qwen 모델의 학습 데이터에 Markdown 형식이 많이 포함되어 있을 가능성이 높습니다.
  3. 정보 밀도: 각 항목이 독립적으로 표현되어 부분 매칭에 유리합니다.

토큰 효율성

TOON 포맷이 기대대로 가장 효율적이었습니다:

  • TOON: 평균 약 120 토큰 (기준)
  • Markdown-KV: 평균 약 210 토큰 (+75%)
  • HTML: 평균 약 180 토큰 (+50%)
  • JSON: 평균 약 195 토큰 (+62%)

토큰 효율성의 실제 의미

50개 테이블 기준으로 계산하면:

  • TOON: 6,000 토큰
  • Markdown-KV: 10,500 토큰

월 100만 테이블을 처리하는 서비스라면:

  • 토큰 차이: 90,000,000 토큰/월
  • 비용 차이 (OpenAI 가격 기준 $0.0001/1K 토큰): $9/월

규모가 커질수록 이 차이는 유의미해집니다.

의사결정 프레임워크: 어떤 포맷을 선택할 것인가?

실험 결과를 바탕으로 다음과 같은 의사결정 트리를 제안합니다:

질문 1: 검색 정확도가 최우선인가?
└─ Yes → Markdown-KV 선택
└─ No → 질문 2로

질문 2: 대용량 처리 (>100K 테이블/일)인가?
└─ Yes → TOON 선택
└─ No → 질문 3으로

질문 3: 기존 시스템이 특정 포맷을 사용 중인가?
└─ Yes → 기존 포맷 유지 (변환 비용 고려)
└─ No → HTML 또는 Markdown 선택 (범용성)

한계점 및 추가 고려사항

1. 실험 규모의 한계

50개 샘플은 트렌드를 파악하기에는 충분하지만, 통계적 유의성을 확보하기에는 부족합니다. 특히:

  • Recall@5 이상에서는 차이가 수렴할 가능성
  • 특정 도메인(예: 금융 표)에서는 다른 결과가 나올 수 있음

2. Embedding 모델 의존성

Qwen3-Embedding-8B는 우수한 성능을 보이지만, 이는 결과에 편향을 줄 수 있습니다. OpenAI의 text-embedding-3-large나 Cohere의 embed-multilingual-v3.0으로 실험하면 다른 포맷이 우세할 수 있습니다.

3. Generation 단계 미평가

Retrieval 성능만으로는 불충분합니다. 실제 RAG 시스템에서는:

  • LLM이 retrieved context를 얼마나 잘 이해하는가?
  • 최종 답변의 품질은?

이를 평가하기 위해서는 추가 실험이 필요합니다:

def evaluate_end_to_end(query, retrieved_chunks, ground_truth_answer):
# LLM에 retrieved chunks를 전달하여 답변 생성
generated_answer = llm_generate(query, retrieved_chunks)

# 답변 품질 평가 (ROUGE, BERTScore 등)
score = evaluate_answer_quality(generated_answer, ground_truth_answer)
return score

향후 연구 방향

1. 대규모 벤치마크

  • 1,000개 이상의 테이블로 실험 확장
  • 다양한 카테고리별 성능 비교
  • 테이블 복잡도(행/열 수, nested structure)에 따른 포맷 성능 변화 분석

2. 하이브리드 접근

여러 포맷을 동시에 활용하는 전략:

def hybrid_retrieval(query):
# TOON으로 1차 검색 (효율성)
toon_candidates = toon_collection.query(query, n_results=10)

# Markdown-KV로 재순위화 (정확성)
refined_results = rerank_with_markdown_kv(toon_candidates)
return refined_results

3. 포맷별 최적화

각 포맷에 특화된 Retrieval 전략:

  • TOON: 구조 인식 검색
  • Markdown-KV: Key 기반 필터링 + Value 검색
  • JSON: 스키마 활용 쿼리 확장

4. 도메인 특화 실험

  • 금융 표: 숫자와 단위가 중요
  • 법률 표: 계층 구조와 참조가 중요
  • 과학 표: 수식과 기호가 중요

각 도메인에서 최적 포맷이 다를 수 있습니다.

실무 적용 가이드

Step 1: 요구사항 분석

requirements = {
"accuracy_priority": "high", # high/medium/low
"volume": "100K tables/day",
"budget": "tight",
"latency_requirement": "<2s",
"existing_format": "HTML"
}

Step 2: 파일럿 실험

작은 규모로 3-4개 포맷을 비교:

# 실험 설정
formats_to_test = ["markdown_kv", "toon", "html"]
sample_size = 100

# 평가 실행
results = {}
for fmt in formats_to_test:
results[fmt] = {
"recall": evaluate_recall(fmt, sample_size),
"avg_tokens": calculate_avg_tokens(fmt, sample_size),
"conversion_cost": estimate_conversion_cost(fmt)
}

# 최적 선택
best_format = select_best(results, requirements)

Step 3: 프로덕션 롤아웃

  1. A/B 테스팅: 기존 포맷과 신규 포맷을 동시 운영
  2. 모니터링: 실제 사용자 쿼리에서의 성능 추적
  3. 점진적 전환: 성능이 검증되면 단계적으로 확대

References

메모랜덤 flow에 사용된 문서영역별 Clustering 성능평가

· 약 8분
강민석
AI Research Engineer, Brain Crew

TL;DR

GS Caltex 메모랜덤-연구노트 매칭 프로젝트에서 PyMuPDF 기반 파서, Titan Embed V2 임베딩, ChromaDB 벡터 검색, Claude Sonnet 4.5 LLM 판정을 결합한 파이프라인을 구축했습니다. 137개 연구노트 중 82.5%가 메모랜덤과 매칭되었으며, Label Propagation 알고리즘이 BCubed F1 0.763으로 최고 성능을 기록했습니다. 단일 클러스터로 수렴하는 경향이 강해 의미 기반보다 서사 구조 기반 접근이 더 효과적임을 확인했습니다.

Key Takeaways

  • LLM 기반 매칭 판정의 보수적 설계: 벡터 유사도만으로는 부족한 정확도를 Claude Sonnet 4.5의 명시적 판정(표 데이터 유무, 섹션 타입 필터링)으로 보완하여 82.5% 매칭률 달성. Temperature=0.0으로 일관성 확보가 핵심.

  • 클러스터링 알고리즘 선택은 데이터 특성에 의존적: Label Propagation(F1 0.763)이 평균적으로 우수하나, 단일 주제 데이터(ELN3)는 Connected Components로 완벽 매칭(F1 1.0), 복잡한 다중 주제(ELN5)는 HDBSCAN이 유리(F1 0.812). 사전 데이터 분석 필수.

  • HDBSCAN 과분할 문제와 파라미터 민감도: min_cluster_size 5 이상에서 평균 37개 클러스터 생성으로 recall 급락. 최적값은 2~3 + min_samples=3 조합으로 F1 0.736 달성. 정성 피드백과 정량 평가 일치.

  • 단일 클러스터 수렴 현상의 근본 원인: 연구노트 간 임베딩 유사도가 높아 GraphCommunity 알고리즘에서 평균 1.1~1.9개 클러스터만 생성. 의미 기반 분할보다 서사 구조(시간순, 실험 단계) 기반 청킹이 더 효과적.

  • BCubed F1 메트릭의 실무 적용성: Precision/Recall 균형 평가로 과분할(precision 하락)과 과소분할(recall 하락) 동시 탐지 가능. 클러스터 수와 F1을 함께 모니터링하여 알고리즘 선택 가이드 제공.

상세 내용

배경: 연구노트-메모랜덤 자동 매칭 시스템 구축

GS Caltex 프로젝트는 PDF 형태의 연구노트(ELN)와 메모랜덤을 자동으로 매칭하여 연구 결과를 체계화하는 시스템 개발을 목표로 했습니다. 기존 수작업 매칭은 시간이 많이 소요되고 일관성이 부족했으며, 메모랜덤의 목차 구조를 활용하여 관련 연구노트를 자동으로 클러스터링하는 솔루션이 필요했습니다.

핵심 과제는 두 가지였습니다:

  1. 정확한 정답셋 생성: 벡터 유사도만으로는 부정확한 매칭이 많아 LLM 판정 단계 추가
  2. 효과적인 클러스터링: 메모랜덤 목차별로 연구노트를 의미있게 그룹화

아키텍처 설계: 파싱 → 임베딩 → 벡터 검색 → LLM 판정

1단계: 문서 파싱 및 청킹

메모랜덤과 연구노트는 서로 다른 파싱 전략을 적용했습니다:

# 메모랜덤: 폰트 크기 기반 목차 추출
class MemorandumNaiveParser:
def extract_toc(self, page):
if font_size >= 13.5:
return "대제목" # "1. 목적"
elif font_size >= 11.5:
return "소제목" # "2.1. 균주"
else:
return "본문"

# 연구노트: 키워드 기반 섹션 분류
SECTION_KEYWORDS = {
"실험개요": ["실험개요", "실험 개요"],
"실험방법": ["실험방법", "실험 방법"],
"실험결과": ["실험결과", "Task Results"],
"결론": ["결론", "고찰", "결과 및 토의"],
}

의사결정 포인트: PyMuPDF를 선택한 이유는 로컬 처리 가능, 빠른 속도, 폰트 메타데이터 추출 지원 때문입니다. Upstage Document Parse API도 테스트했으나, 대부분의 문서에서 PyMuPDF와 유사한 품질을 보여 비용 효율적인 로컬 처리를 선택했습니다.

2단계: 임베딩 및 벡터 저장

# Amazon Titan Embed Text V2 설정
embedding_config = {
"model_id": "amazon.titan-embed-text-v2:0",
"dimensions": 1024,
"normalize": True, # L2 정규화로 코사인 유사도 계산
"max_tokens": 8192,
"safety_margin": 0.85 # 실제 최대: 6,553 토큰
}

# ChromaDB 디스크 기반 저장
chroma_client = chromadb.PersistentClient(path="./chroma_db")
collection = chroma_client.create_collection(
name="memorandum_eln",
metadata={"hnsw:space": "cosine"}
)

의사결정 포인트: Titan V2를 선택한 이유는 AWS Bedrock 통합 용이성과 8K 토큰 컨텍스트 길이입니다. 메모랜덤 청크가 평균 500 토큰으로 긴 편이라 OpenAI의 512 토큰 제약은 부적합했습니다.

3단계: 벡터 검색 + LLM 판정

# Top-K=5 벡터 검색
results = collection.query(
query_embeddings=[eln_embedding],
n_results=5,
where={"session_id": session_id}
)

# Claude Sonnet 4.5 매칭 판정
prompt = f"""
다음 연구노트와 메모랜덤 청크가 같은 실험을 다루는지 판단하세요.

[판정 기준]
- True: 표(Table)에 구체적 실험 데이터(OD, 수율, 농도 등) 있음
- False: 결론/목적/향후 계획 섹션
- False: 판단 어려움 (보수적 판정)

[연구노트]
{eln_content}

[메모랜덤 청크]
{memorandum_chunk}

JSON 형식으로 응답: {{"match": true/false, "confidence": "high/medium/low"}}
"""

response = bedrock.invoke_model(
modelId="global.anthropic.claude-sonnet-4-5-20250929-v1:0",
body=json.dumps({
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 1000,
"temperature": 0.0, # 일관성 최대화
"messages": [{"role": "user", "content": prompt}]
})
)

의사결정 포인트: 벡터 유사도만 사용했을 때 "실험 방법" 섹션과 "실험 결과" 섹션이 오매칭되는 문제가 빈번했습니다. LLM을 추가하여 표 데이터 유무를 명시적으로 확인하도록 설계한 결과, precision이 크게 향상되었습니다. Temperature=0.0은 반복 실행 시 일관된 판정을 보장하기 위한 설정입니다.

정답셋 생성 결과: 137개 노트 중 82.5% 매칭

4개 데이터셋(ELN1, 3, 4, 5)에서 총 270개 매칭 쌍을 생성했습니다:

데이터셋주제매칭률평균 매칭/노트평균 거리
ELN13-HP 발효86.5%2.1개0.763
ELN3일반 연구100.0%2.5개0.699
ELN4CO2 Polyol68.8%2.5개0.732
ELN5Pilot 촉매 공정90.0%2.5개0.733

주목할 점:

  • 평균 거리 0.699~0.763: 코사인 거리 기준으로 상당히 가까운 편이나, 절대값으로는 명확한 경계 설정이 어려움 → LLM 판정 필요성 입증
  • ELN3 100% 매칭: 단일 주제로 집중된 데이터셋은 벡터 유사도가 높고 LLM 판정도 명확
  • ELN4 68.8% 매칭: 다양한 실험 방법론이 혼재되어 낮은 매칭률

클러스터링 성능 평가: BCubed F1 메트릭

BCubed F1 선택 이유:

  • Precision: 같은 클러스터에 속한 아이템 중 실제로 같은 카테고리인 비율 → 과분할 패널티
  • Recall: 같은 카테고리에 속한 아이템 중 같은 클러스터에 할당된 비율 → 과소분할 패널티
  • F1-Score: Precision과 Recall의 조화평균으로 균형 평가
def bcubed_precision(item_i, cluster_assignments, ground_truth):
"""아이템 i에 대한 BCubed Precision"""
cluster_i = cluster_assignments[item_i]
category_i = ground_truth[item_i]

# 같은 클러스터에 속한 아이템들
same_cluster = [j for j, c in enumerate(cluster_assignments) if c == cluster_i]

# 그 중 실제로 같은 카테고리인 아이템들
correct = [j for j in same_cluster if ground_truth[j] == category_i]

return len(correct) / len(same_cluster)

# 전체 BCubed F1 계산
precision = np.mean([bcubed_precision(i, clusters, labels) for i in range(n)])
recall = np.mean([bcubed_recall(i, clusters, labels) for i in range(n)])
f1 = 2 * precision * recall / (precision + recall)

알고리즘별 성능 비교: Label Propagation 우승

전체 평균 성능:

알고리즘평균 F1평균 클러스터 수특징
Label Propagation0.7631.9안정적, 단순 구조
Connected Components0.7331.1최소 클러스터 생성
Louvain0.6893.1세분화 경향
HDBSCAN0.6148.8과분할 심각

Label Propagation이 우수한 이유:

  1. 그래프 기반 전파: 이웃 노드 라벨 중 다수결로 자신의 라벨 업데이트
  2. 자연스러운 경계 형성: 유사도가 높은 영역은 하나의 라벨로 수렴
  3. 적절한 클러스터 수: 평균 1.9개로 과분할/과소분할 균형
# Label Propagation 작동 원리
def label_propagation(graph, max_iter=100):
# 초기: 모든 노드에 고유 라벨
labels = {node: i for i, node in enumerate(graph.nodes())}

for _ in range(max_iter):
for node in graph.nodes():
# 이웃 라벨 중 가장 많은 것 선택
neighbor_labels = [labels[n] for n in graph.neighbors(node)]
labels[node] = max(set(neighbor_labels), key=neighbor_labels.count)

return labels

데이터셋별 최적 알고리즘:

데이터셋최적 알고리즘F1이유
ELN3CC/LP1.000단일 주제로 명확한 경계
ELN4Louvain0.952다양한 실험 방법론, 세분화 필요
ELN5HDBSCAN0.812복잡한 pilot 공정, 노이즈 존재
ELN1CC/LP0.5973-HP 발효 단계별 구분 어려움

HDBSCAN 과분할 문제와 해결책

문제 상황:

  • min_cluster_size=5에서 ELN1에 평균 37개 클러스터 생성 (실제 목차 5개)
  • 단일 연구노트가 여러 클러스터로 분할되어 recall 급락 (F1 0.15~0.27)

파라미터 튜닝 결과:

# 최적 조합: (min_cluster_size=2~3, min_samples=3)
best_config = {
"min_cluster_size": 3, # 최소 클러스터 크기
"min_samples": 3, # 핵심 포인트 판정 기준
"metric": "euclidean",
"cluster_selection_method": "eom" # Excess of Mass
}

# 성능 개선
# Before (5, 1): F1 0.540, 평균 16.5개 클러스터
# After (3, 3): F1 0.736, 평균 5.3개 클러스터

의사결정 포인트: min_cluster_size를 낮추면 과분할 완화되나, 너무 낮으면 노이즈를 클러스터로 인식. min_samples=3으로 핵심 포인트 판정을 엄격히 하여 균형 확보.

GraphCommunity 파라미터 영향 분석

k_neighbors 영향:

kLP F1Louvain F1CC F1경향
50.7650.7530.812k 증가 시 성능 저하
100.7330.7540.707-
150.7790.7590.687-
200.7340.7180.687-

의사결정: k=5를 기본값으로 선택. k가 클수록 약한 연결까지 포함하여 단일 클러스터로 수렴하는 경향 강화.

유사도 메트릭 비교:

# Euclidean vs Cosine
# Euclidean: 평균 F1 0.731
# Cosine: 평균 F1 0.718

# 의사결정: Euclidean 선택
# 이유: Titan V2는 이미 L2 정규화 적용하여 방향성보다 거리가 유의미

핵심 인사이트: 단일 클러스터 수렴 현상

발견 사항:

  • CC/LP 알고리즘에서 평균 클러스터 수 1.1~1.9개
  • ELN3 전체가 하나의 클러스터로 수렴했으나 F1=1.0 (정답도 단일 클러스터)

원인 분석:

  1. 높은 임베딩 유사도: 연구노트 간 평균 코사인 거리 0.7대로 근접
  2. 공통 도메인 용어: "발효", "OD", "수율" 등 반복 출현
  3. 서사 구조의 부재: 시간순/실험 단계 정보가 임베딩에 미반영

실무 적용 제안:

# 개선 방향 1: 메타데이터 통합
chunk_metadata = {
"content": text,
"date": extract_date(text),
"experiment_phase": classify_phase(text), # "준비", "진행", "분석"
"section_type": section_type
}

# 개선 방향 2: 하이브리드 임베딩
hybrid_embedding = concatenate([
semantic_embedding, # Titan V2
temporal_embedding, # 날짜 정보
structural_embedding # 섹션 타입
])

실무 적용 가이드

1. 데이터 특성 파악 후 알고리즘 선택:

def select_algorithm(data_characteristics):
if data_characteristics["topic_diversity"] == "single":
return "connected_components" # F1 1.0 기대

elif data_characteristics["cluster_boundaries"] == "clear":
return "louvain" # F1 0.95+ 기대

elif data_characteristics["noise_level"] == "high":
return {
"algorithm": "hdbscan",
"params": {"min_cluster_size": 3, "min_samples": 3}
}

else:
return "label_propagation" # 범용적으로 안정적

2. BCubed F1과 클러스터 수 동시 모니터링:

# 과분할 탐지
if avg_clusters > expected_clusters * 2 and f1 < 0.7:
print("과분할 의심: min_cluster_size 증가 필요")

# 과소분할 탐지
if avg_clusters < expected_clusters * 0.5 and f1 < 0.7:
print("과소분할 의심: k_neighbors 감소 또는 algorithm 변경")

3. LLM 판정 프롬프트 엔지니어링:

# 핵심: 명시적 기준 + 보수적 판정
prompt_template = """
[판정 기준] (우선순위 순)
1. 표(Table) 데이터 존재 여부
2. 정량적 수치 (농도, 수율, 온도 등) 존재 여부
3. 섹션 타입 (결론/계획은 제외)

[보수적 판정 원칙]
- 애매한 경우 False 반환
- 추론 과정을 reasoning 필드에 기록
"""

References

근사 최근접 탐색(ANN) 오차와 데이터 분포 밀도의 관계 고찰

· 약 9분
김태한
AI Research Engineer, Brain Crew

TL;DR

RAG 시스템에서 n_results는 단순히 '반환할 결과 개수'가 아닌 '검색 반경(search radius)'을 의미합니다. ANN 알고리즘의 근사 특성으로 인해 작은 n_results 값은 진짜 근접 벡터를 놓칠 수 있으며, 특히 고밀도 데이터 분포와 추상적 쿼리에서 이 문제가 심화됩니다. LGE RAG 프로젝트에서 n_results=100일 때 찾지 못했던 정답 문서가 n_results=500에서는 25번째로 검색되는 현상을 통해, 데이터 밀도와 쿼리 특성에 따라 충분히 큰 n_results 설정이 필수적임을 확인했습니다.

Key Takeaways

  • n_results는 검색 반경을 결정하는 파라미터: 단순 출력 개수가 아니라 ANN 알고리즘이 탐색할 벡터 공간의 범위를 의미하며, 작은 값은 근사 오차에 더 취약함
  • 데이터 밀도가 높을수록 더 큰 n_results 필요: 유사한 문서가 밀집된 환경에서는 작은 검색 반경으로 진짜 근접 벡터를 놓칠 확률이 급증함
  • 추상적 쿼리는 밀도 문제를 악화: "7키로 러닝", "별자리 보기" 같은 일반적 표현은 임베딩 공간에서 넓은 영역에 분산되어 충분한 탐색 범위가 더욱 중요함
  • 프로덕션 환경에서는 넉넉한 n_results 설정 후 reranking 전략 권장: 초기 검색에서 후보를 충분히 확보한 뒤, 상위 k개를 재정렬하여 정확도와 성능의 균형을 맞춤
  • 벡터 검색은 정렬된 전수 탐색이 아님: HNSW 등 ANN 알고리즘은 근사 방식이므로 n_results 변화에 따라 결과 순서와 내용이 모두 달라질 수 있음

상세 내용

배경: n_results 파라미터에 대한 오해

벡터 검색 시스템을 처음 접하는 엔지니어들은 n_results를 '최종 출력 개수'로만 이해하는 경향이 있습니다. 예를 들어 "상위 10개만 필요하니까 n_results=10"처럼 설정하는 것이죠.

LGE RAG 프로젝트에서 저 역시 동일한 접근을 했습니다. 그러나 동일한 쿼리에 대해 n_results 값만 변경했을 때 상위 결과의 순서와 내용이 완전히 달라지는 현상을 발견했습니다. 더 놀라운 점은 n_results를 늘렸을 때 더 관련성 높은 문서가 상위에 등장했다는 것입니다.

문제 상황: 동일 쿼리, 다른 결과

쿼리: "스마트폰 앱으로 별 보기를 한다"

n_results=100 결과

[1] 스마트폰 화면을 켠다 (무관한 문서)
[2] 스마트폰을 집어 든다 (무관한 문서)
[3] 휴대폰 밝기를 조절한다 (무관한 문서)
→ 정답 문서("스카이뷰 앱") 포함 안 됨

n_results=500 결과

[1] 스마트폰을 하늘로 향해 초기 별자리 지도를 띄운다 ✓
[2] 가이드에 따라 스마트폰을 원을 그리듯 움직여 센서를 보정한다 ✓
...
[25] 스마트폰에서 스카이뷰 앱을 실행한다 ✓
→ 정답 문서들이 상위권 및 25번째 등장

동일한 쿼리, 동일한 임베딩 모델, 동일한 벡터 DB에서 오직 n_results만 달랐는데 왜 이런 결과가 나올까요?

원인 분석 1: ANN 알고리즘의 근사 특성

전수 탐색과 ANN의 차이

많은 엔지니어들이 벡터 검색을 다음과 같이 상상합니다:

# 머릿속 기대: 전수 탐색 후 정렬
def ideal_search(query_vector, all_vectors):
distances = [cosine_distance(query_vector, v) for v in all_vectors]
sorted_results = sorted(distances)
return sorted_results[:n_results] # 상위 n개 자르기

하지만 실제 Chroma, FAISS 등이 사용하는 **ANN(Approximate Nearest Neighbor)**은 다릅니다:

# 실제 동작: 그래프 기반 근사 탐색 (HNSW 예시)
def ann_search(query_vector, hnsw_graph, n_results):
entry_point = hnsw_graph.top_layer_node
visited = set()
candidates = []

# 상위 레이어부터 탐색
for layer in range(top_layer, 0, -1):
entry_point = search_layer(query_vector, entry_point, layer, ef=1)

# 최하위 레이어에서 ef 크기만큼 탐색
candidates = search_layer(query_vector, entry_point, layer=0, ef=n_results)

# 탐색한 candidates 중 상위 n_results 반환
return heapq.nsmallest(n_results, candidates, key=lambda x: x.distance)

핵심 차이점:

  • 전수 탐색이 아님: 모든 벡터를 확인하지 않고 그래프 구조를 따라 '탐험'
  • n_results가 탐색 범위(ef) 결정: 작은 n_results = 좁은 탐험 영역
  • 그래프 경로 의존성: 초기 진입점과 이웃 노드 구조에 따라 특정 영역을 아예 방문하지 않을 수 있음

주요 ANN 알고리즘 비교

알고리즘핵심 원리n_results 영향적합한 시나리오
HNSW계층적 그래프, 각 층에서 greedy 탐색ef_search 파라미터와 연동, 작으면 탐색 중단 빠름높은 정확도 필요, 메모리 여유 있음
IVFk-means 클러스터링 후 클러스터 내 탐색nprobe 값으로 탐색 클러스터 수 결정대규모 데이터, 속도 우선
PQ벡터 양자화로 압축압축으로 인한 정보 손실 존재메모리 제약, 약간의 정확도 손실 허용
LSH해시 함수로 유사 벡터 버킷 분류해시 충돌 가능, 작은 k에서 누락 위험빠른 프로토타이핑, 저차원

결론: n_results가 작을수록 ANN 알고리즘은 더 좁은 범위만 탐색하고 조기 종료합니다. 진짜 근접 벡터가 탐색 경로에서 벗어나 있으면 영영 발견하지 못합니다.

원인 분석 2: 데이터 분포 밀도의 영향

고밀도 데이터의 특성

LGE 프로젝트의 행동 로그 데이터는 다음과 같은 특성을 가졌습니다:

<!-- 문서들이 구조적으로 거의 동일 -->
<activity_info>
{날짜} {시간대} {장소} 일정이다.
{시작시간}부터 {종료시간}까지 {상세장소}에서 {행동}한다.
이 활동은 {동반자}와 함께 했다. {도구}를 사용했다.
전에는 {이전행동}한다. 그 후에는 {다음행동}한다.
</activity_info>

이런 데이터는 임베딩 공간에서 어떻게 배치될까요?

# 추상화된 시각화
벡터 공간 상의 분포:

"러닝화 벗기" 클러스터 (초고밀도)
┌─────────────────┐
│ ●●●●●●●●●●●●●● │ ← 날짜/시간만 다른 수백 개 문서
│ ●●●●●●●●●●●●●● │ (의미적으로 거의 동일)
│ ●●●●●●●●●●●●●● │
└─────────────────┘

vs

"별자리 관측" 영역 (저밀도)
● ← "스카이뷰 앱" 문서
(적은 빈도, 멀리 떨어짐)

문제가 되는 시나리오

추상적 쿼리 + 고밀도 클러스터 = 재앙

# 쿼리: "7키로 러닝을 하다"
query_embedding = model.encode("7키로 러닝을 하다")

# 문제 1: "러닝" 키워드가 포함된 고밀도 클러스터가 탐색 시작점
# 문제 2: "7키로"라는 구체적 정보는 임베딩에서 약하게 표현됨
# 문제 3: n_results=100이면 고밀도 클러스터 내부만 탐색하고 종료

실제 데이터 예시:

[유사도 0.89] 러닝화를 벗는다 (9:25~9:33, 집 현관)
[유사도 0.88] 러닝화를 벗는다 (9:06~9:25, 집 현관)
[유사도 0.87] 러닝화 끈을 조인다 (8:30~9:00, 아파트 출입구)
[유사도 0.86] 러닝화를 벗는다 (19:56~20:00, 대전 현관)
...
[유사도 0.65] ← n_results=100 여기서 중단
---
[유사도 0.64] 스포츠워치 러닝 모드 7km 기록 저장 ← 정답!

왜 n_results=500에서는 성공했나?

# n_results=500 탐색 과정
1. "러닝" 고밀도 클러스터 탐색 (0~200번째)
2. 유사도가 낮아지면서 인접 클러스터로 확장
3. "운동 기록" 관련 클러스터 진입 (300~400번째)
4. "7km 기록" 문서 발견! (425번째)
5. 재정렬 후 상위권으로 부상

핵심: 큰 n_results는 여러 클러스터를 가로지르는 탐색을 가능하게 합니다.

해결 과정: 적절한 n_results 설정 전략

1. 데이터 밀도 분석

먼저 자신의 데이터 특성을 파악해야 합니다:

from sklearn.neighbors import NearestNeighbors
import numpy as np

def analyze_density(embeddings, sample_size=1000):
"""벡터 공간의 밀도 분석"""
sample_indices = np.random.choice(len(embeddings), sample_size)
sample_vectors = embeddings[sample_indices]

nbrs = NearestNeighbors(n_neighbors=100, metric='cosine').fit(embeddings)
distances, indices = nbrs.kneighbors(sample_vectors)

# 10번째, 50번째, 100번째 이웃까지의 평균 거리
print(f"10th neighbor avg distance: {distances[:, 9].mean():.4f}")
print(f"50th neighbor avg distance: {distances[:, 49].mean():.4f}")
print(f"100th neighbor avg distance: {distances[:, 99].mean():.4f}")

# 거리 증가율
growth_rate = distances[:, 99].mean() / distances[:, 9].mean()
print(f"Distance growth rate (10th->100th): {growth_rate:.2f}x")

if growth_rate < 1.5:
print("⚠️ HIGH DENSITY - 큰 n_results 필요")
elif growth_rate < 2.5:
print("⚡ MEDIUM DENSITY - 적절한 n_results 필요")
else:
print("✅ LOW DENSITY - 작은 n_results도 안전")

# 실행 결과 예시 (LGE 프로젝트)
# 10th neighbor: 0.1234
# 50th neighbor: 0.1456
# 100th neighbor: 0.1589
# Growth rate: 1.29x ← 매우 고밀도!

2. 쿼리 추상화 수준 평가

def estimate_query_abstraction(query):
"""쿼리의 추상화 정도 추정"""
concrete_markers = ["스카이뷰", "7km", "09:25", "평창 공원"]
abstract_markers = ["러닝", "별 보기", "운동", "휴식"]

concrete_score = sum(1 for m in concrete_markers if m in query)
abstract_score = sum(1 for m in abstract_markers if m in query)

if abstract_score > concrete_score:
return "ABSTRACT", 500 # 추상적이면 큰 n_results
else:
return "CONCRETE", 100 # 구체적이면 작은 n_results

# 예시
estimate_query_abstraction("스마트폰 앱으로 별 보기")
# → ("ABSTRACT", 500)

estimate_query_abstraction("평창 공원에서 스카이뷰 앱 실행")
# → ("CONCRETE", 100)

3. 동적 n_results + Reranking 전략

프로덕션 환경에서는 다음과 같은 파이프라인을 권장합니다:

from sentence_transformers import CrossEncoder

class AdaptiveRetriever:
def __init__(self, vectordb, reranker_model="cross-encoder/ms-marco-MiniLM-L-6-v2"):
self.vectordb = vectordb
self.reranker = CrossEncoder(reranker_model)

def search(self, query, final_k=10, safety_factor=10):
"""
안전한 검색 전략:
1. 넉넉한 후보 추출 (final_k * safety_factor)
2. Reranking으로 정확도 보정
3. 최종 k개 반환
"""
# Step 1: 넉넉한 초기 검색
initial_n = final_k * safety_factor # 예: 10 * 10 = 100
candidates = self.vectordb.query(
query_texts=[query],
n_results=initial_n
)

# Step 2: Cross-encoder로 재정렬
pairs = [[query, doc] for doc in candidates['documents'][0]]
rerank_scores = self.reranker.predict(pairs)

# Step 3: 상위 k개 추출
sorted_indices = np.argsort(rerank_scores)[::-1][:final_k]
final_results = [candidates['documents'][0][i] for i in sorted_indices]

return final_results

# 사용 예시
retriever = AdaptiveRetriever(chroma_collection)

# 안전한 검색 (내부적으로 100개 검색 후 10개로 rerank)
results = retriever.search("스마트폰 앱으로 별 보기", final_k=10)

4. A/B 테스트 기반 최적화

def find_optimal_n_results(queries, ground_truth, vectordb):
"""다양한 n_results 값 비교"""
test_n_values = [50, 100, 200, 500, 1000]
results = {}

for n in test_n_values:
recall_scores = []
for query, true_docs in zip(queries, ground_truth):
retrieved = vectordb.query(query_texts=[query], n_results=n)
retrieved_ids = set(retrieved['ids'][0][:10]) # 상위 10개만 평가
true_ids = set(true_docs)

recall = len(retrieved_ids & true_ids) / len(true_ids)
recall_scores.append(recall)

results[n] = {
'recall@10': np.mean(recall_scores),
'std': np.std(recall_scores)
}

return results

# 실행 결과 예시
# n=50: recall@10=0.62
# n=100: recall@10=0.71
# n=200: recall@10=0.85
# n=500: recall@10=0.94 ← 최적점
# n=1000: recall@10=0.95 (미미한 개선, 비용 증가)

결과 및 인사이트

정량적 개선

LGE 프로젝트에서 n_results 조정 후 측정한 결과:

Metricn=100n=500개선율
Recall@100.680.91+33.8%
MRR (Mean Reciprocal Rank)0.420.73+73.8%
정답 문서 발견율71%96%+25%p

의사결정 프레임워크

다음 flowchart를 통해 n_results를 결정하세요:

데이터 밀도 분석
├─ HIGH DENSITY → base_n = 500
├─ MEDIUM DENSITY → base_n = 200
└─ LOW DENSITY → base_n = 100

쿼리 특성 평가
├─ 추상적 쿼리 → base_n * 1.5
├─ 일반 쿼리 → base_n * 1.0
└─ 구체적 쿼리 → base_n * 0.5

성능 제약 확인
├─ 지연시간 중요 → Reranking 전략
└─ 정확도 우선 → 큰 n_results 유지

최종 n_results = min(계산값, 데이터 총량)

추가 최적화 팁

# 1. HNSW ef_search 파라미터 조정 (Chroma 예시)
collection = client.create_collection(
name="optimized_collection",
metadata={
"hnsw:space": "cosine",
"hnsw:search_ef": 500, # n_results와 연동
"hnsw:M": 32 # 그래프 연결성 증가
}
)

# 2. Hybrid Search로 보완
from rank_bm25 import BM25Okapi

class HybridRetriever:
def __init__(self, vectordb, documents):
self.vectordb = vectordb
tokenized_docs = [doc.split() for doc in documents]
self.bm25 = BM25Okapi(tokenized_docs)

def search(self, query, n_results=100, alpha=0.7):
# Vector search
vec_results = self.vectordb.query(query, n_results=n_results)
vec_scores = {id: score for id, score in
zip(vec_results['ids'][0], vec_results['distances'][0])}

# BM25 search
bm25_scores = self.bm25.get_scores(query.split())

# Hybrid ranking
final_scores = {}
for doc_id in set(vec_scores.keys()):
vec_score = vec_scores.get(doc_id, 0)
bm25_score = bm25_scores[doc_id] if doc_id < len(bm25_scores) else 0
final_scores[doc_id] = alpha * vec_score + (1-alpha) * bm25_score

return sorted(final_scores.items(), key=lambda x: x[1], reverse=True)

교훈 및 베스트 프랙티스

  1. n_results는 성능 튜닝의 핵심 레버: 단순한 출력 파라미터가 아니라 검색 품질을 결정하는 하이퍼파라미터
  2. "충분히 크게, 그 다음 줄이기": 초기 개발 시 넉넉한 n_results로 시작해 reranking으로 정제하는 전략이 안전
  3. 데이터 프로파일링 필수: 밀도 분석 없이 임의로 n_results를 정하면 재앙
  4. 쿼리 타입별 분기 처리: 추상적/구체적 쿼리에 따라 동적으로 n_results 조정
  5. 모니터링 지표 설정: Recall@k, MRR 등을 지속적으로 추적해 회귀 방지

References

MLflow 기술 검토(RAG 성능 실험 테스트베드 기능)

· 약 10분
김태한
AI Research Engineer, Brain Crew

TL;DR

MLflow는 전통적인 ML과 LLM 애플리케이션의 전체 생명주기를 관리할 수 있는 오픈소스 통합 플랫폼입니다. LangGraph 기반 RAG Agent 개발 시 Tracking으로 하이퍼파라미터와 메트릭을 관리하고, Tracing으로 복잡한 LLM 호출 흐름을 추적하며, Evaluation으로 LLM-as-a-Judge를 포함한 다양한 평가 지표를 자동화할 수 있습니다. OpenTelemetry 표준 준수로 기존 옵저버빌리티 도구와 쉽게 연동 가능하며, 완전 오픈소스로 온프레미스/클라우드 자체 호스팅이 가능합니다.

Key Takeaways

  • 계층적 실험 관리: Experiment > Run 구조로 RAG 시스템의 chunk_size, top_k, temperature 등 다양한 설정 조합을 체계적으로 추적하고 MLflow UI에서 시각적으로 비교할 수 있어, 최적 구성 탐색이 효율적입니다.

  • OpenTelemetry 표준 기반 Tracing: MLflow Tracing은 OpenTelemetry 호환으로 Grafana, Datadog, New Relic 등 기존 옵저버빌리티 도구와 즉시 연동 가능하며, Span 계층 구조로 복잡한 LLM 체인의 입출력과 토큰 사용량을 단계별로 추적할 수 있습니다.

  • LLM-as-a-Judge 평가 자동화: faithfulness, answer_relevance 등 주관적 품질 지표를 LLM으로 자동 평가하고, make_genai_metric()으로 커스텀 평가 기준을 프롬프트로 정의하여 평가 프로세스를 표준화할 수 있습니다.

  • 프롬프트 버전 관리: 프롬프트를 실험 변수 및 아티팩트로 저장하여 변경 사항을 추적하고, 여러 프롬프트 변형의 성능을 정량적으로 비교해 A/B 테스트를 수행할 수 있습니다.

  • 오픈소스 vs 상용 플랫폼 선택: MLflow는 Apache 2.0 오픈소스로 인프라 비용만 발생하고 전통적 ML과 LLM을 통합 관리 가능한 반면, LangSmith는 LangChain 전용 SaaS로 즉시 사용 가능하지만 벤더 종속성이 있습니다. 프로젝트 요구사항(자체 호스팅 필요성, 기존 도구 통합, 비용 구조)에 따라 선택해야 합니다.

상세 내용

배경: LLM 애플리케이션의 실험 관리 문제

LLM 기반 RAG Agent 개발은 전통적인 ML 모델과 다른 어려움이 있습니다. 문서 청크 크기, 임베딩 모델, 검색 개수(top_k), LLM temperature, 프롬프트 템플릿 등 수많은 하이퍼파라미터 조합을 실험해야 하며, LLM 출력의 비결정성과 주관성으로 인해 품질 평가가 어렵습니다. 또한 여러 컴포넌트(Retriever → LLM → Reranker)가 연결된 복잡한 파이프라인에서 병목 구간을 찾기 위해 각 단계의 실행 흐름을 추적해야 합니다.

MLflow는 이러한 문제를 해결하기 위해 전통적인 ML과 LLM 애플리케이션을 모두 지원하는 통합 플랫폼으로, Tracking, Tracing, Evaluation 기능을 제공합니다.

1. MLflow Tracking: 실험 파라미터와 메트릭 관리

핵심 구조

MLflow는 Experiment(실험 그룹) > Run(단일 실행) 계층 구조로 실험을 조직화합니다. 각 Run은 고유 ID로 식별되며 다음을 기록합니다:

  • Parameters: 모델 설정값 (불변)
  • Metrics: 정량적 성능 지표 (시간에 따라 변화 가능)
  • Artifacts: 파일 형태의 결과물 (모델, 설정 파일, 생성된 답변 등)
  • Tags: 메타데이터 (환경, 버전 등)

RAG 시스템 적용 사례

import mlflow

mlflow.set_experiment("rag-optimization")

with mlflow.start_run(run_name="chunk-512-topk-5"):
# 파라미터 기록
mlflow.log_param("chunk_size", 512)
mlflow.log_param("chunk_overlap", 50)
mlflow.log_param("top_k", 5)
mlflow.log_param("embedding_model", "text-embedding-3-small")
mlflow.log_param("llm_model", "gpt-4")
mlflow.log_param("temperature", 0.7)

# RAG 파이프라인 실행
result = rag_pipeline.run(query)

# 메트릭 기록
mlflow.log_metric("response_time", result.latency)
mlflow.log_metric("num_retrieved_docs", len(result.docs))
mlflow.log_metric("total_tokens", result.token_count)

# 아티팩트 저장
mlflow.log_text(result.answer, "generated_answer.txt")
mlflow.log_dict(result.config, "config.json")

의사결정 포인트: Parameters는 실험 시작 시 결정되는 불변 값으로, Metrics는 실행 중/후에 측정되는 성능 지표로 구분해야 합니다. 프롬프트 템플릿은 아티팩트로 저장하면 버전별 변경 사항을 명확히 추적할 수 있습니다.

UI 활용

MLflow UI에서 여러 Run의 메트릭을 테이블 또는 차트로 비교할 수 있습니다. 예를 들어 chunk_size와 response_time의 상관관계를 scatter plot으로 시각화하거나, top_k 값에 따른 답변 품질 변화를 확인할 수 있습니다. Backend 서버로 배포하면 REST API로 프로그래밍 방식 접근도 가능합니다.

2. MLflow Tracing: LLM 호출 흐름 추적

핵심 개념: Trace와 Span

MLflow Tracing은 OpenTelemetry 표준을 따르며 다음 구조를 사용합니다:

  • Trace: 전체 요청/세션의 실행 흐름
  • Span: Trace를 구성하는 개별 작업 단위 (시작/종료 시간, 입출력, 메타데이터 포함)
  • Span은 Parent-Child 계층 구조로 실행 순서를 표현

자동 Tracing vs 수동 Tracing

자동 Tracing (Autolog):

import mlflow

# LangChain 자동 추적 활성화
mlflow.langchain.autolog()

# 이후 LangChain 호출은 자동으로 Trace 생성
chain = create_retrieval_chain(retriever, llm)
result = chain.invoke({"input": "What is RAG?"})

자동 추적은 다음을 자동 수집합니다:

  • 각 컴포넌트(Retriever, LLM, Chain)별 Span
  • 입출력 데이터
  • 토큰 사용량 (LLM 호출 시)
  • 실행 시간

수동 Tracing (Decorator):

import mlflow

@mlflow.trace(name="document_preprocessing", span_type="PROCESSING")
def preprocess_documents(docs):
"""문서 전처리 로직"""
mlflow.set_span_attribute("num_docs", len(docs))
processed = [clean_text(doc) for doc in docs]
return processed

@mlflow.trace(name="rerank_documents", span_type="RETRIEVAL")
def rerank(query, docs):
"""검색 결과 재정렬"""
scores = compute_relevance_scores(query, docs)
mlflow.set_span_attribute("rerank_model", "cross-encoder-v2")
return sorted(zip(docs, scores), key=lambda x: x[1], reverse=True)

의사결정 근거: 자동 추적은 LangChain/LangGraph 기본 동작을 추적할 때 편리하지만, 비즈니스 로직이나 커스텀 컴포넌트는 수동 데코레이터로 명시적으로 Span을 추가해야 합니다. 특히 문서 전처리, 필터링, 재정렬 등 RAG 파이프라인의 중간 단계를 추적하려면 수동 Tracing이 필수입니다.

Trace 시각화

MLflow UI의 Traces 탭에서 다음을 확인할 수 있습니다:

  • Tree View: Span 간 계층 구조와 실행 순서
  • Timeline View: 각 Span의 시작/종료 시간과 병렬 실행 여부
  • Details Panel: Span별 입출력 데이터, 토큰 사용량, 커스텀 속성
  • Error Tracking: 예외 발생 Span 및 스택 트레이스

OpenTelemetry 통합

MLflow Tracing은 OpenTelemetry 표준을 준수하므로 기존 관찰성 도구와 쉽게 연동됩니다:

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# OpenTelemetry 설정
trace.set_tracer_provider(TracerProvider())
otlp_exporter = OTLPSpanExporter(endpoint="http://grafana-tempo:4317")
trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(otlp_exporter))

# MLflow Tracing은 자동으로 OpenTelemetry와 통합됨
mlflow.langchain.autolog()

이를 통해 Grafana, Datadog, New Relic 등에서 MLflow Trace를 시각화하고, 마이크로서비스 환경에서 분산 추적이 가능합니다.

3. MLflow Evaluation: LLM 출력 품질 평가

평가 워크플로우

MLflow Evaluation은 다음 단계로 구성됩니다:

  1. 평가 데이터셋 준비 (Pandas DataFrame)
  2. 모델 또는 예측 함수 정의
  3. 평가 지표(Scorer) 선택
  4. mlflow.evaluate() 실행
  5. 결과 분석 (MLflow UI 또는 API)

평가 데이터셋 구조

import pandas as pd

eval_data = pd.DataFrame({
"inputs": [
"What is the capital of France?",
"Explain quantum computing",
"How does photosynthesis work?"
],
"context": [
"France is a country in Europe. Paris is its capital.",
"Quantum computing uses quantum bits...",
"Plants use sunlight to produce energy..."
],
"ground_truth": [
"Paris",
"A computing paradigm using quantum mechanics",
"Process where plants convert light to chemical energy"
]
})

필수 컬럼:

  • inputs: 모델 입력
  • context: (선택) RAG의 검색 문서 등 추가 정보
  • ground_truth 또는 targets: (선택) 정답 레이블

Built-in Evaluators 활용

import mlflow

# LLM 출력 품질 평가
results = mlflow.evaluate(
model="openai:/gpt-4", # 또는 커스텀 함수
data=eval_data,
model_type="question-answering",
evaluators="default", # 기본 메트릭 세트
extra_metrics=[
mlflow.metrics.toxicity(),
mlflow.metrics.flesch_kincaid_grade_level(),
mlflow.metrics.answer_similarity(),
mlflow.metrics.faithfulness(model="openai:/gpt-4-turbo"),
mlflow.metrics.answer_relevance(model="openai:/gpt-4-turbo")
]
)

print(results.metrics)

주요 LLM 메트릭:

  • toxicity: 유해성 점수 (0~1, 낮을수록 좋음)
  • flesch_kincaid_grade_level: 가독성 (미국 학년 수준)
  • answer_similarity: 임베딩 기반 답변-정답 유사도
  • faithfulness: 답변이 제공된 context에 충실한지 (LLM-as-Judge)
  • answer_relevance: 답변이 질문과 관련 있는지 (LLM-as-Judge)

LLM-as-a-Judge 동작 원리

faithfulness, answer_relevance 같은 메트릭은 LLM을 판단자로 사용합니다:

  1. 평가용 프롬프트 생성 (질문 + 답변 + context)
  2. Judge LLM에 전송 (예: GPT-4)
  3. LLM이 평가 기준에 따라 점수 반환 (1~5 척도 등)
  4. 점수를 정규화하여 저장

의사결정 포인트: Judge 모델은 평가 대상 모델보다 강력해야 신뢰성이 높습니다. 예를 들어 GPT-3.5로 생성한 답변을 GPT-4로 평가하거나, 오픈소스 LLM 출력을 Claude Opus로 평가하는 방식이 권장됩니다.

Custom Evaluators 작성

함수 기반 메트릭:

from mlflow.metrics import make_metric

def contains_keyword(eval_df, builtin_metrics):
"""답변에 특정 키워드가 포함되어 있는지 체크"""
keywords = ["quantum", "photosynthesis", "capital"]
scores = []
for _, row in eval_df.iterrows():
answer = row["outputs"].lower()
score = 1.0 if any(kw in answer for kw in keywords) else 0.0
scores.append(score)
return scores

keyword_metric = make_metric(
eval_fn=contains_keyword,
greater_is_better=True,
name="keyword_presence"
)

mlflow.evaluate(
model=rag_model,
data=eval_data,
extra_metrics=[keyword_metric]
)

LLM-as-Judge 커스텀 메트릭:

from mlflow.metrics.genai import make_genai_metric

custom_faithfulness = make_genai_metric(
name="custom_faithfulness",
definition="답변이 제공된 문서에만 기반하고 외부 지식을 사용하지 않는지 평가",
grading_prompt="""
다음 기준으로 답변을 평가하세요:
- 5점: 모든 정보가 문서에서 직접 추출됨
- 4점: 대부분 문서 기반이지만 약간의 추론 포함
- 3점: 문서와 외부 지식이 혼합됨
- 2점: 주로 외부 지식 사용
- 1점: 문서와 무관한 정보

질문: {inputs}
문서: {context}
답변: {outputs}

점수만 반환하세요 (1~5).
""",
grading_context_columns=["context"],
examples=[
{
"inputs": "What is the capital?",
"outputs": "Paris is the capital.",
"context": "Paris is the capital of France.",
"score": 5,
"justification": "답변이 문서에서 직접 추출됨"
}
],
model="openai:/gpt-4-turbo",
parameters={"temperature": 0.0}
)

mlflow.evaluate(
model=rag_model,
data=eval_data,
extra_metrics=[custom_faithfulness]
)

의사결정 근거: 프로젝트별 도메인 특화 평가 기준(예: 의료 분야의 전문 용어 정확성, 금융 분야의 수치 정확성)은 커스텀 메트릭으로 정의해야 합니다. 프롬프트에 Few-shot 예시를 포함하면 Judge LLM의 평가 일관성이 크게 향상됩니다.

평가 결과 활용

# 평가 결과 출력
print(results.metrics)
# {'toxicity/v1/mean': 0.02, 'faithfulness/v1/mean': 4.5, ...}

# 행별 상세 결과
results_df = results.tables["eval_results_table"]
print(results_df[["inputs", "outputs", "faithfulness/v1/score"]])

# MLflow UI에서 시각화
# - 메트릭별 분포 히스토그램
# - 실패 사례 필터링
# - 여러 모델 간 평가 결과 비교

4. 추가 고급 기능

프롬프트 버전 관리

import mlflow

prompt_template_v1 = """
You are a helpful assistant. Answer the question based on the context.

Context: {context}
Question: {question}
Answer:
"""

with mlflow.start_run():
mlflow.log_param("prompt_version", "v1")
mlflow.log_text(prompt_template_v1, "prompt_template.txt")

# 프롬프트 성능 평가
results = evaluate_prompt(prompt_template_v1, test_data)
mlflow.log_metrics(results)

프롬프트를 파라미터와 아티팩트로 저장하여 변경 사항을 추적하고, 여러 버전의 성능을 비교할 수 있습니다.

Multi-Turn 대화 추적

import mlflow

session_id = "user-123-session-456"

with mlflow.start_run(run_name=f"conversation-{session_id}") as run:
mlflow.set_tag("session_id", session_id)

conversation_history = []
for turn, user_input in enumerate(user_inputs):
with mlflow.start_span(name=f"turn_{turn}") as span:
response = chatbot.reply(user_input, conversation_history)
conversation_history.append({"user": user_input, "bot": response})

mlflow.log_metric(f"turn_{turn}_latency", response.latency)

# 전체 대화 저장
mlflow.log_dict({"conversation": conversation_history}, "full_conversation.json")

session_id 태그로 대화를 그룹화하고, 턴별 Span으로 각 응답을 추적합니다.

OpenTelemetry 분산 추적

마이크로서비스 환경에서 여러 서비스에 걸친 요청을 추적:

# Service A (Gateway)
import mlflow
from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("gateway_request"):
with mlflow.start_span(name="preprocess_input"):
cleaned_input = preprocess(user_query)

# Service B 호출 (Trace context 자동 전파)
response = requests.post("http://rag-service/query", json={"input": cleaned_input})

OpenTelemetry context propagation으로 Service A와 Service B의 Span이 하나의 Trace로 연결됩니다.

5. LangSmith와의 비교

MLflow 선택이 유리한 경우:

  • 전통적인 ML 모델과 LLM을 동일 플랫폼에서 관리하고 싶을 때
  • 온프레미스 또는 프라이빗 클라우드에서 자체 호스팅이 필요할 때
  • 기존 옵저버빌리티 스택(Grafana, Prometheus)과 통합하고 싶을 때
  • 오픈소스 라이선스로 비용 절감이 중요할 때
  • Scikit-learn, PyTorch, TensorFlow 등 다양한 프레임워크를 함께 사용할 때

LangSmith 선택이 유리한 경우:

  • LangChain/LangGraph를 주요 프레임워크로 사용하고, 즉시 사용 가능한 SaaS가 필요할 때
  • Playground 기능으로 프롬프트를 즉시 테스트하고 수정하고 싶을 때
  • 사용자 피드백(thumbs up/down)을 손쉽게 수집하고 관리하고 싶을 때
  • 인프라 운영 리소스가 부족하고 관리형 서비스를 선호할 때

의사결정 체크리스트:

항목MLflowLangSmith
라이선스오픈소스 (Apache 2.0)상용 (Free tier 제한적)
호스팅자체 호스팅 필요클라우드 SaaS
프레임워크 지원범용 (Scikit-learn, PyTorch, LangChain 등)LangChain 전용
통합성OpenTelemetry 표준LangChain 에코시스템
UI/UX범용 실험 관리 UILangChain 특화 대화형 UI
비용인프라 비용만사용량 기반 과금

하이브리드 접근: 일부 팀은 개발 단계에서 LangSmith로 빠른 프로토타이핑을 하고, 프로덕션 배포는 MLflow로 전환하는 전략을 사용합니다.

실전 적용 시 주의사항

1. 민감 데이터 로깅 제어

LLM 입출력에 개인정보가 포함될 수 있으므로 로깅 전 필터링이 필요합니다:

import mlflow
from mlflow.utils.autologging_utils import disable_for_unsupported_versions

# 특정 필드 제외
mlflow.langchain.autolog(log_inputs=False, log_outputs=True)

# 또는 커스텀 필터 적용
def sanitize_output(output):
# 이메일, 전화번호 등 마스킹
return re.sub(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', '[EMAIL]', output)

2. 대규모 Trace 저장 비용

Tracing을 모든 요청에 활성화하면 스토리지 비용이 급증할 수 있습니다. 샘플링 전략 적용:

import random
import mlflow

# 10% 샘플링
if random.random() < 0.1:
mlflow.langchain.autolog()
else:
mlflow.langchain.autolog(disable=True)

3. Evaluation Judge 모델 비용

LLM-as-a-Judge 메트릭은 평가 데이터셋 크기에 비례해 API 호출 비용이 발생합니다. 캐싱 전략 활용:

from mlflow.metrics.genai import make_genai_metric

custom_metric = make_genai_metric(
name="faithfulness",
# ...
model="openai:/gpt-4-turbo",
parameters={
"temperature": 0.0, # 결정적 출력으로 캐싱 효율 향상
"seed": 42
}
)

4. MLflow Server 고가용성

프로덕션 환경에서는 MLflow Tracking Server를 고가용성으로 구성:

  • Backend Store: PostgreSQL/MySQL (복제 구성)
  • Artifact Store: S3/GCS (자동 복제)
  • Load Balancer: 여러 MLflow 서버 인스턴스 앞단 배치
  • 모니터링: Prometheus + Grafana로 서버 상태 추적

References

LLM이 가장 잘 이해하는 Table Format에 대한 평가실험

· 약 8분
김성연
AI Research Engineer, Brain Crew

TL;DR

재무제표 데이터를 LLM에 전달할 때 데이터 포맷에 따라 성능과 비용이 크게 달라집니다. 11가지 포맷을 비교한 결과, TSV(tab-separated) 포맷이 정확도 100%, 최소 토큰 사용(7,192개), 최단 응답시간(8.24초)으로 모든 지표에서 최고 성능을 보였습니다. 반면 DICT와 XML은 프로그래밍 문법의 메타 문자로 인해 토큰을 2배 이상 낭비했고, STRING 포맷은 정확도가 75%로 떨어졌습니다. 실무에서는 TSV가 이론적 최적이지만, Markdown Key-Value가 가독성과 효율성의 균형점으로 더 실용적일 수 있습니다.

Key Takeaways

  • 간결한 포맷이 LLM 성능과 비용 모두 우수: TSV는 XML 대비 토큰을 57% 절감하고 응답속도를 3배 향상시켰습니다. 메타 문자를 최소화하는 것이 핵심입니다.
  • 구조화된 포맷이 필수: STRING 같은 비구조화 포맷은 정확도가 25% 하락합니다. 테이블 형태의 명확한 구조가 LLM의 이해도를 크게 높입니다.
  • 프로그래밍 문법은 토큰 낭비: DICT, XML처럼 {, }, ' 등 메타 문자가 많은 포맷은 실제 데이터 대비 구조 표현에 토큰을 과다 소모합니다. JSON이나 TSV 같은 간결한 대안을 선택하세요.
  • 가독성과 효율성의 트레이드오프 고려: 이론적으로 TSV가 최적이지만, 실무에서는 Markdown Key-Value처럼 사람과 기계 모두 읽기 쉬운 포맷이 유지보수와 확장성 면에서 더 나을 수 있습니다.
  • 포맷 선택은 비용에 직결: 대규모 RAG 시스템에서 포맷 최적화만으로 토큰 비용을 50% 이상 절감할 수 있습니다. 초기 설계 단계에서 포맷을 신중히 선택하세요.

상세 내용

배경: 왜 테이블 포맷이 중요한가?

많은 RAG(Retrieval-Augmented Generation) 파이프라인에서 재무제표, 스프레드시트, 데이터베이스 쿼리 결과 등 테이블 형태의 데이터를 LLM에 전달해야 합니다. 하지만 같은 데이터라도 어떤 포맷으로 인코딩하느냐에 따라 LLM의 이해도, 토큰 사용량, 응답 속도가 크게 달라집니다.

예를 들어, Elasticsearch에서 추출한 재무제표 데이터를 LLM에 전달할 때:

  • JSON으로 보낼 것인가?
  • CSV나 TSV로 보낼 것인가?
  • Markdown 테이블이나 HTML을 사용할 것인가?

이 선택은 시스템 정확도와 운영 비용에 직접적인 영향을 미칩니다. IBK Capital 프로젝트에서는 이 질문에 답하기 위해 체계적인 실험을 수행했습니다.

실험 설계

평가 대상 포맷 (11가지)

  1. TSV (tab-separated values)
  2. JSON
  3. CSV
  4. Markdown Table
  5. HTML Table
  6. Markdown Key-Value
  7. DICT (Python dictionary list)
  8. LaTeX
  9. XML
  10. NumPy array
  11. STRING (자연어 형식)

평가 지표

  • 정확도: LLM이 데이터 기반 질문에 정확히 답변한 비율 (0-1)
  • 토큰 사용량: 프롬프트와 응답에 소요된 총 토큰 수
  • 응답 속도: 질의응답 완료까지 걸린 시간 (초)

실험 환경

  • 모델: AWS Bedrock Claude Sonnet 4.5
  • 데이터: Elasticsearch에서 추출한 실제 재무제표 데이터 (매출액, EBIT, EBITDA 등 약 40개 항목)
  • 질문 형식: "2020년 12월의 매출액은 얼마인가요?" 같은 특정 값 조회

종합 점수 계산 각 지표를 정규화(0-1)한 후 가중 평균:

  • 정확도: 0.5
  • 토큰 효율: 0.3
  • 속도: 0.2

실험 결과: TSV의 압도적 우위

종합 순위

순위포맷종합점수정확도토큰수지연시간(초)
1TSV1.00001.007,1928.24
2JSON0.89731.009,94110.25
3HTML0.87681.0010,22911.59
4Markdown0.85051.009,80516.17
5Markdown KV0.81761.0011,07515.41
..................
10XML0.55231.0016,85225.37
11STRING0.37730.759,18315.30

핵심 발견

  • TSV를 제외한 대부분 구조화 포맷은 정확도 1.00 달성
  • STRING 포맷만 정확도 0.75로 하락 → 구조화가 필수
  • 토큰 사용량 차이: 최소(TSV 7,192) vs 최대(XML 16,852) = 2.3배
  • 응답 속도 차이: 최소(TSV 8.24초) vs 최대(DICT 31.44초) = 3.8배

왜 TSV가 최고 성능을 보이는가?

동일한 재무제표 데이터를 세 가지 포맷으로 표현한 예시로 분석해보겠습니다.

TSV (7,192 토큰)

재무제표	2019/12	2020/12	2021/12	2022/12	2022/09	2023/09
매출액 594,159 591,566 578,744 606,454 473,909 385,849
EBIT 5,148 52,063 13,045 3,755 10,252 -16,558

특징

  • 구분자: 탭 문자 하나만 사용
  • 메타 문자: 거의 없음 (줄바꿈뿐)
  • 정보 밀도: 매우 높음 (실제 데이터에 집중)

Markdown Key-Value (11,075 토큰)

## Record 1

재무제표: 매출액
2019/12: 594,159
2020/12: 591,566
2021/12: 578,744
...

특징

  • 구조 요소: ## Record N, 키-값 구분 :
  • 가독성: 레코드별 명확한 구분
  • 토큰 증가 원인: 마크다운 헤더와 구분자

DICT (14,436 토큰 - TSV의 2배)

[{'재무제표': '매출액', '2019/12': '594,159', '2020/12': '591,566', ...}, 
{'재무제표': 'EBIT', '2019/12': '5,148', '2020/12': '52,063', ...}]

특징

  • 메타 문자 과다: {, }, [, ], ', :, , 반복
  • 키 중복: 각 레코드마다 '재무제표': 반복
  • 토큰 낭비: 프로그래밍 문법에 토큰 소모

토큰 차이 분석

요소TSVMarkdown KVDICT
레코드 구분줄바꿈## Record N}, {
키-값 구분:': '
데이터 구분줄바꿈', '
컨테이너없음코드블록[, ]

TSV가 최소 토큰을 사용하는 이유:

  1. 불필요한 메타 문자 제거: DICT의 {, }, ' 같은 문법 요소 없음
  2. 키 중복 없음: 헤더에 한 번만 키 정의
  3. 구분자 최소화: 탭 하나로 열 구분 (CSV는 쉼표 + 따옴표 필요)

왜 Markdown Key-Value가 DICT보다 나은가?

실험 결과 Markdown Key-Value(11,075 토큰)가 DICT(14,436 토큰)보다 23% 효율적입니다.

DICT의 문제점

# 각 레코드마다 반복되는 메타 문자
{'재무제표': '매출액', '2019/12': '594,159', ...} # { } ' ' : , 모두 토큰 소모
{'재무제표': 'EBIT', '2019/12': '5,148', ...} # 키 이름 '재무제표' 반복

Markdown Key-Value의 장점

## Record 1
재무제표: 매출액
2019/12: 594,159
  1. 간결한 구분자: : 하나로 키-값 구분
  2. 키 중복 최소화: 레코드 헤더로 한 번만 정의
  3. LLM 친화적: 마크다운은 LLM 학습 데이터에 흔한 형식
  4. 가독성: 사람이 읽고 디버깅하기 쉬움

실무 의사결정: TSV vs Markdown Key-Value

이론적 최적: TSV

  • 토큰 최소 (7,192)
  • 속도 최고 (8.24초)
  • 비용 최저

실무 선택: Markdown Key-Value

프로덕션 환경에서 Markdown Key-Value를 선택한 이유:

  1. 가독성과 유지보수성

    # TSV - 기계 최적화
    항목 2020 2021 2022
    매출 100 110 120

    # Markdown KV - 사람과 기계 모두 고려
    ## 2020년 실적
    매출: 100
    영업이익: 10
  2. 디버깅 용이성

    • 로그 파일에서 데이터 확인 시 TSV는 읽기 어려움
    • Markdown은 구조가 명확해 문제 파악 빠름
  3. 확장성

    • 추가 메타데이터 삽입 용이
    • 중첩 구조 표현 가능
    • 주석 추가 가능
  4. 성능 트레이드오프 합리성

    • TSV 대비 54% 토큰 증가 (7,192 → 11,075)
    • 하지만 DICT 대비 23% 절감 (14,436 → 11,075)
    • 실용성 고려 시 충분히 효율적

코드 예시: 포맷 변환 함수

def convert_to_markdown_kv(df, record_name="Record"):
"""DataFrame을 Markdown Key-Value 형식으로 변환"""
result = []
for idx, row in df.iterrows():
result.append(f"## {record_name} {idx + 1}\n")
result.append("```")
for col, value in row.items():
result.append(f"{col}: {value}")
result.append("```\n")
return "\n".join(result)

def convert_to_tsv(df):
"""DataFrame을 TSV 형식으로 변환"""
return df.to_csv(sep='\t', index=False)

# 사용 예시
import pandas as pd

df = pd.DataFrame({
'재무제표': ['매출액', 'EBIT'],
'2020/12': [591566, 52063],
'2021/12': [578744, 13045]
})

# 비용 최적화가 중요한 경우
tsv_format = convert_to_tsv(df)

# 가독성과 유지보수가 중요한 경우
markdown_format = convert_to_markdown_kv(df)

실무 적용 가이드

시나리오별 포맷 선택

시나리오추천 포맷이유
대용량 배치 처리TSV비용과 속도 최우선
프로덕션 APIMarkdown KV가독성과 효율 균형
디버깅/개발Markdown KV사람이 읽기 쉬움
레거시 시스템 연동JSON표준 호환성
실시간 응답TSV최저 지연시간

비용 절감 계산 예시

# GPT-4 기준 (input $2.50/1M tokens)
COST_PER_1M_TOKENS = 2.50

# 일일 100만 건 처리 시
DAILY_QUERIES = 1_000_000

# 포맷별 토큰 사용량
tokens_xml = 16_852
tokens_tsv = 7_192

# 비용 계산
cost_xml = (tokens_xml * DAILY_QUERIES / 1_000_000) * COST_PER_1M_TOKENS
cost_tsv = (tokens_tsv * DAILY_QUERIES / 1_000_000) * COST_PER_1M_TOKENS

print(f"XML 사용 시: ${cost_xml:,.2f}/day") # $42.13/day
print(f"TSV 사용 시: ${cost_tsv:,.2f}/day") # $17.98/day
print(f"절감액: ${cost_xml - cost_tsv:,.2f}/day") # $24.15/day (57% 절감)
print(f"연간 절감: ${(cost_xml - cost_tsv) * 365:,.2f}") # $8,815/year

피해야 할 포맷과 이유

  1. STRING (자연어)

    • 정확도 75% → 25% 오류율은 실무에서 치명적
    • 구조 없어 파싱 불안정
  2. XML

    • 토큰 2.3배 낭비 (16,852 vs 7,192)
    • 태그 중복으로 비효율적
  3. DICT

    • 프로그래밍 문법 메타 문자로 토큰 과다 소모
    • JSON이 더 표준적이고 효율적

추가 고려사항

대용량 데이터 처리

1000개 이상 레코드 처리 시:

  • TSV/CSV는 100줄마다 헤더 반복 권장
  • Markdown은 청크 단위로 분할
  • JSON은 스트리밍 파싱 고려
def chunk_tsv_with_headers(df, chunk_size=100):
"""TSV를 헤더 반복하며 청크로 분할"""
chunks = []
for i in range(0, len(df), chunk_size):
chunk = df.iloc[i:i+chunk_size]
chunks.append(chunk.to_csv(sep='\t', index=False))
return chunks

다른 연구 결과와의 비교

improvingagents.com의 연구(1000개 직원 레코드, 8개 속성)에서도 유사한 결과:

  • Markdown Key-Value: 60.7% 정확도
  • INI: 55.7%
  • YAML: 54.5%
  • Markdown Table: 51.8%

차이점:

  • 본 실험은 재무 데이터로 정확도가 더 높음 (대부분 100%)
  • 도메인 특성상 테이블 구조가 더 명확해 LLM이 잘 이해

결론 및 제언

핵심 요약

  1. TSV가 이론적 최적: 토큰 57% 절감, 속도 3.8배 향상
  2. Markdown Key-Value가 실무 최적: 효율성과 실용성의 균형
  3. 간결함이 핵심: 메타 문자 최소화가 성능과 비용에 직결
  4. 구조화는 필수: STRING 같은 비구조화 포맷은 정확도 25% 하락

실무 적용 체크리스트

  • 비용이 최우선이면 TSV 사용
  • 팀 협업과 유지보수 고려 시 Markdown Key-Value
  • STRING, XML, DICT는 피하기
  • 대용량 데이터는 청크 분할 및 헤더 반복
  • 포맷 변경만으로 연간 수천~수만 달러 절감 가능

향후 연구 방향

  • 다양한 LLM 모델(GPT-4, Claude, Llama 등)에서 재현성 검증
  • 비정형 데이터(텍스트 포함 테이블)에서의 포맷 영향 분석
  • 멀티모달 환경(이미지 + 테이블)에서의 최적 포맷 연구

References