跳转至

rdagent fin_factor 命令行调用流程分析

本文基于源码梳理 rdagent fin_factor 的实际调用链,重点回答三个问题:

  1. 命令 rdagent fin_factor 是如何被注册出来的。
  2. 命令执行后会进入哪些核心对象和阶段。
  3. 因子实验代码、回测执行、反馈记录分别在什么位置完成。

1. 命令入口从哪里来

rdagent 这个命令本身来自 pyproject.toml 的脚本入口:

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

这意味着当用户在命令行输入:

rdagent fin_factor

实际会进入 rdagent/app/cli.py 中的 app 对象。这个 app 是一个 Typer 应用,里面完成了所有子命令注册:

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

这里的 fin_factor 不是字符串,而是从下面这个模块导入的 main 函数:

from rdagent.app.qlib_rd_loop.factor import main as fin_factor

所以第一段调用链可以写成:

rdagent
  -> pyproject.toml [project.scripts]
  -> rdagent.app.cli:app
  -> Typer 子命令 fin_factor
  -> rdagent.app.qlib_rd_loop.factor.main()

2. fin_factor 命令实际调用的主函数

rdagent/app/qlib_rd_loop/factor.py 中的 main() 是这个子命令的直接入口:

def main(
    path: Optional[str] = None,
    step_n: Optional[int] = None,
    loop_n: Optional[int] = None,
    all_duration: str | None = None,
    checkout: Annotated[bool, typer.Option("--checkout/--no-checkout", "-c/-C")] = True,
    checkout_path: Optional[str] = None,
):

从源码可以看出,这个入口主要做两件事:

  1. 决定是新开一个 FactorRDLoop,还是从历史 session 恢复。
  2. 用 asyncio.run() 启动整个研发闭环。

核心逻辑如下:

if not checkout_path is None:
    checkout = Path(checkout_path)

if path is None:
    model_loop = FactorRDLoop(FACTOR_PROP_SETTING)
else:
    model_loop = FactorRDLoop.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 is not None:从某个 __session__ 快照恢复执行。
  • step_n:限制最多再跑多少个 step。
  • loop_n:限制最多再跑多少轮 loop。
  • all_duration:设置全局超时时间。
  • checkout / checkout_path:控制恢复 session 时是否复用/切换日志与 session 目录。

3. FactorRDLoop 只是一个薄封装

FactorRDLoop 定义在 rdagent/app/qlib_rd_loop/factor.py,本身非常薄,真正的流程框架来自父类 RDLoop:

class FactorRDLoop(RDLoop):
    skip_loop_error = (FactorEmptyError,)

    def running(self, prev_out: dict[str, Any]):
        exp = self.runner.develop(prev_out["coding"])
        if exp is None:
            raise FactorEmptyError("Factor extraction failed.")
        return exp

这个子类只做了两件事:

  1. 声明 FactorEmptyError 属于可跳过当前 loop 的错误。
  2. 重写 running(),在 runner 返回空结果时主动抛错。

所以 fin_factor 的主要行为不在 FactorRDLoop 本身,而在它继承的 RDLoop + LoopBase。

4. FACTOR_PROP_SETTING 决定了这条链路装配哪些类

新建 FactorRDLoop(FACTOR_PROP_SETTING) 时,真正重要的是 FACTOR_PROP_SETTING。它定义在 rdagent/app/qlib_rd_loop/conf.py:

class FactorBasePropSetting(BasePropSetting):
    scen = "rdagent.scenarios.qlib.experiment.factor_experiment.QlibFactorScenario"
    hypothesis_gen = "rdagent.scenarios.qlib.proposal.factor_proposal.QlibFactorHypothesisGen"
    hypothesis2experiment = "rdagent.scenarios.qlib.proposal.factor_proposal.QlibFactorHypothesis2Experiment"
    coder = "rdagent.scenarios.qlib.developer.factor_coder.QlibFactorCoSTEER"
    runner = "rdagent.scenarios.qlib.developer.factor_runner.QlibFactorRunner"
    summarizer = "rdagent.scenarios.qlib.developer.feedback.QlibFactorExperiment2Feedback"

