nj-quant

🍥 A 股市场量化轮转交易系统

简体中文 | English

快速开始 • 核心功能 • 架构 • 参数优化 • 相关文档

---

📝 项目说明

Note

本项目仅供个人学习与研究使用，不对稳定性、技术支持做任何保证 用户须遵守所使用数据源的条款及适用法律，不得用于非法用途

---

🚀 快速开始

环境准备

# 克隆项目
git clone https://github.com/noahjzc/nj-quant.git
cd nj-quant

# 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt
pip install optuna scipy  # 未纳入 requirements.txt

配置文件

# 创建数据库配置（必须）
# 复制 config/database.ini.example 或手动创建
# 格式：标准 INI，[postgresql] 节含 host/port/database/user/password

运行回测

# 单次回测（默认使用 Parquet 缓存）
python backtesting/run_daily_rotation.py --start 2024-01-01 --end 2024-12-31

# 无缓存直查数据库
python backtesting/run_daily_rotation.py --start 2024-01-01 --end 2024-12-31 --no-cache

# 使用优化参数
python backtesting/run_daily_rotation.py --start 2024-01-01 --end 2024-12-31 \
    --config output/best_params_xxx.json

# 使用 ML 排名器
python backtesting/run_daily_rotation.py --start 2024-01-01 --end 2024-12-31 \
    --ml-model models/lightgbm_model.pkl

参数优化

# 单期优化
python optimization/optuna/run_daily_rotation_optimization.py \
    --mode single --start 2024-01-01 --end 2024-12-31 --trials 100

# Walk-Forward 优化
python optimization/optuna/run_daily_rotation_optimization.py \
    --mode walkforward --start 2022-01-01 --end 2024-12-31 --trials 50

# 基于稳健性筛选
python optimization/optuna/run_daily_rotation_optimization.py \
    --mode walkforward --start 2022-01-01 --end 2024-12-31 \
    --trials 50 --select-by-robustness

Web 看板

cd web/frontend
npm install
npm run dev
# 访问 http://localhost:3000

测试

pytest tests/ -v
pytest tests/strategy/rotation/test_compute_signal_masks.py -v

---

✨ 核心功能

🎨 回测与引擎

功能	说明
每日轮转回测引擎	向量化信号生成，两阶段交易执行，市场状态检测
Master DataFrame 缓存	30+ 天历史预加载，滚动窗口，避免重复 I/O
市场状态检测	strong / neutral / weak 三档自动识别
信号引擎	14 种买入/卖出信号类型，OR / AND 双模式
两阶段执行	先卖后买，融合市场状态感知仓位管理

📈 Alpha158 因子库

功能	说明
KBar 因子	9 个 OHLC 蜡烛形态因子（KMID, KLEN, KUP, KLOW, KSFT 等）
价格因子	OPEN0, HIGH0, LOW0 共 3 个
滚动因子	5 窗口 × 29 算子 = 145 个（动量、波动率、趋势、成交量等）
因子处理器	rank / zscore / winsorize / 方向感知加权
无 Qlib 依赖	纯 Python 实现，156 个因子全自包含

⚙️ Optuna 参数优化

功能	说明
TPE 贝叶斯优化	Tree-structured Parzen Estimator，14 个参数同时优化
Walk-Forward	滚动窗口 + 参数向前携带
稳健性筛选	Monte Carlo + CSCV + Deflated Sharpe 综合评分
Parquet 缓存	跨 Trial 复用，分钟级完成百次试验

🤖 ML 排名器

功能	说明
LightGBM 推理	替代 z-score 多因子加权排名，接口兼容
自动特征对齐	推理时自动检测模型所需因子名
宽松容错	缺失特征超过 30% 才报警告
训练流水线	strategy/ml/train.py 一键训练

🔒 稳健性检验

