1. 시스템 개요
Alchemetric은 AI 기반 퀀트 트레이딩 플랫폼으로, 데이터 수집 → NLP 분석 → 피처 엔지니어링 → 학습 → 예측 → 리포트/매매까지 전 과정을 자동화한다. 10개 모듈로 구성되며 Docker Compose 기반으로 배포한다.
Alchemetric = Alchemy(연금술) + Metric(지표). 시장 데이터를 가치 있는 투자 시그널로 변환한다는 의미를 담고 있다.
데이터 수집
→
NLP 분석
→
피처 엔지니어링
→
ML 학습
→
DL 학습
→
백테스팅
→
매매
→
리포트
| 항목 | 내용 |
|---|---|
| 프로젝트명 | Alchemetric |
| 목적 | AI 기반 퀀트 트레이딩 자동화 |
| 대상 시장 | KOSPI, KOSDAQ, NYSE, NASDAQ |
| 모듈 수 | 10개 (M0 ~ M9) |
| 배포 방식 | Docker Compose (4개 서비스) |
| 핵심 전략 | 머신러닝 + NLP(KR-FinBert-SC) + 딥러닝 복합 전략 |
| 피처 | 7-Phase 69개 (기술적 24 + 펀더멘털 9 + 거시 11 + 뉴스 5 + 공시/수급 10) |
2. 전체 아키텍처
외부 데이터 소스에서 수집한 원시 데이터가 NLP 분석과 피처 엔지니어링을 거쳐 PostgreSQL feature_store에 저장되고, ML/DL 모델이 학습 및 예측을 수행하여 최종 매매 시그널과 시장 리포트를 생성한다.
┌───────────────────────────────────────────────────────────────────────────────┐ │ EXTERNAL DATA SOURCES │ ├─────────┬────────┬─────────┬─────────┬─────────┬─────────┬─────────┬──────────┤ │yfinance │ FDR │ KIS API │DART API │ FRED │ Naver │KIS API │ KRX* │ │(주가+ │ (KR3Y │(펀더멘털) │(재무+공시)│(기준금리 │ News API│(수급 │ (섹터 │ │ 거시7) │ 국채) │ │ │ DXY,CPI)│ (NLP분석) │ 데이터) │ 데이터) │ └────┬────┴───┬────┴────┬────┴────┬────┴────┬────┴────┬────┴────┬────┴─────┬────┘ │ │ │ │ │ │ │ │ └────────┴─────────┴─────────┴─────────┴─────────┴─────────┴──────────┘ │ ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ ┌─────────────────┐ ┌────────────────┐ ┌────────────────┐ │ M0: 데이터 수집 │ │ M1: 데이터 │ │ M2: 피처 │ │ (원시 데이터) │ │ 분석 (NLP) │ │ 엔지니어링 │ └────────┬────────┘ └───────┬────────┘ └───────┬────────┘ └──────────────────┴──────────────────┘ │ ┌─────────▼─────────┐ │ PostgreSQL 15 │ :5432 │ feature_store │ └─────────┬─────────┘ │ ┌─────────▼─────────┐ │ M3: ML / M4: DL+RL │ │ (학습/예측) │ └─────────┬─────────┘ │ ┌─────────▼─────────┐ │ M5: 백테스팅 │ │ (전략 검증) │ └─────────┬─────────┘ │ ┌─────────────┬────────┴───────┬─────────────┐ ▼ ▼ ▼ ▼ ┌────────────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────┐ │ M6: 매매* │ │ M7: User │ │ M8: Admin │ │ M9: 리포트* │ │ (모의+실매매) │ │ Dash │ │ Dash │ │ (구독 서비스) │ └────────────────┘ │ :8501 │ │ :8502 │ └──────────────┘ └───────────┘ └───────────┘ ■ 완료 ■ 부분 ■ 개발 예정 (*)
3. 서비스 구성 (Docker Compose)
전체 시스템은 docker-compose.yml 기반으로 4개 서비스를 관리한다. PostgreSQL이 가장 먼저 기동되고, 헬스체크 통과 후 FastAPI 앱이 시작되며, 이후 두 개의 Streamlit 대시보드가 기동된다.
Update:
main.py의 초기화 흐름이lifespan컨텍스트 매니저 방식으로 변경되었다. 기존의 모듈 레벨database.create_tables()호출이lifespan내부로 이동하여, 앱 시작/종료 시점의 리소스 관리가 명확해졌다.
| 서비스명 | 이미지 | 포트 | 역할 | 의존성 |
|---|---|---|---|---|
| quant_postgres | postgres:15-alpine |
5432 | 운영 데이터베이스 (feature_store, 모델 메타, 스케줄) | - |
| quant_app | FastAPI (Dockerfile) |
8000 | REST API 서버 (데이터 수집, ML, 스케줄러) | postgres (healthy) |
| quant_dashboard | Streamlit (Dockerfile.dashboard) |
8501 | 사용자 대시보드 (차트, 예측 결과 조회) | app |
| quant_admin | Streamlit (Dockerfile.dashboard) |
8502 | 관리자 대시보드 (DB 관리, 스케줄러, ML 파이프라인) | app |
볼륨 구성
| 볼륨명 | 마운트 경로 | 용도 |
|---|---|---|
| postgres_data | /var/lib/postgresql/data |
PostgreSQL 데이터 영속화 |
| saved_models | /app/saved_models |
학습된 ML 모델 파일 (.joblib) 영속화 |
| ./app/logs | /app/logs |
로그 파일 바인드 마운트 |
4. 모듈 구성
Alchemetric은 기능 단위로 10개 모듈(M0~M9)로 분리되어 있으며, 각 모듈은 독립적으로 개발 및 테스트가 가능하다.
| 모듈 | 명칭 | 목적 | 상태 | 주요 기술 |
|---|---|---|---|---|
| M0 | 데이터 수집 | 주가, 재무, 거시경제, 뉴스, 공시, 수급 수집 | 완료 | yfinance, FDR, KIS API, DART API, FRED, Naver API |
| M1 | 데이터 분석 | 뉴스 NLP 센티먼트, DART 공시 분석 | 부분 | KR-FinBert-SC, transformers |
| M2 | 피처 엔지니어링 | 7-Phase 피처 생성 (Phase 1~6, 69개) | 부분 | pandas, 자체 indicators 모듈 |
| M3 | 머신러닝 | 분류/회귀 모델 학습, 예측, 하이퍼파라미터 튜닝 | 완료 | scikit-learn, XGBoost, LightGBM, Optuna |
| M4 | 딥러닝 + 강화학습 | LSTM, Transformer 시계열 분류, DQN/PPO 매매 에이전트 | 완료 | PyTorch, Stable-Baselines3, Gymnasium |
| M5 | 백테스팅 | 시그널 앙상블 백테스트, 성과 지표, 벤치마크 비교 | 완료 | 자체 BacktestEngine, NumPy, pandas |
| M6 | 매매 시스템 | 모의/실전 자동 매매 | 예정 | KIS API (실전/모의) |
| M7 | 사용자 대시보드 | 차트, 예측 결과, 뉴스 센티먼트 (4페이지) | 완료 | Streamlit, Plotly |
| M8 | 관리자 대시보드 | DB 관리, 스케줄러, ML 파이프라인, 뉴스/공시 관리 (12페이지) | 완료 | Streamlit |
| M9 | 리포트 + 구독 | 시장 리포트 자동 생성, LLM 요약, 3채널 구독 발송 | 예정 | Jinja2, GPT-4o-mini, matplotlib |
M6, M9은 향후 개발 예정이며, 현재 아키텍처에 인터페이스만 정의되어 있다. M4(DL+RL)와 M5(백테스팅)는 완료되었다. M1은 뉴스 NLP + DART 공시 분석이 완료되었고, 대안 데이터는 예정이다.
5. 데이터 흐름도
각 데이터 소스에서 수집된 원시 데이터가 NLP 분석과 피처 엔지니어링을 거쳐 최종 소비자(ML 모델, 대시보드, 리포트)에게 전달되는 전체 흐름이다.
[Step 1] 주가 데이터 수집 yfinance → kr_fetcher / us_fetcher → StockDaily (DB) ↓ [Step 2] 펀더멘털 데이터 수집 KIS API → kis_fetcher → FundamentalData (DB) DART API → dart_fetcher → FinancialStatement (DB) ↓ [Step 3] 거시경제 지표 수집 yfinance → macro_fetcher (7종) → MacroIndicator (DB) FDR → macro_fetcher (KR3Y) → (EAV 구조) FRED API → macro_fetcher (3종) → 기준금리, DXY, CPI ↓ [Step 4] 뉴스 수집 + NLP 분석 Naver API → news_fetcher → NewsArticle (DB) + KR-FinBert-SC 센티먼트 ↓ [Step 5] DART 공시 수집 DART API → disclosure_fetcher → DartDisclosure (DB) + 유형 분류 + 센티먼트 ↓ [Step 6] KRX 수급 수집 KIS API → krx_fetcher → KRXSupplyDemand (DB) 공매도, 프로그램매매 ↓ [피처 엔지니어링] StockDaily + Fundamental + Macro + News + Disclosure + SupplyDemand ↓ feature_engineer.py ↓ 69개 피처 생성 (7-Phase) ↓ Phase 1: 기술적 24 (SMA, EMA, RSI, MACD, BB, OBV ...) ↓ Phase 2: 펀더멘털 +9 (PER, PBR, ROE ...) ↓ Phase 3: 거시경제 +11 (환율, VIX, 기준금리, DXY, CPI ...) ↓ Phase 4: 뉴스 센티먼트 +5 ↓ Phase 5: DART 공시 + 수급 +10 ↓ FeatureStore (DB) ↓ [ML / DL / RL 파이프라인] trainer.py ↓ ML: RandomForest / XGBoost / LightGBM → .joblib ↓ DL: LSTM / Transformer → .pt ↓ RL: DQN / PPO (Gymnasium + SB3) → .zip ↓ Optuna 하이퍼파라미터 튜닝 (ML/DL/RL 공통) ↓ MLModel + MLPrediction (DB) + 모델 파일 ↓ predictor.py → signal_generator.py ↓ 매매 시그널 출력 (BUY / SELL / HOLD) ↓ [백테스팅] backtester.py → backtest_service.py ↓ 시그널 앙상블 (majority / weighted / probability / unanimous) ↓ 매매 시뮬레이션 (수수료 0.015% + 세금 0.20%) ↓ 성과 지표 (Sharpe, Sortino, MDD, Win Rate, Alpha) ↓ Buy & Hold 벤치마크 비교 ↓ BacktestRun + BacktestTrade + BacktestDaily (DB) ↓ Dashboard / Admin / Report* / Trading*
6. 기술 스택
| 계층 | 기술 | 용도 |
|---|---|---|
| Backend API | FastAPI, Uvicorn | REST API 서버, 비동기 처리 |
| Database | PostgreSQL 15, SQLite | 운영 DB(PostgreSQL), 개발용(SQLite) |
| ORM | SQLAlchemy 2.0+ | DB 추상화, 모델 정의, 마이그레이션 |
| 데이터 수집 | yfinance, FDR, opendartreader, KIS API, FRED API, Naver News API | 주가, 거시지표, 재무제표, 뉴스, 공시, 수급 수집 |
| ML | scikit-learn, XGBoost, LightGBM, Optuna | 분류/회귀 모델, 하이퍼파라미터 튜닝 |
| DL / RL | PyTorch, Stable-Baselines3, Gymnasium | LSTM, Transformer 시계열 분류, DQN/PPO 강화학습 매매 에이전트 |
| NLP | KR-FinBert-SC, transformers | 뉴스 센티먼트 분석 (한국어 금융 특화) |
| Scheduler | APScheduler 3.10+ | 데이터 수집, 학습, 거시지표 자동 스케줄링 |
| Dashboard | Streamlit | 사용자/관리자 웹 대시보드 |
| Trading* | KIS API (실전/모의) | 자동 매매 실행 |
| Deployment | Docker, Docker Compose | 컨테이너 기반 배포, 서비스 오케스트레이션 |
* 표시된 항목은 향후 개발 예정이다.
7. 디렉토리 구조
프로젝트 루트 기준 주요 디렉토리 및 파일 구조이다. 계층형 아키텍처(routes → services → repositories → models)를 따른다.
AI_Finance/ ├── app/ │ ├── api/ │ │ ├── main.py FastAPI 앱 인스턴스, lifespan 기반 초기화, 라우터 등록 │ │ ├── routes/ 엔드포인트 라우터 (stock, ml, backtest, macro, news, disclosure ...) │ │ └── schemas.py Pydantic 요청/응답 스키마 │ ├── data_collector/ │ │ ├── pipeline.py 9-Step 배치 파이프라인 │ │ ├── kr_fetcher.py 한국 주가 수집 (yfinance) │ │ ├── us_fetcher.py 미국 주가 수집 (yfinance) │ │ ├── kis_fetcher.py KIS 펀더멘털 수집 │ │ ├── dart_fetcher.py DART 재무제표 수집 │ │ ├── macro_fetcher.py 거시경제 지표 수집 (11종, FRED 포함) │ │ ├── news_fetcher.py 뉴스 수집 + KR-FinBert-SC 센티먼트 │ │ ├── disclosure_fetcher.py DART 공시 수집 + 센티먼트 │ │ ├── krx_fetcher.py KRX 수급 데이터 수집 (KIS API) │ │ ├── stock_codes.py 종목 코드 관리 │ │ ├── google_trends_fetcher.py Google Trends 수집 │ │ └── naver_community_fetcher.py Naver 종토방 크롤링 │ ├── scheduler/ │ │ └── scheduler.py APScheduler 잡 관리 (JobScheduler) │ ├── indicators/ │ │ ├── moving_average.py SMA, EMA │ │ ├── momentum.py RSI, MACD │ │ ├── volatility.py Bollinger Bands │ │ └── volume.py OBV │ ├── ml/ │ │ ├── feature_engineer.py 69개 피처 생성 (Phase 1~6) │ │ ├── trainer.py 모델 학습 (RF, XGB, LGBM, LSTM, Transformer, DQN, PPO) │ │ ├── predictor.py 예측 실행 (.joblib / .pt / .zip 라우팅) │ │ ├── tuner.py Optuna 하이퍼파라미터 튜닝 │ │ ├── signal_generator.py 매매 시그널 생성 │ │ ├── training_scheduler.py 학습 스케줄 관리 │ │ ├── ml_config.yaml ML 설정 파일 │ │ ├── backtester.py 백테스팅 엔진 (시그널 앙상블, 포트폴리오 시뮬레이션) │ │ ├── deep_learning/ LSTM, Transformer 분류 모델 │ │ └── reinforcement/ DQN, PPO 강화학습 (SB3 + Gymnasium) │ ├── models/ │ │ ├── stock.py StockDaily, FeatureStore │ │ ├── fundamental.py FundamentalData, FinancialStatement │ │ ├── macro.py MacroIndicator (EAV) │ │ ├── ml.py MLModel, MLPrediction │ │ ├── backtest.py BacktestRun, BacktestTrade, BacktestDaily │ │ ├── news.py NewsArticle │ │ ├── disclosure.py DartDisclosure, KRXSupplyDemand │ │ └── schedule.py ScheduleJob, JobTargetCode, JobStep, ScheduleLog, PipelineStepLog │ ├── repositories/ DB CRUD 계층 │ ├── services/ 비즈니스 로직 계층 │ ├── core/ │ │ ├── logging.py Loguru 기반 로깅 │ │ ├── market_calendar.py 영업일 캘린더 (XKRX/XNYS/XNAS) │ │ ├── exceptions.py 커스텀 예외 클래스 │ │ └── decorators.py 재시도, 타이머 데코레이터 │ ├── db/ │ │ └── connection.py DB 커넥션 팩토리 (PG/SQLite) │ ├── config.py 환경 설정 (DB, API키, 모델 경로) │ └── run.py Uvicorn 기동 스크립트 ├── dashboard/ 사용자 Streamlit 대시보드 │ ├── app.py 메인 엔트리 │ ├── pages/ 멀티페이지 구성 │ ├── components/ 재사용 UI 컴포넌트 │ └── api/ API 클라이언트 ├── admin/ 관리자 Streamlit 대시보드 │ ├── app.py 메인 엔트리 │ ├── pages/ 멀티페이지 구성 │ └── api/ API 클라이언트 ├── docs/ 프로젝트 문서 ├── docker-compose.yml 서비스 오케스트레이션 ├── Dockerfile FastAPI 컨테이너 ├── Dockerfile.dashboard Streamlit 컨테이너 └── requirements.txt Python 의존성
8. 배포 및 운영
Quick Start
# 1. 환경변수 설정 cp .env.example .env vi .env # DB, KIS, DART, FRED, Naver, Slack API 키 설정 # 2. Docker Compose 기동 docker-compose up -d --build # 3. 로그 확인 docker-compose logs -f app # 4. 서비스 중지 docker-compose down
서비스 URL
| 서비스 | URL | 설명 |
|---|---|---|
| API Server | http://localhost:8000 |
FastAPI REST API |
| API Docs | http://localhost:8000/docs |
Swagger UI (자동 생성) |
| User Dashboard | http://localhost:8501 |
사용자 Streamlit 대시보드 |
| Admin Dashboard | http://localhost:8502 |
관리자 Streamlit 대시보드 |
| PostgreSQL | localhost:5432 |
데이터베이스 직접 접속 |
헬스체크 및 모니터링
FastAPI 앱의 헬스체크 엔드포인트와 PostgreSQL 헬스체크로 서비스 상태를 확인할 수 있다.
# API 서버 헬스체크 curl http://localhost:8000/health # PostgreSQL 헬스체크 docker exec quant_postgres pg_isready -U postgres # 전체 서비스 상태 docker-compose ps # 로그 모니터링 (실시간) docker-compose logs -f --tail=100 app
로그 시스템: Loguru 기반 구조화된 로깅을 사용하며, 로그 파일은
./app/logs/디렉토리에 바인드 마운트되어 호스트에서 직접 확인 가능하다.
주의:
.env파일에 KIS API 키(실전/모의), DART API 키, FRED API 키, Naver API 키, Slack 토큰, DB 비밀번호 등 민감 정보가 포함되므로 반드시 버전 관리에서 제외해야 한다.
'Project > 🚀 AI Finance 2026' 카테고리의 다른 글
| #6 [모듈1] 데이터 분석 - 개발문서 (0) | 2026.02.19 |
|---|---|
| #5 [모듈0] 데이터 수집 - 개발문서 (0) | 2026.02.19 |
| #4 Alchemetric API 정의서 (0) | 2026.02.06 |
| #3 Alchemetric ERD (0) | 2026.02.03 |
| #1 Alchemetric 프로젝트 개발 명세서 (0) | 2026.02.03 |
