kakao-analyzer 1.0.2

Comprehensive analysis tool for KakaoTalk chat exports

🔥 카카오톡 대화 분석기 (Kakao Talk Analyzer)

카카오톡 대화 내보내기 CSV 파일을 종합적으로 분석하는 차세대 AI 기반 올인원 도구

pip install kakao-analyzer

🎯 카카오톡의 특성을 완벽하게 이해하는 스마트 분석기

• 연속 메시지 자동 그룹핑 (1분 이내 메시지 통합)
• 한국어 채팅 패턴 인식 (ㅋㅋ, ㅠㅠ, 이모티콘 등)
• 시스템 메시지 자동 필터링 (삭제된 메시지, 투표, 정산 등)
• 실제 대화만 분석하여 더 정확한 인사이트 제공

🚀 주요 기능

🎯 카카오톡 특화 기능 ⭐ NEW!

• 스마트 메시지 그룹핑: 1분 이내 연속 메시지를 하나로 통합하여 실제 의도 파악
• 한국어 채팅 패턴 분석: ㅋㅋ, ㅎㅎ, ㅠㅠ, ㅇㅋ 등 한국인의 채팅 습관 인식
• 시스템 메시지 필터링: 삭제된 메시지, 투표, 정산, 입장/퇴장 알림 자동 제거
• 멘션 분석: @ 기능을 이용한 사용자 언급 패턴과 네트워크 분석
• 감정 표현 분석: 웃음, 슬픔, 동의 표현 등의 감정 패턴 추적

📊 기본 통계 분석

• 사용자별 활동 통계: 메시지 수, 참여율, 일평균 활동량
• 시간적 패턴 분석: 시간대별, 요일별, 월별 활동 분포
• 단어 빈도 분석: 한국어 형태소 분석 및 키워드 추출
• 메시지별 단어 수 통계: 원본 및 필터링된 단어 수 분석 (평균, 중간값, 최대값)
• 이모티콘/이모지 사용 통계: 반응 패턴 분석

💬 대화 역학 분석

• 대화 턴 분석: 자동 대화 세션 구분
• 주제 전환 탐지: 임베딩 기반 주제 변화 감지
• 참여자 패턴: 대화 시작자, 응답자 분석 (시작 횟수 순으로 정렬)
• 상호작용 분석: 사용자 간 소통 패턴
• 멘션 네트워크 분석: @ 멘션을 통한 사용자 간 언급 관계 및 상호 멘션 분석

🎯 재미있는 지표

• 참여 불평등: 지니 계수를 통한 발언권 분석
• 답장 속도: 반응 시간 통계 및 분포
• 활동 연속성: 연속 메시지 및 활동일 분석
• 심야 채팅: 밤샘 대화 패턴 분석

🔍 고급 분석

• 임베딩 기반 주제 분석: 의미론적 유사도를 통한 주제 세그먼트
• SPLADE 하이브리드 검색: Dense + Sparse 벡터를 활용한 대화 검색
• 시계열 분석: 시간에 따른 대화 패턴 변화
• 감정 분석: 대화 분위기와 감정 패턴 추적
• 스마트 토픽 클러스터링: 고급 주제 분류 및 테마 분석
• 대화 리듬 분석: 응답 패턴과 시간적 리듬 분석
• 대규모 데이터셋 최적화: 지능형 청킹과 메모리 효율성

📈 시각화 (개선됨!)

• 활동 히트맵: 시간대 × 요일 활동 분포
• 일별 타임라인: 메시지 수 추이 그래프
• 주제 타임라인: 주제 세그먼트 시각화 (겹침 문제 해결)
• 워드클라우드: 한국어 폰트 지원으로 깨짐 현상 해결
• 사용자 활동 차트: 많은 사용자도 깔끔하게 표시 (겹침 문제 해결)

🛠️ 설치 및 실행

📦 PyPI를 통한 간편 설치 (권장)

# 기본 설치
pip install kakao-analyzer

# 전체 기능 설치 (AI 모델 포함)
pip install kakao-analyzer[full]

# 개발 도구 포함 설치
pip install kakao-analyzer[dev]

