DOCS/troubleshooting/250726_happybell80_뉴스스킬이식.md

뉴스 스킬 이식 작업

배경

company-x_homepage의 뉴스 수집 기능을 RO-BEING의 독립적인 마이크로서비스 스킬로 이식

작업 시간

• 시작: 2025년 7월 26일 오후 3시
• 완료: 2025년 7월 26일 오후 4시 48분

주요 작업 내용

• Google News 검색 기능을 FastAPI 기반 마이크로서비스로 전환
• ChromaDB를 활용한 벡터 저장소 통합
• RO-BEING 스킬 아키텍처에 맞는 HTTP API 구현

프로젝트 이식 과정에서 발생한 이슈와 해결 방법

1. 프로젝트 구조 차이점

문제: company-x_homepage는 단순 스크립트 구조였으나, ivada_robeing은 마이크로서비스 아키텍처 필요

해결:

• 독립적인 skill_news 마이크로서비스로 구현
• FastAPI 기반 RESTful API 구조로 변경
• Docker 컨테이너화로 독립성 확보

2. 데이터 저장소 통합

문제: 기존 파일 기반 저장 vs RO-BEING의 ChromaDB/PostgreSQL 구조

해결:

• NewsDataManager를 ChromaDB 기반으로 재작성
• 벡터 임베딩을 활용한 유사도 검색 기능 추가
• 메타데이터를 JSON으로 저장하여 호환성 유지

3. 비동기 처리 패턴

문제: 동기식 스크립트 vs FastAPI의 비동기 패턴

해결:

• 모든 서비스 메서드를 async/await 패턴으로 변경
• BackgroundTasks를 활용한 비동기 파이프라인 구현
• asyncio 기반 동시성 처리

4. 환경변수 관리

문제: 각 프로젝트의 서로 다른 환경변수 체계

해결:

• 공통 환경변수는 유지
• 프로젝트별 특화 변수는 기본값 제공
• .env.example 파일로 문서화

5. Playwright 브라우저 설정

문제: Docker 환경에서 Playwright 실행 시 한글 렌더링 문제

해결:

# 한글 폰트 설치
RUN apt-get update && apt-get install -y \
    fonts-nanum \
    fonts-nanum-coding \
    fonts-nanum-extra

6. 모듈 임포트 구조

문제: 상대경로 vs 절대경로 임포트 충돌

해결:

• 패키지 구조로 정리 (app 디렉토리)
• __init__.py 파일 추가
• 상대 임포트 사용 (from ..models import NewsArticle)

7. API 응답 모델

문제: 딕셔너리 기반 데이터 vs Pydantic 모델

해결:

• 모든 데이터 구조를 Pydantic 모델로 정의
• 타입 안정성 확보
• API 문서 자동 생성

8. 중복 검사 로직

문제: 파일 기반 중복 검사 vs 데이터베이스 기반

해결:

• ChromaDB의 메타데이터 쿼리 활용
• URL과 제목 기반 OR 조건 검색
• 효율적인 인덱싱

9. 로깅 시스템

문제: print 문 vs 구조화된 로깅

해결:

• Python logging 모듈 사용
• 로그 레벨별 관리
• 파일 및 콘솔 동시 출력

10. 네트워크 통합

문제: 독립 실행 vs RO-BEING 네트워크 통합

해결:

networks:
  robeing-network:
    external: true

일반적인 문제 해결

Playwright 오류

# 브라우저 재설치
docker exec -it robeing-skill-news playwright install chromium

ChromaDB 초기화

# 데이터 삭제 후 재시작
rm -rf ./data/chroma
docker-compose restart skill-news

메모리 부족

# Docker 리소스 제한 조정
docker-compose down
# docker-compose.yml에 리소스 제한 추가

API 응답 없음

# 로그 확인
docker logs robeing-skill-news -f --tail 100

의존성 충돌

# 컨테이너 재빌드
docker-compose build --no-cache skill-news

성능 최적화 팁

1. 배치 처리: 여러 기사를 한 번에 처리
2. 캐싱: ChromaDB의 벡터 캐싱 활용
3. 비동기 처리: 동시에 여러 URL 스크래핑
4. 리소스 관리: Playwright 브라우저 재사용

디버깅 명령어

# 실시간 로그 모니터링
docker logs -f robeing-skill-news

# 컨테이너 접속
docker exec -it robeing-skill-news bash

# API 테스트
curl http://localhost:8505/health

# Python 디버깅
docker exec -it robeing-skill-news python -m pdb main.py

교훈

1. 마이크로서비스 아키텍처의 중요성: RO-BEING의 스킬 시스템은 독립성을 강조하므로, 처음부터 HTTP API 기반으로 설계하는 것이 중요
2. 타입 안정성: Pydantic 모델을 사용하여 데이터 검증을 철저히 하면 런타임 에러를 크게 줄일 수 있음
3. 환경변수 문서화: .env.example 파일을 통해 필요한 환경변수를 명확히 문서화하면 배포 시 실수를 방지할 수 있음
4. 벡터 DB 활용: ChromaDB를 통한 의미 기반 검색은 단순 키워드 매칭보다 훨씬 강력한 기능 제공
5. 비동기 처리: FastAPI의 BackgroundTasks를 활용하면 긴 작업도 효율적으로 처리 가능