ml4t-backtest

PyPI

License: MIT

설정 가능한 실행(execution), 회계(accounting), 위험(risk), 그리고 프레임워크 동등성 검증(framework-parity validation)을 갖춘 양적 전략(quantitative strategies)의 이벤트 기반 백테스팅(Event-driven backtesting).

ML4T 라이브러리 생태계의 일부

이 라이브러리는 Machine Learning for Trading에서 설명하는 트레이딩을 위한 머신러닝 워크플로우를 지원하는 6개의 상호 연결된 라이브러리 중 하나입니다:

이들은 데이터 인프라(data infrastructure), 피처 엔지니어링(feature engineering), 모델링(modeling), 시그널 평가(signal evaluation), 전략 백테스팅(strategy backtesting), 그리고 실시간 배포(live deployment)를 포괄합니다.

이 라이브러리가 하는 일

백테스팅은 주문 실행, 포지션 추적, 위험 관리를 정확하게 시뮬레이션하는 것을 필요로 합니다. ml4t-backtest는 다음 기능을 제공합니다:

• 포인트 인 타임 정합성(point-in-time correctness)을 갖춘 이벤트 기반 아키텍처 (룩어헤드 바이어스 없음)
• 실제 브로커의 동작과 일치하는 엑싯 우선 주문 처리(Exit-first order processing)
• 설정 가능한 실행 모드 (same-bar 또는 next-bar 체결)
• price, bid, ask, midpoint, 그리고 측면(side)-인식 소스를 이용한 인용지 인식 실행 및 마킹
• 포지션 수준의 위험 규칙 (손절매(stop-loss), 이익실현(take-profit), 트레일링 스톱)
• 포트폴리오 수준의 제약 조건 (최대 포지션, 손실폭 제한(drawdown limits))
• 현금(Cash), 증거금(margin), 그리고 암호화폐 계정 정책
• 감사 및 다운스트림 분석을 위한 1급 트레이드(trade), 체결(fill), 및 포트폴리오 상태 내보내기(export)
• 프레임워크별 동등성을 위한 40개 이상의 동작 노브(behavioral knobs)

백테스팅에 사용된 동일한 Strategy 클래스는 프로덕션 배포를 위해 ml4t-live에서도 변경 없이 작동합니다.

설치

ml4t-backtest는 Linux, macOS, 그리고 Windows에서 CPython 3.12, 3.13, 및 3.14를 지원합니다.

uv add ml4t-backtest

핵심 패키지와 빠른 시작은 외부 서비스나 특별한 하드웨어를 필요로 하지 않습니다. 선택적 추가 기능(Optional extras)은 기능별로 격리되어 있습니다.

uv add 'ml4t-backtest[viz]' # Plotly, Matplotlib, and Dash 보고서
uv add 'ml4t-backtest[advanced]' # 그래프 라우팅 및 포트폴리오 최적화
uv add 'ml4t-backtest[comparison]' # 공개 프레임워크 비교 종속성

비교용 추가 패키지에는 라이선스가 필요한 VectorBT Pro 또는 컨테이너화된 LEAN 엔진은 포함되어 있지 않습니다.
해당 검증 환경은 자체 레포지토리 접근 권한이나 컨테이너 런타임이 필요하며, 일반적인 라이브러리 사용 범위에 속하지 않습니다. 지원되는 설정 경로는 설치 가이드를 참조하십시오.

빠른 시작 (Quick Start)

첫 번째 백테스트는 내장된 합성 데이터를 사용하며 모든 체결(fill)을 설명합니다. 이후 튜토리얼 시퀀스에서는 주문, 다중 자산 포트폴리오, 비용, 계정 규칙, 위험 관리 및 결과를 다룹니다.

from datetime import datetime

import polars as pl
...

각 Engine 인스턴스는 단일 사용(single-use)입니다. 독립적인 실행이 필요할 때마다 새 인스턴스를 생성해야 합니다.