설치 후 바로 사용 가능:

kakao-analyzer --input your_chat.csv

💻 개발자용 설치

개발이나 커스터마이징을 원한다면:

# 저장소 클론
git clone https://github.com/xistoh162108/kakaotalk_analyzer.git
cd kakaotalk_analyzer

# 의존성 설치
pip install -r requirements.txt

# 개발 모드로 설치
pip install -e .

📋 요구사항

• Python: 3.8 이상
• 운영체제: Windows, macOS, Linux 모두 지원
• 메모리: 최소 4GB RAM (대용량 데이터는 8GB+ 권장)

🚀 빠른 시작

1단계: 설치

pip install kakao-analyzer

2단계: 카카오톡 대화 내보내기

1. 카카오톡 앱에서 분석하고 싶은 대화방 열기
2. ☰ 메뉴 → 채팅방 설정 → 대화 내용 내보내기
3. 텍스트 파일(.txt) 선택하여 내보내기
4. 내보낸 파일을 CSV 형식으로 변환 (또는 직접 CSV로 준비)

3단계: 분석 실행

# 기본 분석
kakao-analyzer --input your_chat.csv

# 고급 AI 분석 포함 (권장)
kakao-analyzer --input your_chat.csv --use-splade --use-ollama

✨ 사용법

# 기본 분석 (가장 간단)
kakao-analyzer --input chat.csv

# 출력 디렉토리 지정
kakao-analyzer --input chat.csv --outdir my_analysis

# 도움말 보기
kakao-analyzer --help

🛠️ 고급 옵션

kakao-analyzer --input INPUT [옵션들]

필수 옵션:
  --input INPUT                입력 CSV 파일 경로

분석 옵션:
  --window-minutes MINUTES     대화 턴 구분 시간 (기본값: 30분)
  --topic-window-size SIZE     주제 분석 윈도우 크기 (기본값: 15)
  --similarity-threshold FLOAT 유사도 임계값 (기본값: 0.3)
  --batch-size SIZE            임베딩 배치 크기 (기본값: 32)
  --max-workers WORKERS        최대 병렬 작업 수 (기본값: 4)

AI 모델 옵션:
  --use-ollama                 Ollama 임베딩 사용 (로컬)
  --model-name MODEL           Ollama 모델명 (기본값: gpt-oss:20b)
  --embed-model MODEL          임베딩 모델명 (기본값: bge-m3)
  --use-splade                 SPLADE 희소 검색 활성화

대규모 데이터 옵션:
  --subset-size SIZE           테스트용 부분집합 크기  
  --subset-strategy STRATEGY   부분집합 전략 (balanced/temporal/diverse/random)

카카오톡 특화 옵션:
  --disable-message-grouping   연속 메시지 그룹핑 비활성화 (비추천)
  --group-window-seconds N     메시지 그룹핑 시간 창 (기본값: 60초)

출력 옵션:
  --outdir DIRECTORY           출력 디렉토리
  --figure-dpi DPI             그래프 해상도 (기본값: 300)
  --log-level LEVEL            로그 레벨 (DEBUG/INFO/WARNING/ERROR)
  --quiet                      콘솔 출력 억제
  --skip-viz                   시각화 생성 건너뛰기

💡 사용 예제

# 🌟 기본 분석 (추천)
kakao-analyzer --input chat.csv

# 🤖 AI 기능 전체 활용
kakao-analyzer --input chat.csv --use-splade --use-ollama --model-name "gpt-oss:20b"

# 📊 특정 디렉토리에 결과 저장
kakao-analyzer --input chat.csv --outdir my_results

# ⚡ 대용량 데이터 빠른 테스트
kakao-analyzer --input big_chat.csv --subset-size 1000 --subset-strategy balanced

# 🔧 세밀한 설정 조정
kakao-analyzer --input chat.csv --topic-window-size 20 --similarity-threshold 0.4

# 🎨 고해상도 그래프 생성
kakao-analyzer --input chat.csv --figure-dpi 600

# 🔇 조용한 실행 (CI/CD용)
kakao-analyzer --input chat.csv --quiet --skip-viz --log-level ERROR

