quantbench/executor

Fork 0

Files

Jongheon Kim ab99abad8a feat: 프로젝트 기본 구조 구축

2025-10-04 22:11:32 +09:00

9.3 KiB

Raw Permalink Blame History

BAA 전략 API 사용 가이드

시작하기

1. 서버 실행

# 개발 서버 실행
python manage.py runserver

# 서버가 http://localhost:8000 에서 실행됩니다

2. 준비된 스크립트 사용

세 가지 편리한 스크립트가 제공됩니다:

A. 전체 예제 실행 (`baa_api_examples.sh`)

모든 주요 기능을 순차적으로 테스트합니다.

./baa_api_examples.sh

실행 내용:

사용 가능한 전략 목록 조회
BAA-G12 시뮬레이션 모드 실행
BAA-G4 실제 데이터 모드 (현재 날짜)
BAA-G12 특정 날짜 기준 (2024-01-31)

B. 빠른 테스트 (`quick_baa_test.sh`)

단일 포트폴리오를 빠르게 생성하고 요약 정보를 표시합니다.

# 기본 실행 (BAA-G4, $50,000, 현재 날짜)
./quick_baa_test.sh

# 전략 변형 지정
./quick_baa_test.sh BAA-G12

# 전략 + 초기 자본 지정
./quick_baa_test.sh BAA-G4 100000

# 전략 + 초기 자본 + 특정 날짜
./quick_baa_test.sh BAA-G12 75000 2024-01-31

출력 예시:

====== 포트폴리오 요약 ======
기준일: 2025-10-04
모드: offensive
카나리아 bad 개수: 0
총 투자액: $49947.08
잔여 현금: $52.92

====== 포트폴리오 구성 ======
VEA: 818주 @ $61.06 = $49947.08

====== 카나리아 상태 ======
SPY: 모멘텀=8.55%, bad=false
VWO: 모멘텀=10.15%, bad=false
VEA: 모멘텀=8.63%, bad=false
BND: 모멘텀=1.32%, bad=false

C. 개별 curl 명령어 참조 (`BAA_CURL_EXAMPLES.md`)

다양한 curl 명령어 예제와 응답 샘플을 포함한 상세 가이드입니다.

API 엔드포인트

1. 전략 구현체 목록 조회

요청:

GET /api/strategies/implementations/

응답:

{
  "available_implementations": {
    "BoldAssetAllocation": {
      "name": "BoldAssetAllocation",
      "description": "상대 모멘텀과 절대 모멘텀을 결합한 공격적 전술적 자산배분 전략",
      "versions": [...]
    }
  }
}

2. 전략 실행

요청:

POST /api/strategies/execute/
Content-Type: application/json

{
  "strategy_name": "BoldAssetAllocation",
  "version": "1.0.0",
  "parameters": {
    "initial_capital": 50000,
    "variant": "BAA-G4",
    "use_real_data": true,
    "as_of_date": null
  }
}

응답:

{
  "execution_id": 123,
  "status": "pending",
  "message": "Strategy execution started"
}

3. 실행 결과 조회

요청:

GET /api/executions/{execution_id}/

응답 (완료 시):

{
  "execution_id": 123,
  "strategy": "BoldAssetAllocation",
  "version": "1.0.0",
  "status": "completed",
  "started_at": "2025-10-04T10:30:00Z",
  "completed_at": "2025-10-04T10:30:10Z",
  "result": {
    "mode": "offensive",
    "portfolio": [...],
    "canary_status": {...}
  }
}

주요 파라미터

파라미터	필수	기본값	설명
`initial_capital`	✓	100000	초기 자본 (달러)
`variant`	✓	"BAA-G12"	전략 변형 (BAA-G12, BAA-G4, BAA-G12/T3, BAA-G4/T2, BAA-SPY)
`use_real_data`	✓	false	실제 데이터 사용 여부
`as_of_date`	✗	null	기준일 (YYYY-MM-DD 형식, null이면 현재)
`offensive_top`	✗	전략별	공격 유니버스에서 선택할 자산 수
`defensive_top`	✗	3	방어 유니버스에서 선택할 자산 수
`breadth_param`	✗	1	카나리아 임계값