这相当于告诉 RDLoop:

  • 场景对象用 QlibFactorScenario
  • 假设生成器用 QlibFactorHypothesisGen
  • 假设转实验器用 QlibFactorHypothesis2Experiment
  • 代码开发器用 QlibFactorCoSTEER
  • 实验执行器用 QlibFactorRunner
  • 反馈总结器用 QlibFactorExperiment2Feedback

也就是说,fin_factor 不是把逻辑硬编码在一个函数里,而是通过配置把一整套“场景组件”装配起来。

5. RDLoop 初始化时完成对象装配

RDLoop.__init__() 在 rdagent/components/workflow/rd_loop.py 中:

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)

这里完成了整条执行链的核心依赖注入:

FactorRDLoop
  -> QlibFactorScenario
  -> QlibFactorHypothesisGen
  -> QlibFactorHypothesis2Experiment
  -> QlibFactorCoSTEER
  -> QlibFactorRunner
  -> QlibFactorExperiment2Feedback
  -> Trace

Trace 很关键,它保存历史实验与反馈,后续 proposal 阶段会把这些历史记录重新喂给 LLM。

6. 真正的运行骨架来自 LoopBase.run()

RDLoop 继承 LoopBase,而 LoopBase 通过元类 LoopMeta 自动收集 step。对 RDLoop 而言,实际步骤是:

direct_exp_gen -> coding -> running -> feedback

LoopBase.run() 做的事情可以概括成:

  1. 初始化计时器、step 数、loop 数。
  2. 启动 kickoff_loop() 持续创建新 loop。
  3. 启动若干个 execute_loop() worker 并行消费 loop。
  4. 每完成一个 step 就 dump 一次 session 快照。
  5. 达到 step_n、loop_n 或 all_duration 条件后停止。

这套机制让 rdagent fin_factor 同时具备:

  • 多轮迭代能力
  • 并行执行能力
  • 超时停止能力
  • 中断恢复能力

7. 每一轮 loop 的四个阶段

下面按真实 step 顺序展开。

7.1 direct_exp_gen:先提假设,再把假设转成实验任务

RDLoop.direct_exp_gen() 的核心逻辑:

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

其中:

  • _propose() 调 self.hypothesis_gen.gen(self.trace)
  • _exp_gen() 调 self.hypothesis2experiment.convert(hypothesis, self.trace)

也就是说,这一步内部其实包含两个子阶段。

7.1.1 假设生成:QlibFactorHypothesisGen

QlibFactorHypothesisGen 会先根据 trace.hist 构造上下文:

  • 历史 hypothesis 与 feedback
  • 最近一次实验的反馈
  • 一个简单的 RAG 提示
  • 假设输出格式说明
  • 假设撰写规范

然后交给 APIBackend().build_messages_and_create_chat_completion(...) 调用 LLM,最后把 JSON 响应转成 Hypothesis 对象。

因此 proposal 阶段不是固定规则生成,而是:

Trace 历史
  + QlibFactorScenario 描述
  + Prompt 模板
  + LLM
  -> Hypothesis

7.1.2 实验生成:QlibFactorHypothesis2Experiment

这一步继续调用 LLM,但目标从“提出想法”变成“把想法拆成可实现的 factor task”。

它会把如下信息喂给模型:

  • 当前 hypothesis
  • 场景说明
  • 历史实验与反馈
  • 已有 factor 列表
  • 实验输出格式要求

模型返回 JSON 后,会被转成多个 FactorTask,再组装成 QlibFactorExperiment。

每个 FactorTask 至少包含:

  • factor_name
  • factor_description
  • factor_formulation
  • variables

同时,这一步还会做一层去重:

  • 从历史 based_experiments 中收集已存在因子
  • 如果本轮任务名和历史重名,则从新任务里排除

这说明 fin_factor 的 proposal 阶段不仅“生成新任务”,还会主动避免重复挖掘完全同名因子。

7.2 coding:QlibFactorCoSTEER 生成因子代码

RDLoop.coding() 非常直接:

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

对应到因子场景,self.coder 是 QlibFactorCoSTEER,本质上是 FactorCoSTEER 的别名。