📁 출력 구조

분석 완료 후 다음과 같은 구조로 결과가 생성됩니다:

output_directory/
├── summary/                    # 요약 정보
│   ├── analysis_summary.json   # 전체 분석 요약
│   └── processed_messages.csv  # 처리된 메시지 데이터
├── basics/                     # 기본 통계
│   └── basic_statistics.json   # 상세 통계 데이터
├── context/                    # 맥락 분석
│   ├── topic_segments.json     # 주제 세그먼트 데이터
│   ├── topic_segments.csv      # 주제 세그먼트 테이블
│   ├── mood_analysis.json      # 감정 및 분위기 분석
│   ├── advanced_topics.json    # 고급 주제 클러스터링
│   ├── rhythm_analysis.json    # 대화 리듬 분석
│   ├── mention_analysis.json   # 멘션 패턴 및 네트워크 분석
│   ├── hybrid_index.meta.json  # 검색 인덱스 (SPLADE)
│   └── splade_scores.parquet   # 희소 벡터 데이터 (SPLADE)
├── fun/                        # 재미 지표
│   └── fun_metrics.json        # 참여 불평등, 답장 속도 등
├── figures/                    # 시각화
│   ├── heatmap_hour_weekday.png
│   ├── timeseries_daily.png
│   ├── topic_timeline.png
│   ├── wordcloud_global.png
│   ├── user_activity_distribution.png
│   └── reply_latency_distribution.png
├── reports/                    # 리포트
│   ├── analysis_report.md      # 종합 분석 리포트
│   └── qa_test_report.md       # 품질 보증 리포트 (테스트시)
└── logs/                       # 로그
    ├── pipeline_metadata.json  # 실행 메타데이터
    └── analyzer.log            # 분석 로그

📋 입력 데이터 형식

카카오톡에서 내보낸 CSV 파일이 필요합니다. 지원하는 컬럼 형식:

필수 컬럼

• user 또는 User 또는 사용자: 메시지 작성자
• message 또는 Message 또는 메시지: 메시지 내용
• datetime 또는 Date 또는 시간: 메시지 시간

예제 CSV 형식

user,message,datetime
김민수,안녕하세요!,2024-01-01 10:00:00
이지은,네 안녕하세요! ㅎㅎ,2024-01-01 10:01:00
박서준,오늘 날씨 좋네요,2024-01-01 10:02:00

🧪 테스트

기본 기능 테스트

# 기본 기능 테스트 (의존성 없이)
python simple_test.py

# 전체 테스트 스위트 (의존성 설치 후)
python test_runner.py

테스트 데이터 생성

# 1000개 메시지 테스트 데이터 생성
python test_runner.py --generate-data

🔧 고급 설정

🚀 GPU 가속 지원 (NEW!)

• 자동 GPU 인식: CUDA가 설치된 시스템에서 자동으로 GPU 사용
• 메모리 최적화: GPU 메모리의 75%까지 자동 제한하여 안정성 보장
• 모델 자동 이관: 임베딩 및 SPLADE 모델을 GPU로 자동 로드
• 배치 크기 최적화: GPU 메모리에 따라 배치 크기 자동 조정

GPU 메모리별 최적화

• 12GB+ (RTX 3080Ti/4080 이상): 배치 크기 128, Half precision
• 8-12GB (RTX 3070/4070): 배치 크기 64, Half precision
• 4-8GB (GTX 1660/RTX 3060): 배치 크기 48, Mixed precision
• 4GB 미만: CPU 모드로 자동 전환

임베딩 모델

• 기본값: Mock 임베딩 (외부 의존성 없음)
• 고급 옵션: SentenceTransformer 모델 (sentence-transformers 설치 필요)
• GPU 가속: CUDA 지원 시 자동으로 GPU에서 실행

SPLADE 하이브리드 검색

• 활성화: --use-splade 옵션 사용
• 기능: Dense + Sparse 벡터를 결합한 고급 검색
• 용도: 특정 주제나 키워드로 대화 검색
• GPU 가속: Half precision으로 GPU에서 고속 처리

