跳转至

rdagent fin_factor_report 命令行调用流程分析

rdagent fin_factor_report 和 fin_factor 使用同一个因子执行框架,但它的 proposal 阶段不是“从历史反馈中自由提出 hypothesis”,而是“先读 PDF 报告,从报告里抽取因子和 hypothesis,再进入标准因子开发与回测链”。

本文重点说明:

  1. CLI 入口如何进入 fin_factor_report
  2. 它与 fin_factor 的相同点和不同点
  3. 报告解析、因子抽取、后续 coding/running 如何接起来

1. 命令入口

rdagent/app/cli.py 中:

from rdagent.app.qlib_rd_loop.factor_from_report import main as fin_factor_report

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

因此入口链是:

rdagent
  -> rdagent.app.cli:app
  -> Typer 子命令 fin_factor_report
  -> rdagent.app.qlib_rd_loop.factor_from_report.main()

模块文件底部同样保留了:

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

2. 主函数

rdagent/app/qlib_rd_loop/factor_from_report.py 中:

def main(report_folder=None, path=None, all_duration=None, checkout=True):

主逻辑:

if path is None and report_folder is None:
    model_loop = FactorReportLoop()
elif path is not None:
    model_loop = FactorReportLoop.load(path, checkout=checkout)
else:
    model_loop = FactorReportLoop(report_folder=report_folder)

asyncio.run(model_loop.run(all_duration=all_duration))

这里和 fin_factor 有两个关键差异:

  1. 入口参数里没有 step_n / loop_n
  2. loop_n 在 FactorReportLoop.__init__() 内部由报告数量决定

因此 fin_factor_report 的控制方式偏“批量处理报告”,而不是用户手动指定要跑多少轮。

3. FactorReportLoop 继承自 FactorRDLoop

定义如下:

class FactorReportLoop(FactorRDLoop, metaclass=LoopMeta):

这意味着:

  • 它复用了 fin_factor 的 coder / runner / summarizer
  • 但改写了 proposal 阶段
  • 同时也自定义了反馈逻辑

换句话说,fin_factor_report 的后半段仍然是标准因子研发链,变化主要发生在最前面的“任务来源”。

4. FACTOR_FROM_REPORT_PROP_SETTING 的作用

rdagent/app/qlib_rd_loop/conf.py 中:

class FactorFromReportPropSetting(FactorBasePropSetting):
    scen = "rdagent.scenarios.qlib.experiment.factor_from_report_experiment.QlibFactorFromReportScenario"
    report_result_json_file_path = "git_ignore_folder/report_list.json"
    max_factors_per_exp = 10000
    report_limit = 10000

因此它在 FactorBasePropSetting 的基础上只额外改了几件事:

  • 场景对象切到 report 场景
  • 增加默认报告列表文件
  • 限制每个实验最多抽取多少因子
  • 限制最多处理多少份报告

其余的:

  • hypothesis2experiment
  • coder
  • runner
  • summarizer

都沿用 factor 场景。

5. FactorReportLoop.__init__() 做了什么

初始化时先调用:

super().__init__(PROP_SETTING=FACTOR_FROM_REPORT_PROP_SETTING)

这一步会完成标准因子场景装配:

  • scenario
  • coder
  • runner
  • summarizer
  • trace

然后 FactorReportLoop 自己再做报告列表初始化:

if report_folder is None:
    self.judge_pdf_data_items = json.load(open(report_result_json_file_path, "r"))
else:
    self.judge_pdf_data_items = [i for i in Path(report_folder).rglob("*.pdf")]

self.loop_n = min(len(self.judge_pdf_data_items), report_limit)
self.shift_report = 0

这里可以理解为:

  • judge_pdf_data_items:待处理 PDF 队列
  • loop_n:最多处理多少份报告
  • shift_report:遇到无效报告时用于跳过

6. 核心差异:direct_exp_gen 不再从 trace 自由生成

fin_factor_report 最核心的差异在这里。

标准 fin_factor 的 direct_exp_gen 是:

trace -> hypothesis_gen -> hypothesis2experiment

而 FactorReportLoop.direct_exp_gen() 是:

选中一份 PDF
  -> 从 PDF 中抽因子
  -> 从报告文本中生成 hypothesis
  -> 组装 QlibFactorExperiment

对应的代码主线:

report_file_path = self.judge_pdf_data_items[self.loop_idx + self.shift_report]
exp = extract_hypothesis_and_exp_from_reports(str(report_file_path))

如果 exp is None:

  • 认为该报告无有效因子
  • shift_report += 1
  • loop_n -= 1
  • 继续尝试下一份报告

7. extract_hypothesis_and_exp_from_reports() 的链路

这一层是真正的报告理解入口。

主逻辑如下:

exp = FactorExperimentLoaderFromPDFfiles().load(report_file_path)
if exp is None or exp.sub_tasks == []:
    return None

pdf_screenshot = extract_first_page_screenshot_from_pdf(report_file_path)
docs_dict = load_and_process_pdfs_by_langchain(report_file_path)
factor_result = ...
report_content = "\n".join(docs_dict.values())
hypothesis = generate_hypothesis(factor_result, report_content)
exp.hypothesis = hypothesis
return exp

可以拆成四步。

7.1 从 PDF 抽取 factor experiment