FactorCoSTEER 再继承通用 CoSTEER,它的工作方式是:

  1. 把 Experiment 转成可进化对象。
  2. 创建 RAGEvoAgent。
  3. 在多轮 evolve 中不断修改实现。
  4. 用 evaluator 检查实现质量。
  5. 选择一个可接受的 fallback 版本作为最终提交结果。

这里不是“一次性生成代码”,而是“多轮生成-执行-评价-再改进”。

7.2.1 coding 阶段评估什么

因子 coder 使用的是 FactorEvaluatorForCoder,它会综合三类检查:

  1. 执行反馈
  2. 因子值检查
  3. 代码质量与最终决策

内部第一步就会真正执行工作区代码:

execution_feedback, gen_df = implementation.execute()

也就是说,在 coding 阶段就已经会运行生成的 factor.py,并检查:

  • 代码是否能跑通
  • 是否产出了 result.h5
  • 结果 dataframe 是否满足预期格式

7.2.2 FactorFBWorkspace.execute() 真正怎么跑代码

FactorFBWorkspace.execute() 的行为很关键:

  1. 创建独立工作目录。
  2. 将 factor.py 注入工作区。
  3. 将 source data 软链接到工作区。
  4. 用配置里的 Python 解释器执行 factor.py。
  5. 读取输出文件 result.h5。
  6. 返回 (execution_feedback, factor_dataframe)。

如果执行失败,会把 stderr/stdout 截断后作为反馈返回;如果没有生成 result.h5,则视为失败。

所以 coding 阶段的输出不是抽象代码文本,而是:

  • 已写入 workspace 的 factor.py
  • 真实运行后的执行反馈
  • 真实生成的因子 dataframe

7.3 running:QlibFactorRunner 组织因子合并与 Qlib 回测

FactorRDLoop.running() 调用的是:

exp = self.runner.develop(prev_out["coding"])

这里的 runner 是 QlibFactorRunner。它比 coding 阶段更偏“实验执行器”,主要负责把成功实现的因子整合到 Qlib 回测流程里。

核心步骤如下。

7.3.1 先准备基线和历史 SOTA

如果 exp.based_experiments 中最后一个实验还没跑过,runner 会先递归执行它。这通常意味着会先确保 baseline 或历史 SOTA 已经有结果。

7.3.2 提取并合并本轮新因子

process_factor_data(exp) 会再次调用各个成功 workspace 的 implementation.execute("All"),拿到全量样本上的因子值,然后:

  • 过滤掉无效结果
  • 过滤掉分钟级数据
  • 把所有成功因子按列拼接成一个 dataframe

7.3.3 与历史 SOTA 因子做去重

如果存在历史 SOTA 因子集合,runner 会计算新旧因子之间的相关性,删除与已有因子高度相似的新因子:

  • 通过 deduplicate_new_factors()
  • 若相关性超过阈值,认为重复
  • 如果全部被判定重复,则抛 FactorEmptyError

这就是为什么有些 loop 会被跳过而不是直接崩溃,因为 FactorRDLoop.skip_loop_error 已经把这类错误标记为“跳过当前轮”。

7.3.4 写入 combined_factors_df.parquet

合并好的因子不会只留在内存里,而是会被写到实验工作区:

<experiment_workspace>/combined_factors_df.parquet

这里特意用了 parquet 而不是 pickle,源码注释说明原因是不同环境中的 numpy 版本兼容性。

7.3.5 调用 Qlib 环境执行回测

QlibFactorRunner 依赖 QlibFBWorkspace.execute() 真正跑回测。这个方法会:

  1. 根据配置选择 docker 或 conda 环境。
  2. 在工作区执行 qrun <config>。
  3. 再执行 python read_exp_res.py 读取实验结果。
  4. 从工作区读取:
  5. qlib_res.csv
  6. ret.pkl

根据不同情况,runner 会选择不同配置文件:

  • conf_baseline.yaml
  • conf_combined_factors.yaml
  • conf_combined_factors_sota_model.yaml

如果历史中存在 SOTA model,还会把对应的 model.py 注入当前工作区,并把训练超参数通过环境变量传进去。

所以 running 阶段的本质是:

