Files

sm4640 a2a82084ba

news-summary-bot-cicd / build_push_deploy (push) Successful in 25m15s

Details

Docs: [3.0.0] 전체 문서 업데이트 — YouTube Data API + n8n Discord 전송 구조 반영

- README: 아키텍처, 환경변수, API 응답 형식 업데이트
- n8n-setup: RSS → YouTube Data API playlistItems 전환, 노드별 상세 설정
- development: discord.py 제거 반영, API 응답 형식 추가
- operations: CI/CD 자동 배포 설명, DISCORD_WEBHOOK_URL 제거
- testing: DISCORD_WEBHOOK_URL 더미값 제거
- .env.example: DISCORD_WEBHOOK_URL 제거
- tests/test_discord.py 삭제 (모듈 삭제됨)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-25 15:18:39 +09:00

3.5 KiB

Raw Blame History

개발 가이드

YouTube 뉴스 영상을 자동 요약하는 FastAPI 기반 봇의 개발 문서입니다.

프로젝트 구조

news-summary-bot/
├── app/
│   ├── __init__.py
│   ├── main.py          # FastAPI 엔드포인트 (/summarize, /health)
│   ├── config.py        # pydantic-settings 환경변수
│   ├── transcript.py    # yt-dlp + 쿠키로 자막 추출
│   └── summarizer.py    # Claude Sonnet 4.6 요약
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
└── .gitignore

로컬 환경 설정

Python 3.12 이상 필요.

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

# 환경변수 파일 생성
cp .env.example .env
# .env 파일을 열어 API 키 등 설정

# 개발 서버 실행
uvicorn app.main:app --reload

서버가 정상 실행되면 http://localhost:8000 에서 접근 가능합니다.

API 엔드포인트

POST /summarize

YouTube 영상 URL을 받아 자막을 추출하고 Claude로 요약합니다. 결과를 JSON으로 반환하며, Discord 전송은 n8n에서 처리합니다.

인증: X-Api-Secret 헤더에 시크릿 값 전달 (API_SECRET 환경변수가 설정된 경우 필수)
요청 본문:
- video_url (string, 필수) — YouTube 영상 URL
- title (string, 선택) — 영상 제목

응답:

// 성공
{"status": "ok", "title": "...", "summary": "요약 텍스트"}

// 스킵 (라이브/쇼츠)
{"status": "skipped", "title": "...", "reason": "..."}

// 에러
{"status": "error", "title": "...", "error_type": "...", "error_message": "..."}

GET /health

서버 상태 확인용 헬스체크 엔드포인트입니다. 별도 인증 없이 호출 가능합니다.

로컬 테스트

헬스체크 확인

curl http://localhost:8000/health

요약 요청

curl -X POST http://localhost:8000/summarize \
  -H "Content-Type: application/json" \
  -H "X-Api-Secret: your-secret-here" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "title": "뉴스 영상 제목"
  }'

정상 처리 시 요약 텍스트가 포함된 JSON 응답이 반환됩니다.

주요 모듈 설명

transcript.py

YouTube URL에서 video ID를 추출하고 yt-dlp를 사용하여 자막을 가져옵니다. 한국어(ko) 자막을 우선으로 시도하며, 없을 경우 영어(en) 자막을 fallback으로 사용합니다.

라이브/예정 영상과 쇼츠는 SkipVideo 예외를 발생시켜 스킵합니다. yt-dlp의 DownloadError에서 라이브 관련 메시지가 감지되면 자동으로 스킵 처리됩니다.

서버 환경에서는 YouTube 봇 감지를 우회하기 위해 /app/cookies.txt 쿠키 파일을 사용합니다. 로컬 개발 시에는 가정용 IP라 쿠키 없이도 동작합니다.

summarizer.py

Anthropic의 Claude Sonnet 4.6 모델을 사용하여 자막 텍스트를 요약합니다. 시스템 프롬프트에 뉴스/경제 요약에 최적화된 포맷을 지정하여 일관된 형식의 요약을 생성합니다.

config.py

pydantic-settings를 사용하여 .env 파일 또는 시스템 환경변수에서 설정값을 로드합니다. 필수 값이 누락되면 서버 시작 시 에러가 발생합니다.

환경변수

변수	필수	설명
`ANTHROPIC_API_KEY`	O	Anthropic API 키
`API_SECRET`	X	n8n → FastAPI 인증용 시크릿 (미설정 시 인증 생략)

3.5 KiB Raw Blame History