FactorExperimentLoaderFromPDFfiles().load(report_file_path) 是最重的一步。它内部会执行:

  1. load_and_process_pdfs_by_langchain() 读取 PDF 文本
  2. classify_report_from_dict() 判断报告是否属于可用的量化/因子报告
  3. extract_factors_from_report_dict() 从报告里抽因子名、描述、公式、变量
  4. merge_file_to_factor_dict_to_factor_dict() 合并多报告结果
  5. check_factor_viability() 过滤不可实现因子
  6. FactorExperimentLoaderFromDict().load(filtered_factor_dict) 组装成 QlibFactorExperiment

所以这里已经不是普通的“提 hypothesis”,而是先把报告内容解析成结构化因子任务。

7.2 提取首页截图

pdf_screenshot = extract_first_page_screenshot_from_pdf(report_file_path)

这个截图会被打到日志里,方便后续 UI 或 trace 检查。

7.3 再次提取完整文本

docs_dict = load_and_process_pdfs_by_langchain(report_file_path)
report_content = "\n".join(docs_dict.values())

这里用的是 LangChain 的 PDF loader,把文本合成一个完整字符串供 hypothesis 生成。

7.4 基于“抽出的因子结果 + 报告全文”生成 hypothesis

generate_hypothesis(factor_result, report_content) 会调用 LLM:

response = APIBackend().build_messages_and_create_chat_completion(...)

然后把返回 JSON 转成标准 Hypothesis 对象。

因此这里的 hypothesis 不是凭空提出,而是对“报告中提到的因子集合”的高层总结。

8. direct_exp_gen 生成实验后的补充处理

在 FactorReportLoop.direct_exp_gen() 中,得到 exp 后还会做几件事:

8.1 绑定 baseline 与历史成功实验

exp.based_experiments = [QlibFactorExperiment(sub_tasks=[], hypothesis=exp.hypothesis)] + [
    t[0] for t in self.trace.hist if t[1]
]

这表示:

  • 第一项是一个空任务 baseline experiment
  • 后面接历史上 decision 为真的 experiment

8.2 限制每份报告最多处理的因子数

exp.sub_workspace_list = exp.sub_workspace_list[:max_factors_per_exp]
exp.sub_tasks = exp.sub_tasks[:max_factors_per_exp]

这一步用于防止单份报告抽出过多因子。

9. coding 阶段与 fin_factor 相同

FactorReportLoop.coding():

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

这里的 self.coder 仍然是 QlibFactorCoSTEER。

因此 coding 阶段和 fin_factor 没有本质区别,仍然是:

  1. 把每个 FactorTask 交给 CoSTEER
  2. 生成和迭代 factor.py
  3. 真实执行代码
  4. 用 evaluator 判断实现是否可接受

10. running 阶段与 fin_factor 相同

由于 FactorReportLoop 继承 FactorRDLoop,且没有覆写 running(),所以执行的是:

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

这里的 runner 仍然是 QlibFactorRunner。

它会:

  1. 重新跑成功实现的因子 workspace
  2. 合并新因子
  3. 与历史 SOTA factor 去重
  4. 写入 combined_factors_df.parquet
  5. 调用 QlibFBWorkspace.execute() 运行 qrun
  6. 读取 qlib_res.csv 和 ret.pkl

所以 fin_factor_report 的后半段完全复用标准因子回测链。

11. feedback 阶段的逻辑

成功执行时:

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

其中 summarizer 仍然是 QlibFactorExperiment2Feedback。

失败时,它会构造一个:

HypothesisFeedback(decision=False, ...)

12. 一个源码注意点

FactorReportLoop.direct_exp_gen() 返回的是 exp 本体,而不是标准 RDLoop 里那种:

{"propose": hypo, "exp_gen": exp}

coding() 已经按这个新返回值来写了:

self.coder.develop(prev_out["direct_exp_gen"])

但 feedback() 的异常分支仍然保留了:

prev_out["direct_exp_gen"]["exp_gen"]

这和当前 direct_exp_gen() 的返回结构并不一致。也就是说,成功路径是自洽的,但异常路径在源码层面存在结构不一致风险。

这个问题不影响理解主流程,但做源码阅读时值得注意。

13. session 与恢复

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

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

生成快照。

恢复执行使用:

FactorReportLoop.load(path, checkout=checkout)

14. 一张图看完整调用链

rdagent fin_factor_report --report-folder=<pdf_dir>
  -> rdagent/app/cli.py
  -> rdagent/app/qlib_rd_loop/factor_from_report.py: main()
  -> FactorReportLoop(FACTOR_FROM_REPORT_PROP_SETTING)
  -> LoopBase.run()
  -> direct_exp_gen
       -> 选一份 PDF
       -> FactorExperimentLoaderFromPDFfiles.load()
       -> 分类报告、抽取因子、过滤不可实现因子
       -> load_and_process_pdfs_by_langchain()
       -> generate_hypothesis()
       -> 得到 QlibFactorExperiment
  -> coding
       -> QlibFactorCoSTEER
       -> 生成并迭代 factor.py
  -> running
       -> QlibFactorRunner
       -> 合并因子并执行 Qlib 回测
  -> feedback
       -> QlibFactorExperiment2Feedback
       -> 写回 Trace
  -> 下一份报告

15. 结论

rdagent fin_factor_report 的本质可以概括成:

CLI 入口
  -> 批量读取 PDF 报告
  -> 从报告中抽取结构化因子任务
  -> 基于报告内容生成 hypothesis
  -> 复用标准 fin_factor 的 coding / running / feedback 链
  -> 逐份报告完成因子实现与回测

所以它不是独立的一套工作流,而是“报告解析前置 + 标准因子研发后置”的组合命令。