rdagent fin_model 命令行调用流程分析¶
本文基于源码分析 rdagent fin_model 的调用链,重点说明:
- CLI 是如何把
fin_model暴露出来的。 fin_model的标准循环如何装配。- 模型场景下 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() 负责:
- 初始化计时器与限制条件
- 启动
kickoff_loop()创建循环 - 启动
execute_loop()执行 worker - 每个 step 完成后把整个 loop 对象 pickle 到
__session__ - 到达
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 里会包含:
namedescriptionformulationarchitecturevariableshyperparameterstraining_hyperparametersmodel_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 框架,流程是:
- 把实验转成可进化对象
- 多轮生成和修改
model.py - 用 evaluator 执行、检查、反馈
- 选择一个可接受的 fallback 版本
所以 fin_model 的 coding 阶段不是一次性出代码,而是“生成 -> 运行 -> 评价 -> 迭代”的 CoSTEER 闭环。
10. running 阶段:QlibModelRunner¶
QlibModelRunner.develop() 是 fin_model 和 fin_factor 差异最大的部分。
它的主要职责是:
- 准备历史最佳因子特征
- 将当前轮生成的
model.py注入实验工作区 - 设置训练超参数环境变量
- 调用 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_epochslrearly_stopbatch_sizeweight_decay
10.4 按模型类型选择配置¶
runner 会根据 model_type 和是否存在 SOTA factor 选择不同配置:
TimeSeries+ baseline factor:conf_baseline_factors_model.yamlTimeSeries+ SOTA factor:conf_sota_factors_model.yamlTabular+ baseline factor:conf_baseline_factors_model.yamlTabular+ SOTA factor:conf_sota_factors_model.yaml
同时还会设置:
dataset_clsnum_featuresstep_lennum_timesteps
10.5 实际执行仍走 QlibFBWorkspace.execute()¶
执行阶段最终落到 rdagent/scenarios/qlib/experiment/workspace.py 的 QlibFBWorkspace.execute():
- 选择
docker或conda环境 - 在工作区执行
qrun <config> - 执行
python read_exp_res.py - 读取
qlib_res.csv与ret.pkl
最后 QlibModelRunner 将结果写回:
exp.resultexp.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 逻辑”切换到了模型研发场景。