rd-agent-factor-mining

> ⚙️ 本技能遵循公共运行环境契约（最高优先级，先于本文其余内容执行）： > 详见 [_shared/env-contract.md](../_shared/env-contract.md)，执行前先读它。 # RD-Agent 因子挖掘（端到端流水线） 调用 RD-Agent（Alpha Agent）自动挖掘 A 股 alpha 因子，覆盖完整链路： **preflight → evolve（LLM 演化）→ 轮询 → 批量回测 → 排名 → explain → export → 报告**。 ## 0. 环境前置（必须，一分钟先过） 做任何挖掘前，先跑容器内三项健康检查。任一 FAIL 都要先修再挖。 ```bash cd ~/projects/quantmind && python3 scripts/alpha_agent/factor_pipeline.py --check-env # 期望 3 项全 PASS: conda_shim / litellm_patch / deepseek_key ``` | 检查项 | 作用 | 失败处理 | |---|---|---| | `hardware` | 最低 **8 核 / 32GB**。RD-Agent 演化会把 CPU/内存打满，低于此规格直接 412 失败，避免整机卡死 | 换机器或关其他重负载；测试可设 `ALPHA_AGENT_SKIP_HW_LOCK=1`（生产勿开） | | `conda_shim` | RD-Agent LocalEnv 硬编码 `rdagent4qlib` conda 环境，容器无 conda，靠 shim 映射到容器 python | 确认 `docker/conda-shim` 挂载 `/usr/local/bin/conda:ro` 且文件有 `+x` | | `litellm_patch` | litellm 1.97 + pydantic 2.13 冲突（`Message is not fully defined`） | 确认 `docker/litellm_sitecustomize.py` 挂载为 `site-packages/sitecustomize.py:ro` | | `deepseek_key` | 因子挖掘走 DeepSeek 通道（`llm_env.py` 优先级最高） | 更新 `~/projects/quantmind/.env` 的 `DEEPSEEK_API_KEY`，改后必须 `docker compose up -d quantmind` recreate | > preflight 机制全在管道脚本内置；手动检修环境见文末「常见问题」。 ## 1. 一键管线（推荐入口） ```bash cd ~/projects/quantmind # 最小示例：一个方向，演化+批量回测+排名（默认报告 /tmp/rd_agent_factor_report.md） python3 scripts/alpha_agent/factor_pipeline.py --direction "连板高度递减与涨停回封率" # 全流程：演化 + 回测 + top5 解读 + 最高 |IC| 导出 python3 scripts/alpha_agent/factor_pipeline.py \ --direction "筹码集中度上行伴随低位换手放大" \ --universe csi300 --loops 3 \ --explain-top 5 --export --min-ic 0.03 \ --out /tmp/factor_report.md # 只看环境 python3 scripts/alpha_agent/factor_pipeline.py --check-env ``` **参数**： | 参数 | 默认 | 说明 | |---|---|---| | `--direction` | 必填 | 挖掘方向/假设，中文优先（见方向建议库） | | `--universe` | `csi300` | csi300/csi500/csi1000/sse50/gem/star/csi800/all_a | | `--loops` | 3 | 演化轮数，实际以任务详情为准（可能出现归一值） | | `--check-env` | off | 只跑环境健康检查 | | `--no-backtest` | off | 演化完成即停，不批量回测 | | `--backtest-start` | 2025-01-01 | 回测起始日（到当天） | | `--backtest-universe` | =universe | 回测股票池 | | `--explain-top N` | 0 | 对 |IC| 排名前 N 因子调 LLM 解读 | | `--export` / `--min-ic` | off / 0.0 | 对 |IC|≥min 的最高因子 export 进生产特征库 | | `--out` | /tmp/rd_agent_factor_report.md | 报告路径 | | `--show-log` | off | 轮询时打印任务日志 | **管线阶段**（脚本自动执行）： 1. preflight 三项健康检查 2. `evolve` 启动演化 → 拿 `task_id` 3. 轮询 `tasks/{id}` 直到 `completed`（打印 phase/loop/error） 4. 收集本次 `task_id` 的因子（`metadata.task_id` 过滤） 5. 逐个 `factor/{id}/backtest` 触发 → 轮询全部 completed 6. 按 `|IC|` 排序打印排行榜 7. 对 `--explain-top` 因子 `explain`（LLM 解读，写入报告） 8. `--export` 最高分因子 9. 生成 Markdown 报告到 `--out` 一个方向跑完约 **30–90 分钟**（数据管线 + LLM 演化 + 逐因子回测）。 ## 1.5 因子工厂（QuantDB 富字段 × 算子 × 窗口 → 成千上万表达式因子） R&D-Agent 是「LLM 提假设 → 逐因子回测」；**因子工厂**是「系统性批量衍生」：拿 QuantDB 的几百个数值字段 （`l1_factors` / `features_daily`）做算子 × 窗口 × 二元组合，全量算 IC/ICIR、相关性去重，产出可训练 parquet。 适合「数据面已知、想从海量式子里筛好货」。两者互补，可都跑。 ```bash # 容器内执行（重依赖 duckdb/pandas，QwenPaw 本地 venv 跑不了） docker exec -w /app quantmind python /app/backend/scripts/factor_factory.py \ --start-date 2025-09-01 --end-date 2026-08-31 --top-n 200 # 冒烟（小样本，先验证环境） docker exec -w /app quantmind python /app/backend/scripts/factor_factory.py --smoke ``` - **产物**：`data/quantcustom/6_ml_datasets/l1_factors/dt=YYYYMMDD/data.parquet`（列：`symbol`(后缀式) + `date` + OHLCV + 因子 float32）、`MANIFEST.csv`、`PROPOSALS.json`。 - **关键参数**：`--windows 5,10,20,60`、`--ops tsrank,tsstd,roc,zscore,delta,decay,slope`、`--cs-ops csrank,cszscore`、`--binary-ops csdiff,csratio,tscorr`、`--top-n 200`、`--pool-factor 3.0`、`--corr-threshold 0.85`、`--jobs 0`（自动并行）、`--compression zstd`、`--out`。 - **只读展示**：`GET /api/v1/alpha-agent/factory-factors`（读 MANIFEST，前端因子库加「工厂」徽标，仅展示不回测/训练操作）。 - **训练侧读取**：`QuantDBFactorReader(mode="CUSTOM")`（`QM_QUANTCUSTOM_DATA_DIR`）。 - 落盘/目录口径见 [[quantdb-data-structure]] 的 `quantcustom` 小节。 ## 2. 手动分步（需要精细控制时用 API） ### 认证 ```bash BASE=http://127.0.0.1:8000 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" ``` ### 池子 / 类别 / 数据健康 ```bash curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/universes" # 支持的股票池 curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/markets" # 支持的市场 curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/factor-categories" # 挖掘类别参考 curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/data-summary" # 数据覆盖（日期/股票数） ``` ### 启动演化 ```bash curl -s -X POST "$BASE/api/v1/alpha-agent/evolve" -H "$AUTH" \ --data-urlencode "market=a_share" \ --data-urlencode "universe=csi300" \ --data-urlencode "loop_n=3" \ --data-urlencode "direction=低换手率高动量" \ -w "\nHTTP %{http_code}\n" # 返回 task_id（后续所有步骤用） ``` ### 轮询 / 取消 ```bash curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/tasks/{task_id}" # 状态 progress/phase/loop/error curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/tasks/{task_id}/log" # 实时日志（含失败原因） curl -s -X POST -H "$AUTH" "$BASE/api/v1/alpha-agent/tasks/{task_id}/cancel" # 状态机: pending → running → backtesting → completed | failed ``` ### 因子回测（注意是 query 参数，不是 form） ```bash curl -s -X POST -H "$AUTH" "$BASE/api/v1/alpha-agent/factors/{factor_id}/backtest?start_date=2025-01-01&end_date=2026-08-21&universe=csi300&data_source=qlib_bin" # factors 列表里 ic_value/sharpe_ratio/rank_ic 回测完成后回填；status 变 completed ``` ### 解读 / 导出 / 统计 ```bash curl -s -X POST -H "$AUTH" "$BASE/api/v1/alpha-agent/factors/{factor_id}/explain" # LLM 解读因子逻辑 curl -s -X POST -H "$AUTH" "$BASE/api/v1/alpha-agent/factors/{factor_id}/export" # 加入生产特征库 curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/factors" # 全部因子（含本次 task 的） curl -s -H "$AUTH" "$BASE/api/v1/alpha-agent/stats" # avg_ic/best_sharpe 等 ``` ## 3. 方向建议库（direction 直接用） 优先挖 78 核心因子集之外的空白区（筹码/微观结构/连板情绪/隔夜/资金流持续性）： ```text 1. 连板情绪承继 连板高度递增与涨停回封率，捕捉题材情绪承接力由弱转强的启动票 2. 筹码分布 筹码集中度上行伴随低位换手放大，获利盘充分消化的突破信号 3. 隔夜/日内背离 隔夜收益与日内收益背离，捕捉大单隔夜布局意图 4. 资金流持续性 主力大单净流入的天数持续性与金额强度共振 5. 下行波动偏度 低下行风险与负偏度修正，挖掘低波动异象的非对称变体 6. 量价微观结构 开盘跳空幅度与量能共振，叠加尾盘动量延续 7. 动量质量 趋势斜率 R2 与收益动量叠加，过滤高噪音动量 8. 波动聚簇修正 波动率自相关的反转信号（高低波动切换） 9. 流动性衰减 换手率衰减速度与跌幅对比 10. 行业相对强度 个股相对行业指数 20 日超额与行业轮动方向一致 ``` 每批建议跑 1–3 个方向（串行排队），避免队列过载。 ## 4. 验收标准（工具完成后自查） - [ ] preflight 三项 PASS - [ ] 演化任务 `completed`（非 failed） - [ ] 有因子入库且完成批量回测（`ic_value` 非空） - [ ] 排行榜上 |IC| 高、ICIR 明显 > 0 的因子受关注 - [ ] 高分因子完成 `explain`，解读与 direction 假设一致（非噪声） - [ ] 确认有效的因子已 `export`（日志有导出记录） - [ ] 报告落盘（默认 /tmp/rd_agent_factor_report.md） ## 5. 常见问题与踩坑 | 现象 | 根因 | 处理 | |---|---|---| | `timeout: failed to run command 'python'` + `conda: not found` | 容器无 conda，RD-Agent 需 `rdagent4qlib` env | conda shim 挂载 `/usr/local/bin/conda`；宿主机文件记得 `chmod +x` | | `Message is not fully defined` / `ChatCompletionReasoningSummaryTextBlock is not defined` | litellm 1.97 + pydantic 2.13 冲突 | `docker/litellm_sitecustomize.py` 挂载为 sitecustomize | | `Authentication Fails ... api key is invalid` | DEEPSEEK_API_KEY 失效 | 换 key 到 `.env`，`docker compose up -d quantmind` recreate 才生效 | | 因子 `status=pending` 且 `ic_value=null` | 还没跑回测 | 触发 `backtest`（pipeline `/--no-backtest` 时更是如此） | | 任务秒 failed | 先看 `tasks/{id}/log` 尾部具体错误 | 常见上面两类，按表修 | | `engine upstream unavailable`(503) | 回测并发把 engine 挤忙 | 稍等重试；少并行任务 | | 传 `universe=all_a` 详情显示 `csi300` | 后端对部分池归一 | 以任务详情 universe 为准 | ## 6. 参考文件 - 一键管线：`scripts/alpha_agent/factor_pipeline.py` - 环境修复：`docker/conda-shim`、`docker/litellm_sitecustomize.py`（compose 挂载固化） - RD-Agent Runner 入口：`scripts/alpha_agent/run_rd_agent.py` - 因子工厂：`backend/scripts/factor_factory.py`（+ `backend/scripts/alpha_library_factors.py` 复用算子/写盘）