跳转至

rdagent fin_quant 命令行调用流程分析

rdagent fin_quant 是 Qlib 场景里最复杂的一个命令,因为它不是只做 factor 或 model,而是在两者之间动态切换并联合演进。

本文重点说明:

  1. fin_quant 如何从 CLI 进入。
  2. 它与标准 RDLoop 有哪些结构差异。
  3. factor/model 两条分支如何在同一循环里切换。

1. 命令入口

rdagent/app/cli.py 里注册了 fin_quant:

from rdagent.app.qlib_rd_loop.quant import main as fin_quant

app.command(name="fin_quant")(fin_quant)

因此入口调用链是:

rdagent
  -> rdagent.app.cli:app
  -> Typer 子命令 fin_quant
  -> rdagent.app.qlib_rd_loop.quant.main()

和 fin_model 一样,模块文件本身也保留了:

if __name__ == "__main__":
    fire.Fire(main)

所以统一 CLI 层是 Typer,模块独立运行时兼容 Fire。

2. 主函数

rdagent/app/qlib_rd_loop/quant.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:
    quant_loop = QuantRDLoop(QUANT_PROP_SETTING)
else:
    quant_loop = QuantRDLoop.load(path, checkout=checkout)

asyncio.run(quant_loop.run(step_n=step_n, loop_n=loop_n, all_duration=all_duration))

因此 fin_quant 同样支持:

  • 全新启动
  • session 恢复
  • step 数控制
  • loop 数控制
  • 总时长控制

3. QuantRDLoop 与标准 RDLoop 的差异

QuantRDLoop 继承自 RDLoop,但它并不是单纯复用标准装配,而是重写了:

  • __init__
  • direct_exp_gen
  • coding
  • running
  • feedback

原因很简单:它需要在 factor 和 model 两条研发链之间切换。

它声明可跳过的错误是:

skip_loop_error = (FactorEmptyError, ModelEmptyError)

4. QUANT_PROP_SETTING 装配的是双轨组件

rdagent/app/qlib_rd_loop/conf.py 中:

class QuantBasePropSetting(BasePropSetting):
    scen = "rdagent.scenarios.qlib.experiment.quant_experiment.QlibQuantScenario"
    quant_hypothesis_gen = "rdagent.scenarios.qlib.proposal.quant_proposal.QlibQuantHypothesisGen"

    model_hypothesis2experiment = "rdagent.scenarios.qlib.proposal.model_proposal.QlibModelHypothesis2Experiment"
    model_coder = "rdagent.scenarios.qlib.developer.model_coder.QlibModelCoSTEER"
    model_runner = "rdagent.scenarios.qlib.developer.model_runner.QlibModelRunner"
    model_summarizer = "rdagent.scenarios.qlib.developer.feedback.QlibModelExperiment2Feedback"

    factor_hypothesis2experiment = "rdagent.scenarios.qlib.proposal.factor_proposal.QlibFactorHypothesis2Experiment"
    factor_coder = "rdagent.scenarios.qlib.developer.factor_coder.QlibFactorCoSTEER"
    factor_runner = "rdagent.scenarios.qlib.developer.factor_runner.QlibFactorRunner"
    factor_summarizer = "rdagent.scenarios.qlib.developer.feedback.QlibFactorExperiment2Feedback"

这说明 fin_quant 的核心不是一个 coder / runner,而是两套:

factor 轨:
  hypothesis2experiment / coder / runner / summarizer

model 轨:
  hypothesis2experiment / coder / runner / summarizer

5. QuantRDLoop.__init__() 如何装配

QuantRDLoop 初始化时会显式创建:

  • QlibQuantScenario
  • QlibQuantHypothesisGen
  • factor 的 experiment generator / coder / runner / summarizer
  • model 的 experiment generator / coder / runner / summarizer
  • QuantTrace

与标准 RDLoop 最大差异是,它没有单一的:

  • self.hypothesis2experiment
  • self.coder
  • self.runner
  • self.summarizer

而是分别维护 factor/model 两套对象。

6. QlibQuantScenario 是联合场景描述器

rdagent/scenarios/qlib/experiment/quant_experiment.py 中的 QlibQuantScenario 同时提供:

  • 联合背景
  • 因子背景
  • 模型背景
  • 统一 source data 说明
  • factor/model 各自的 interface、output format、simulator

调用 get_scenario_all_desc() 时可以根据:

  • filtered_tag
  • action

返回不同版本的场景说明。

因此在 quant 场景中,给 LLM 的 prompt 是“带 action 上下文的动态描述”,而不是静态固定描述。

7. QuantTrace 比普通 Trace 多了控制器

QuantTrace 继承 Trace,额外持有:

self.controller = EnvController()

这个 controller 用于在 factor/model 两个动作之间做策略选择,默认是 bandit。

8. direct_exp_gen:先决定 action,再生成对应实验

这是 fin_quant 的核心差异。

QuantRDLoop.direct_exp_gen() 的主逻辑:

hypo = self._propose()
assert hypo.action in ["factor", "model"]
if hypo.action == "factor":
    exp = self.factor_hypothesis2experiment.convert(hypo, self.trace)
else:
    exp = self.model_hypothesis2experiment.convert(hypo, self.trace)
