서울 기온 AI 비서
내 데이터를 아는 AI 비서입니다. 서울의 월평균 기온 100개월치를 Firestore에 저장하고, 그 요약을 AI에게 알려준 뒤 대화합니다. "가장 더웠던 달은 언제야?"처럼 물으면 일반적인 답이 아니라 저장된 데이터에 근거한 답을 받습니다.
배포 주소
백엔드는 Render 무료 서버라 한동안 쓰지 않으면 잠듭니다. 첫 요청은 최대 1분쯤 걸릴 수 있고, 이때 화면에 "서버를 깨우는 중" 안내가 표시됩니다.
주요 기능
- 데이터 기반 AI 채팅: 질문하면 데이터 요약을 반영한 답변을 받습니다. 답변을 기다리는 동안 로딩이 표시되고, 대화는 자동 저장됩니다.
- 데이터 관리: (날짜, 기온, 메모) 데이터를 추가·수정·삭제합니다. 바꾸면 요약도 바로 갱신됩니다.
- 대화 기록: 이전 대화 목록을 보고, 골라서 다시 불러오거나 삭제합니다.
- 데이터 요약: 기간, 개수, 평균, 최고, 최저, 최근 추세를 항상 화면 위에 보여줍니다.
기술 스택
| 영역 | 사용 기술 |
|---|
| 백엔드 | Python, FastAPI, Pydantic, Uvicorn |
| 데이터베이스 | Firebase Firestore (data, conversations 컬렉션) |
| AI | Google Gemini (gemini-3.5-flash), openai 패키지로 OpenAI 호환 주소 호출 |
| 프론트엔드 | HTML, CSS, JavaScript (프레임워크 없음) |
| 배포 | Render (백엔드), Vercel (프론트엔드) |
AI는 Gemini를 사용합니다. openai 패키지의 호출 주소만 Gemini로 지정했기 때문에, .env의 LLM_BASE_URL, GEMINI_API_KEY, GEMINI_MODEL 값을 바꾸면 다른 OpenAI 호환 모델로 교체할 수 있습니다.
컨텍스트 주입 방식
AI는 내 데이터를 모릅니다. 그래서 질문을 보낼 때마다 데이터 요약을 시스템 프롬프트에 넣어 함께 보냅니다.
POST /api/chat으로 질문이 들어옵니다.- Firestore의
data 컬렉션을 읽어 요약(기간, 개수, 평균/최대/최소, 추세)을 계산합니다.
- 요약을 시스템 프롬프트의 빈칸에 채웁니다.
- 시스템 프롬프트, 이전 대화(최근 10개 메시지), 새 질문을 AI에 보냅니다.
- 질문과 답변을
conversations 컬렉션에 저장합니다.
데이터를 수정하면 다음 질문부터 바뀐 요약이 반영됩니다.
API
| 메서드 | 경로 | 설명 |
|---|
| POST | /api/data | 새 데이터 추가 |
| GET | /api/data | 데이터 목록 (날짜순) |
| PUT | /api/data/{id} | 데이터 수정 |
| DELETE | /api/data/{id} | 데이터 삭제 |
| GET | /api/data/summary | 데이터 요약 (프롬프트 주입용) |
| POST | /api/conversations | 대화 저장 |
| GET | /api/conversations | 대화 목록 (최근순, 본문 제외) |
| GET | /api/conversations/{id} | 대화 불러오기 (전체 메시지) |
| DELETE | /api/conversations/{id} | 대화 삭제 |
| POST | /api/chat | AI 채팅 (대화 자동 저장) |
대화 목록은 본문 없이 제목과 메시지 개수만 주고, 본문은 GET /api/conversations/{id}로 받습니다.
폴더 구조
ai-assistant/
├── backend/
│ ├── main.py # FastAPI 앱, CORS, 라우터 등록
│ ├── schemas.py # Pydantic 요청/응답 검증
│ ├── routers/ # 주소(엔드포인트) 정의: data, conversations, chat
│ ├── services/ # 실제 처리: firestore, data, summary, conversations, chat
│ ├── scripts/ # 데이터 준비(prepare_data), DB 적재(seed_data)
│ └── data/ # 원본 CSV와 100개월 JSON
└── frontend/ # index.html, style.css, app.js, config.js, build.js
라우터는 주소와 입력 검증, 오류 응답만 맡고, 실제 처리는 서비스에 둡니다. 요약 계산(services/summary.py)은 DB와 무관한 순수 함수라 스크립트와 API가 같이 씁니다.
로컬 실행 방법
Python 3.10 이상이 필요합니다.
# 1. 백엔드 준비
cd backend
python -m venv .venv
.venv\Scripts\activate # macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
# 2. 환경 변수: .env.example 을 .env 로 복사한 뒤 값 채우기
# Firebase 서비스 계정 키 파일은 backend/serviceAccount.json 으로 저장
# 3. 데이터 100개를 Firestore에 넣기 (처음 한 번)
python -m scripts.seed_data
# 4. 백엔드 실행 → http://127.0.0.1:8000/docs
uvicorn main:app --reload
# 5. 프론트엔드 실행 (새 터미널) → http://localhost:5500
cd ../frontend
python -m http.server 5500
환경 변수
백엔드 (backend/.env, Render 환경 변수)
| 이름 | 설명 |
|---|
GEMINI_API_KEY | Gemini API 키 (Google AI Studio에서 발급) |
GEMINI_MODEL | 사용할 모델. 기본값 gemini-3.5-flash |
FIREBASE_SERVICE_ACCOUNT_JSON | 서비스 계정 키 JSON 내용 전체 (배포용) |
FIREBASE_SERVICE_ACCOUNT_PATH | 서비스 계정 키 파일 경로 (로컬용, 위 값이 없을 때 사용) |
ALLOWED_ORIGINS | CORS 허용 주소 목록 (쉼표로 구분) |
프론트엔드 (Vercel 환경 변수)
| 이름 | 설명 |
|---|
API_BASE_URL | 백엔드 주소. 배포 때 build.js가 이 값으로 config.js를 만듭니다. |
API 키와 서비스 계정 키는 코드에 넣지 않으며, .env와 키 파일은 .gitignore로 저장소에서 제외합니다.
데이터
- 내용: 서울 월평균 기온 100개월 (2017-09 ~ 2025-12). 메모에는 그 달의 폭염일(일최고 33℃ 이상)과 열대야(일최저 25℃ 이상) 일수가 들어 있습니다.
- 만드는 법: 일별 자료 11,323일치를 월별로 평균 (
python -m scripts.prepare_data)
- 출처: Open-Meteo Historical Weather API, ERA5 재분석 자료 (Copernicus Climate Change Service), CC BY 4.0
- 재분석 자료는 격자 평균값이라 기상청 관측소 공식 통계와 다를 수 있습니다.
스크린샷
| 채팅 (요약 + 질문과 답변) | 데이터 관리 (수정) | 대화 기록 (불러오기) |
|---|
| | |
