AI 튜토리얼

Calibrain Harness로 트레이딩 분류기 포워드 테스트하기

Calibrain Harness 설치, 모델 및 Bybit 테스트넷 인증 정보 구성, 터미널 실행, 예측 검토, 모의 거래 활성화, 모델 성능 평가와 보정·실행·리스크 제어 적용 방법을 알아봅니다.

2026년 11월 11일약 18분 소요

Calibrain Harness란 무엇인가요?

Calibrain Harness는 고속 분류 모델을 위한 오픈 소스 포워드 테스트 시스템입니다. 지원되는 모델을 무기한 선물 시장 데이터에 연결하고, 마감된 각 캔들에서 라벨링 가능한 질문을 제시하며, 반환된 확률을 기대값으로 변환한 뒤, 조건을 충족하는 거래를 Bybit 테스트넷에서만 선택적으로 실행합니다.

이 프로젝트는 서로 연관된 두 가지 도구, 즉 트레이딩 봇과 모델 평가 하니스를 결합합니다. 거래로 이어지지 않은 예측을 포함해 모든 예측을 저장하고 이후 시장 결과와 비교합니다. 이를 통해 수수료, 슬리피지, 실행, 정책 규칙의 영향을 모델 품질과 분리할 수 있습니다.

중요: Calibrain Harness는 활발히 개발 중인 연구용 소프트웨어이며 금융 조언이 아닙니다. 거래 호스트는 Bybit 테스트넷으로 하드코딩되어 있고 메인넷 전환 기능은 없습니다. 인터페이스, 기본값, 질문 세트는 커밋에 따라 변경될 수 있습니다.

시스템 작동 방식

하니스는 모델에 “매수, 매도 또는 관망”을 답하도록 요청하는 대신, 이후 가격 데이터로 객관적으로 라벨링할 수 있는 질문을 제시합니다. 예를 들어 고정된 기간 동안 양의 목표가와 음의 손절가 중 어느 경계에 먼저 도달하는지를 묻습니다.

메인넷의 공개 시장 데이터, 뉴스, 거시경제 상황, 오더북 정보, 파생상품 데이터를 수집합니다.
특징 생성기가 단위가 표시된 간결한 상태를 만들고, 관련 상품과 가격 구간의 과거 기본 발생률을 추가합니다.
Kairos 또는 Jev가 해당 상태와 유형이 지정된 7개의 라벨링 가능한 질문을 받습니다.
응답을 엄격하게 검증합니다. 유효하지 않은 응답은 부정적 예측으로 해석하지 않고 오류로 기록합니다.
보정 계층을 통해 모델 확률과 과거 기본 발생률을 결합합니다.
정책이 R 단위의 기대값을 계산하고 진입 조건을 적용하며 리스크 규모를 결정합니다.
자동 거래가 활성화되어 있으면 조건을 충족하는 주문을 Bybit 테스트넷으로 전송합니다.
평가 및 보고를 위해 요청, 응답, 라벨, 실행 기록, 거래를 SQLite에 저장합니다.

테스트넷 시장 데이터는 합성 데이터이거나 메인넷과 다를 수 있으므로 신호와 라벨에는 메인넷 데이터를 사용합니다. 다만 주문은 테스트넷에서만 실행하며, 테스트넷에서 이용 가능한 호가 깊이에 따라 규모를 결정합니다.

주요 기능

다중 분류 모델

현재 하니스는 Minara Cloud를 통해 DMind가 제공하는 Kairos와 TypeSafe가 제공하는 Jev를 지원합니다. 두 모델 모두 동일한 System One 요청 형식, 질문 세트, 검증, 정책 및 평가 파이프라인을 사용합니다.

의사 결정, 보정 가중치, 평가, 보고서는 모델별로 분리되어 유지됩니다. 라이브 모델 전환은 새로운 실행 기록을 시작하며 봇이 포지션을 보유하지 않은 상태에서만 허용되어 서로 다른 모델의 결과가 섞이지 않도록 합니다.

블룸버그 스타일 터미널

Next.js 터미널은 하나의 WebSocket을 통해 실시간 업데이트를 수신합니다. 차트, 모델 신호, 보정 및 원시 기대값, 포지션, 계정 정보, 오더북 및 깊이 뷰, 시장 맵, 뉴스, 청산, 파생상품 데이터, 그리고 각 모델 요청과 응답이 포함된 의사 결정 블로터를 제공합니다.