전략 변형별 특징

BAA-G12 (Balanced)

추천 대상: 중위험 선호, 분산 투자
자산 수: 12개 (주식 7 + 대체자산 3 + 채권 2)
선택: Top 6
기대 CAGR: ~14.6%
기대 MaxDD: ~8.7%

./quick_baa_test.sh BAA-G12 100000

BAA-G4 (Aggressive)

추천 대상: 고위험 선호, 집중 투자
자산 수: 4개 (QQQ, VWO, VEA, BND)
선택: Top 1
기대 CAGR: ~21.0%
기대 MaxDD: ~14.6%

./quick_baa_test.sh BAA-G4 100000

BAA-G12/T3

추천 대상: BAA-G12와 G4의 중간
자산 수: 12개
선택: Top 3
기대 CAGR: ~16.4%
기대 MaxDD: ~11.4%

./quick_baa_test.sh BAA-G12/T3 100000

BAA-G4/T2

추천 대상: 적당한 공격성
자산 수: 4개
선택: Top 2
기대 CAGR: ~17.7%
기대 MaxDD: ~12.7%

./quick_baa_test.sh BAA-G4/T2 100000

BAA-SPY

추천 대상: 단순함 선호, SPY 기반
자산 수: 1개 (SPY)
선택: SPY만 사용
기대 CAGR: ~11.4%
기대 MaxDD: ~16.2%

./quick_baa_test.sh BAA-SPY 100000

실행 모드

시뮬레이션 모드 (`use_real_data: false`)

목적: 백테스트 결과 확인
데이터: 1970-2022년 통계 기반
실행 시간: ~2초
결과: CAGR, Sharpe Ratio, Max DD 등 성과 지표

curl -X POST http://localhost:8000/api/strategies/execute/ \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "BoldAssetAllocation",
    "parameters": {
      "variant": "BAA-G12",
      "use_real_data": false
    }
  }'

실제 데이터 모드 (`use_real_data: true`)

목적: 실제 포트폴리오 제안
데이터: yfinance API를 통한 실시간 가격
실행 시간: ~5-15초 (데이터 다운로드 포함)
결과: 티커별 매수 수량, 현재가, 배분액

curl -X POST http://localhost:8000/api/strategies/execute/ \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "BoldAssetAllocation",
    "parameters": {
      "variant": "BAA-G4",
      "initial_capital": 50000,
      "use_real_data": true
    }
  }'

포트폴리오 해석

공격 모드 (Offensive)

카나리아 자산이 모두 양호할 때 활성화됩니다.

특징:

주식 및 성장 자산에 투자
높은 수익 잠재력
선택된 자산에 동일 가중 배분

예시:

{
  "mode": "offensive",
  "canary_bad_count": 0,
  "portfolio": [
    {"ticker": "VEA", "weight": 100.0, "shares": 818}
  ]
}

방어 모드 (Defensive)

카나리아 자산 중 1개 이상이 음수 모멘텀일 때 활성화됩니다.

특징:

채권 및 안전 자산으로 전환
크래시 보호
Top 3 방어 자산 선택

예시:

{
  "mode": "defensive",
  "canary_bad_count": 1,
  "portfolio": [
    {"ticker": "DBC", "weight": 33.33, "shares": 1555},
    {"ticker": "TLT", "weight": 33.33, "shares": 374},
    {"ticker": "LQD", "weight": 33.33, "shares": 327}
  ]
}

워크플로우 예시

월간 리밸런싱 워크플로우

#!/bin/bash
# monthly_rebalance.sh

# 1. 현재 포트폴리오 생성
EXEC_ID=$(curl -s -X POST http://localhost:8000/api/strategies/execute/ \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "BoldAssetAllocation",
    "parameters": {
      "initial_capital": 100000,
      "variant": "BAA-G12",
      "use_real_data": true
    }
  }' | jq -r '.execution_id')

# 2. 실행 완료 대기
sleep 10

# 3. 결과 조회 및 저장
DATE=$(date +%Y%m%d)
curl -s http://localhost:8000/api/executions/${EXEC_ID}/ \
  | jq '.result' > portfolio_${DATE}.json

