跳转至

rdagent fin_model 命令行调用流程分析

本文基于源码分析 rdagent fin_model 的调用链,重点说明:

  1. CLI 是如何把 fin_model 暴露出来的。
  2. fin_model 的标准循环如何装配。
  3. 模型场景下 proposal、coding、running、feedback 分别做什么。

1. 命令入口

rdagent 命令来自 pyproject.toml:

[project.scripts]
rdagent = "rdagent.app.cli:app"

真正注册 fin_model 子命令的是 rdagent/app/cli.py:

from rdagent.app.qlib_rd_loop.model import main as fin_model

app = typer.Typer()
app.command(name="fin_model")(fin_model)

所以第一段调用链是:

rdagent
  -> rdagent.app.cli:app
  -> Typer 子命令 fin_model
  -> rdagent.app.qlib_rd_loop.model.main()

需要注意两层入口同时存在:

  • 从统一 CLI 调用时,用的是 Typer
  • 直接执行 rdagent/app/qlib_rd_loop/model.py 时,文件底部仍保留了 fire.Fire(main)

也就是说,项目级统一命令入口是 Typer,模块单独运行时兼容 Fire。

2. fin_model 的主函数

rdagent/app/qlib_rd_loop/model.py 中的入口如下:

def main(
    path=None,
    step_n: int | None = None,
    loop_n: int | None = None,
    all_duration: str | None = None,
    checkout: bool = True,
):

核心逻辑非常直接:

if path is None:
    model_loop = ModelRDLoop(MODEL_PROP_SETTING)
else:
    model_loop = ModelRDLoop.load(path, checkout=checkout)
asyncio.run(model_loop.run(step_n=step_n, loop_n=loop_n, all_duration=all_duration))

这意味着:

  • path is None:从零开始执行模型演进流程
  • path 有值:从历史 __session__ 快照恢复
  • step_n:限制剩余 step 数
  • loop_n:限制剩余 loop 数
  • all_duration:限制总运行时长
  • checkout:恢复时是否截断并复用当前 session/log

3. ModelRDLoop 是标准 RDLoop

ModelRDLoop 定义非常薄:

class ModelRDLoop(RDLoop):
    skip_loop_error = (ModelEmptyError,)

它没有覆写 coding、running、feedback,因此 fin_model 直接使用 RDLoop 的标准四阶段:

direct_exp_gen -> coding -> running -> feedback

也就是说,fin_model 是 Qlib 场景里最接近“标准模板”的命令。

4. MODEL_PROP_SETTING 决定装配哪些组件

rdagent/app/qlib_rd_loop/conf.py 中定义了模型场景的依赖注入配置:

class ModelBasePropSetting(BasePropSetting):
    scen = "rdagent.scenarios.qlib.experiment.model_experiment.QlibModelScenario"
    hypothesis_gen = "rdagent.scenarios.qlib.proposal.model_proposal.QlibModelHypothesisGen"
    hypothesis2experiment = "rdagent.scenarios.qlib.proposal.model_proposal.QlibModelHypothesis2Experiment"
    coder = "rdagent.scenarios.qlib.developer.model_coder.QlibModelCoSTEER"
    runner = "rdagent.scenarios.qlib.developer.model_runner.QlibModelRunner"
    summarizer = "rdagent.scenarios.qlib.developer.feedback.QlibModelExperiment2Feedback"

因此 ModelRDLoop(MODEL_PROP_SETTING) 初始化时会得到:

QlibModelScenario
QlibModelHypothesisGen
QlibModelHypothesis2Experiment
QlibModelCoSTEER
QlibModelRunner
QlibModelExperiment2Feedback
Trace

5. RDLoop 初始化时的装配过程

rdagent/components/workflow/rd_loop.py 中的 RDLoop.__init__() 会把上面的字符串配置动态 import 成对象:

scen = import_class(PROP_SETTING.scen)()
self.hypothesis_gen = import_class(PROP_SETTING.hypothesis_gen)(scen)
self.hypothesis2experiment = import_class(PROP_SETTING.hypothesis2experiment)()
self.coder = import_class(PROP_SETTING.coder)(scen)
self.runner = import_class(PROP_SETTING.runner)(scen)
self.summarizer = import_class(PROP_SETTING.summarizer)(scen)
self.trace = Trace(scen=scen)