내장 보정 및 평가

Calibrain Harness는 w · model + (1 − w) · base rates 공식을 사용해 모델 확률과 상품별 기본 발생률을 결합합니다. 가중치는 0.5에서 시작하며, 질문에 라벨이 지정된 결과가 최소 100개 누적되면 15분마다 재적합됩니다.

평가에는 Brier 점수와 순위 확률 점수, 기후 기준 및 제공된 기본 발생률 대비 성능, AUC, 신뢰도, 기대 보정 오류, 확률 적분 변환 분석, 기대값 순위, 일관성 프로브, 실행 품질, 실행 기록별 거래 결과가 포함됩니다.

테스트넷 실행 제어

진입에는 테스트넷 최우선 가격 대비 상한이 설정된 IOC 지정가 주문을 사용합니다. 목표가는 리듀스 온리 지정가 주문으로 대기할 수 있으며, 관리형 손절가는 메인넷의 실행 가능한 가격을 사용해 트리거되고 테스트넷에서 상한이 설정된 리듀스 온리 IOC 주문으로 청산됩니다. 또한 시간 손절, 마크 가격 백스톱, 일일 손실 한도, 포지션 한도, 포트폴리오 리스크 한도, 킬 스위치를 제공합니다.

사전 요구 사항

설치 전에 다음을 준비하세요.

Python 3.12.
npm이 포함된 Node.js 20 이상.
Minara Cloud의 Kairos API 키 또는 TypeSafe 콘솔의 Jev API 키.
Bybit 테스트넷 API 관리에서 발급한 Bybit 테스트넷 API 인증 정보.

Bybit 키에는 주문 및 포지션을 위한 Contract 권한이 있어야 합니다. 출금 권한은 부여하지 마세요.

Calibrain Harness 설치

1. 저장소 복제

git clone https://github.com/zadescoxp/calibrain-harness.git
cd calibrain-harness

2. Python 환경 생성

Python 3.12 가상 환경을 생성하고 종속 항목을 설치한 다음 예시 설정을 복사합니다.

python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env

.env에 인증 정보를 추가하거나 나중에 터미널의 KEYS 명령으로 입력하세요. 애플리케이션은 이 파일에서 키를 읽습니다. 이 파일은 gitignore에 포함되어 있으며 소유자만 접근할 수 있는 권한으로 설정하는 것이 전제됩니다. 키는 데이터베이스에 저장되지 않으며 브라우저로 전체 내용이 전송되지도 않습니다.

3. 터미널 UI 빌드

cd web-next
npm ci
npm run build
cd ..

이 명령으로 web-next/out에 정적 터미널이 생성됩니다. Python 서비스가 UI, API, WebSocket을 제공하므로 별도의 프로덕션 Node.js 프로세스는 필요하지 않습니다.

4. 서비스 시작

.venv/bin/python -m ctb.server

http://127.0.0.1:8800을 엽니다. 서버는 로컬에서 127.0.0.1에 바인딩되며 교차 출처 쓰기를 거부합니다.

UI가 아직 빌드되지 않은 경우 해당 주소에 빌드 명령이 포함된 짧은 페이지가 표시됩니다. API와 실시간 WebSocket은 계속 사용할 수 있습니다.

모델 및 인증 정보 구성

.env에서 CTB_MODEL_PROVIDER를 사용해 Kairos 또는 Jev를 선택합니다.

CTB_MODEL_PROVIDER=kairos
KAIROS_API_KEY=your_kairos_key

Jev의 경우 다음을 사용합니다.

CTB_MODEL_PROVIDER=jev
TYPESAFE_API_KEY=your_typesafe_key
CTB_JEV_MODEL=jev-1.14.0

문서에 명시된 Jev 모델은 jev-1.14.0으로 고정되어 있지만, CTB_JEV_MODEL로 재정의할 수 있습니다. Kairos 인증 정보는 Kairos가 활성화된 Minara Cloud 그룹에 속해야 합니다.

.env.example에 제공된 변수 이름을 사용해 Bybit 테스트넷 인증 정보를 추가합니다. .env 또는 data/ 아래의 파일을 커밋하지 마세요.

먼저 관찰 전용 모드로 실행