# 4. 매수 주문 생성 (예시)
jq -r '.portfolio[] | "BUY \(.shares) \(.ticker) @ \(.current_price)"' \
  portfolio_${DATE}.json > orders_${DATE}.txt

echo "Portfolio saved to portfolio_${DATE}.json"
echo "Orders saved to orders_${DATE}.txt"

트러블슈팅

1. "execution_id": null

원인: 전략 이름 또는 파라미터 오류

해결:

# 사용 가능한 전략 확인
curl http://localhost:8000/api/strategies/implementations/

2. "status": "failed"

원인: 파라미터 검증 실패 또는 데이터 다운로드 오류

확인:

curl http://localhost:8000/api/executions/{execution_id}/ | jq '.error_message'

3. 데이터 다운로드 실패

원인: 네트워크 또는 yfinance API 문제

해결:

인터넷 연결 확인
잠시 후 재시도
다른 날짜로 시도

4. 서버 응답 없음

확인:

# 서버 상태 확인
curl http://localhost:8000/api/strategies/implementations/

# Django 서버 로그 확인
python manage.py runserver  # 콘솔 출력 확인

성능 최적화

1. 병렬 실행

여러 전략을 동시에 실행할 수 있습니다:

# 동시 실행
curl -X POST http://localhost:8000/api/strategies/execute/ \
  -d '{"strategy_name":"BoldAssetAllocation","parameters":{"variant":"BAA-G12","use_real_data":true}}' &

curl -X POST http://localhost:8000/api/strategies/execute/ \
  -d '{"strategy_name":"BoldAssetAllocation","parameters":{"variant":"BAA-G4","use_real_data":true}}' &

wait

2. 캐싱 (향후 구현 예정)

동일한 날짜의 반복 요청은 캐시된 데이터를 사용할 수 있습니다.

보안 고려사항

프로덕션 환경

@csrf_exempt 제거 및 CSRF 토큰 사용
API 키 인증 추가
HTTPS 사용
Rate limiting 적용

다음 단계

자동화: cron을 사용한 월간 자동 리밸런싱
알림: 이메일/슬랙 알림 설정
대시보드: 웹 UI 추가
백테스트: 과거 날짜 범위에 대한 성과 분석

지원

문제가 발생하면 다음을 확인하세요:

Django 서버 로그
BAA_CURL_EXAMPLES.md 예제
BAA_STRATEGY_README.md 전략 설명

9.3 KiB Raw Permalink Blame History

BAA 전략 API 사용 가이드

시작하기

1. 서버 실행

2. 준비된 스크립트 사용

A. 전체 예제 실행 (baa_api_examples.sh)

B. 빠른 테스트 (quick_baa_test.sh)

C. 개별 curl 명령어 참조 (BAA_CURL_EXAMPLES.md)

API 엔드포인트

1. 전략 구현체 목록 조회

2. 전략 실행

3. 실행 결과 조회

주요 파라미터

전략 변형별 특징

BAA-G12 (Balanced)

BAA-G4 (Aggressive)

BAA-G12/T3

BAA-G4/T2

BAA-SPY

실행 모드

시뮬레이션 모드 (use_real_data: false)

실제 데이터 모드 (use_real_data: true)

포트폴리오 해석

공격 모드 (Offensive)

방어 모드 (Defensive)

워크플로우 예시

월간 리밸런싱 워크플로우

트러블슈팅

1. "execution_id": null

2. "status": "failed"

3. 데이터 다운로드 실패

4. 서버 응답 없음

성능 최적화

1. 병렬 실행

2. 캐싱 (향후 구현 예정)

보안 고려사항

프로덕션 환경

다음 단계

지원

9.3 KiB

Raw Permalink Blame History

A. 전체 예제 실행 (`baa_api_examples.sh`)

B. 빠른 테스트 (`quick_baa_test.sh`)

C. 개별 curl 명령어 참조 (`BAA_CURL_EXAMPLES.md`)

시뮬레이션 모드 (`use_real_data: false`)

실제 데이터 모드 (`use_real_data: true`)