From 70de874ae19c7229d0b8d4e6c7683b146cd53e81 Mon Sep 17 00:00:00 2001 From: kyu Date: Wed, 20 May 2026 21:53:56 +0900 Subject: [PATCH] Add README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 프로젝트 개요·파이프라인·서비스 표·점수 산출 공식·빠른 시작·API 예시· DB 핵심 테이블·디렉토리 구조 정리. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 232 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..93bc890 --- /dev/null +++ b/README.md @@ -0,0 +1,232 @@ +# Trading AI + +워렌 버핏 스타일 가치투자 관점의 한국 주식 AI 분석 파이프라인. +뉴스·공시·재무·기술적 지표·미증시 동조 시그널을 통합해 종목별 종합 점수와 매수/매도 추천을 산출하고 텔레그램으로 전달한다. + +--- + +## 파이프라인 + +``` +[뉴스 RSS/네이버] → 형태소(바른) → 임베딩(bge-m3) → 중복제거(Qdrant) → 분석(EXAONE) + ↓ +[DART 공시/재무] → 재무비율(ROE·OPM·DR·FCF) → ┐ +[네이버 주가] → 기술지표(MA/RSI/MACD/볼밴) → ┤ +[미국 ETF/페어] → 섹터·페어 회귀 시그널 → ┼→ 종합 스코어링 → 추천 → 텔레그램 +[ECOS 매크로] → USD/KRW·국고채10년 → ┤ (10공식 앙상블) +[그래프 신경망] → GAT 다음날 수익률 예측 → ┘ +``` + +--- + +## 서비스 구성 (Docker Compose) + +| 서비스 | 포트 | 역할 | +|--------|------|------| +| `news-collector` | 8787 | 뉴스 수집 + 형태소/임베딩/중복제거/EXAONE 분석 | +| `bareunaapi` | 5757 | 한국어 형태소분석 FastAPI 래퍼 | +| `bareun` | 5656/9902 | 바른 NLP gRPC 서버 | +| `dart-collector` | 8888 | DART 공시/재무제표 수집 | +| `score-engine` | 8686 | 종합 점수 계산 + 텔레그램 브리핑 | +| `ta-engine` | 8484 | 기술적분석 (MA/RSI/MACD/볼밴/스토캐스틱) | +| `aux-signal` | 8282 | 컨센서스·기관/외국인 수급·ECOS 매크로 | +| `us-market` | 8383 | 미증시 섹터 ETF·페어 회귀 시그널 | +| `graph-engine` | 9090 | GAT 그래프 신경망 (graph_score) | +| `kis-api` | 8585 | 네이버모바일 주가 + 매매시그널 | +| `dashboard-api` | 8989 | 대시보드 REST API + HTML | +| `telegram-bot` | - | `/buy /sell /stock /deep /market` 명령 처리 | +| `ollama` | 11434 | EXAONE 3.5 7.8B 추론 + bge-m3 임베딩 | +| `n8n` / `worker` | 5678 | 워크플로우 자동화 | +| `postgres` | 5432 | 메인 DB | +| `redis` | 6379 | 캐시·중복제거 | +| `qdrant` | 6333 | 뉴스 벡터 유사도 필터 | + +--- + +## 점수 산출 + +``` +종합점수 = 펀더멘털통합 × 0.24 + + 뉴스(catalyst 가중) × 0.18 + + 기술 × 0.15 + + DART 공시 × 0.10 + + 외국인 수급 × 0.14 + + 공매도 × 0.06 + + 가격 모멘텀 × 0.03 + + DCF 안전마진 × 0.10 + + 시장 레짐 보정 (±5~10) + + 앙상블 보팅 (±18) ← 10공식 매수/매도 합 × 학습 가중치 +``` + +**10공식 앙상블 보팅** (각 공식이 독립 신호 발신, 백테스트 회귀로 가중치 학습): + +| 공식 | 출처 | 매수 신호 조건 | +|------|------|---------------| +| 매직포뮬러 | Greenblatt | ROC + EY ≥ 20 | +| F-Score | Piotroski 2000 | 7신호 ≥ 6 | +| 알트만 Z | Altman 1968 | Z ≥ 2.6 | +| PEG | Lynch GARP | PER / 이익성장률 ≤ 1.5 | +| 12-1 모멘텀 | AQR (Carhart) | (P_-21 / P_-252) − 1 ≥ 10% | +| Beneish M | Beneish 1999 | 의심도 < 50 + CFO/NI > 1 | +| GP/A | Novy-Marx 2013 | 영업이익/총자산 ≥ 15% | +| G-Score | Mohanram 2005 | 5신호 vs 섹터 중앙값 ≥ 4 | +| Amihud | Amihud 2002 | 비유동성 ≥ 100 (소형 알파) | +| BAB(베타) | Frazzini-Pedersen | β < 0.7 (저베타 알파) | + +**버핏 가치투자 필터** (`is_value_investable`): +- 영업이익 > 0 +- ROE ≥ 10% +- 부채비율 ≤ 200% +- PER ≤ 60 +- 시총 ≥ 100억 +- `dart_corps.is_active = true` (상장폐지 제외) + +**추천 등급** (점수 + 다수 공식 동의 강제): +- **강력매수**: ≥ 70 AND 매수 보팅 ≥ 3 +- **매수관심**: ≥ 40 AND 매수 보팅 ≥ 1 AND 매도 보팅 < 2 +- **매도관심**: ≤ −30 OR 매도 보팅 ≥ 3 +- **강력매도**: ≤ −60 OR 매도 보팅 ≥ 4 +- 그 외 **관망** + +--- + +## 빠른 시작 + +### 사전 요구사항 +- Ubuntu 22.04, Docker / Docker Compose +- GPU 2장 (GPU0: EXAONE 추론용 ≥12GB / GPU1: bge-m3 임베딩용 ≥8GB) +- NAS NFS 마운트 (`/mnt/nas`) — PostgreSQL 데이터 영속화용 + +### 환경변수 +`.env` 파일 생성 (예시): +``` +POSTGRES_HOST=postgres +POSTGRES_PORT=5432 +POSTGRES_DB=trading_ai +POSTGRES_USER=kyu +POSTGRES_PASSWORD=... + +REDIS_PASSWORD=... +REDIS_MAX_MEMORY=2gb + +DART_API_KEY=... +ECOS_API_KEY=... +FINNHUB_API_KEY=... + +TELEGRAM_BOT_TOKEN=... +TELEGRAM_CHAT_ID=... + +OLLAMA_NUM_PARALLEL=4 +QDRANT_COLLECTION=news_vectors +QDRANT_VECTOR_SIZE=1024 +``` + +### 실행 +```bash +docker compose up -d +docker compose ps # 전체 상태 +docker logs trading-score-engine -f # 로그 추적 +``` + +### 초기 데이터 로딩 +```bash +# DART 기업목록 수집 +curl -X POST http://localhost:8888/collect/corps + +# 다년치 사업보고서 백필 (F-Score·PEG용, years≥2 필수) +curl -X POST 'http://localhost:8888/collect/financials?count=3000&years=10&annual_only=true' + +# 섹터 정보 채우기 +curl -X POST http://localhost:8888/collect/sectors + +# 점수 수동 재계산 +curl -X POST http://localhost:8686/score/calculate + +# 백테스트 기반 공식 가중치 학습 +curl -X POST 'http://localhost:8686/learn-weights?days=90' +``` + +--- + +## 주요 API + +### 추천 / 랭킹 +```bash +# 오늘의 추천 종목 +docker exec trading-postgres psql -U kyu -d trading_ai -c " + SELECT s.stock_code, d.corp_name, s.total_score, s.recommendation, + s.magic_score, s.f_score, s.buy_votes, s.sell_votes + FROM stock_scores s JOIN dart_corps d ON d.stock_code=s.stock_code + WHERE d.is_active=true AND s.score_date=CURRENT_DATE + ORDER BY s.total_score DESC LIMIT 10;" + +# REST +curl http://localhost:8686/recommendations +curl http://localhost:8686/stock/005930 # 삼성전자 +curl http://localhost:8686/backtest # 추천 성과 백테스트 +curl http://localhost:8484/technical/005930 # 기술분석 +curl http://localhost:8989/api/summary # 대시보드 요약 +``` + +### 학습 / 예측 +```bash +curl -X POST 'http://localhost:8686/learn-weights?days=90' +curl http://localhost:8686/learn-weights +curl -X POST http://localhost:8686/learn-pricing +curl http://localhost:8686/predict-price/005930 +``` + +--- + +## 데이터베이스 핵심 테이블 + +| 테이블 | 설명 | +|--------|------| +| `news_analysis` | 분석된 뉴스 (sentiment / intensity / catalyst) | +| `news_raw` | 수집/분석 분리용 임시 저장소 | +| `dart_corps` | DART 기업목록 (`is_active=true` 필터 필수) | +| `dart_financials` | 재무제표 + 비율 (ROE / OPM / DR / FCF) | +| `stock_scores` | 일별 종합 점수 + 10공식 신호 + 가중치 | +| `stock_technical` | 기술지표 + 매매신호 | +| `weight_config` | 공식별 학습 가중치 (자동 갱신) | +| `pricing_model` | 30일 수익률 회귀/RF 모델 메타 | + +상세 스키마는 `CLAUDE.md` 참고. + +--- + +## 디렉토리 구조 + +``` +trading/ +├── CLAUDE.md # 프로젝트 상세 가이드 (Claude Code용) +├── docker-compose.yml # 전체 서비스 정의 +├── init-db.sql # 초기 스키마 +├── news-collector/ # 뉴스 수집·분석 +├── bareunaapi/ # 형태소분석 래퍼 +├── dart-collector/ # DART 공시·재무 +├── score-engine/ # 종합 스코어링 +├── ta-engine/ # 기술적 분석 +├── aux-signal/ # 컨센서스·수급·매크로 +├── us-market/ # 미증시 동조 시그널 +├── graph-engine/ # GAT 그래프 신경망 +├── kis-api/ # 주가 수집 +├── dashboard-api/ # 대시보드 REST +├── telegram-bot/ # 텔레그램 봇 +└── scripts/ # 설치/상태 스크립트 +``` + +--- + +## 주의사항 + +- 모든 추천 쿼리에 `WHERE d.is_active=true` 필수 (상장폐지 제외). +- NAS fstab은 반드시 한 줄, `nfsvers=3` 옵션 필수. +- Ollama 단일 컨테이너가 GPU0·GPU1을 동시 사용. `runtime: nvidia` 필요. +- `.env` / `pg_backup/` / `models/` 등 민감 자산은 `.gitignore` 처리됨. + +--- + +## 라이선스 + +내부 프로젝트.