这说明 fin_model 的主函数只负责启动循环,真正的场景能力都由配置装配完成。

6. 运行骨架:LoopBase.run()

RDLoop 继承自 LoopBase。LoopBase.run() 负责:

  1. 初始化计时器与限制条件
  2. 启动 kickoff_loop() 创建循环
  3. 启动 execute_loop() 执行 worker
  4. 每个 step 完成后把整个 loop 对象 pickle 到 __session__
  5. 到达 step_n、loop_n、all_duration 后停止

因此 fin_model 具备:

  • 多轮迭代
  • 并行 step 执行
  • session 断点恢复
  • 全局超时控制

7. 四阶段调用流程

7.1 direct_exp_gen

RDLoop.direct_exp_gen() 内部会依次执行:

hypo = self._propose()
exp = self._exp_gen(hypo)
return {"propose": hypo, "exp_gen": exp}

也就是:

QlibModelHypothesisGen.gen(trace)
  -> 生成 hypothesis
QlibModelHypothesis2Experiment.convert(hypothesis, trace)
  -> 生成 QlibModelExperiment

7.1.1 hypothesis 生成

QlibModelHypothesisGen 会把这些信息整理后送给 LLM:

  • 历史 hypothesis + feedback
  • 最近一次同类实验的 hypothesis + feedback
  • 当前 SOTA hypothesis + feedback
  • 针对量化模型的 RAG 提示

这里的 RAG 提示强调两点:

  • 优先考虑时序建模场景,适合 GRU/LSTM
  • 数据规模有限,模型和训练超参数要受控

7.1.2 experiment 生成

QlibModelHypothesis2Experiment 会把 hypothesis 转成一个或多个 ModelTask。每个 task 里会包含:

  • name
  • description
  • formulation
  • architecture
  • variables
  • hyperparameters
  • training_hyperparameters
  • model_type

最终产物是 QlibModelExperiment。

8. QlibModelExperiment 与场景对象

模型实验对象定义在 rdagent/scenarios/qlib/experiment/model_experiment.py:

class QlibModelExperiment(ModelExperiment):
    def __init__(...):
        self.experiment_workspace = QlibFBWorkspace(
            template_folder_path=Path(__file__).parent / "model_template"
        )

它会自动带上一个基于 model_template 的实验工作区。

同时 QlibModelScenario 提供给 LLM 的场景说明包括:

  • 背景信息
  • 代码接口规范
  • 输出格式规范
  • 模拟器/执行器说明
  • 当前模型运行环境

9. coding 阶段:QlibModelCoSTEER

RDLoop.coding() 会调用:

exp = self.coder.develop(prev_out["direct_exp_gen"]["exp_gen"])

这里的 self.coder 是 QlibModelCoSTEER,而它只是:

QlibModelCoSTEER = ModelCoSTEER

ModelCoSTEER 本质上沿用通用 CoSTEER 框架,流程是:

  1. 把实验转成可进化对象
  2. 多轮生成和修改 model.py
  3. 用 evaluator 执行、检查、反馈
  4. 选择一个可接受的 fallback 版本

所以 fin_model 的 coding 阶段不是一次性出代码,而是“生成 -> 运行 -> 评价 -> 迭代”的 CoSTEER 闭环。

10. running 阶段:QlibModelRunner

QlibModelRunner.develop() 是 fin_model 和 fin_factor 差异最大的部分。

它的主要职责是:

  1. 准备历史最佳因子特征
  2. 将当前轮生成的 model.py 注入实验工作区
  3. 设置训练超参数环境变量
  4. 调用 Qlib 模板进行训练与回测

10.1 先处理历史 SOTA factor

如果 based_experiments 里存在成功的 QlibFactorExperiment,runner 会:

  • 通过 process_factor_data() 把历史 SOTA factor 重新跑成 dataframe
  • 合并为 combined_factors_df.parquet
  • 放进当前 experiment workspace

