하이퍼파라미터

하이퍼파라미터를 사용하면 하나의 전략 정의에서 파라미터를 체계적으로 바꿔 가며 백테스트를 실행할 수 있습니다. AQE는 설정된 탐색 범위의 조합을 필요할 때마다 생성하고 순차적으로 실행하며, 정확한 값을 결정론적 시드와 함께 기록합니다. 일반 실행에서는 별도 값이 없을 때 사용할 전략의 기본값을 그대로 유지하므로 이 기능을 추가해도 기존 백테스트 동작은 바뀌지 않습니다.

구성 정의하기

HyperParameterConfig를 만들고 각 파라미터를 한 번씩 등록하세요. values()는 이산적인 값의 집합을 정의하고, range(min, max, increment)는 수치 탐색 범위를 만듭니다. 하이퍼파라미터 플래그를 지정하지 않으면 HyperParameter::new()에 지정한 기본값이 사용됩니다.

use aq_engine::prelude::*;

let mut hyperparameters = HyperParameterConfig::new();
hyperparameters
    .set_sweep_id("ema-crossover-v1")
    .add_hyper_parameter(
        HyperParameter::new("atr_period", 14).values([10, 14, 20]),
    )?
    .add_hyper_parameter(
        HyperParameter::new("ema_period", 21).range(10.0, 30.0, 5.0),
    )?;

set_sweep_id()는 선택 사항입니다. 생략하면 AQE가 구성에서 안정적인 ID를 도출합니다. 알아보기 쉽고 지속적으로 사용할 스윕 폴더 이름이 필요하면 명시적으로 값을 지정하세요.

전략 로직에서 값 사용하기

타입별 헬퍼를 사용해 전략 컨텍스트에서 현재 적용된 값을 읽으세요. 마지막 인수에는 기존과 마찬가지로 별도 값이 없을 때 사용할 기본값을 코드에 직접 지정합니다.

let atr_period = aq_engine::core::strategy::hyperparameters::hyper_int(
    ctx,
    "atr_period",
    14_usize,
);
let ema_period = aq_engine::core::strategy::hyperparameters::hyper_int(
    ctx,
    "ema_period",
    21_usize,
);

알파 모델, 인사이트 파이프, 기타 전략 컴포넌트를 구성할 때 이 값을 사용하세요. AQE의 하이퍼파라미터 예제는 두 입력을 기본 제공 EMA 교차 알파에 연결하고 인사이트 제출 파이프라인을 추가합니다.

실행하기

각 StrategyState에 구성을 연결한 다음 기존 상태 실행기를 그대로 사용하세요. 구성이 없는 상태는 이전과 완전히 동일하게 동작합니다. 구성이 있는 상태는 run_backtest() 또는 run_live() 전에 --hyper-seed를 자동으로 해석합니다.

let mut state = build_strategy_state(timeframe.clone());
state.set_hyper_parameter_config(hyperparameters);
state.run_backtest(start, end, timeframe).await?;

전체 스윕을 실행하려면 hyperparameters.process_runs(&args)를 순회하고, 각 선택에 대해 새 상태를 만든 뒤 set_hyper_parameter_config(config.clone())를 호출하고, 일반적인 run_backtest() 전에 set_hyper_parameter_run(&selection, true)를 호출하세요. 완료된 상태는 변경 가능한 브로커 및 전략 런타임 상태를 소유하므로 다음 시드에 안전하게 재사용할 수 없습니다.

실시간 모드에서도 같은 방식으로 구성을 연결하고 state.run_live(None).await?를 호출하세요. 실시간 모드는 선택한 시드 하나를 자동으로 해석하며 전체 스윕은 거부합니다.

결과 파일 루트 경로는 선택 사항입니다. 지정하지 않으면 결과는 프로세스 작업 디렉터리를 기준으로 기록됩니다. 인접한 전략 메타데이터 위치가 있으면 해당 위치를 기준으로 합니다. 루트 경로가 스윕 여부를 결정하지는 않습니다. 선택한 명령줄 플래그가 이를 결정합니다.

명령줄 플래그

명령	결과
cargo run --release	일반 실행의 기본값으로 한 번 실행합니다.
cargo run --release -- --hyper-sweep	모든 데카르트 곱 조합을 순차적으로 실행합니다.
cargo run --release -- --hyper-seed c89cfd30	저장된 조합 하나를 실행합니다. 고유한 시드 접두사도 허용됩니다.
cargo run --release -- --live --hyper-seed c89cfd30	정확히 해당 파라미터 선택으로 실시간 세션 하나를 시작합니다.

선택한 시드는 생성된 시드 중 정확히 하나와 일치해야 합니다. 접두사가 어떤 실행과도 일치하지 않거나 둘 이상의 실행과 일치하면 AQE는 명확한 오류를 보고합니다. 실시간 세션은 최대 하나의 시드만 허용하므로 --hyper-sweep --live는 거부됩니다. JSON 순열 테이블을 직접 계산하거나 전달할 필요는 없습니다.

결과와 재현성

전체 스윕에서 AQE는 backtests/hyper/<sweep-id>/<seed>/ 아래에 결과를 기록합니다. 각 결과에는 일반 SQLite 백테스트 데이터베이스와 시드 및 최종 적용값이 추가된 지표가 포함됩니다. 동일한 전략 구성과 동일한 시드는 같은 파라미터 선택을 재현합니다. 동일한 성과를 재현하려면 시장 데이터와 비결정론적으로 동작하는 외부 연동의 조건도 일정하게 유지해야 합니다.

AQS에서 사용하기

AlgoQuant Studio를 사용한다면 노드 편집기에서 동일한 탐색 범위를 설정하고 Hyperparameters 사이드바에서 노드 입력을 바인딩하세요. AQS가 AQE 구성을 생성하고 시드 선택을 처리합니다. AQS의 하이퍼파라미터를 참조하세요.