Simon
7e369d9680
「因子组合」/`POST /api/research/backtests` 走的是 `LocalEngine/TopKBacktestRunner`， 上一版只把理由接进了组合引擎，同一件事在两个引擎上就会有两种说法。这次补齐： - `engine.py` / `qlib_adapter/engine.py`：因子面板**只算一次** （`build_factor_panels_full`）→ 复合分与「理由里引用的因子原始值」同源同张面板； 复合分口径逐字未变（与 `selection.score_panel_for_factors` 相同）。 - `local_engine.py`：调仓日保留完整排名与合格集，各站点写入结构化理由 —— 买入（按名次建仓 / 顺延成交 / 涨停 / 停牌 / 现金不足 / 不足最低佣金）、 卖出（全量换仓 / 跌出 TopN / 不在候选池 / 停牌顺延 / 跌停顺延）； `Trade.entry_reason/exit_reason` 两端齐全；每个交易日记录持仓市值， 结果填 `factor_curves`（持仓市值加权平均的因子原始值，空仓日不落点）。 - 新增 `SELL_REBALANCE_FULL`（「调仓换仓卖出」）：单策略调仓是「先全清再建仓」， 被卖出的股票**可能仍排在 TopN 内**（如 rank=1），这时写「跌出 TopN」就是假解释； 按事实分 code（仍在 TopN 内 → 全量换仓；否则 → 跌出 TopN / 不在候选池）。 - 顺延成交不拿挂单日的旧名次冒充当日名次（rank/total/score=None，因子值/成交价/预算 取成交当日真实值）；「候选池不足」的提示记录保持 reason=None（词表里没有对应语义， 硬套就是编理由）。 验证： - 新增 `tests/test_local_engine_reasons.py` 14 条：理由数字对回面板、涨停比值对回行情与 板块规则、停牌/跌停/现金不足/最低佣金、顺延成交、全量换仓 vs 不在池两个分支、 Trade 两端理由、因子曲线市值加权（手算加权值断言 + 等权平均对不上）、空仓不落点。 后端 524 条全过（510 + 14），ruff clean。 - 强回归：用改前引擎并排跑 9 个场景，`signal_history`(日期/方向/成交/原因文案/价格)、 `trades`、`positions`、`summary`、净值/回撤、`unimplemented` 逐条一致 —— 理由与曲线 是纯新增字段，成交行为零变化。
103 lines
4.4 KiB
Python
103 lines
4.4 KiB
Python
"""QlibEngine —— 基于 Qlib 数据管线的研究引擎（QuantEngine 实现）。
|
||
|
||
v1 能力（本阶段已打通并测试）：
|
||
1. provider.build_qlib_dataset：把本地行情按 qlib 二进制格式落盘（data/qlib）
|
||
2. dataset.ensure_qlib_init + D.features：从 QlibDataset 读取行情（真实 qlib 通路）
|
||
3. 在 Qlib 读取的行情面板上执行 TopK 因子回测 → 标准 BacktestResult
|
||
（与 LocalEngine 记账规则一致：无未来函数、成本/涨跌停/停牌近似 + unimplemented 标注）
|
||
|
||
说明：
|
||
- 因子分（score）在源行情上按 app.quant.factors 计算（注册表口径一致）；
|
||
qlib 侧负责数据读取供给（未来可由 Qlib Dataset 直接产出特征）。
|
||
- Alpha158 特征集 + LightGBM 预测信号的模型增强（walk-forward 训练/预测）为下一步
|
||
TODO，详见 docs/ROADMAP.md §2 与 docs/QLIB_VERIFICATION.md。
|
||
- 默认研究引擎仍是 LocalEngine（app/quant/engine.py）；切换只需注入本类。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from pathlib import Path
|
||
|
||
import pandas as pd
|
||
|
||
from app.domain.entities.research import BacktestResult, FactorTestReport, ResearchSpec
|
||
from app.quant.composite import build_factor_panels_full
|
||
from app.quant.engine import QuantEngine
|
||
from app.quant.local_engine import (
|
||
TopKBacktestRunner,
|
||
composite_score,
|
||
run_spec_factor_test,
|
||
)
|
||
from app.quant.qlib_adapter.dataset import ensure_qlib_init, load_close_panel
|
||
from app.quant.qlib_adapter.provider import build_qlib_dataset
|
||
|
||
_ENGINE_NOTE = "QlibEngine v1：本地行情→QlibDataset(bin)→D.features 读取→TopK 因子回测"
|
||
|
||
|
||
class QlibEngine(QuantEngine):
|
||
"""基于 Qlib 数据管线的引擎；因子评估复用共享实现，回测从 QlibDataset 读取行情。"""
|
||
|
||
name = "qlib"
|
||
|
||
# qlib 落盘需要 OHLCV（vwap/factor 由本地合成，不来自行情表）
|
||
_DUMP_COLUMNS = {"open", "high", "low", "close", "volume", "amount"}
|
||
|
||
def __init__(self, qlib_dir: Path | None = None) -> None:
|
||
# 默认落盘到 data/qlib（与 storage.qlib_dir 一致）；可注入临时目录便于测试
|
||
self.qlib_dir = qlib_dir or _default_qlib_dir()
|
||
|
||
def required_columns(self, spec: ResearchSpec) -> set[str]:
|
||
# 回测需把全字段落盘成 qlib 数据集；因子测试走共享实现，只需 close+因子字段
|
||
if spec.type == "backtest":
|
||
return set(self._DUMP_COLUMNS)
|
||
from app.quant.engine import factor_required_columns
|
||
|
||
return factor_required_columns(spec)
|
||
|
||
def run_factor_test(
|
||
self, daily: pd.DataFrame, spec: ResearchSpec, horizon_days: int = 21
|
||
) -> FactorTestReport:
|
||
# 因子评估与数据无关，直接复用共享实现（与 LocalEngine 同口径）
|
||
report, _panels = run_spec_factor_test(daily, spec, horizon_days)
|
||
return report
|
||
|
||
def run_backtest(
|
||
self, daily: pd.DataFrame, spec: ResearchSpec, eligibility_fn=None
|
||
) -> BacktestResult:
|
||
"""回测（与 LocalEngine 共用 TopKBacktestRunner → 口径一致）。
|
||
|
||
`eligibility_fn`（选股条件/时点 ST 过滤）必须透传，否则条件与
|
||
`exclude_st` 在 Qlib 引擎下会被**静默忽略**（AGENT.md §24 禁止假装支持）。
|
||
"""
|
||
# 与 LocalEngine 同口径：复合分与买卖理由/因子曲线用**同一张**原始因子面板
|
||
full = build_factor_panels_full(daily, spec.factors)
|
||
score = composite_score([(d.name, p, w, d.direction) for d, p, w in full])
|
||
factor_panels = {d.name: (d, p) for d, p, _w in full}
|
||
|
||
self.qlib_dir.mkdir(parents=True, exist_ok=True)
|
||
uri = build_qlib_dataset(daily, self.qlib_dir)
|
||
ensure_qlib_init(uri)
|
||
|
||
symbols = [str(s) for s in daily["symbol"].unique()]
|
||
start, end = spec.period
|
||
close = load_close_panel(uri, symbols, start, end)
|
||
if close.empty:
|
||
raise RuntimeError(
|
||
"QlibDataset 读取为空：请检查 build_qlib_dataset 落盘与 provider_uri"
|
||
)
|
||
close = close.sort_index()
|
||
|
||
result = TopKBacktestRunner(
|
||
spec, score, close, eligibility_fn=eligibility_fn, factor_panels=factor_panels
|
||
).run()
|
||
result.config_snapshot = spec.model_dump(mode="json")
|
||
note = _ENGINE_NOTE
|
||
result.unimplemented = [note, *result.unimplemented]
|
||
return result
|
||
|
||
|
||
def _default_qlib_dir() -> Path:
|
||
from app.core.config import PROJECT_ROOT
|
||
|
||
return PROJECT_ROOT / "data" / "qlib"
|