这一步相当于给模型训练提供“当前最优因子库”。

10.2 注入 model.py

runner 会检查 coding 阶段产出的 workspace:

if exp.sub_workspace_list[0].file_dict.get("model.py") is None:
    raise ModelEmptyError("model.py is empty")

然后把 model.py 写到 experiment workspace 中:

exp.experiment_workspace.inject_files(**{"model.py": ...})

10.3 注入训练参数

如果 training_hyperparameters 不为空,runner 会把这些参数作为环境变量传给 Qlib 执行环境:

  • n_epochs
  • lr
  • early_stop
  • batch_size
  • weight_decay

10.4 按模型类型选择配置

runner 会根据 model_type 和是否存在 SOTA factor 选择不同配置:

  • TimeSeries + baseline factor:conf_baseline_factors_model.yaml
  • TimeSeries + SOTA factor:conf_sota_factors_model.yaml
  • Tabular + baseline factor:conf_baseline_factors_model.yaml
  • Tabular + SOTA factor:conf_sota_factors_model.yaml

同时还会设置:

  • dataset_cls
  • num_features
  • step_len
  • num_timesteps

10.5 实际执行仍走 QlibFBWorkspace.execute()

执行阶段最终落到 rdagent/scenarios/qlib/experiment/workspace.py 的 QlibFBWorkspace.execute():

  1. 选择 docker 或 conda 环境
  2. 在工作区执行 qrun <config>
  3. 执行 python read_exp_res.py
  4. 读取 qlib_res.csv 与 ret.pkl

最后 QlibModelRunner 将结果写回:

  • exp.result
  • exp.stdout

若结果为空,则抛出 ModelEmptyError。

11. feedback 阶段:QlibModelExperiment2Feedback

标准 RDLoop.feedback() 在成功执行时会调用:

feedback = self.summarizer.generate_feedback(prev_out["running"], self.trace)

模型场景对应的 summarizer 是 QlibModelExperiment2Feedback。

它会把这些内容送给 LLM:

  • 当前 hypothesis
  • 当前模型任务信息
  • 当前 model.py
  • 当前实验结果中的关键指标
  • 历史 SOTA hypothesis / task / code / result

最后产出 HypothesisFeedback,并把 (experiment, feedback) 追加进 trace.hist。

这会直接影响下一轮 proposal。

12. session 恢复机制

LoopBase 每完成一个 step 就会把当前对象 dump 到:

<trace_path>/__session__/<loop_id>/<step_id>_<step_name>

fin_model 恢复执行时走:

ModelRDLoop.load(path, checkout=checkout)

它支持:

  • 传 session 文件直接恢复
  • 传目录时自动选择最新 session
  • checkout=True 时截断后续 session/log

13. 一张图看完整链路

rdagent fin_model
  -> rdagent/app/cli.py
  -> rdagent/app/qlib_rd_loop/model.py: main()
  -> ModelRDLoop(MODEL_PROP_SETTING)
  -> LoopBase.run()
  -> direct_exp_gen
       -> QlibModelHypothesisGen
       -> QlibModelHypothesis2Experiment
       -> QlibModelExperiment + ModelTask
  -> coding
       -> QlibModelCoSTEER / ModelCoSTEER
       -> 生成并迭代 model.py
  -> running
       -> QlibModelRunner
       -> 合并 SOTA factor
       -> 注入 model.py 与训练超参数
       -> 选择 Qlib 配置执行训练/回测
  -> feedback
       -> QlibModelExperiment2Feedback
       -> 写回 Trace
  -> 下一轮循环

14. 结论

rdagent fin_model 的本质不是“跑一个模型脚本”,而是:

CLI 入口
  -> LLM 生成模型 hypothesis
  -> LLM 生成模型任务
  -> CoSTEER 迭代实现 model.py
  -> Qlib runner 训练并回测
  -> LLM 生成反馈并推动下一轮模型演进

和 fin_factor 相比,它复用了相同的工作流骨架,但把“实现对象”和“runner 逻辑”切换到了模型研发场景。