RQAlpha 项目研究站 · 运行策略
RQAlpha 怎么运行策略：五种方式与参数优先级
RQAlpha 把「参数配置」从策略代码里剥离出来：同一份策略代码，换启动参数就能变成不同的研究、风控与调优任务。可以走命令行、config.yml、策略内的 __config__，也可以在自己的 Python 程序里用 run_file / run_code / run_func 直接调用——但必须理解优先级，否则会出现「设置了却不生效」。
rqalpha run …
config.yml
__config__
run_file/code/func
依据官方 run_algorithm 文档整理的四种配置入口示意；非官方流程图。
本页依据的版本、来源与实测状态
- 依据版本release/6.3.0（2026-07-23 发布）；仓库默认分支为 master
- Python 要求requires-python >=3.8（分类器覆盖 3.8–3.14）
- 本页官方来源docs/source/intro/run_algorithm.rst、rqalpha/config.yml、mod_config.yml
- 证据等级官方文档与仓库文件（①②级）＋ 本机实测（③级，限安装与运行链路）
- 实测状态安装链路已实测；本页参数与优先级来自官方文档原文核验
- 旧版本写法4.x 起 --matching-type / --signal / --slippage 已迁入 sys_simulation Mod；
--strategy-type已废弃
五种运行方式对照
RQAlpha 官方文档按「谁来传参数」区分这几种方式，适用场景不同。
| 方式 | 写法 | 适合场景 | 注意点 |
|---|---|---|---|
| 命令行 | rqalpha run -f 策略.py -s 起 -e 止 --account stock 100000 | 快速试跑、临时改参数、脚本化批量 | 并非所有参数都有命令行选项，特殊的用 -mc 或配置文件补 |
| 配置文件 | 当前目录放 config.yml / config.json，直接 rqalpha run | 固定参数长期复用 | 用 generate-config 生成模板；模板不含 Mod 配置项 |
策略内 __config__ | 策略文件里定义 __config__ 字典，框架自动识别 | 自动化测试中给每个策略固定参数 | 官方明确：不建议在策略开发与日常运行中使用 |
run_file | from rqalpha import run_file，传策略路径 + config 字典 | 在自己的程序 / Notebook 里驱动回测 | 代码传入的 config 优先级高于 config.yml |
run_code | 把策略源码作为字符串传入 | 策略由程序生成 / 参数化拼装 | 同样会先读当前目录的 config.yml，再被代码参数覆盖 |
run_func | 直接传 init / handle_bar 等函数对象 | 函数已定义在当前环境（如 Notebook 交互式研究） | 函数名符合 API 规范时可直接 run_func(**globals()) |
参数优先级：为什么我设置的参数不生效？
RQAlpha 官方专门用警告框强调这一点，配置不生效时先查这里。
| 层级（高 → 低） | 来源 | 什么时候会「被覆盖」 |
|---|---|---|
| 1（最高） | 策略代码中的配置 | 只要策略里写了配置，命令行的同名参数就不起作用 |
| 2 | 命令行传参，或 run_file / run_code / run_func 的函数传参 | 会被策略内配置覆盖 |
| 3 | 用户配置文件（当前目录 config.yml / config.json） | 会被上面两层覆盖；代码调用时也会先读它 |
| 4（最低） | 系统默认配置 | 所有上层的默认来源；完整默认值见 rqalpha/config.yml |
--extra-vars 留出可注入的位置）。rqalpha run 常用命令行参数
表中是 RQAlpha 官方文档列出的常用项，完整列表以 rqalpha run -h 为准。
| 缩写 | 全称 | 作用 |
|---|---|---|
-d | --data-bundle-path | 数据包路径（与下载时指定的路径保持一致） |
-f | --strategy-file | 策略文件路径 |
-s / -e | --start-date / --end-date | 回测起止日期（实盘时忽略结束日期） |
-a | --account | 账户类型与起始资金，可传多次（股票+期货混合） |
-fq | --frequency | 频率 1d / 1m（分钟级需自备数据源） |
-rt | --run-type | b 回测 / p 模拟交易 / r 实盘交易 |
-mm | --margin-multiplier | 保证金乘数（期货场景常用） |
-l | --log-level | verbose / info / warning / error，批量回测时常用 error 降噪 |
-mc | --mod-config | 设置 Mod 配置项，可传多个 |
| — | --extra-vars | 传变量到 context，参数调优的关键（见参数调优页） |
系统 Mod 带来的扩展参数
在 RQAlpha 里开启对应 Mod 后即可使用；需要 -mc 传的项也在其中。
| 参数 | 所属 Mod | 作用 |
|---|---|---|
-bm / --benchmark | sys_analyser | 基准指数；不设置则没有基准参照 |
-o / --output-file | sys_analyser | 把回测数据输出到指定文件（常用 .pkl） |
-p / --plot、--no-plot、--plot-save | sys_analyser | 回测结束后画收益曲线；--plot-save 可保存到文件（无图形界面环境适用） |
--progress / --no-progress | sys_progress | 命令行显示回测进度条 |
--short-stock / --no-short-stock | sys_accounts | 是否允许股票卖空 |
--signal | sys_simulation | 信号模式：不撮合直接成交（用于只看信号） |
-sp / --slippage、-cm / --commission-multiplier | sys_simulation | 滑点与手续费乘数，直接影响回测真实性 |
-me / --match-engine | sys_simulation | 撮合引擎：current_bar（当前 Bar 收盘价）/ next_bar（下一 Bar 开盘价） |
-r / --rid | sys_simulation | 指定回测 ID（rid），用于区分多次回测结果 |
-mc sys_accounts.auto_switch_order_value True | sys_accounts | 资金不足时自动使用全部剩余资金下单（官方示例） |
current_bar 用当前 Bar 收盘价撮合（信号与成交同一根 Bar，偏乐观），next_bar 用下一根 Bar 开盘价撮合（更接近「收盘后决策、次日开盘执行」的真实流程）。切换后收益与回撤通常会有明显差异，务必在报告里写明用哪种。运行排查表
以下是 RQAlpha 里「配置看似写了、行为却不对」的典型情形。
| 现象 | 原因 | 处理 |
|---|---|---|
| 命令行参数没生效 | 策略文件里也写了配置（策略内优先级最高），或当前目录存在 config.yml | 按优先级表定位；先临时移走 config.yml 验证 |
| 换了目录跑，读不到数据 | bundle 路径与运行路径不一致；配置文件在新目录不存在 | 运行时显式传 -d，或在当前目录放 config.yml |
| 没有收益曲线图 | 未加 plot 参数，或缺少图形环境 / matplotlib 后端问题 | 加 -p；服务器环境用 --plot-save 存图；按安装页 FAQ 配 TkAgg |
| 批量跑时日志刷屏 | 默认日志级别冗余 | 批量任务统一设 log_level: error（官方调参示例就这写法） |
| 结果文件互相覆盖 | 多次回测输出到同一文件名 | 输出文件名带参数（官方示例 results/out-{short}-{long}.pkl），或用 --rid 区分 |
| 模拟/实盘启动报错 | 缺少对应数据源与账户实现，或未开启 persist | 先确认 -rt p/r 的前置条件（数据源、账户）；需要断点续跑时再开 persist |
一次完整回测怎么跑：命令、预期输出与落盘
官方「10 分钟教程」把回测要素收敛成六项；下面是 RQAlpha 的最小可用链路——先跑起来，再加画图，最后把结果落盘归档。
| 回测要素 | 参数写法 | 不写会怎样 | 注意点 |
|---|---|---|---|
| 数据源路径 | -d / --data-bundle-path，或配置文件里的 base.data_bundle_path | 按默认位置找数据包，找不到就读不到数据 | 下载数据包时改过路径的，运行时必须传同一个路径 |
| 策略文件路径 | -f / --strategy-file，或 base.strategy_file | 没有策略可执行，命令直接报错退出 | 用代码方式启动时，改为传策略路径或策略源码 |
| 回测起始日期 | -s / --start-date | 取配置文件里的 base.start_date 默认值 | 日期格式 YYYY-MM-DD |
| 回测结束日期 | -e / --end-date | 取 base.end_date 默认值 | 实盘（-rt r）会忽略结束日期 |
| 起始资金与账户类型 | -a / --account stock 100000，可传多次 | 该账户没有可用资金，下单会被拒 | 股票期货混合就传两次：--account stock 10000 --account future 20000 |
| 基准 Benchmark | -bm / --benchmark | 官方说明：不设置则没有基准参照 | 缺基准时，相对收益类指标没有对照物 |
从空目录到一份可分析的结果
1. rqalpha generate-config —— 生成配置模板（预期输出：当前目录出现 config.yml，含全部默认值与注释，但不含 Mod 段）；
2. rqalpha run -f ./rqalpha/examples/buy_and_hold.py -s 2016-06-01 -e 2016-12-01 --account stock 100000 --benchmark 000300.XSHG —— 官方教程的最小命令（预期输出：命令行打印回测日志，结束时给出 summary 段的风险收益指标）；
3. 在第 2 步命令后追加 --plot —— 回看收益曲线（预期输出：回测结束后弹出图形窗口；无图形界面的服务器改用 --plot-save 收益.png）；
4. 再追加 -o result.pkl —— 把结果落盘归档（预期输出：当前目录生成 result.pkl）；
5. python -c "import pandas as pd; d = pd.read_pickle('result.pkl'); print(list(d.keys()))" —— 读回来做后续分析（预期输出：total_portfolios、summary、benchmark_portfolios、benchmark_positions、stock_positions、trades、stock_portfolios 七个键）；
6. rqalpha plot result.pkl —— 直接对已落盘的结果重新画图，不必重跑回测（该子命令由 sys_analyser 提供）。
-me current_bar / next_bar）、滑点（-sp）或手续费乘数（-cm）就可能得出不同结论；实验记录里写清这三项，比只写一个收益数字更有用。同一件事，八种入口分别怎么写？
官方 run_algorithm 文档给出五种运行方式，再加上显式指定配置文件路径与 IDE 调试，日常落到操作上一共八种写法；它们最终都调用 RQAlpha 同一套引擎。
| 入口 | 同一件事怎么写（buy_and_hold.py，2016-06-01 → 2016-12-01，股票账户 10 万，基准 000300.XSHG） | 适合场景 | 注意点 |
|---|---|---|---|
| 命令行 | rqalpha run -f ./buy_and_hold.py -s 2016-06-01 -e 2016-12-01 --account stock 100000 --benchmark 000300.XSHG | 快速试跑、脚本化批处理 | 并非所有参数都有命令行选项，特殊的用 -mc 或配置文件补 |
| 当前目录 config.yml | 写 base.strategy_file / start_date / end_date / accounts.stock / benchmark，再加 extra.log_level 与 mod.sys_analyser.plot | 固定参数长期复用 | 运行时自动读当前目录的 config.yml / config.json；模板不含 Mod 段 |
--config 指定路径 | rqalpha run --config /path/to/研究.yml | 研究 / 模拟 / 实盘各存一份配置 | 与「当前目录自动读取」同时存在时，用显式传入的那份 |
策略内 __config__ | 策略文件里写 __config__ 字典（base / extra / mod 三段） | 自动化测试里给单个策略固定参数 | 官方明确不建议在策略开发与日常运行中使用；它会覆盖命令行 |
run_file | from rqalpha import run_file；run_file("./buy_and_hold.py", config) | 在自己的脚本或 Notebook 里驱动回测，便于与数据处理、并行框架结合 | 代码传入的 config 优先级更高，但 RQAlpha 仍会先读当前目录的 config.yml |
run_code | from rqalpha import run_code；run_code(code_string, config) | 策略源码由程序生成或参数化拼装 | 策略以字符串传入，报错定位不如文件方式直观 |
run_func | run_func(init=init, before_trading=before_trading, handle_bar=handle_bar, config=config)；函数名符合 API 规范时可直接 run_func(**globals()) | 函数已定义在当前环境（如 Notebook 交互式研究） | 传的是函数对象，改函数名要同步改参数 |
| PyCharm 运行 / 调试 | Run/Debug Configurations 的 Script 指向 conda 环境里的 rqalpha 入口，Script parameters 填 run -f rqalpha-strategy/test.py -d /Users/you/.rqalpha/bundle -s 2016-06-01 -e 2016-12-01 --account stock 100000 --benchmark 000300.XSHG | 断点调试策略、观察每一步变量 | Windows 没有 bin 目录，解释器要指向 envs\rqalpha\Scripts\python.exe；Python 3.5+ 的入口文件是 Scripts\rqalpha-script.py；先在策略里 from rqalpha.api import * 才有自动补全 |
config.yml / config.json 并加载，只是代码传入的 config 优先级更高；② --resume 只在模拟交易与实盘交易（-rt p / -rt r）下有意义，用于暂停后恢复；③ --enable-profiler 可启动策略逐行性能分析，回测结束会打印每行耗时，适合定位慢在哪一步。配置文件里那些「看着无害」的默认值
用 rqalpha generate-config 生成模板后，多数人只改日期与账户资金。下面这些默认值同样会改变结论，而且改动它们不需要写任何策略代码。
| 配置项 | 默认值 | 会怎样影响结果 | 注意点 |
|---|---|---|---|
base.end_date | 2050-01-01 | 忘了改就把回测跑到未来，而数据只到下载日 | 每次显式传 -s/-e，或在策略里写死 |
base.run_type | b（回测） | 想跑模拟或实盘要显式改为 p/r | 结果文件里 run_type 字段会回显实际运行类型 |
base.frequency | 1d | 改成 1m 前必须先有分钟数据 | 开源版本不提供分钟级数据源 |
base.market | CN | 开启 HK 后无法交易 A 股任何标的 | 两个市场不能同时交易 |
base.round_price | false | 限价单价格可能不是最小变动单位的整数倍 | 实盘对齐时建议开；对应的命令行选项为 --round-price |
base.auto_update_bundle | false | 回测中缺盘前竞价成交量/期货历史参数时不会自动补 | 开它会在回测过程中联网下载数据 |
base.partial_fill_on_insufficient_cash | false | 资金不足时直接放弃下单，而不是尽量成交 | 想模拟算法母单执行过程时再打开 |
base.capital_gain_tax_rate | 0 | 默认不计这块费；官方写明后续版本将改为 0.0318 | 跨版本比收益前先确认它 |
base.futures_time_series_trading_parameters | false | 期货回测是否使用历史交易参数 | 只影响期货账户 |
extra.log_level | info | 排查参数不生效时看不出细节 | 排查阶段用 verbose，跑批量回测时再降回 error |
__config__ > 命令行/函数传参 > 用户配置文件 > 系统默认配置文件），再用 rqalpha run --help 核对当前版本里这个选项是否还存在——4.x 起有相当一批参数被移进了 Mod 命名空间。当前版本的参数面与文档写法有哪些差异？
本站 2026-10-10 在安装实例上执行 rqalpha run --help，逐项比对了官方文档仓里的写法。下表左边是文档里的写法，右边是当前版本的实际情况——照抄文档容易在这几处卡住。
| 文档里的写法 | 当前版本实测 | 会怎样表现出来 | 怎么处理 |
|---|---|---|---|
-me / --match-engine（文档「系统内置 Mod Option 扩展」一节） | 实际选项是 -mt / --matching-type，取值 current_bar | next_bar | last | best_own | best_counterparty | vwap | counterparty_offer | 照文档写会直接报「No such option」并打印帮助信息 | 一切参数以 rqalpha run --help 为准 |
--no-plot | 当前只有 --plot 开关，没有反向开关 | 同样报「No such option」 | 不加该参数；绘图相关选项见帮助信息的绘图分组 |
-cm / --commission-multiplier | 仍可用，但已标注 [deprecated]；推荐 -scm / --stock-commission-multiplier | 现在能跑通，升级后有被移除的风险 | 新脚本直接用推荐参数，旧脚本留一次迁移 |
-smc / --stock-min-commission | 已标注 [deprecated]；推荐 -cnsmc / --cn-stock-min-commission | 同上 | 同上 |
--resume | 在帮助信息里标记为 [DEPRECATED] | 不会有硬报错，但已不推荐使用 | 改用配置文件或函数传参方式控制 |
| 文档未列出的当前可用项 | --stock-t1/--no-stock-t1、--dividend-reinvestment、--cash-return-by-stock-delisted、--cash-validation/--no-cash-validation、--inactive-limit、--slippage-model、--pit-tax、--management-fee | 不知道有这些开关时，会用绕路的方式实现同一件事 | 把帮助信息当成版本说明书，升级后看一遍 |
--stock-t1 决定 T+1 是否建模、--cash-validation 决定资金校验是否参与拒单、--inactive-limit 决定成交量为 0 时是否限制交易。它们的默认值不一定符合你的假设，而关闭校验类开关会让回测结果更乐观。常见问题
一次回测的最小命令是什么？
官方「10 分钟教程」给的形状是：rqalpha run -f 策略.py -s 2016-06-01 -e 2016-12-01 --account stock 100000 --benchmark 000300.XSHG，需要看曲线再加 --plot，需要存结果再加 -o result.pkl。
配置写在策略里更方便，为什么官方不建议？
RQAlpha 官方文档把 __config__ 定位为「自动化测试中给每个策略配置参数」的手段，并明确不建议在策略开发与运行中使用——因为它会覆盖命令行，导致参数不可见、批量调优失效。
run_file 和命令行方式有什么区别？
run_file 是把 RQAlpha 当作库调用：你在自己的 Python 程序里传策略路径与 config 字典，便于和数据处理、并行框架结合；命令行方式适合快速验证与脚本化批处理。两者最终都走 RQAlpha 同一套引擎。
可以一次跑多个账户吗？
可以。RQAlpha 官方参数说明给了股票 + 期货混合策略的写法：--account stock 10000 --account future 20000；配置文件中对应 base.accounts 的 stock / future 两项。
模拟交易与实盘交易怎么开始？
参数上是 -rt p（模拟）与 -rt r（实盘），并支持 pause/resume 持久化（persist）。但官方仓库本身不提供券商通道，实盘接入需要自行扩展或使用生态方案，务必先做小规模验证。
这些参数能保证回测贴近实盘吗？
不能保证。滑点、手续费乘数、撮合引擎、复权口径都会改变结果；把参数写清楚、把假设说明白，比追求「一个漂亮数字」更重要。本站不提供任何收益承诺。