RQAlpha 交易税费 Mod(sys_transaction_cost)完全指南:配置项、命令行参数与税费计算源码解析
RQAlpha 交易税费 Mod(sys_transaction_cost)完全指南:配置项、命令行参数与税费计算源码解析
RQAlpha 是一个可扩展、可替换的 Python 量化回测与交易框架,其交易税费由 sys_transaction_cost Mod 统一负责。本文将围绕该 Mod 的官方说明文档展开,完整覆盖其开启/关闭命令、全部配置项与默认值,并结合仓库源码(mod.py、deciders.py、interface.py)深入讲解股票与期货两类税费决策器的底层实现、最小手续费算法、单边印花税与历史税率(pit_tax)机制。读完本文,你将能精确控制回测中的佣金、印花税与最小手续费,并理解税费在 RQAlpha 框架中的注册与调用链路。
一、Mod 定位:不同市场、不同标的的税费计算中枢
sys_transaction_cost 是 RQAlpha 的交易税费 Mod,其核心职责是"实现不同市场不同交易标的的税费计算逻辑"(见 README.rst)。在 RQAlpha 中,税费计算并非硬编码在撮合或账户逻辑里,而是通过"决策器(Decider)"机制按标的类型(instrument type)注册、按需调用:
- 股票类标的(A 股普通股票、指数、ETF、LOF 等股票账户内交易品种)使用
StockTransactionCostDecider; - 期货合约使用
FuturesTransactionCostDecider。
该 Mod 在仓库的默认配置中处于启用状态,见 mod_config.yml:
sys_transaction_cost:
enabled: true
因此,在未显式干预的情况下,每一次回测/模拟成交都会自动计提佣金与印花税(期货为佣金),从而让回测结果更贴近真实交易成本。
二、开启与关闭交易税费 Mod
官方文档提供了两条命令行指令,用于控制该 Mod 的加载状态:
# 关闭交易税费 Mod
$ rqalpha mod disable sys_transaction_cost
# 启用交易税费 Mod
$ rqalpha mod enable sys_transaction_cost
rqalpha mod 系列命令负责管理各 Mod 的启用/禁用状态。关闭本 Mod 后,成交将不再计提任何交易费用(等同于零成本撮合),适合用于研究"纯策略收益"与"扣除成本后收益"之间的差异。
三、模块配置项全解析
官方文档给出了该 Mod 的可用配置项(Python 字典形式):
{
# 股票最小手续费,单位元
"cn_stock_min_commission": 5,
# 佣金倍率,即在默认的手续费率基础上按该倍数进行调整,股票的默认佣金为万八,期货默认佣金因合约而异
"commission_multiplier": None,
"stock_commission_multiplier": 1,
"futures_commission_multiplier": 1,
# 印花倍率,即在默认的印花税基础上按该倍数进行调整,股票默认印花税为千分之一,单边收取
"tax_multiplier": 1,
}
对照 init.py 中的 __config__,当前仓库实际支持的配置项更完整,且存在一处字段演进:
| 配置项 | 默认值 | 类型 | 说明 |
|---|---|---|---|
cn_stock_min_commission |
None |
float | 股票最小手续费(单位:元),已标记为即将废弃(deprecated),设置后会在启动时打印警告,提示改用 stock_min_commission |
stock_min_commission |
5 |
float | 股票最小手续费(单位:元),默认 5 元,即单笔佣金不足 5 元按 5 元收取 |
commission_multiplier |
None |
float | 旧版"统一佣金倍率",已废弃并拆分为股票/期货两个独立倍率(CLI 参数 -cm 同样标注为 deprecated) |
stock_commission_multiplier |
1 |
float | 股票佣金倍率,在默认佣金率(万八,即 0.0008)基础上相乘 |
futures_commission_multiplier |
1 |
float | 期货佣金倍率,在合约自身佣金参数基础上相乘 |
tax_multiplier |
1 |
float | 印花倍率,在默认印花税基础上相乘 |
pit_tax |
False |
bool | 是否使用回测当时时间点对应的真实历史印花税率(见下文"历史税率切换") |
参数合法性校验:在 mod.py 的
start_up阶段,框架会检查stock_commission_multiplier与tax_multiplier,若取值小于 0 则抛出ValueError,提示取值范围为[0, +∞)。配置倍率时请保证非负。
配置可通过 --config 指定配置文件,或在策略运行命令中以 mod__sys_transaction_cost__<key> 的形式注入(见下文 CLI 参数)。
四、命令行参数:无需配置文件即可调整税费
init.py 为 rqalpha run 命令动态注册了以下 CLI 选项(cli_prefix = "mod__sys_transaction_cost__"):
| 短参数 | 长参数 | 作用 |
|---|---|---|
-cm |
--commission-multiplier |
设置统一佣金倍率([deprecated] 已废弃) |
-scm |
--stock-commission-multiplier |
设置股票佣金倍率 |
-fcm |
--futures-commission-multiplier |
设置期货佣金倍率 |
-cnsmc |
--cn-stock-min-commission |
设置 A 股最小手续费(单位:元) |
-smc |
--stock-min-commission |
设置最小手续费([deprecated],实际写入 cn_stock_min_commission) |
-tm |
--tax-multiplier |
设置印花倍率 |
--pit-tax |
— | 启用历史真实印花税率(flag,默认关闭) |
典型用法示例(将股票佣金提升至默认万八的 1.5 倍、最小手续费设为 10 元):
$ rqalpha run -f 策略文件.py \
-scm 1.5 \
-cnsmc 10 \
--pit-tax
注意:-smc 虽然长参数名是 --stock-min-commission,但其取值实际写入 cn_stock_min_commission 字段(见 init.py),属历史兼容设计,新代码应使用 -cnsmc 或配置文件中的 stock_min_commission。
五、源码级原理:股票税费的计算逻辑
股票税费决策器 StockTransactionCostDecider 位于 deciders.py,核心参数在初始化时固定:
self.commission_rate = 0.0008 # 默认佣金率:万八
self.tax_rate = 0.0005 # 默认印花税率:万分之五
5.1 佣金:万八 + 最小手续费 + 按订单分摊算法
单笔佣金毛额的计算公式为:
cost_commission = price * quantity * commission_rate * commission_multiplier
即 成交价 × 成交量 × 0.0008 × 股票佣金倍率。由于 A 股普遍存在"单笔佣金最低 5 元"的行业惯例,源码实现了一个按 order_id 记账的剩余手续费算法(_calc_commission,deciders.py):
- 以
order_id为键,将每个订单的"剩余待收最小手续费"初始化为min_commission(默认 5 元)存入commission_map; - 每笔
trade到来时计算其cost_commission; - 若
cost_commission > 剩余手续费:首笔成交直接返回cost_commission(等价于免去最小手续费),后续成交返回cost_commission - 剩余手续费; - 若
cost_commission <= 剩余手续费:首笔成交直接收取min_commission(提前把最小手续费收掉),后续成交返回 0(最小手续费已在前面收过)。
该设计保证了"一个订单拆成多笔成交时,最小手续费只收一次",避免大单被拆分时重复收取 5 元门槛费。若 order_id 为空(如某些批量场景),则退化为 max(cost_commission, min_commission) 的简单形式。
5.2 印花税:卖出单边收取,仅限普通股票
_calc_tax 的实现(deciders.py)非常明确:
def _calc_tax(self, args):
if args.side == SIDE.BUY or args.instrument.type != INSTRUMENT_TYPE.CS:
return 0
cost_money = args.price * args.quantity
return cost_money * self.tax_rate * self.tax_multiplier
即买入不收取印花税(单边收取),且只有类型为 CS(普通股票)的标的才计税;ETF、指数等其他品种即使卖出也不收印花税。税额 = 成交价 × 数量 × 印花税率 × 印花倍率。
5.3 历史税率切换(pit_tax)
官方文档说明"股票默认印花税为千分之一,单边收取"。需要结合源码理解这一表述:当前仓库中,当 pit_tax=False(默认)时,tax_rate 固定为 0.0005(万分之五);当 pit_tax=True 时,决策器会监听 PRE_BEFORE_TRADING 事件,并依据时间节点自动切换真实历史税率(deciders.py):
STOCK_PIT_TAX_CHANGE_DATE = datetime(2023, 8, 28)
# 交易日期 < 2023-08-28:tax_rate = 0.001(千分之一)
# 交易日期 >= 2023-08-28:tax_rate = 0.0005(万分之五)
因此,若回测区间跨越 2023-08-28,且希望还原当时真实的印花税政策(此前为千分之一,此后减半为万分之五),应开启 --pit-tax;否则全程按当前万分之五计收。
5.4 批量估算(batch_estimate)
除逐笔 calc 外,StockTransactionCostDecider 还实现了 batch_estimate(deciders.py),用于组合调仓等场景的快速成本估算:
commission = max(成交量变化额 × 价格 × 万八 × 倍率, 最小手续费)
tax = 成交量变化额 × 价格 × 印花税率 × (变化额 < 0) # 仅卖出方向计印花税
六、源码级原理:期货税费的计算逻辑
期货决策器 FuturesTransactionCostDecider(deciders.py)不设统一费率,而是逐合约读取交易所规定的佣金参数:
info = self.env.data_proxy.get_futures_trading_parameters(ins.order_book_id, self.env.trading_dt)
其核心逻辑(_calc_commission)可概括为:
- 按计费方式分支(
info.commission_type):BY_MONEY(按成交额):佣金 =价格 × 数量 × 合约乘数(contract_multiplier) × 佣金比率;BY_VOLUME(按手数):佣金 =数量 × 佣金比率;
- 按开平仓方向分支(
position_effect):- 开仓(
OPEN):使用open_commission_ratio; - 平仓:平昨仓部分使用
close_commission_ratio,平今仓部分使用close_commission_today_ratio(区分close_today_quantity);
- 开仓(
- 最后统一乘以期货佣金倍率
futures_commission_multiplier。
期货不收取印花税与其它费用:TransactionCost(commission=..., tax=0, other_fees=0)。因此期货的成本控制核心在于佣金倍率与合约参数,这也解释了为何"期货默认佣金因合约而异"(README 原话)。
七、与框架的交互:Decider 注册与调用链
7.1 注册阶段(start_up)
TransactionCostMod.start_up(mod.py)完成两件事:
- 解析配置并校验倍率合法性、处理
cn_stock_min_commission弃用告警; - 遍历
INST_TYPE_IN_STOCK_ACCOUNT(股票账户内的各标的类型,跳过PUBLIC_FUND公募基金),为每个类型注册StockTransactionCostDecider;同时为INSTRUMENT_TYPE.FUTURE注册FuturesTransactionCostDecider。
注册动作通过 env.set_transaction_cost_decider(instrument_type, decider) 写入环境(environment.py)。
7.2 调用阶段(calc_transaction_cost)
环境对外暴露统一入口 calc_transaction_cost(environment.py):
- 根据成交标的的
ins.type与ins.market查找已注册的 Decider; - 查不到时抛出
NotImplementedError(提示 "No such transaction cost decider"); - 查到则调用
decider.calc(args)返回TransactionCost。
TransactionCostArgs 与 TransactionCost 均为 NamedTuple(interface.py),前者携带 instrument/price/quantity/side/position_effect/order_id/close_today_quantity,后者由 commission/tax/other_fees 三项构成,并提供 total 属性汇总总费用。任何第三方 Mod 都可以实现 AbstractTransactionCostDecider 接口(calc 方法)替换默认税费逻辑,这正是该 Mod"可扩展、可替换"的体现。
7.3 策略侧读取与测试验证
- 策略上下文(strategy_context.py)会将
stock_commission_multiplier、futures_commission_multiplier暴露为上下文属性,策略代码可直接读取当前生效的倍率。 - 仓库提供集成测试 test_commission_multiplier.py,用于验证佣金倍率配置对成交成本的实际影响,可作为二次开发时参考的验证范式。
八、注意事项与常见问题
cn_stock_min_commission已弃用:启动时若显式配置该字段,会收到日志警告 "cn_stock_min_commission is deprecated, use stock_min_commission instead",请迁移到stock_min_commission。- 倍率取值范围为
[0, +∞):负数配置会在start_up阶段直接报错终止。 - 公募基金(PUBLIC_FUND)不注册股票税费决策器:此类标的的税费由其它机制处理,勿期望本 Mod 覆盖。
- 印花税只对普通股票(CS)的卖出方向收取:ETF、LOF、指数、可转债等品种卖出不产生印花税;期货无印花税。
- 历史回测请按需开启
--pit-tax:默认固定万分之五税率,若要还原 2023-08-28 之前"千分之一"的真实政策,必须开启该选项。 - 最小手续费按订单分摊:同一订单多笔成交只收取一次最低 5 元门槛费,这是
commission_map按order_id记账的核心价值,理解此算法可避免对回测费用产生误判。
综上,sys_transaction_cost Mod 以"不同市场、不同标的差异化计税"为设计目标,通过 Decider 注册机制与最小手续费分摊、单边印花税、历史税率切换等细节实现,为 RQAlpha 回测提供了贴近真实市场规则的交易成本模型。掌握其配置项与源码实现,即可对回测成本进行精细控制与定制。