quantmind-operations

> ⚙️ 本技能遵循公共运行环境契约（最高优先级，先于本文其余内容执行）： > 详见 [_shared/env-contract.md](../_shared/env-contract.md)，执行前先读它。 # QuantMind 运营操作技能 QuantMind 量化平台的完整运营操作指南。所有 API 都通过 API 网关（默认 `http://127.0.0.1:8000` 或 `http://192.168.31.68:3080`）访问，统一加 `/api/v1` 前缀。 ## 认证 所有请求需要 Bearer Token： ```bash # 获取 token（admin 账号） TOKEN=$(curl -s -X POST $BASE/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"admin123","tenant_id":"default"}' \ | python3 -c "import sys,json; print(json.load(sys.stdin).get('access_token',''))") # 通用请求头 AUTH="Authorization: Bearer $TOKEN" CT="Content-Type: application/json" ``` ## 1. 模型训练（5 步流程） 模型训练分 **5 步**，与前端 ModelTrainingPage 一致： ``` 特征选择 → 训练目标 → 参数配置 → 执行训练 → 结果入库 ``` ### 1.1 特征选择（筛选输入因子） ```bash # 获取特征字典（类别/数量由 QuantDB l1_factors 动态生成，以接口返回为准） curl -s -H "$AUTH" "$BASE/api/v1/models/feature-catalog" # 带数据覆盖统计（含建议训练/验证/测试区间） curl -s -H "$AUTH" "$BASE/api/v1/models/feature-catalog?include_coverage=true" # 管理端特征字典（含扫描详情） curl -s -H "$AUTH" "$BASE/api/v1/admin/models/feature-catalog" ``` 选择特征 key 列表（如 `["mom_ret_5d", "vol_std_20"]`）或按类别（`feature_categories`）。 特征类别由后端特征目录**动态生成**，随 QuantDB `l1_factors` 数据版本变化（示例 version `20260831` 返回 10 类 110 特征：`momentum` / `fundamental` / `money_flow` / `style` / `technical` / `turnover` / `concept` / `volatility` / `chip` / `industry`）。**先读接口返回的 `categories[].id`，不要硬编码类别清单。** ### 1.2 训练目标（定义 T+N 标签口径） - `target_horizon_days`：预测周期（T+1 / T+5 / T+20 等） - `target_mode`：`regression`（回归）或 `classification`（分类） - `label_formula`：标签计算公式（如 `close_future/close - 1`） - `effective_trade_date`：生效交易日 - `training_window`：训练窗口（如 `rolling`） ### 1.3 参数配置（设置超参与训练上下文） - **时间划分**：`train_start/end`、`valid_start/end`、`test_start/end`、`val_ratio` - **模型超参**：`num_boost_round`、`early_stopping_rounds`、`lgb_params`/`xgb_params`/`catboost_params`/`dl_params` - **训练上下文 `context`**：`initial_capital`、`benchmark`、`commission_rate`、`slippage`、`deal_price`、`market`、`industry_as_feature` ### 1.4 执行训练（编排请求与日志预览） ```bash curl -s -X POST "$BASE/api/v1/models/run-training" -H "$AUTH" -H "$CT" -d '{ "model_type": "lightgbm", "model_types": ["lightgbm", "xgboost", "catboost"], "ensemble": "stacking", "job_name": "我的模型", "display_name": "我的模型", "train_start": "2022-01-01", "train_end": "2024-12-31", "valid_start": "2023-06-01", "valid_end": "2024-06-30", "test_start": "2024-07-01", "test_end": "2024-12-31", "val_ratio": 0.15, "num_boost_round": 1000, "early_stopping_rounds": 100, "features": ["mom_ret_5d", "vol_std_20"], "feature_categories": ["momentum", "volatility"], "target_horizon_days": 1, "target_mode": "regression", "label_formula": "close_future/close - 1", "effective_trade_date": "2025-01-02", "training_window": "rolling", "context": {"initial_capital": 1000000, "benchmark": "000300.SH", "commission_rate": 0.0003, "slippage": 0.001, "deal_price": "close", "market": "CN", "industry_as_feature": false}, "deploy_to_production": false }' ``` **支持的 model_type（13 种，以 `backend/shared/training/request.py::ALLOWED_MODEL_TYPES` 为准）**： - 树/线性：`lightgbm` / `xgboost` / `catboost` / `linear` / `random_forest` - 深度学习：`gru` / `lstm` / `alstm` / `transformer` / `tabnet` / `tcn` / `nativetft` - 其他：`mlp`（sklearn 实现） - ⚠️ `hybrid_gru_tree` 已剔除（QLIB map 无实现），**勿再传**（会被 422 拒绝/落入不支持）。 **ensemble 取值**：`none` / `stacking` / `blending` / `voting`（多模型训练时生效） **可选高级参数**：`wfa`（walk-forward，`rolling`/`expanding`）、`target_horizon_days`（单周期 T+N，1–30）、各模型专属超参 `lgb_params`/`xgb_params`/`catboost_params`/`dl_params` > ⚠️ 已下线/死配置：`horizons`（多周期，2026-09 随多周期训练一并清理）、`optuna`、`n_folds`（只建类型不参与序列化，传了不生效）。 **返回**：`runId` + 有效/缺失特征统计 ### 1.5 结果入库（查看元数据与产物） ```bash # 轮询训练状态（pending→running→completed/failed） curl -s -H "$AUTH" "$BASE/api/v1/models/training-runs/{run_id}" # 训练完成后模型进入 /models，可设为默认 curl -s -X PATCH -H "$AUTH" -H "$CT" "$BASE/api/v1/models/default" -d '{"model_id":"xxx"}' # 查看模型列表确认入库 curl -s -H "$AUTH" "$BASE/api/v1/models" curl -s -H "$AUTH" "$BASE/api/v1/models?include_archived=true" # 系统内置模型 curl -s -H "$AUTH" "$BASE/api/v1/models/system-models" # ⚠️ 手工融合模型已下线：原 ensemble 创建路由不存在 # （多周期 + 手工融合已于 2026-09 清理，见 backend/scripts/cleanup_multi_horizon_ensemble.py； # 仅在多模型训练时用 model_types + ensemble 合成，或保留历史融合模型做推理兼容） ``` ## 2. 模型管理（管理端） ### 2.1 扫描本地模型目录 ```bash curl -s -H "$AUTH" "$BASE/api/v1/admin/models/scan" ``` ### 2.2 数据状态 ```bash # Qlib + 特征快照数据状态 curl -s -H "$AUTH" "$BASE/api/v1/admin/models/data-status" ``` ### 2.3 推理前置检查（生成明日信号） ```bash curl -s -H "$AUTH" "$BASE/api/v1/admin/models/precheck-inference" ``` ### 2.4 滚动回测 ```bash curl -s -X POST "$BASE/api/v1/admin/models/backtest" -H "$AUTH" -H "$CT" -d '{ "model_id": "xxx", "start": "2024-01-01", "end": "2024-12-31" }' # 可用回测日期 curl -s -H "$AUTH" "$BASE/api/v1/admin/models/backtest/trading-dates" # 回测历史 curl -s -H "$AUTH" "$BASE/api/v1/admin/models/backtest/history/{model_id}" ``` ### 2.5 推理回测（选股策略事件驱动） ```bash curl -s -X POST "$BASE/api/v1/admin/models/inference-backtest" -H "$AUTH" -H "$CT" -d '{ "model_id": "xxx" }' ``` ## 3. 后台数据更新（五市场） ### 3.1 统一日同步（推荐） ```bash # 提交同步任务，返回 task_id（market: A/CN=QuantDB, US=QuantUS, HK=QuantHK, BC=区块链, FUTURES=期货） curl -s -X POST "$BASE/api/v1/admin/data-platform/daily-sync" -H "$AUTH" -H "$CT" -d '{ "market": "A", "symbols": [], "incremental": true, "calibrate": true }' # 查询同步状态 curl -s -H "$AUTH" "$BASE/api/v1/admin/data-platform/daily-sync/status/{task_id}" ``` **各市场同步数据源**： | 市场 | market 值 | 数据源 | 说明 | |---|---|---|---| | A股 | A / CN | QuantDB SDK | 4阶段：parquet→PG→Qlib→特征快照 | | 美股 | US | Yahoo Finance | `quantus_daily_sync.py` | | 港股 | HK | Yahoo + akshare + CCASS | `quanthk_daily_sync.py` | | 区块链 | BC | Binance | `quantbc_daily_sync.py`（支持 --minute） | | 期货 | FUTURES | akshare | `quantfutures_daily_sync.py` | ### 3.2 定时同步调度（每市场独立配置） ```bash # 查看全部市场定时配置 curl -s -H "$AUTH" "$BASE/api/v1/admin/data-platform/sync-schedule" # 查看单市场配置 curl -s -H "$AUTH" "$BASE/api/v1/admin/data-platform/sync-schedule/{market}" # 保存单市场配置（enabled/time/days/datasets/with_qlib） curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/admin/data-platform/sync-schedule/{market}" \ -d '{"enabled": true, "time": "22:30", "days": [1,2,3,4,5], "datasets": ["all"], "with_qlib": true}' # 立即触发一次同步（测试） curl -s -X POST -H "$AUTH" "$BASE/api/v1/admin/data-platform/sync-schedule/{market}/run" ``` ### 3.3 同步状态 / 进度 ```bash curl -s -H "$AUTH" "$BASE/api/v1/admin/data-platform/sync-status" curl -s -H "$AUTH" "$BASE/api/v1/admin/data-platform/sync-progress" ``` ### 3.4 Qlib 同步（增量重建缓存） ```bash # 同步数据集时带 with_qlib 触发 Qlib 缓存重建 curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/admin/data-platform/quantdb/sync-datasets" \ -d '{"datasets":["l1_factors","l2_factors"],"with_qlib":true}' # 查看 Qlib + 特征快照数据状态（含年度快照详情） curl -s -H "$AUTH" "$BASE/api/v1/admin/models/data-status" ``` **Qlib 路径**（`QlibDataBuilder.for_market`）：A股 `.qlib_cache/cn_data`，HK/US/BC/FUTURES 各目录下 `.qlib_cache/{hk,us,bc,futures}_data`。 ### 3.5 特征快照（更新特征 parquet） ```bash # 指定年份（A股按年生成 model_features_{year}.parquet） curl -s -X POST -H "$AUTH" "$BASE/api/v1/admin/data-platform/update-feature-parquet?year=2026" # 多市场特征更新（非 A 股市场，market 必填：hong_kong / us_stock / crypto） curl -s -X POST -H "$AUTH" "$BASE/api/v1/admin/data/update-market-features?market=hong_kong" # 特征快照年度详情（A股逐年 metadata.json） curl -s -H "$AUTH" "$BASE/api/v1/admin/models/data-status" ``` **特征快照结构**：A股 `db/feature_snapshots/model_features_{year}.parquet`（含 `.metadata.json` 年度详情），非A股单体 `model_features_{market}.parquet`。 ### 3.6 基本面同步 / 数据新鲜度 ```bash curl -s -X POST -H "$AUTH" "$BASE/api/v1/admin/data-platform/sync-fundamentals" curl -s -H "$AUTH" "$BASE/api/v1/admin/data-platform/freshness" ``` ### 3.7 在线状态 / 数据源健康 ```bash curl -s -H "$AUTH" "$BASE/api/v1/admin/data-platform/online-status" curl -s -H "$AUTH" "$BASE/api/v1/admin/data-platform/sources" curl -s -H "$AUTH" "$BASE/api/v1/admin/data-platform/sources/{name}/health" ``` ### 3.8 万得 L2 原始数据导入（手动，不走 daily-sync） 逐笔委托/成交/十档盘口由 `wind_l2_import.py` 从万得逐日 7z 手动导入 （schema/单位/坑见 [[quantdb-fields]] 第三章，含深市成交量≈2×、tick_data 单位混源）： ```bash