Ollama 연동 (한국어 모델 완전 지원)

• 활성화: --use-ollama 옵션 사용
• 요구사항: Ollama 서버 실행 중이어야 함
• 기본 모델: gpt-oss:20b (추천)

🇰🇷 지원 한국어 모델들

모델명	크기	특징	사용법
gpt-oss:20b	20B	범용 한국어 모델 (기본값)	--model-name "gpt-oss:20b"
gpt-oss:40b	40B	고성능 한국어 모델	--model-name "gpt-oss:40b"
llama3-ko	8B	LLaMA3 한국어 파인튜닝	--model-name "llama3-ko"
aya:8b	8B	다국어 지원 (한국어 포함)	--model-name "aya:8b"
gemma2-ko	9B	Google Gemma2 한국어 버전	--model-name "gemma2-ko"
solar-ko	10.7B	Upstage SOLAR 한국어 모델	--model-name "solar-ko"
eeve-korean	10.8B	한국 전용 대화 모델	--model-name "eeve-korean"
beomi-ko	13B	한국어 특화 고성능 모델	--model-name "beomi-ko"

🚀 모델 설치 및 사용법

# Ollama 설치 (한 번만)
curl -fsSL https://ollama.ai/install.sh | sh

# 한국어 모델 다운로드 (예: gpt-oss:20b)
ollama pull gpt-oss:20b

# 분석 실행
kakao-analyzer --input chat.csv --use-ollama --model-name "gpt-oss:20b"

📊 분석 결과 해석

참여 불평등 (지니 계수)

• 0.0-0.3: 매우 균등한 참여
• 0.3-0.5: 약간 불균등
• 0.5-0.7: 불균등한 참여
• 0.7-1.0: 매우 불균등 (소수가 대화 주도)

멘션 분석 지표

• 상호 멘션 관계: 서로 멘션하는 사용자 쌍의 수와 빈도
• 멘션 네트워크 밀도: 전체 가능한 멘션 관계 대비 실제 멘션 관계 비율
• 멘션 목적 분류: 질문, 부탁/요청, 인사, 긴급, 토론/의견 등으로 자동 분류

답장 속도 카테고리

• 즉석 답장: 1분 이내
• 빠른 답장: 1-5분
• 보통 답장: 5-30분
• 느린 답장: 30분 이상

주제 세그먼트

• 임베딩 유사도 기반으로 자동 감지
• 각 세그먼트별 키워드, 참여자, 지속시간 제공
• 주제 전환 패턴 분석

🎨 시각화 가이드

모든 그래프는 한국어 폰트를 지원하며, 다음 형식으로 저장됩니다:

• 형식: PNG (기본값)
• 해상도: 300 DPI (기본값)
• 크기: 자동 조정

주요 시각화

1. 활동 히트맵: 언제 가장 활발한지 한눈에 파악
2. 일별 타임라인: 시간에 따른 대화량 변화
3. 주제 타임라인: 대화 주제의 시간적 흐름
4. 워드클라우드: 자주 사용된 단어들
5. 사용자 활동: 각 참여자의 기여도
6. 답장 속도: 소통 스타일 분석

💡 활용 사례

개인/그룹 분석

• 친구들과의 대화 패턴 분석
• 가족 단톡방 활동 분석
• 동호회/커뮤니티 소통 패턴

연구 목적

• 디지털 커뮤니케이션 연구
• 사회 네트워크 분석
• 언어학 연구 데이터

비즈니스 분석

• 팀 커뮤니케이션 효율성
• 고객 소통 패턴
• 커뮤니티 관리 인사이트

🛡️ 개인정보 보호

• 모든 분석은 로컬에서 수행됩니다
• 데이터는 외부로 전송되지 않습니다
• 결과 파일에는 원본 메시지가 포함될 수 있으니 공유 시 주의하세요
• 개인 식별 정보가 포함된 분석 결과는 신중히 관리하세요

🐛 문제 해결

일반적인 문제

1. 모듈을 찾을 수 없음

pip install -r requirements.txt

2. 한국어 폰트 문제

