From 2e0e3ba5c9d2c863a0799833c26b11778072da73 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Sat, 26 Jul 2025 16:50:44 +0900 Subject: [PATCH] =?UTF-8?q?Add:=20=EB=89=B4=EC=8A=A4=20=EC=8A=A4=ED=82=AC?= =?UTF-8?q?=20=EC=9D=B4=EC=8B=9D=20=ED=8A=B8=EB=9F=AC=EB=B8=94=EC=8A=88?= =?UTF-8?q?=ED=8C=85=20=EB=AC=B8=EC=84=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - company-x_homepage의 뉴스 기능을 RO-BEING 스킬로 이식 - 마이크로서비스 아키텍처 전환 과정 문서화 - 주요 이슈와 해결 방법 정리 - 교훈 섹션 포함 --- .../250726_happybell80_뉴스스킬이식.md | 176 ++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 docs/troubleshooting/250726_happybell80_뉴스스킬이식.md diff --git a/docs/troubleshooting/250726_happybell80_뉴스스킬이식.md b/docs/troubleshooting/250726_happybell80_뉴스스킬이식.md new file mode 100644 index 0000000..226107f --- /dev/null +++ b/docs/troubleshooting/250726_happybell80_뉴스스킬이식.md @@ -0,0 +1,176 @@ +# 뉴스 스킬 이식 작업 + +## 배경 +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 실행 시 한글 렌더링 문제 + +**해결**: +```dockerfile +# 한글 폰트 설치 +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 네트워크 통합 + +**해결**: +```yaml +networks: + robeing-network: + external: true +``` + +## 일반적인 문제 해결 + +### Playwright 오류 +```bash +# 브라우저 재설치 +docker exec -it robeing-skill-news playwright install chromium +``` + +### ChromaDB 초기화 +```bash +# 데이터 삭제 후 재시작 +rm -rf ./data/chroma +docker-compose restart skill-news +``` + +### 메모리 부족 +```bash +# Docker 리소스 제한 조정 +docker-compose down +# docker-compose.yml에 리소스 제한 추가 +``` + +### API 응답 없음 +```bash +# 로그 확인 +docker logs robeing-skill-news -f --tail 100 +``` + +### 의존성 충돌 +```bash +# 컨테이너 재빌드 +docker-compose build --no-cache skill-news +``` + +## 성능 최적화 팁 + +1. **배치 처리**: 여러 기사를 한 번에 처리 +2. **캐싱**: ChromaDB의 벡터 캐싱 활용 +3. **비동기 처리**: 동시에 여러 URL 스크래핑 +4. **리소스 관리**: Playwright 브라우저 재사용 + +## 디버깅 명령어 + +```bash +# 실시간 로그 모니터링 +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를 활용하면 긴 작업도 효율적으로 처리 가능 \ No newline at end of file