봇은 주문을 실행하지 않는 상태로 시작합니다. 이 모드에서는 시장 데이터를 계속 수집하고, 선택한 모델을 호출하며, 결정을 기록하고, 예측에 레이블을 지정합니다. 연결 상태를 확인하고 테스트넷 포지션을 열지 않은 채 모델 동작을 분석할 수 있으므로 권장되는 시작 방식입니다.

Python 서비스를 시작합니다.
127.0.0.1:8800에서 터미널을 엽니다.
시장 데이터와 모델 결정이 표시되는지 확인합니다.
LOG 및 EVAL 화면에서 오류와 지연 시간을 확인합니다.
설정이 올바르게 작동할 때만 AUTO-TRADE를 활성화합니다.

터미널 사용

주요 화면

MON, F1: 관심 목록, 차트, 모델 마커, 계정, 포지션, 시장 맵, 호가창, 뉴스, 파생상품, 흐름 데이터 및 결정 내역을 표시합니다.
EVAL, F2: 보정, 조사 결과, EV 순위, 질문 점수, 일관성 프로브, 운영 지표, 손익 및 실행 품질을 표시합니다. 결과는 모델, 실행, 심볼, 질문 세트 및 시간대별로 필터링할 수 있습니다.
TRADES, F3: 기준 가격, 체결, 슬리피지 및 정확한 R을 포함한 개별 실행과 거래를 나열합니다.
NEWS, F4: 헤드라인과 Kairos news_return 예측을 표시합니다. 뉴스 수익률 예측은 Kairos에서만 사용할 수 있습니다.
LOG, F5: 시스템 이벤트와 오류를 표시합니다.

명령줄 예시

/를 눌러 터미널 명령줄을 엽니다. 일반적인 명령은 다음과 같습니다.

심볼을 불러오려면 BTC 또는 ETH를 입력합니다.
모델을 즉시 조회하고 일관성 프로브를 실행하려면 ASK 또는 PRB를 입력합니다.
차트 시간대를 변경하려면 1M부터 4H까지 입력합니다.
거래 시간대를 설정하려면 TF 5M을 입력합니다.
심볼 유니버스를 선택하려면 UNIV를 입력합니다.
최대 포지션 수를 설정하려면 POS 10을 입력합니다.
인증 정보를 관리하려면 KEYS를 입력합니다.
터미널 도움말을 표시하려면 HELP를 입력합니다.

기능 키 바의 MODEL을 통해 Kairos와 Jev 사이를 전환할 수 있습니다. 전환하기 전에 봇의 포지션이 모두 청산되어 있어야 합니다.

테스트넷 거래를 신중하게 활성화

결정을 관찰하고 설정을 검증한 후 명령 모음에서 AUTO-TRADE를 사용해 테스트넷 주문을 허용합니다. 엄격 모드에서는 최소 기대값, 설정 품질, 방향 일치, 수익률 분포 일치, 거래소 간 차이, 포지션 상태 및 숏 포지션 권한을 포함한 구성된 모든 조건을 통과한 보정 예측이 있을 때만 거래합니다.

탐색 모드는 기본적으로 비활성화되어 있습니다. CTB_EXPLORATION=1로 설정하면 엄격한 조건이 거래를 차단할 때 시스템이 감소된 위험으로 모델이 선호하는 방향으로 거래할 수 있습니다. 이 기능의 목적은 실제 실행 데이터를 수집하는 것이며, 엄격한 정책이 긍정적인 엣지를 발견했다는 의미가 아닙니다.

테스트넷 유동성은 매우 부족할 수 있으며 메인넷과 다르게 작동할 수 있습니다. 프로젝트의 초기 선행 테스트에서는 실행 품질이 테스트넷 손익을 좌우할 수 있음이 확인되었습니다. 테스트넷 결과를 향후 수익성의 증거가 아닌 연구 데이터로 취급하세요.

킬 스위치 사용

터미널의 KILL 버튼은 봇 포지션을 청산하고 주문을 취소하며 시스템을 중지합니다. 프로젝트 디렉터리에서 다음 명령으로도 같은 작업을 실행할 수 있습니다.

touch KILL

테스트넷에서 수동으로 연 포지션은 일반적으로 표시되지만 봇이 관리하지는 않습니다. 킬 스위치는 문서화된 예외입니다.