`bar[

Quote-Aware Execution

from ml4t.backtest import BacktestConfig, DataFeed
from ml4t.backtest.config import ExecutionPrice

...

QUOTE_SIDE를 사용하면 견적(quote)이 있을 때 매수(buys)는 ask에서 체결되고 매도(sells)는 bid에서 체결됩니다. mark_price는 별도로 설정할 수 있으므로, 한 소스에서 거래하고 다른 소스에서 장부(book)를 표시(mark)할 수 있습니다.

견적 인식(Quote-aware) 실행은 결과 표면(result surface)에 미시구조(microstructure) 컨텍스트도 보존합니다:

• result.to_fills_dataframe()에는 bid/ask/midpoint/spread/size 컨텍스트가 포함됩니다.
• result.to_trades_dataframe()에는 결측값 허용(nullable) 진입/퇴장 견적 요약이 포함됩니다.
• result.to_portfolio_state_dataframe()는 시간이 지남에 따라 설정된 표시 소스(mark source)를 반영합니다.
• result.to_predictions_dataframe()는 후속 진단(downstream diagnostics)을 위해 원시 모델/입력 표면을 보존합니다.

Reproducible Config Snapshots

BacktestConfig는 또한 직렬화 가능한 백테스트 사전 설정 표면입니다. 입력 설정을 희소하게 유지한 다음, 실제로 실행된 완전히 해결된(fully resolved) 구성을 영구 저장할 수 있습니다.

config = BacktestConfig.from_yaml("config/my_backtest.yaml")
result = Engine(feed, strategy, config).run()

...

내보내진 결과 디렉터리에는 다음이 포함됩니다:

• config.yaml: 재생 가능한 해결된 구성 페이로드(replayable resolved config payload)
• spec.yaml: 라이브러리 버전 및 실현된 실행 기간을 포함하는 더 풍부한 런타임 스냅샷

일반적인 피드 의미론(generic feed semantics)에는 최상위 feed를, 사용자 정의 출처(user-defined provenance)와 같은 입력 경로 또는 전략 ID에는 최상위 metadata를 BacktestConfig에서 사용하십시오.

Commission and Slippage

from ml4t.backtest import BacktestConfig, CommissionType
from ml4t.backtest.config import SlippageType, SpreadConvention

...

Multi-Asset Rebalancing

from ml4t.backtest import Strategy, TargetWeightExecutor, RebalanceConfig

class WeightStrategy(Strategy):
...

RebalanceConfig는 min_trade_value와 min_weight_change를 기본값으로 0.0으로 설정하므로, 이 필터들은 선택적 활성화(opt-in)입니다.

BacktestConfig()는 기본적으로 중립 비용(neutral costs)을 사용합니다: commission_type=NONE 및 slippage_type=NONE. 증권사별 수수료 모델과 합성 슬리피지(synthetic slippage)는 선택적입니다.

크로스 프레임워크 검증 (Cross-Framework Validation)

주요 감사(audit)는 ETF 할당, CME 선물, 암호화폐 무기한 펀딩(crypto perpetual-funding), 외환(FX), 그리고 미국 주식 패널 사례 연구에서 고정된 데이터와 목표값을 사용합니다. 프로필은 프레임워크별 실행 동작을 구성하며, 실제로 지원되는 프레임워크 및 자산 조합만이 필요합니다. 실전 전략 게이트는 17개의 필수 쌍을 다루고 8개의 미지원 쌍을 별도로 기록합니다.

시나리오 매트릭스와 250개 자산 워크로드는 여전히 유용한 합성 진단 및 스트레스 테스트입니다. 이들은 현실적인 전략 동등성(strategy equivalence)을 확립하지는 않습니다.

실전 전략 감사 (Real-strategy audit)

17개 필수 쌍 모두 통과했으며, 8개 쌍은 미지원으로 선언되었습니다. 이 감사는 고정된 과거 시장 데이터와 모델에서 파생된 목표값을 사용하는 다섯 가지 실제 데이터 전략 워크로드를 사용합니다. 통과하려면 동일한 평가 타임스탬프 커버리지, 수량(quantities)이 $10^{-5}$에서 같고 가격(prices)이 $10^{-8}$에서 같은 완전한 체결 스트림(complete fill streams), 그리고 동일한 센트 단위로 반올림되는 계정 금액(account monetary values)이 필요합니다. FX 워크로드는 고정된 목표값 스트림에 USD로 표시된 쌍을 사용하므로 모든 필수 엔진은 네이티브 USD 평가를 사용합니다.

패리티 프로토콜(parity protocol)은 양쪽 모두에서 거래 비용과 포지션 규칙을 비활성화합니다. 이는 목표 크기 결정(target sizing), 주문 순서 지정(order sequencing), 체결, 현금 및 증거금 동작(cash and margin behavior), 해당되는 경우 펀딩, 그리고 평가를 테스트합니다. 이 프로토콜은 선택된 각 사례 연구 생산 결과(case-study production result)와 그 원래 비용 및 위험 오버레이를 재현한다고 주장하지 않습니다.

실제 전략 엔진 성능 (Real-strategy engine performance)

이 표는 17개의 정확성 통과 쌍에 대한 모든 엔진 호출의 벽 시간(wall time)을 보고합니다. 비율은 프레임워크 중앙값 / ML4T 중앙값입니다. 값이 1보다 크면 ML4T가 엔진 호출을 더 빠르게 완료했음을 의미합니다.

합성 진단 시나리오 (Synthetic diagnostic scenarios)

시나리오 매트릭스는 합성 일치성 테스트(synthetic conformance tests)를 포함합니다.

방법론 및 상세 결과는 validation/README.md를 참조하십시오.

릴리스 게이트 명령어:

# 빠른 패리티 계약 게이트 (vectorbt/backtrader/zipline 전반의 시나리오 01)
ML4T_COMPARISON_INPROC=1 uv run pytest tests/contracts/test_cross_engine_contracts.py -q

...

성능

릴리스 성능 증거는 결정론적 단일 자산, 250개 자산 일별, 견적 인식(quote-aware), 리밸런싱, 그리고 부분 체결 워크로드를 다룹니다. 각 워크로드는 신규 자식 프로세스에서 세 번 실행됩니다. 250개 자산 워크로드는 주기적으로 50 포지션 포트폴리오에 진입하고 나갑니다. 증거는 설정(setup)과 Engine.run()을 분리하고, 전체 자식 프로세스에 걸친 최대 RSS를 측정하며, 실행 시간 및 메모리 샘플 분포를 보고하고, 보존된 금융 출력 체크섬 및 카운트를 검증합니다. 전용 상품 비포함 핫패스(instrument-free hotpath) 벤치마크는 실행 시간 회귀 제한을 강제합니다.

릴리스 기준선과 상품 비포함 피드 회귀 검사를 로컬에서 실행하십시오:

워크로드 정의와 예상 체크섬은 validation/performance_baselines.json에 유지됩니다. 이 ML4T 전용 측정값들은 크로스 머신 성능 주장(cross-machine performance claims)이 아닌 회귀 기준선(regression baselines)입니다.