rdagent fin_factor_report 命令行调用流程分析¶
rdagent fin_factor_report 和 fin_factor 使用同一个因子执行框架,但它的 proposal 阶段不是“从历史反馈中自由提出 hypothesis”,而是“先读 PDF 报告,从报告里抽取因子和 hypothesis,再进入标准因子开发与回测链”。
本文重点说明:
- CLI 入口如何进入
fin_factor_report - 它与
fin_factor的相同点和不同点 - 报告解析、因子抽取、后续 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 有两个关键差异:
- 入口参数里没有
step_n/loop_n 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 += 1loop_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) 是最重的一步。它内部会执行:
load_and_process_pdfs_by_langchain()读取 PDF 文本classify_report_from_dict()判断报告是否属于可用的量化/因子报告extract_factors_from_report_dict()从报告里抽因子名、描述、公式、变量merge_file_to_factor_dict_to_factor_dict()合并多报告结果check_factor_viability()过滤不可实现因子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 没有本质区别,仍然是:
- 把每个
FactorTask交给 CoSTEER - 生成和迭代
factor.py - 真实执行代码
- 用 evaluator 判断实现是否可接受
10. running 阶段与 fin_factor 相同¶
由于 FactorReportLoop 继承 FactorRDLoop,且没有覆写 running(),所以执行的是:
exp = self.runner.develop(prev_out["coding"])
这里的 runner 仍然是 QlibFactorRunner。
它会:
- 重新跑成功实现的因子 workspace
- 合并新因子
- 与历史 SOTA factor 去重
- 写入
combined_factors_df.parquet - 调用
QlibFBWorkspace.execute()运行qrun - 读取
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 链
-> 逐份报告完成因子实现与回测
所以它不是独立的一套工作流,而是“报告解析前置 + 标准因子研发后置”的组合命令。