• macOS: Apple Gothic 자동 사용
• Windows: Malgun Gothic 자동 사용
• Linux: Noto Sans CJK KR 설치 권장

3. 메모리 부족

• 큰 데이터셋의 경우 --topic-window-size 값을 줄여보세요
• 임베딩 비활성화: 설정에서 use_embeddings = False

4. CSV 인코딩 문제

• 자동 인코딩 감지 기능 내장
• 수동 지정이 필요한 경우 파일을 UTF-8로 변환

로그 확인

# 상세 로그로 실행
kakao-analyzer --input chat.csv --log-level DEBUG

# 로그 파일 확인 (기본 출력 디렉토리)
cat chat_analysis/logs/run.log

📈 성능 최적화

대용량 데이터 처리

• 배치 크기 조정: 설정에서 batch_size 변경
• 임베딩 비활성화: 기본 분석만 필요한 경우
• 윈도우 크기 감소: 메모리 사용량 절약

속도 향상

• 병렬 처리: 가능한 곳에서 자동 적용
• 캐싱: 중간 결과 자동 저장
• 최적화된 알고리즘: 대용량 데이터 대응

🚧 로드맵

현재 이 프로젝트는 지속적으로 개발 중이며, 다음과 같은 기능들이 추가될 예정입니다:

🔮 예정된 기능들

• 🌐 다중 메신저 지원: 라인, 텔레그램, 디스코드 등 다른 메신저 플랫폼 지원
• 📱 웹 인터페이스: 브라우저에서 사용할 수 있는 직관적인 UI
• ⚡ 실시간 분석: 대화 진행 중 실시간 패턴 분석
• 🤖 고급 AI 기능: GPT-4 통합, 더 정교한 감정 분석
• 📊 대시보드: 실시간 모니터링 및 알림 시스템
• 🔍 검색 엔진: 대화 내용 고급 검색 및 필터링
• 📈 트렌드 분석: 시간에 따른 대화 패턴 변화 추적
• 🎨 테마 커스터마이제이션: 시각화 스타일 및 색상 테마 선택
• 💾 클라우드 백업: 분석 결과 자동 백업 및 동기화
• 📧 리포트 자동 발송: 정기적인 분석 리포트 이메일 발송

🎯 다음 버전 (v1.1.0) 예정 기능

• 음성 메시지 길이 분석
• 파일 공유 패턴 분석
• 대화방 참여자 변화 추적
• 감정 변화 시계열 분석
• 키워드 알림 시스템

👨‍💻 개발자

🎓 주 개발자

• xistoh162108 (KAIST)
  • 📧 이메일: [e-mail]
  • 🏫 소속: 한국과학기술원 (KAIST)
  • 🔗 GitHub: @xistoh162108

🤖 AI 협력 개발

• Claude AI (Anthropic)
  • 코드 아키텍처 설계 및 구현
  • 알고리즘 최적화 및 한국어 특화 기능
  • 문서화 및 사용자 경험 개선

이 프로젝트는 인간-AI 협업의 결과물로, 학술 연구와 실용적 도구 개발의 만남을 보여줍니다.

🤝 기여하기

🔗 협업 방식

• 이슈 리포팅: GitHub Issues
• 기능 제안: Pull Request 환영
• 학술 협력: 연구 목적 사용 시 인용 부탁드립니다

💡 개선 아이디어

• 새로운 분석 지표 추가
• 다른 메신저 지원 (라인, 텔레그램 등)
• 웹 인터페이스 개발
• 실시간 분석 기능

📝 인용 (Citation)

학술 논문이나 연구에서 사용하실 때:

xistoh162108, & Claude AI. (2025). Kakao Talk Analyzer: 
Comprehensive analysis tool for KakaoTalk chat exports (v1.0.1). 
https://github.com/xistoh162108/kakaotalk_analyzer

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참고하세요.

🙏 감사의 말

• 한국어 자연어 처리: KoNLPy, mecab-python3
• 시각화: matplotlib, seaborn, wordcloud
• 데이터 처리: pandas, numpy
• 머신러닝: scikit-learn, sentence-transformers

---

🤖 Generated with Claude Code

Co-Authored-By: Claude [e-mail]