本轮通过 coding 的因子
  + 历史 SOTA 因子/模型
  + Qlib 模板工作区
  -> qrun 回测
  -> 产出绩效结果

7.4 feedback:把结果写回 Trace

RDLoop.feedback() 有两条分支:

  1. 本轮有异常
  2. 本轮成功执行

如果发生异常:

  • 构造一个 HypothesisFeedback(decision=False, ...)
  • 把异常信息写进 observations
  • 把失败的实验记录进 trace.hist

如果执行成功:

  • 交给 self.summarizer.generate_feedback(...)
  • 得到结构化 feedback
  • 再把 (experiment, feedback) 追加进 trace.hist

因此 Trace 会不断累积:

(实验, 反馈)
(实验, 反馈)
(实验, 反馈)
...

下一轮 proposal 又会把这些历史记录作为上下文,形成一个真正的自迭代闭环。

8. session 恢复与断点续跑机制

fin_factor 的一个重要特性是支持从 session 快照恢复。

LoopBase 每完成一个 step,都会把当前 loop 对象 pickle 到:

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

恢复时通过 FactorRDLoop.load(path, checkout=...) 加载:

  • 如果传入的是目录,则自动取最新快照
  • 如果 checkout=True,会截断后续 session/log,只保留当前节点之前的状态
  • 如果 checkout 是路径,则把恢复后的 session 输出到新目录

这意味着下面这种模式是成立的:

跑到一半停止
  -> 定位某个 __session__ 快照
  -> load()
  -> 从中间继续执行

这也是源码注释里提到的“continue running session”的来源。

9. 缓存机制在这条链路里的位置

fin_factor 这条链路里至少有两层缓存:

9.1 workspace 级缓存

FactorFBWorkspace.execute() 使用 cache_with_pickle(hash_func),对于同一份 factor.py 实现,可以避免重复执行。

9.2 runner 级缓存

QlibFactorRunner.develop() 也使用 cache_with_pickle(...),缓存键由:

  • 历史 based_experiments 中的任务信息
  • 当前 exp.sub_tasks 中的任务信息

共同计算而来。

这意味着如果任务集合没有变化,runner 层的回测结果也可以复用。

10. 一张图看完整调用链

rdagent fin_factor
  -> pyproject.toml: rdagent = rdagent.app.cli:app
  -> rdagent/app/cli.py
  -> app.command(name="fin_factor")(factor.main)
  -> rdagent/app/qlib_rd_loop/factor.py: main()
  -> FactorRDLoop(FACTOR_PROP_SETTING) or FactorRDLoop.load(...)
  -> asyncio.run(loop.run(...))
  -> LoopBase.run()
  -> direct_exp_gen
       -> QlibFactorHypothesisGen.gen(trace)
       -> QlibFactorHypothesis2Experiment.convert(hypothesis, trace)
       -> QlibFactorExperiment + FactorTask[]
  -> coding
       -> QlibFactorCoSTEER.develop(exp)
       -> 反复生成/执行/评估 factor.py
       -> 产出 sub_workspace_list
  -> running
       -> QlibFactorRunner.develop(exp)
       -> process_factor_data()
       -> 合并/去重因子
       -> 写入 combined_factors_df.parquet
       -> QlibFBWorkspace.execute()
       -> qrun 回测,读取 qlib_res.csv / ret.pkl
  -> feedback
       -> QlibFactorExperiment2Feedback.generate_feedback(...)
       -> trace.hist 追加 (experiment, feedback)
  -> 下一轮 loop

11. 结论

rdagent fin_factor 表面上只是一个 CLI 命令,但源码层面它实际上启动了一套“可恢复、可并行、可自迭代”的研发闭环。可以把它概括成下面这句话:

Typer 命令入口
  -> 组装 Qlib 因子场景组件
  -> 用 LLM 生成 hypothesis 与 factor tasks
  -> 用 CoSTEER 实现并调试因子代码
  -> 用 Qlib runner 合并因子并执行回测
  -> 把结果写回 Trace,驱动下一轮演化

如果只看 CLI,很容易误以为 rdagent fin_factor 只是“跑一个脚本”;但从源码结构看,它更接近一个带 session 管理的自动化研发工作流引擎。