d4bd508618
All checks were successful
news-summary-bot-cicd / build_push_deploy (push) Successful in 4m40s
- yt-dlp에 쿠키 파일(/app/cookies.txt) 지원 추가 (YouTube 봇 감지 우회) - CI/CD에 paths-ignore: **/*.md 추가하여 문서 수정 시 빌드 스킵 - 전체 문서 업데이트: 라우트 변경, 쿠키 인증 방식, n8n Expression 모드 안내 - .gitignore에 cookies.txt 추가 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
105 lines
3.3 KiB
Markdown
105 lines
3.3 KiB
Markdown
# 개발 가이드
|
|
|
|
YouTube 뉴스 영상을 자동 요약하여 Discord로 전송하는 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 요약
|
|
│ └── discord.py # Discord 웹훅 전송
|
|
├── Dockerfile
|
|
├── docker-compose.yml
|
|
├── requirements.txt
|
|
├── .env.example
|
|
└── .gitignore
|
|
```
|
|
|
|
## 로컬 환경 설정
|
|
|
|
**Python 3.12 이상** 필요.
|
|
|
|
```bash
|
|
# 의존성 설치
|
|
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로 요약한 뒤 Discord 웹훅으로 전송합니다.
|
|
|
|
- **인증**: `X-Api-Secret` 헤더에 시크릿 값 전달 (API_SECRET 환경변수가 설정된 경우 필수)
|
|
- **요청 본문**:
|
|
- `video_url` (string, 필수) — YouTube 영상 URL
|
|
- `title` (string, 필수) — 영상 제목
|
|
|
|
### GET /health
|
|
|
|
서버 상태 확인용 헬스체크 엔드포인트입니다. 별도 인증 없이 호출 가능합니다.
|
|
|
|
## 로컬 테스트
|
|
|
|
### 헬스체크 확인
|
|
|
|
```bash
|
|
curl http://localhost:8000/health
|
|
```
|
|
|
|
### 요약 요청
|
|
|
|
```bash
|
|
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": "뉴스 영상 제목"
|
|
}'
|
|
```
|
|
|
|
정상 처리 시 Discord 채널에 요약 메시지가 전송됩니다.
|
|
|
|
## 주요 모듈 설명
|
|
|
|
### transcript.py
|
|
|
|
YouTube URL에서 video ID를 추출하고 `yt-dlp`를 사용하여 자막을 가져옵니다. 한국어(`ko`) 자막을 우선으로 시도하며, 없을 경우 영어(`en`) 자막을 fallback으로 사용합니다.
|
|
|
|
서버 환경에서는 YouTube 봇 감지를 우회하기 위해 `/app/cookies.txt` 쿠키 파일을 사용합니다. 로컬 개발 시에는 가정용 IP라 쿠키 없이도 동작합니다.
|
|
|
|
### summarizer.py
|
|
|
|
Anthropic의 **Claude Sonnet 4.6** 모델을 사용하여 자막 텍스트를 요약합니다. 시스템 프롬프트에 뉴스/경제 요약에 최적화된 포맷을 지정하여 일관된 형식의 요약을 생성합니다.
|
|
|
|
### discord.py
|
|
|
|
요약 결과를 **Discord Embed** 형식으로 구성하여 웹훅 URL로 전송합니다. 영상 제목, 요약 내용, 원본 링크 등을 포함합니다.
|
|
|
|
### config.py
|
|
|
|
`pydantic-settings`를 사용하여 `.env` 파일 또는 시스템 환경변수에서 설정값을 로드합니다. 필수 값이 누락되면 서버 시작 시 에러가 발생합니다.
|
|
|
|
## 환경변수
|
|
|
|
| 변수 | 필수 | 설명 |
|
|
|------|------|------|
|
|
| `ANTHROPIC_API_KEY` | O | Anthropic API 키 |
|
|
| `DISCORD_WEBHOOK_URL` | O | Discord 웹훅 URL |
|
|
| `API_SECRET` | X | n8n → FastAPI 인증용 시크릿 (미설정 시 인증 생략) |
|