return {"propose": hypo, "exp_gen": exp}

也就是说,proposal 阶段先产出一个带 action 的 hypothesis,再决定后续走哪条链。

8.1 action 是怎么选出来的

QlibQuantHypothesisGen.prepare_context() 支持三种策略:

  1. bandit
  2. llm
  3. random

默认配置来自:

QUANT_PROP_SETTING.action_selection = "bandit"

8.1.1 bandit

如果是 bandit:

  • 从最近一次 experiment.result 中提取指标
  • 读取最近一次动作 factor 或 model
  • 调用 trace.controller.record(metric, prev_action) 更新 bandit
  • 调用 trace.controller.decide(metric) 选择下一动作

EnvController 内部使用的是 LinearThompsonTwoArm,也就是一个双臂 Thompson Sampling 结构。

8.1.2 llm

如果是 llm:

  • 把历史 hypothesis/feedback 拼成 prompt
  • 让 LLM 直接输出下一轮动作 action

8.1.3 random

直接在 factor / model 之间随机选。

8.2 action 决定 prompt 上下文

动作一旦确定,QlibQuantHypothesisGen 会:

  • 把 self.targets 设成对应动作
  • 只挑出和该动作相关的 trace 子集
  • 为 factor 和 model 分别构造不同的 RAG 提示

例如:

  • factor:早期优先简单快速因子,后期鼓励高 IC 因子
  • model:强调时序模型与受控超参数

8.3 hypothesis 输出对象

最终返回的不是普通 Hypothesis,而是:

class QlibQuantHypothesis(Hypothesis):
    action: str

所以 quant 场景中 hypothesis 本身带有路由信息。

9. coding:按 action 路由到不同 coder

QuantRDLoop.coding():

if action == "factor":
    exp = self.factor_coder.develop(...)
elif action == "model":
    exp = self.model_coder.develop(...)

因此 coding 阶段的真实分支是:

  • factor:QlibFactorCoSTEER
  • model:QlibModelCoSTEER

也就是分别复用 fin_factor 和 fin_model 的 CoSTEER 开发能力。

10. running:按 action 路由到不同 runner

QuantRDLoop.running():

if action == "factor":
    exp = self.factor_runner.develop(...)
elif action == "model":
    exp = self.model_runner.develop(...)

对应的行为也就是:

  • 因子轮:走 QlibFactorRunner
  • 模型轮:走 QlibModelRunner

所以 fin_quant 的 runner 逻辑不是新的,而是把两条独立流程串在一个总循环里。

11. feedback:按 action 使用不同 summarizer

成功执行时:

if action == "factor":
    feedback = self.factor_summarizer.generate_feedback(...)
elif action == "model":
    feedback = self.model_summarizer.generate_feedback(...)

失败时统一回落为:

HypothesisFeedback(decision=False, ...)

最后同样把 (experiment, feedback) 追加进 trace.hist。

由于 trace.hist 中会同时混合 factor 和 model 结果,下一轮 action 选择、hypothesis 生成时就能看到跨类型历史。

12. factor/model 两条链如何相互影响

这是 fin_quant 最重要的设计点。

12.1 factor 轮会参考模型历史

当 action=factor 时,QlibQuantHypothesisGen 会把:

  • 所有 factor 历史
  • 最近一个被接受的 model 实验

一起放进 specific_trace。

这意味着生成新因子时,会参考当前最佳模型背景。

12.2 model 轮会参考因子历史

当 action=model 时,会把:

  • 所有 model 历史
  • 最近一个被接受的 factor 实验

一起放进上下文。

同时 QlibModelRunner 也会把 SOTA factor 合并成 combined_factors_df.parquet 供模型训练。

这意味着模型迭代会显式建立在当前最佳因子库之上。

13. session 与恢复机制

fin_quant 同样继承 LoopBase 的 session 机制,每完成一个 step 都会在:

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

落一次快照。

恢复时使用:

QuantRDLoop.load(path, checkout=checkout)

14. 一张图看完整调用链

rdagent fin_quant
  -> rdagent/app/cli.py
  -> rdagent/app/qlib_rd_loop/quant.py: main()
  -> QuantRDLoop(QUANT_PROP_SETTING)
  -> LoopBase.run()
  -> direct_exp_gen
       -> QlibQuantHypothesisGen
       -> 先决定 action = factor 或 model
       -> factor_hypothesis2experiment / model_hypothesis2experiment
  -> coding
       -> factor_coder 或 model_coder
  -> running
       -> factor_runner 或 model_runner
  -> feedback
       -> factor_summarizer 或 model_summarizer
  -> 写回 QuantTrace
  -> 下一轮再决定 action

15. 结论

rdagent fin_quant 的本质是一个“动作可切换”的联合研发控制器:

统一 CLI 入口
  -> Quant 场景 hypothesis 生成
  -> 先决定本轮做 factor 还是 model
  -> 路由到对应的生成/开发/执行/反馈链
  -> 把结果混合写回同一个 Trace
  -> 用 bandit / LLM / random 决定下一轮方向

因此它不是简单地把 fin_factor 和 fin_model 顺序拼起来,而是在同一个迭代闭环中动态分配研发资源。