功能	说明
Monte Carlo	Bootstrap 重采样，估计 Sharpe 95% CI
CSCV	Combinatorial Symmetrical CV，估计过拟合概率
Deflated Sharpe	多重检验校正，调整乐观偏差

📊 Web 看板

功能	说明
信号管理	确认/跳过实盘信号
持仓概览	持仓明细、资金日志
数据浏览	股票数据检索
定时任务	Cron 执行状态监控

---

🏗 架构

nj-quant/
├── core/                        # 公共逻辑（无项目依赖）
│   ├── cost_model.py           # 交易成本（印花税/过户费/佣金/滑点/冲击成本）
│   ├── market_constraints.py   # 市场约束（涨跌停/ST/停牌/T+1）
│   ├── stop_loss_strategies.py # 止损止盈（ATR/移动止损/止盈）
│   └── position_manager.py     # 统一仓位管理
│
├── backtesting/                 # 回测框架
│   ├── run_daily_rotation.py   # 入口脚本（CLI + 结果导出 + 稳健性检验）
│   ├── analysis/               # 绩效分析（收益/Sharpe/Sortino/Calmar/回撤/月度收益）
│   └── visualizer.py           # Matplotlib 图表 + HTML 报告
│
├── strategy/                    # 策略定义
│   ├── rotation/              # 每日轮转核心引擎
│   │   ├── daily_rotation_engine.py   # Master DataFrame 缓存，向量化信号
│   │   ├── config.py                 # RotationConfig dataclass
│   │   ├── market_regime.py          # 市场状态检测
│   │   ├── signal_engine/
│   │   │   ├── signal_filter.py      # 14 种信号类型
│   │   │   └── signal_ranker.py     # z-score 多因子排名
│   │   └── ...
│   ├── factors/               # Alpha158 因子库
│   │   ├── alpha158.py        # 156 因子全实现
│   │   └── factor_utils.py    # rank/zscore/winsorize
│   └── ml/                   # LightGBM 排名器
│
├── data/                      # 数据层
│   ├── providers/             # DataProvider（直连 DB）/ CachedProvider（Parquet）
│   ├── cache/                # Parquet 批量缓存
│   ├── db/                   # SQLAlchemy ORM
│   └── sync/                 # AKShare / Tushare / Baostock 数据同步
│
├── optimization/optuna/        # Optuna TPE 优化
├── signal_pipeline/           # 实盘信号管线
├── robustness/               # Monte Carlo / CSCV / Deflated Sharpe
├── web/                      # FastAPI + React 看板
└── tests/                    # 测试套件（27 个测试文件）

详细说明见 CLAUDE.md。

---

⚙️ 参数优化

14 个优化参数：

参数组	参数
仓位管理	max_position_pct，max_total_pct
信号模式	buy_signal_mode（AND / OR）
因子权重	Alpha158 各组权重（方向感知）
ATR 止损	stop_loss_mult，take_profit_mult，trailing_stop_pct，trailing_start_pct
过热惩罚	rsi_threshold，ret5_threshold
数据	preload_days，min_days_listed

---

📚 相关文档

资源	链接
开发指南	CLAUDE.md
阶段审查记录	docs/iteration/
设计规格	docs/superpowers/specs/
Logo 设计	docs/superpowers/specs/2026-05-07-logo-design.md

---

🔧 常见陷阱

Warning

• dataclass 字段必须标注类型，否则成为类变量而非实例字段
• get_stocks_for_date() 返回的 dict 不含 stock_code，引擎需手动补充
• groupby.last() 和 groupby.nth(-2) 返回索引不一致，混合前需对齐
• config/database.ini 需手动创建（未纳入版本控制）
• pytest.ini 的 pythonpath 可能指向不存在的 worktree 路径

详见 CLAUDE.md#known-pitfalls。

---

📜 License

本项目基于 MIT License 发布。

---

💖 感谢使用 nj-quant

如果本项目对你有帮助，欢迎给一个 ⭐️ Star！

开发指南 • 设计文档 • 问题反馈