RQAlpha 交易税费 Mod(sys_transaction_cost)完全指南:配置项、命令行参数与税费计算源码解析

原创2026-10-06 18:16:481,849 阅读
文章标签:金融科技

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):

  1. 以 order_id 为键,将每个订单的"剩余待收最小手续费"初始化为 min_commission(默认 5 元)存入 commission_map;
  2. 每笔 trade 到来时计算其 cost_commission;
  3. 若 cost_commission > 剩余手续费:首笔成交直接返回 cost_commission(等价于免去最小手续费),后续成交返回 cost_commission - 剩余手续费;
  4. 若 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)可概括为:

  1. 按计费方式分支(info.commission_type):
    • BY_MONEY(按成交额):佣金 = 价格 × 数量 × 合约乘数(contract_multiplier) × 佣金比率;
    • BY_VOLUME(按手数):佣金 = 数量 × 佣金比率;
  2. 按开平仓方向分支(position_effect):
    • 开仓(OPEN):使用 open_commission_ratio;
    • 平仓:平昨仓部分使用 close_commission_ratio,平今仓部分使用 close_commission_today_ratio(区分 close_today_quantity);
  3. 最后统一乘以期货佣金倍率 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):

  1. 根据成交标的的 ins.type 与 ins.market 查找已注册的 Decider;
  2. 查不到时抛出 NotImplementedError(提示 "No such transaction cost decider");
  3. 查到则调用 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,用于验证佣金倍率配置对成交成本的实际影响,可作为二次开发时参考的验证范式。

八、注意事项与常见问题

  1. cn_stock_min_commission 已弃用:启动时若显式配置该字段,会收到日志警告 "cn_stock_min_commission is deprecated, use stock_min_commission instead",请迁移到 stock_min_commission。
  2. 倍率取值范围为 [0, +∞):负数配置会在 start_up 阶段直接报错终止。
  3. 公募基金(PUBLIC_FUND)不注册股票税费决策器:此类标的的税费由其它机制处理,勿期望本 Mod 覆盖。
  4. 印花税只对普通股票(CS)的卖出方向收取:ETF、LOF、指数、可转债等品种卖出不产生印花税;期货无印花税。
  5. 历史回测请按需开启 --pit-tax:默认固定万分之五税率,若要还原 2023-08-28 之前"千分之一"的真实政策,必须开启该选项。
  6. 最小手续费按订单分摊:同一订单多笔成交只收取一次最低 5 元门槛费,这是 commission_map 按 order_id 记账的核心价值,理解此算法可避免对回测费用产生误判。

综上,sys_transaction_cost Mod 以"不同市场、不同标的差异化计税"为设计目标,通过 Decider 注册机制与最小手续费分摊、单边印花税、历史税率切换等细节实现,为 RQAlpha 回测提供了贴近真实市场规则的交易成本模型。掌握其配置项与源码实现,即可对回测成本进行精细控制与定制。

登录后查看全文
rqalpha