rdagent fin_factor 命令行调用流程分析¶
本文基于源码梳理 rdagent fin_factor 的实际调用链,重点回答三个问题:
- 命令
rdagent fin_factor是如何被注册出来的。 - 命令执行后会进入哪些核心对象和阶段。
- 因子实验代码、回测执行、反馈记录分别在什么位置完成。
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,
):
从源码可以看出,这个入口主要做两件事:
- 决定是新开一个
FactorRDLoop,还是从历史 session 恢复。 - 用
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
这个子类只做了两件事:
- 声明
FactorEmptyError属于可跳过当前 loop 的错误。 - 重写
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() 做的事情可以概括成:
- 初始化计时器、step 数、loop 数。
- 启动
kickoff_loop()持续创建新 loop。 - 启动若干个
execute_loop()worker 并行消费 loop。 - 每完成一个 step 就 dump 一次 session 快照。
- 达到
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_namefactor_descriptionfactor_formulationvariables
同时,这一步还会做一层去重:
- 从历史
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,它的工作方式是:
- 把
Experiment转成可进化对象。 - 创建
RAGEvoAgent。 - 在多轮 evolve 中不断修改实现。
- 用 evaluator 检查实现质量。
- 选择一个可接受的 fallback 版本作为最终提交结果。
这里不是“一次性生成代码”,而是“多轮生成-执行-评价-再改进”。
7.2.1 coding 阶段评估什么¶
因子 coder 使用的是 FactorEvaluatorForCoder,它会综合三类检查:
- 执行反馈
- 因子值检查
- 代码质量与最终决策
内部第一步就会真正执行工作区代码:
execution_feedback, gen_df = implementation.execute()
也就是说,在 coding 阶段就已经会运行生成的 factor.py,并检查:
- 代码是否能跑通
- 是否产出了
result.h5 - 结果 dataframe 是否满足预期格式
7.2.2 FactorFBWorkspace.execute() 真正怎么跑代码¶
FactorFBWorkspace.execute() 的行为很关键:
- 创建独立工作目录。
- 将
factor.py注入工作区。 - 将 source data 软链接到工作区。
- 用配置里的 Python 解释器执行
factor.py。 - 读取输出文件
result.h5。 - 返回
(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() 真正跑回测。这个方法会:
- 根据配置选择
docker或conda环境。 - 在工作区执行
qrun <config>。 - 再执行
python read_exp_res.py读取实验结果。 - 从工作区读取:
qlib_res.csvret.pkl
根据不同情况,runner 会选择不同配置文件:
conf_baseline.yamlconf_combined_factors.yamlconf_combined_factors_sota_model.yaml
如果历史中存在 SOTA model,还会把对应的 model.py 注入当前工作区,并把训练超参数通过环境变量传进去。
所以 running 阶段的本质是:
本轮通过 coding 的因子
+ 历史 SOTA 因子/模型
+ Qlib 模板工作区
-> qrun 回测
-> 产出绩效结果
7.4 feedback:把结果写回 Trace¶
RDLoop.feedback() 有两条分支:
- 本轮有异常
- 本轮成功执行
如果发生异常:
- 构造一个
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 管理的自动化研发工作流引擎。