From 9ac839fd83b109662dcafaf2f7d006d08503c5ba Mon Sep 17 00:00:00 2001 From: 21in7 Date: Thu, 5 Mar 2026 23:32:14 +0900 Subject: [PATCH] docs: update README and ARCHITECTURE for multi-symbol trading Co-Authored-By: Claude Opus 4.6 --- ARCHITECTURE.md | 89 ++++++++++++++++++++++++++++----------------- README.md | 96 +++++++++++++++++++++++++++---------------------- 2 files changed, 109 insertions(+), 76 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 124948b..9d8f544 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -17,7 +17,22 @@ ## 1. 시스템 오버뷰 -CoinTrader는 **Binance Futures 자동매매 봇**입니다. 기술 지표 신호를 1차 필터로, LightGBM(또는 MLX 신경망) 모델을 2차 필터로 사용하여 XRPUSDT 선물 포지션을 자동 진입·청산합니다. +CoinTrader는 **Binance Futures 자동매매 봇**입니다. 기술 지표 신호를 1차 필터로, LightGBM(또는 MLX 신경망) 모델을 2차 필터로 사용하여 다중 심볼(XRP, TRX, DOGE 등) 선물 포지션을 동시에 자동 진입·청산합니다. + +### 멀티심볼 아키텍처 + +``` +main.py + └─ Config (SYMBOLS=XRPUSDT,TRXUSDT,DOGEUSDT) + └─ RiskManager (공유 싱글턴, asyncio.Lock) + └─ asyncio.gather( + TradingBot(symbol="XRPUSDT", risk=shared_risk), + TradingBot(symbol="TRXUSDT", risk=shared_risk), + TradingBot(symbol="DOGEUSDT", risk=shared_risk), + ) +``` + +각 봇은 독립적인 `Exchange`, `MLFilter`, `DataStream`을 소유합니다. `RiskManager`만 공유 싱글턴으로 글로벌 리스크(일일 손실 한도, 동일 방향 제한, 최대 포지션 수)를 관리합니다. ### 전체 데이터 파이프라인 흐름도 @@ -30,11 +45,11 @@ flowchart TD end subgraph 실시간봇["실시간 봇 (bot.py — asyncio)"] - DS["data_stream.py
MultiSymbolStream
캔들 버퍼 (deque 200개)"] + DS["data_stream.py
MultiSymbolStream (심볼별)
캔들 버퍼 (deque 200개)"] IND["indicators.py
기술 지표 계산
RSI·MACD·BB·EMA·StochRSI·ATR·ADX"] MF["ml_features.py
23개 피처 추출
(XRP 13 + BTC/ETH 8 + OI/FR 2)"] ML["ml_filter.py
MLFilter
ONNX 우선 / LightGBM 폴백
확률 ≥ 0.60 시 진입 허용"] - RM["risk_manager.py
RiskManager
일일 손실 5% 한도
동적 증거금 비율"] + RM["risk_manager.py
RiskManager (공유 싱글턴)
일일 손실 5% 한도
동적 증거금 비율
동일 방향 제한"] EX["exchange.py
BinanceFuturesClient
주문·레버리지·잔고 API"] UDS["user_data_stream.py
UserDataStream
TP/SL 즉시 감지"] NT["notifier.py
DiscordNotifier
진입·청산·오류 알림"] @@ -119,17 +134,17 @@ flowchart TD **파일:** `src/data_stream.py` -봇이 시작되면 가장 먼저 실행되는 레이어입니다. Binance Combined WebSocket 단일 연결로 XRP·BTC·ETH 3개 심볼의 15분봉 캔들을 동시에 수신합니다. +각 봇 인스턴스가 시작되면 가장 먼저 실행되는 레이어입니다. Binance Combined WebSocket 단일 연결로 주 거래 심볼 + 상관관계 심볼(BTC/ETH)의 15분봉 캔들을 동시에 수신합니다. **핵심 동작:** 1. **프리로드**: 봇 시작 시 REST API로 과거 캔들 200개를 `deque`에 즉시 채웁니다. EMA50 안정화에 필요한 최소 캔들(100개)을 확보하여 첫 캔들부터 신호를 계산할 수 있게 합니다. 2. **버퍼 관리**: 심볼별 `deque(maxlen=200)`에 마감된 캔들만 추가합니다. 미마감 캔들(`is_closed=False`)은 무시합니다. -3. **콜백 트리거**: XRP(주 심볼) 캔들이 마감되면 `bot._on_candle_closed()`를 호출합니다. BTC·ETH는 버퍼에만 쌓이고 콜백을 트리거하지 않습니다. +3. **콜백 트리거**: 주 거래 심볼 캔들이 마감되면 `bot._on_candle_closed()`를 호출합니다. 상관관계 심볼(BTC·ETH)은 버퍼에만 쌓이고 콜백을 트리거하지 않습니다. ``` -Combined WebSocket - ├── xrpusdt@kline_15m → buffers["xrpusdt"] → on_candle() 호출 +예: TRXUSDT 봇의 Combined WebSocket + ├── trxusdt@kline_15m → buffers["trxusdt"] → on_candle() 호출 ├── btcusdt@kline_15m → buffers["btcusdt"] (콜백 없음) └── ethusdt@kline_15m → buffers["ethusdt"] (콜백 없음) ``` @@ -252,11 +267,15 @@ SL/TP 주문은 `/fapi/v1/algoOrder` 엔드포인트로 전송됩니다 (일반 | 제어 항목 | 기준 | |----------|------| | 일일 최대 손실 | 기준 잔고의 5% | -| 최대 동시 포지션 | 3개 | +| 최대 동시 포지션 | 3개 (전체 심볼 합산) | +| 동일 방향 제한 | 2개 (LONG 2개면 3번째 LONG 차단) | +| 같은 심볼 중복 | 차단 (1심볼 1포지션) | | 최소 명목금액 | $5 USDT | **반대 시그널 재진입:** 보유 포지션과 반대 방향 신호 발생 시 기존 포지션을 즉시 청산하고, ML 필터 통과 시 반대 방향으로 재진입합니다. 재진입 중 User Data Stream 콜백이 신규 포지션 상태를 덮어쓰지 않도록 `_is_reentering` 플래그로 보호합니다. +**마진 균등 배분:** 멀티심볼 모드에서 각 봇은 전체 잔고를 심볼 수로 나눈 금액만큼만 사용합니다 (`balance / len(symbols)`). 공유 `RiskManager`의 `asyncio.Lock`으로 동시 포지션 등록/해제 시 경합 조건을 방지합니다. + --- ### Layer 5: Event / Alert Layer @@ -272,7 +291,7 @@ Binance `ORDER_TRADE_UPDATE` 웹소켓 이벤트를 구독하여 TP/SL 체결을 ``` 이벤트 필터링 조건: e == "ORDER_TRADE_UPDATE" - AND s == "XRPUSDT" ← 심볼 필터 + AND s == self.symbol ← 심볼 필터 (봇별 독립) AND x == "TRADE" ← 실제 체결 AND X == "FILLED" ← 완전 체결 AND (reduceOnly OR order_type in {STOP_MARKET, TAKE_PROFIT_MARKET} OR rp != 0) @@ -360,11 +379,11 @@ reg_alpha: 1e-4 ~ 1.0 (log scale) reg_lambda: 1e-4 ~ 1.0 (log scale) ``` -결과는 `models/tune_results_YYYYMMDD_HHMMSS.json`에 저장됩니다. +결과는 `models/{symbol}/tune_results_YYYYMMDD_HHMMSS.json`에 저장됩니다. #### Step 2: Active Config 패턴으로 파라미터 승인 -Optuna가 찾은 파라미터는 **자동으로 적용되지 않습니다.** 사람이 결과를 검토하고 직접 `models/active_lgbm_params.json`을 업데이트해야 합니다. +Optuna가 찾은 파라미터는 **자동으로 적용되지 않습니다.** 사람이 결과를 검토하고 직접 `models/{symbol}/active_lgbm_params.json`을 업데이트해야 합니다. ```json { @@ -390,18 +409,20 @@ Optuna가 찾은 파라미터는 **자동으로 적용되지 않습니다.** 사 `scripts/train_and_deploy.sh`는 3단계를 자동으로 실행합니다: ``` -[1/3] 데이터 수집 (fetch_history.py) - - 기존 parquet 없음 → 1년치(365일) 전체 수집 - - 기존 parquet 있음 → 35일치 Upsert (OI/펀딩비 0.0 구간 보충) +[심볼별 반복] --symbol 지정 시 단일 심볼, --all 시 전체 심볼 순차 처리 -[2/3] 모델 학습 (train_model.py) - - active_lgbm_params.json 파라미터 로드 +[1/3] 데이터 수집 (fetch_history.py --symbol {SYM}) + - data/{symbol}/combined_15m.parquet 없음 → 1년치(365일) 전체 수집 + - 있음 → 35일치 Upsert (OI/펀딩비 0.0 구간 보충) + +[2/3] 모델 학습 (train_model.py --symbol {SYM}) + - models/{symbol}/active_lgbm_params.json 파라미터 로드 - 벡터화 데이터셋 생성 (dataset_builder.py) - Walk-Forward 5폴드 검증 후 최종 모델 저장 - - 학습 로그: models/training_log.json + - 학습 로그: models/{symbol}/training_log.json -[3/3] LXC 배포 (deploy_model.sh) - - rsync로 lgbm_filter.pkl → LXC 서버 전송 +[3/3] LXC 배포 (deploy_model.sh --symbol {SYM}) + - rsync로 models/{symbol}/lgbm_filter.pkl → LXC 서버 전송 - 기존 모델 자동 백업 (lgbm_filter_prev.pkl) - ONNX 파일 충돌 방지 (우선순위 보장) ``` @@ -547,7 +568,7 @@ sequenceDiagram ### 5.1 테스트 파일 구성 -`tests/` 폴더에 12개 테스트 파일, 총 **81개의 테스트 케이스**가 작성되어 있습니다. +`tests/` 폴더에 14개 테스트 파일, 총 **99개의 테스트 케이스**가 작성되어 있습니다. ```bash pytest tests/ -v # 전체 실행 @@ -562,14 +583,14 @@ bash scripts/run_tests.sh # 래퍼 스크립트 실행 | `test_indicators.py` | `src/indicators.py` | 7 | RSI 범위(0~100), MACD 컬럼 존재, 볼린저 밴드 상하단 대소관계, 신호 반환값 유효성, ADX 컬럼 존재, ADX<25 횡보장 차단, ADX NaN 폴스루 | | `test_ml_features.py` | `src/ml_features.py` | 11 | 23개 피처 수, BTC/ETH 포함 시 피처 수, RS 분모 0 처리, NaN 없음, side 인코딩, OI/펀딩비 파라미터 반영 | | `test_ml_filter.py` | `src/ml_filter.py` | 5 | 모델 없을 때 폴백 허용, 임계값 이상/미만 판단, 핫리로드 후 상태 변화 | -| `test_risk_manager.py` | `src/risk_manager.py` | 8 | 일일 손실 한도 초과 차단, 최대 포지션 수 제한, 동적 증거금 비율 상한/하한 클램핑 | +| `test_risk_manager.py` | `src/risk_manager.py` | 13 | 일일 손실 한도 초과 차단, 최대 포지션 수 제한, 동일 방향 제한, 심볼 중복 차단, 비동기 포지션 등록/해제, 동적 증거금 비율 상한/하한 클램핑 | | `test_exchange.py` | `src/exchange.py` | 8 | 수량 계산(기본/최소명목금액/잔고0), OI·펀딩비 조회 정상/오류 시 반환값 | | `test_data_stream.py` | `src/data_stream.py` | 6 | 3심볼 버퍼 존재, 빈 버퍼 None 반환, 캔들 파싱, 마감 캔들 콜백 호출, 프리로드 200개 | | `test_label_builder.py` | `src/label_builder.py` | 4 | LONG TP 도달 → 1, LONG SL 도달 → 0, 미결 → None, SHORT TP 도달 → 1 | | `test_dataset_builder.py` | `src/dataset_builder.py` | 9 | DataFrame 반환, 필수 컬럼 존재, 레이블 이진값, BTC/ETH 포함 시 23개 피처, inf/NaN 없음, OI nan 마스킹, RS 분모 0 처리 | | `test_mlx_filter.py` | `src/mlx_filter.py` | 5 | GPU 디바이스 확인, 학습 전 예측 형태, 학습 후 유효 확률, NaN 피처 처리, 저장/로드 후 동일 예측 | | `test_fetch_history.py` | `scripts/fetch_history.py` | 5 | OI=0 구간 Upsert, 신규 행 추가, 기존 비0값 보존, 파일 없을 때 신규 반환, 타임스탬프 오름차순 정렬 | -| `test_config.py` | `src/config.py` | 2 | 환경변수 로드, 동적 증거금 파라미터 로드 | +| `test_config.py` | `src/config.py` | 6 | 환경변수 로드, 동적 증거금 파라미터 로드, `symbols` 리스트, `correlation_symbols`, `max_same_direction`, SYMBOL→symbols 폴백 | > `test_mlx_filter.py`는 Apple Silicon(`mlx` 패키지)이 없는 환경에서 자동 스킵됩니다. @@ -588,6 +609,8 @@ bash scripts/run_tests.sh # 래퍼 스크립트 실행 | 레이블 생성 (SL/TP 룩어헤드) | ✅ | ✅ | `test_label_builder` + `test_dataset_builder` (전체 파이프라인 실제 호출) | | 벡터화 데이터셋 빌더 | ✅ | ✅ | `test_dataset_builder` | | 동적 증거금 비율 계산 | ✅ | — | `test_risk_manager` | +| 동일 방향 포지션 제한 | ✅ | — | `test_risk_manager` | +| 심볼 중복 진입 차단 | ✅ | — | `test_risk_manager` | | 일일 손실 한도 제어 | ✅ | — | `test_risk_manager` | | 포지션 수량 계산 | ✅ | — | `test_exchange` | | OI/펀딩비 API 조회 (정상/오류) | ✅ | ✅ | `test_exchange` + `test_bot` (`process_candle` → OI/펀딩비 → `build_features` 전달) | @@ -622,25 +645,25 @@ bash scripts/run_tests.sh # 래퍼 스크립트 실행 | 파일 | 레이어 | 역할 | |------|--------|------| -| `main.py` | — | 진입점. `Config` 로드 후 `TradingBot.run()` 실행 | -| `src/bot.py` | 오케스트레이터 | 모든 레이어를 조율하는 메인 트레이딩 루프 | -| `src/config.py` | — | 환경변수 기반 설정 (`@dataclass`) | +| `main.py` | — | 진입점. 심볼별 `TradingBot` 생성 + 공유 `RiskManager` + `asyncio.gather()` | +| `src/bot.py` | 오케스트레이터 | 심볼별 독립 트레이딩 루프 (symbol, risk 주입) | +| `src/config.py` | — | 환경변수 기반 설정 (`symbols` 리스트, `correlation_symbols`) | | `src/data_stream.py` | Data | Combined WebSocket 캔들 수신·버퍼 관리 | | `src/indicators.py` | Signal | 기술 지표 계산 및 복합 신호 생성 | | `src/ml_features.py` | ML Filter | 23개 ML 피처 추출 | | `src/ml_filter.py` | ML Filter | ONNX/LightGBM 모델 로드·추론·핫리로드 | | `src/mlx_filter.py` | ML Filter | Apple Silicon GPU 학습 + ONNX export | -| `src/exchange.py` | Execution | Binance Futures REST API 클라이언트 | -| `src/risk_manager.py` | Risk | 일일 손실 한도·동적 증거금 비율·포지션 수 제어 | +| `src/exchange.py` | Execution | Binance Futures REST API 클라이언트 (심볼별 독립) | +| `src/risk_manager.py` | Risk | 공유 싱글턴 — 일일 손실 한도·동일 방향 제한·동적 증거금 비율 | | `src/user_data_stream.py` | Event | User Data Stream TP/SL 즉시 감지 | | `src/notifier.py` | Alert | Discord 웹훅 알림 | | `src/label_builder.py` | MLOps | 학습 레이블 생성 (ATR SL/TP 룩어헤드) | | `src/dataset_builder.py` | MLOps | 벡터화 데이터셋 빌더 (학습용) | | `src/logger_setup.py` | — | Loguru 로거 설정 | -| `scripts/fetch_history.py` | MLOps | 과거 캔들 + OI/펀딩비 수집 (Parquet Upsert) | -| `scripts/train_model.py` | MLOps | LightGBM 모델 학습 (CPU) | +| `scripts/fetch_history.py` | MLOps | 과거 캔들 + OI/펀딩비 수집 (`--symbol` 지원) | +| `scripts/train_model.py` | MLOps | LightGBM 모델 학습 (`--symbol` 지원) | | `scripts/train_mlx_model.py` | MLOps | MLX 신경망 학습 (Apple Silicon GPU) | -| `scripts/tune_hyperparams.py` | MLOps | Optuna 하이퍼파라미터 탐색 (수동 트리거) | -| `scripts/train_and_deploy.sh` | MLOps | 전체 파이프라인 (수집→학습→배포) | -| `scripts/deploy_model.sh` | MLOps | 모델 파일 LXC 서버 전송 | -| `models/active_lgbm_params.json` | MLOps | 승인된 LightGBM 파라미터 (Active Config) | +| `scripts/tune_hyperparams.py` | MLOps | Optuna 하이퍼파라미터 탐색 (`--symbol` 지원) | +| `scripts/train_and_deploy.sh` | MLOps | 전체 파이프라인 (`--symbol` / `--all` 지원) | +| `scripts/deploy_model.sh` | MLOps | 모델 파일 LXC 서버 전송 (`--symbol` 지원) | +| `models/{symbol}/active_lgbm_params.json` | MLOps | 심볼별 승인된 LightGBM 파라미터 (Active Config) | diff --git a/README.md b/README.md index eea34b4..afea9e3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # CoinTrader -Binance Futures 자동매매 봇. 복합 기술 지표와 ML 필터(LightGBM / MLX 신경망)를 결합하여 XRPUSDT(기본) 선물 포지션을 자동으로 진입·청산하며, Discord로 실시간 알림을 전송합니다. +Binance Futures 자동매매 봇. 복합 기술 지표와 ML 필터(LightGBM / MLX 신경망)를 결합하여 다중 심볼(XRP, TRX, DOGE 등) 선물 포지션을 동시에 자동 진입·청산하며, Discord로 실시간 알림을 전송합니다. > **아키텍처 문서**: 코드 구조, 레이어별 역할, MLOps 파이프라인, 동작 시나리오를 상세히 설명한 [ARCHITECTURE.md](./ARCHITECTURE.md)를 참고하세요. @@ -19,7 +19,8 @@ Binance Futures 자동매매 봇. 복합 기술 지표와 ML 필터(LightGBM / M - **Algo Order API 지원**: 계정 설정에 따라 STOP_MARKET/TAKE_PROFIT_MARKET 주문을 `/fapi/v1/algoOrder` 엔드포인트로 자동 전송 (오류 코드 -4120 대응) - **동적 증거금 비율**: 잔고 증가에 따라 선형 감소 (최대 50% → 최소 20%) - **반대 시그널 재진입**: 보유 포지션과 반대 신호 발생 시 즉시 청산 후 ML 필터 통과 시 반대 방향 재진입 -- **리스크 관리**: 트레이드당 리스크 비율, 최대 포지션 수, 일일 손실 한도(5%) 제어 +- **멀티심볼 동시 거래**: 심볼별 독립 봇 인스턴스를 `asyncio.gather()`로 병렬 실행. 공유 RiskManager로 글로벌 리스크 관리 +- **리스크 관리**: 트레이드당 리스크 비율, 최대 포지션 수, 동일 방향 포지션 제한(기본 2개), 일일 손실 한도(5%) 제어 - **포지션 복구**: 봇 재시작 시 기존 포지션 자동 감지 및 상태 복원 - **실시간 TP/SL 감지**: Binance User Data Stream으로 TP/SL 작동을 즉시 감지 (캔들 마감 대기 없음) - **순수익(Net PnL) 기록**: 바이낸스 `realizedProfit - commission`으로 정확한 순수익 계산 @@ -34,34 +35,40 @@ Binance Futures 자동매매 봇. 복합 기술 지표와 ML 필터(LightGBM / M ``` cointrader/ -├── main.py # 진입점 +├── main.py # 진입점 (심볼별 봇 인스턴스 생성 + asyncio.gather) ├── src/ -│ ├── bot.py # 메인 트레이딩 루프 -│ ├── config.py # 환경변수 기반 설정 -│ ├── exchange.py # Binance Futures API 클라이언트 -│ ├── data_stream.py # WebSocket 15분봉 멀티심볼 스트림 (XRP/BTC/ETH) +│ ├── bot.py # 메인 트레이딩 루프 (심볼별 독립 인스턴스) +│ ├── config.py # 환경변수 기반 설정 (symbols 리스트 지원) +│ ├── exchange.py # Binance Futures API 클라이언트 (심볼별 독립) +│ ├── data_stream.py # WebSocket 15분봉 멀티심볼 스트림 │ ├── indicators.py # 기술 지표 계산 및 신호 생성 │ ├── ml_filter.py # ML 필터 (ONNX 우선 / LightGBM 폴백 / 핫리로드) -│ ├── ml_features.py # ML 피처 빌더 (23개 피처) +│ ├── ml_features.py # ML 피처 빌더 (26개 피처) │ ├── mlx_filter.py # MLX 신경망 필터 (Apple Silicon GPU 학습 + ONNX export) │ ├── label_builder.py # 학습 레이블 생성 │ ├── dataset_builder.py # 벡터화 데이터셋 빌더 (학습용) -│ ├── risk_manager.py # 리스크 관리 (일일 손실 한도, 동적 증거금 비율) +│ ├── risk_manager.py # 공유 리스크 관리 (asyncio.Lock, 동일 방향 제한) │ ├── notifier.py # Discord 웹훅 알림 │ └── logger_setup.py # Loguru 로거 설정 ├── scripts/ -│ ├── fetch_history.py # 과거 데이터 수집 (XRP/BTC/ETH + OI/펀딩비, Upsert 지원) -│ ├── train_model.py # LightGBM 모델 학습 (CPU) +│ ├── fetch_history.py # 과거 데이터 수집 (--symbol 단일 / --symbols 다중) +│ ├── train_model.py # LightGBM 모델 학습 (--symbol 지원) │ ├── train_mlx_model.py # MLX 신경망 학습 (Apple Silicon GPU) -│ ├── train_and_deploy.sh # 전체 파이프라인 (수집 → 학습 → LXC 배포) -│ ├── tune_hyperparams.py # Optuna 하이퍼파라미터 자동 탐색 (수동 트리거) -│ ├── deploy_model.sh # 모델 파일 LXC 서버 전송 +│ ├── train_and_deploy.sh # 전체 파이프라인 (--symbol / --all 지원) +│ ├── tune_hyperparams.py # Optuna 하이퍼파라미터 자동 탐색 (--symbol 지원) +│ ├── deploy_model.sh # 모델 파일 LXC 서버 전송 (--symbol 지원) │ └── run_tests.sh # 전체 테스트 실행 ├── dashboard/ │ ├── api/ # FastAPI 백엔드 (로그 파서 + REST API) │ └── ui/ # React 프론트엔드 (Vite + Recharts) -├── models/ # 학습된 모델 저장 (.pkl / .onnx) -├── data/ # 과거 데이터 캐시 (.parquet) +├── models/ # 학습된 모델 저장 (심볼별 하위 디렉토리) +│ ├── xrpusdt/ # models/xrpusdt/lgbm_filter.pkl +│ ├── trxusdt/ # models/trxusdt/lgbm_filter.pkl +│ └── dogeusdt/ # models/dogeusdt/lgbm_filter.pkl +├── data/ # 과거 데이터 캐시 (심볼별 하위 디렉토리) +│ ├── xrpusdt/ # data/xrpusdt/combined_15m.parquet +│ ├── trxusdt/ # data/trxusdt/combined_15m.parquet +│ └── dogeusdt/ # data/dogeusdt/combined_15m.parquet ├── logs/ # 로그 파일 ├── docs/plans/ # 설계 문서 및 구현 플랜 ├── tests/ # 테스트 코드 @@ -86,8 +93,10 @@ cp .env.example .env ```env BINANCE_API_KEY=your_api_key BINANCE_API_SECRET=your_api_secret -SYMBOL=XRPUSDT +SYMBOLS=XRPUSDT,TRXUSDT,DOGEUSDT +CORRELATION_SYMBOLS=BTCUSDT,ETHUSDT LEVERAGE=10 +MAX_SAME_DIRECTION=2 DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... ``` @@ -120,14 +129,17 @@ docker compose logs -f cointrader 맥미니에서 데이터 수집 → 학습 → LXC 배포까지 한 번에 실행합니다. -> **자동 분기**: `data/combined_15m.parquet`가 없으면 1년치(365일) 전체 수집, 있으면 35일치 Upsert로 자동 전환합니다. 서버 이전이나 데이터 유실 시에도 사람의 개입 없이 자동 복구됩니다. +> **자동 분기**: `data/{symbol}/combined_15m.parquet`가 없으면 1년치(365일) 전체 수집, 있으면 35일치 Upsert로 자동 전환합니다. 서버 이전이나 데이터 유실 시에도 사람의 개입 없이 자동 복구됩니다. ```bash -# LightGBM + Walk-Forward 5폴드 (기본값) +# 전체 심볼 학습 + 배포 (SYMBOLS 환경변수의 모든 심볼) bash scripts/train_and_deploy.sh -# MLX GPU 학습 + Walk-Forward 5폴드 -bash scripts/train_and_deploy.sh mlx +# 단일 심볼만 학습 + 배포 +bash scripts/train_and_deploy.sh --symbol TRXUSDT + +# MLX GPU 학습 (단일 심볼) +bash scripts/train_and_deploy.sh mlx --symbol XRPUSDT # LightGBM + Walk-Forward 3폴드 bash scripts/train_and_deploy.sh lgbm 3 @@ -139,34 +151,30 @@ bash scripts/train_and_deploy.sh lgbm 0 ### 단계별 수동 실행 ```bash -# 1. 과거 데이터 수집 (XRP/BTC/ETH 3심볼, 15분봉, 1년치 + OI/펀딩비) -# 기본값: Upsert 활성화 — 기존 parquet의 oi_change/funding_rate=0 구간을 실제 값으로 채움 +# 1. 과거 데이터 수집 (단일 심볼 — 상관관계 심볼 자동 추가) +python scripts/fetch_history.py --symbol TRXUSDT --interval 15m --days 365 +# → data/trxusdt/combined_15m.parquet 에 저장 + +# 1-alt. 명시적 심볼 지정 (기존 방식도 지원) python scripts/fetch_history.py \ --symbols XRPUSDT BTCUSDT ETHUSDT \ --interval 15m \ --days 365 \ --output data/combined_15m.parquet -# 기존 파일을 완전히 덮어쓰려면 --no-upsert 플래그 사용 -python scripts/fetch_history.py \ - --symbols XRPUSDT BTCUSDT ETHUSDT \ - --interval 15m \ - --days 365 \ - --output data/combined_15m.parquet \ - --no-upsert - -# 2-A. LightGBM 모델 학습 (CPU) -python scripts/train_model.py --data data/combined_15m.parquet +# 2-A. LightGBM 모델 학습 (심볼별) +python scripts/train_model.py --symbol TRXUSDT +# → models/trxusdt/lgbm_filter.pkl 에 저장 # 2-B. MLX 신경망 학습 (Apple Silicon GPU) -python scripts/train_mlx_model.py --data data/combined_15m.parquet +python scripts/train_mlx_model.py --data data/xrpusdt/combined_15m.parquet # 3. LXC 서버에 모델 배포 -bash scripts/deploy_model.sh # LightGBM -bash scripts/deploy_model.sh mlx # MLX (ONNX) +bash scripts/deploy_model.sh --symbol XRPUSDT +bash scripts/deploy_model.sh mlx --symbol XRPUSDT ``` -학습된 모델은 `models/lgbm_filter.pkl` (LightGBM) 또는 `models/mlx_filter.weights.onnx` (MLX) 에 저장됩니다. +학습된 모델은 `models/{symbol}/lgbm_filter.pkl` (LightGBM) 또는 `models/{symbol}/mlx_filter.weights.onnx` (MLX) 에 저장됩니다. 심볼별 디렉토리가 없으면 `models/` 루트로 폴백합니다. > **모델 핫리로드**: 봇이 실행 중일 때 모델 파일을 교체하면, 다음 캔들 마감 시 자동으로 감지해 리로드합니다. 봇 재시작이 필요 없습니다. @@ -176,17 +184,17 @@ bash scripts/deploy_model.sh mlx # MLX (ONNX) 결과를 확인하고 직접 승인한 후 재학습에 반영하는 **수동 트리거** 방식입니다. ```bash -# 기본 실행 (50 trials, 5폴드 Walk-Forward, ~30분) -python scripts/tune_hyperparams.py +# 심볼별 튜닝 (50 trials, 5폴드 Walk-Forward, ~30분) +python scripts/tune_hyperparams.py --symbol XRPUSDT # 빠른 테스트 (10 trials, 3폴드, ~5분) -python scripts/tune_hyperparams.py --trials 10 --folds 3 +python scripts/tune_hyperparams.py --symbol TRXUSDT --trials 10 --folds 3 # 베이스라인 측정 없이 탐색만 -python scripts/tune_hyperparams.py --no-baseline +python scripts/tune_hyperparams.py --symbol XRPUSDT --no-baseline ``` -결과는 `models/tune_results_YYYYMMDD_HHMMSS.json`에 저장됩니다. +결과는 `models/{symbol}/tune_results_YYYYMMDD_HHMMSS.json`에 저장됩니다. 콘솔에 Best Params, 베이스라인 대비 개선폭, 폴드별 AUC를 출력하므로 직접 확인 후 판단하세요. > **주의**: Optuna가 찾은 파라미터는 과적합 위험이 있습니다. Best Params를 `train_model.py`에 반영하기 전에 반드시 폴드별 AUC 분산과 개선폭을 검토하세요. @@ -305,8 +313,10 @@ pytest tests/ -v |------|--------|------| | `BINANCE_API_KEY` | — | Binance API 키 | | `BINANCE_API_SECRET` | — | Binance API 시크릿 | -| `SYMBOL` | `XRPUSDT` | 거래 심볼 | +| `SYMBOLS` | `XRPUSDT` | 거래 심볼 목록 (쉼표 구분, 예: `XRPUSDT,TRXUSDT,DOGEUSDT`) | +| `CORRELATION_SYMBOLS` | `BTCUSDT,ETHUSDT` | 상관관계 심볼 (BTC/ETH 수익률·상대강도 피처용) | | `LEVERAGE` | `10` | 레버리지 배수 | +| `MAX_SAME_DIRECTION` | `2` | 동일 방향 최대 포지션 수 (LONG 2개면 3번째 LONG 차단) | | `DISCORD_WEBHOOK_URL` | — | Discord 웹훅 URL | | `MARGIN_MAX_RATIO` | `0.50` | 최대 증거금 비율 (잔고 대비 50%) | | `MARGIN_MIN_RATIO` | `0.20` | 최소 증거금 비율 (잔고 대비 20%) |