테스트 및 스모크 검사 실행

네트워크에 연결하지 않고 단위 테스트를 실행합니다.

.venv/bin/python -m pytest -q tests

활성 모델에 실제 요청을 하나 보내고 응답을 검증합니다.

.venv/bin/python scripts/kairos_smoke.py SOLUSDT

Jev를 명시적으로 대상으로 지정합니다.

.venv/bin/python scripts/kairos_smoke.py SOLUSDT --model jev

롱 포지션을 열고 손절가를 확인한 다음 포지션을 청산하여 최소 규모의 테스트넷 실행 경로를 테스트합니다.

.venv/bin/python scripts/testnet_smoke.py SOLUSDT long

이러한 스모크 스크립트는 실제 외부 요청을 실행하므로 실행하기 전에 선택한 심볼과 인증 정보를 확인하세요.

중요한 구성 옵션 이해

결정 시점 및 브래킷

CTB_DECISION_TF의 기본값은 5이며, 5분 봉이 마감된 후 의사결정을 내립니다.
CTB_HORIZON_BARS의 기본값은 24이며, 기본 타임프레임에서 2시간의 예측 구간을 생성합니다.
CTB_ATR_TF의 기본값은 15이며, 손절 크기 계산에 사용됩니다.
CTB_SL_ATR 및 CTB_TP_ATR의 기본값은 각각 1.5 및 2.5 ATR입니다.
CTB_MIN_SL_BP 및 CTB_MAX_SL_BP는 기본적으로 손절 거리를 40~300 베이시스 포인트로 제한합니다.

엄격한 정책 게이트

CTB_MIN_EDGE_R=0.15는 기본 최소 보정 엣지를 설정합니다.
CTB_MIN_SETUP_QUALITY=1.5는 셋업 품질 임계값을 제어합니다.
CTB_MIN_DIRECTION_MARGIN=0.03은 보정된 방향이 지정된 마진 이상으로 제안된 포지션 방향과 일치하도록 요구합니다.

위험 한도

CTB_RISK_PER_TRADE_PCT=0.5는 손절이 실행될 경우 손실되도록 설정한 자기자본 대비 비율을 정의합니다.
CTB_MAX_POSITIONS, CTB_MAX_SAME_SIDE, CTB_MAX_OPEN_RISK_PCT는 포트폴리오 익스포저를 제한합니다.
CTB_MAX_LEVERAGE=3 및 CTB_MAX_NOTIONAL_USDT=5000은 기본적으로 하드 캡을 제공합니다.
CTB_DAILY_LOSS_LIMIT_PCT=3은 기본 일일 손실 한도를 설정합니다.

비용 및 실행

CTB_TAKER_FEE_BP=5.5 및 CTB_SLIPPAGE_BP=2는 기대값과 라벨에 사용되는 비용 모델에 반영됩니다.
CTB_MAX_ENTRY_SLIP_BP=10은 기본 진입 가격 한도를 설정합니다.
CTB_EXIT_MODE=managed는 문서화된 관리형 청산 프로세스를 활성화합니다.

정책을 비교할 때는 한 번에 하나의 설정 그룹만 변경하고 새 실행을 시작하세요. 각 실행은 구성을 스냅샷으로 저장하므로 이후 분석이 더 쉬워집니다.

고급 평가 팁

모델과 기준선 비교

수익성이 있어 보이는 예측이 자동으로 유용한 것은 아닙니다. 모델이 기후학적 기준과 입력에 포함된 정확한 과거 기준 발생률을 능가하는지 검토하세요. 라벨링된 결과에서 모델이 추가 정보를 거의 제공하지 않는 것으로 나타나면 보정 계층이 모델의 영향력을 줄입니다.

예측 역량과 거래 결과 분리

거래뿐 아니라 라벨이 지정된 모든 의사결정을 검사하려면 EVAL을 사용하세요. 예측 지표는 모델의 확률적 역량을 측정하는 반면, 테스트넷 P&L은 모델, 정책, 비용, 위험 규모 산정 및 실행이 결합된 결과를 측정합니다.

중복되는 의사결정 고려

라벨은 각 의사결정 후 첫 번째 1분 봉부터 시작하여 미래 정보 참조를 방지합니다. 한 봉이 목표가와 손절가에 모두 닿으면 해당 라벨은 손절로 집계됩니다. 그러나 연속된 의사결정의 예측 구간이 서로 겹칠 수 있으므로 원시 샘플 수는 통계적 독립성을 과대평가할 수 있습니다. README는 결론을 도출하기 전에 심볼당 수백 건의 라벨링된 의사결정이 누적될 때까지 기다릴 것을 권장합니다.

일관성 검사

반복 프로브를 사용하여 결정성을 측정하고, 미러 프로브를 사용하여 강세 및 약세 시장 특성을 반전했을 때 모델의 답변이 적절하게 바뀌는지 확인하세요. 또한 하나의 고립된 지표에 의존하지 말고 롱과 숏 간의 일관성을 검토하세요.

보고서 내보내기

EVAL에서 EXPORT MINARA REPORT를 사용하면 평가 결과가 포함된 Markdown 보고서를 작성할 수 있습니다. 비교 결과를 해석하기 전에 모델, 실행, 심볼, 질문 세트 또는 타임프레임으로 필터링하세요.

심볼 및 실행 관리

UNIV 명령은 거래대금 기준 상위 100개까지의 USDT 무기한 계약 중 테스트넷에 상장된 종목을 나열합니다. 유동성 및 스프레드 정보를 포함하며, 호가창이 얇은 종목과 주식 또는 원자재 무기한 계약을 표시합니다. 모델 요청 예산에 따라 최대 30개의 심볼을 선택할 수 있습니다. 유니버스 변경을 적용하기 위해 서비스가 자체적으로 재시작됩니다.

모든 의사결정과 거래는 활성 실행에 할당됩니다. 프로그래밍 방식으로 실행을 생성하려면 봇 거래가 열려 있지 않을 때 POST /api/runs/start를 전송하세요. 모델, 질문, 위험 규칙 또는 실행 설정을 변경할 때 별도의 실행을 시작하면 유용합니다.

UI 작업

변경 사항을 가져오거나 프런트엔드를 수정한 후 정적 내보내기를 다시 빌드하세요.

cd web-next && npm run build

그다음 브라우저를 새로고침하세요. Python 서버를 다시 시작할 필요는 없습니다.

실시간 새로고침 개발을 진행하려면 Python 서버를 실행한 상태로 Next.js를 별도로 시작하세요.

cd web-next && npm run dev

http://localhost:3000을 여세요. 개발 UI는 127.0.0.1:8800의 API 및 WebSocket과 통신합니다.

다음 명령으로 프런트엔드의 타입을 검사하세요.

cd web-next && npx tsc --noEmit

안전 및 운영 관행

호스트가 api-testnet.bybit.com으로 유지되는지 확인하세요. 이 프로젝트에는 의도적으로 메인넷 거래 전환 기능이 없습니다.
관찰 전용 모드로 시작하고 테스트넷 주문을 활성화하기 전에 모델 오류를 검토하세요.
출금 권한이 없는 Bybit 자격 증명을 사용하세요.
.env 및 data/ 디렉터리가 버전 관리에 포함되지 않도록 하세요.
P&L만 고려하지 말고 거래소 간 차이, 체결 비율, 지연 시간, 슬리피지 및 청산 사유를 모니터링하세요.
실행을 테스트하기 전에 킬 스위치 절차에 쉽게 접근할 수 있도록 하세요.
변경 사항을 제출하기 전에 Python 테스트와 프런트엔드 타입 검사를 실행하세요.

결론

Calibrain Harness는 빠른 분류 모델이 무기한 시장 예측에 측정 가능한 정보를 추가하는지 확인할 수 있는 체계적인 방법을 제공합니다. 객관적인 질문, 과거 기준 발생률, 확률 보정, 엄격한 검증, 테스트넷 실행 및 상세한 평가를 하나의 로컬 터미널에서 결합합니다.

먼저 서비스를 설치하고 Kairos 또는 Jev 중 하나를 구성한 다음, 관찰 전용 의사결정 데이터를 수집하세요. 데이터 및 모델 파이프라인이 안정화되면 Bybit 테스트넷에서 실행을 신중하게 테스트하고, 실행을 서로 분리하며, 단기 손익에 의존하지 말고 충분한 샘플을 바탕으로 모델을 기준선과 비교해 평가하세요.