vectorbt Rust 引擎(vectorbt-rust)完整指南:安装、引擎调度原理、源码构建与基准测试

原创2026-09-24 13:32:592,285 阅读
文章标签:金融科技数据分析数据可视化高性能计算

vectorbt Rust 引擎(vectorbt-rust)完整指南:安装、引擎调度原理、源码构建与基准测试

vectorbt 是一个面向量化回测的高性能 Python 框架,其核心计算内核默认由 Numba 加速。vectorbt-rust 是 vectorbt 的可选 Rust 加速引擎,提供与 Numba 内核一一对应的高性能 drop-in 替代实现,并可通过 engine="rust" 参数或全局引擎设置透明分发,无需改动任何调用代码。读完本文你将掌握 vectorbt-rust 的安装与版本兼容机制、auto/numba/rust 三种引擎模式的行为差异、底层 dispatch 解析器的工作方式,以及如何从源码构建、运行回归测试与生成基准测试报告。

提醒:大多数用户不应该直接导入 vectorbt_rust。请优先使用 vectorbt 的公开 API,并在调用时传入 engine="rust" 或设置全局引擎即可。

一、Rust 引擎是什么:Numba 内核的高性能替代品

vectorbt 的公开 API(指标、信号、收益、回撤、组合回测等)在底层依赖一批确定性、数组导向的计算内核。这些内核最初以 Numba JIT 编译函数的形式实现,位于各模块的 nb.py 中。vectorbt-rust 则用 Rust 重新实现了同一批内核,并通过 PyO3 暴露为 Python 扩展模块 vectorbt_rust。

从源码结构看,Rust 侧的实现被组织为七个功能子模块(见 rust/src/lib.rs):

Rust 子模块 对应 vectorbt 功能域
generic 通用数组操作(mask 赋值、fillna、shift、rolling、expand、reduce 等)
indicators 技术指标内核
labels 标签生成内核
returns 收益与风险指标内核
records 记录类内核(区间、回撤等)
portfolio 组合回测内核
signals 信号生成内核

模块入口在 rust/src/lib.rs:vectorbt_rust 通过 #[pymodule] 注册,并在 sys.modules 中挂载各子模块,使 from vectorbt_rust.generic import ... 形式的导入可用。

Rust 侧的关键依赖(见 rust/Cargo.toml)包括:

  • pyo3 0.29:Python/Rust 绑定;
  • numpy 0.29:NumPy 数组互操作;
  • ndarray 0.17:Rust 侧多维数组计算;
  • rand 0.10 与 rand_chacha 0.10:随机数生成(可播种、可复现)。

二、安装与版本兼容性

2.1 与 vectorbt 一起安装

pip install "vectorbt[rust]"

该命令通过 vectorbt 的 rust 可选依赖组安装扩展,其在 pyproject.toml 中定义为固定版本依赖:

[project.optional-dependencies]
rust = [
    "vectorbt-rust==1.1.0",
]

2.2 直接安装扩展包

pip install vectorbt-rust

vectorbt-rust 必须与 vectorbt 版本兼容:引擎解析器会比较双方版本的 major/minor 前缀,前缀不一致时视为不可用。这一检查实现在 vectorbt/_engine.py 的 is_rust_available() 中:它尝试导入 vectorbt_rust,将 vectorbt.__version__ 与 vectorbt_rust.__version__ 分别用 rsplit(".", 1)<a href="https://link.gitcode.com/i/76ef6e1885a1e0296886961b0af85e94" target="_blank">0] 去掉 patch 号后比较;不一致时发出警告并回退到 Numba。该结果会被缓存(_rust_status),需要时可通过 clear_engine_cache() 清除缓存(见 [vectorbt/_engine.py)。

2.3 从源码构建

从仓库根目录构建:

python -m pip install -U pip maturin
python -m pip install -e ".[test]"
python -m maturin develop --manifest-path rust/Cargo.toml --release

也可以直接在 rust/ 目录内构建:

cd rust
python -m maturin develop --release

构建工具链基于 maturin,声明于 rust/pyproject.toml:构建后端要求 maturin>=1.14,<2.0,模块名 vectorbt_rust,Python 版本要求 >=3.11,<3.15,运行依赖 numpy>=2.4.6。

release 构建配置(见 rust/Cargo.toml)开启:

  • lto = true:链接时优化;
  • codegen-units = 1:单代码生成单元,利于跨函数内联优化;
  • opt-level = 3:最高优化等级;
  • strip = true:剥离符号,减小体积。

基准测试必须使用 release 构建;debug 构建包含额外开销,其结果不具备代表性。

三、使用方式:局部指定与全局设置

3.1 单次调用指定引擎

import vectorbt as vbt

out = vbt.MA.run(close, window=20, engine="rust")

只要 vectorbt 的公开 API 接受 engine 参数,即可按调用粒度选择引擎。例如 tests/test_engine.py 中验证了 df.vbt.diff(1, engine="rust")、df.vbt.rolling_mean(2, engine="rust")、rets.vbt.returns.daily(engine="rust") 等访问器方法均支持显式传入引擎(见 tests/test_engine.py)。

3.2 全局设置引擎

import vectorbt as vbt

vbt.settings["engine"] = "rust"

全局引擎设置的默认值为 "auto"(见 vectorbt/_settings.py)。设置后,未显式传 engine 的调用都会走该引擎;通过 vbt.settings.reset() 可恢复默认。

3.3 三种引擎取值的行为差异

取值 行为
auto Rust 已安装、版本兼容且该调用受支持时使用 Rust,否则回退到 Numba
numba 强制使用 Numba 实现
rust 强制使用 Rust;若 Rust 不可用或该调用不受支持,抛出带可操作提示的错误

对应源码逻辑在 resolve_engine()(见 vectorbt/_engine.py):

  • engine=None 时读取 settings["engine"];
  • "numba" 直接返回 Numba;
  • "rust" 时若 vectorbt-rust 未安装则抛出 ImportError,提示 pip install vectorbt-rust(或 pip install vectorbt[rust]);若该调用不支持 Rust(supports_rust.supported 为 False),则抛出 ValueError 并附带原因与 Use engine='numba' 建议;
  • "auto" 时仅当调用受支持且 Rust 可用才走 Rust,否则回退 Numba;
  • 非法取值抛出 ValueError("Invalid engine. Expected 'auto', 'numba', or 'rust'.")。

3.4 随机函数的特殊处理

随机化函数例外:auto 模式下的随机函数会继续使用 Numba,以保持遗留的 NumPy/Numba 随机流(保证可复现性)。只有显式传入 engine="rust" 才使用 Rust 的随机实现。该逻辑由 resolve_random_engine() 实现(见 vectorbt/_engine.py):engine=None 或 "auto" 一律解析为 "numba"。

测试对此有专门覆盖(见 tests/test_engine.py):

np.testing.assert_array_equal(dispatch.shuffle(a, seed=42, engine="auto"), nb.shuffle_nb(a, seed=42))

Rust 侧的 shuffle/shuffle_1d 内核支持 seed 参数,使用 ChaCha8 流密码生成器保证可复现(见 rust/src/generic.rs);tests/test_engine.py 中 test_dispatch_rust_shuffle_is_seeded 验证了同种子输出一致、按列打乱且元素集合不变。

四、底层原理:引擎调度(dispatch)机制

4.1 共享解析器

引擎解析的共享代码位于 vectorbt/_engine.py,它不依赖任何具体模块,被 generic、returns、signals、records、portfolio、indicators、labels 等各域的 dispatch 层复用。核心抽象有两个:

  • RustSupport:一次引擎中立调用的支持性判定结果,包含 supported(是否支持 Rust)、reason(不支持时的原因文本)、conversions(调用 Rust 前所需的软转换列表);
  • RustConversion:记录目标 dtype 与待转换元素个数,用于在 Rust 调用前完成数组 dtype 转换。

combine_rust_support()(见 vectorbt/_engine.py)将多个支持性判定合并,返回第一个不支持的判定结果,并聚合所有需要的转换。

4.2 兼容性判定:什么输入才能走 Rust

dispatch 层通过一组“XXX_compatible_with_rust”函数逐项检查参数(见 vectorbt/_engine.py):

判定函数 检查内容
array_compatible_with_rust 必须是 NumPy 数组、1D/2D;dtype 不匹配时要求可安全转换(np.can_cast(..., casting="safe")),并将转换记为软转换
exact_array_compatible_with_rust 可变参数要求精确 dtype(如 float64),否则不支持
scalar_compatible_with_rust 标量可转换为 float64
unit_interval_compatible_with_rust 标量须落在闭区间 [0, 1](如 VaR 的置信水平)
non_neg_int_compatible_with_rust 整数参数须非负(对应 Rust usize)
non_neg_array_compatible_with_rust int64 数组且不含负值
mask_and_array_compatible_with_rust 数组与布尔 mask 形状一致
mask_and_values_compatible_with_rust 数组、mask、替换值三者形状一致
rolling_compatible_with_rust rolling 参数(window、minp)非负
col_range_compatible_with_rust 列区间须为 (n_cols, 2) 的 int64 数组
col_map_compatible_with_rust 列映射须为(col_idxs,col_lens)数组对
array_shape_compatible_with_rust 数组形状须与要求完全一致
flex_array_compatible_with_rust 数组可广播到目标 shape 且可转换 dtype(灵活数组处理)
callback_unsupported_with_rust 接收回调的函数一律标记为不支持 Rust

这些检查会产生两个层面的行为:auto 模式下不支持的调用静默回退 Numba;rust 模式下则抛出带明确原因的 ValueError。tests/test_engine.py 的 TestEngineResolution 类对此有系统化断言(见 tests/test_engine.py),例如 float32 数组受支持但需要转换为 float64,int64 数组不可安全转换到 float64 而直接不支持,非法引擎值抛 ValueError,未安装 Rust 时显式 engine="rust" 抛 ImportError。

4.3 一个典型 dispatch 函数的完整调用链

以 set_by_mask 为例(见 vectorbt/generic/dispatch.py),其流程为:

  1. 调用 resolve_engine(engine, supports_rust=combine_rust_support(...)) 得到实际引擎;
  2. 解析结果为 "rust" 时,用 prepare_array_for_rust 将数组转成 Rust 期望的精确 dtype(float64 / bool_);
  3. 从 vectorbt_rust.generic 导入 set_by_mask_rs 并调用;
  4. 否则回退到 vectorbt.generic.nb.set_by_mask_nb(Numba 实现)。

每个 dispatch 包装函数都保持与对应 *_nb 函数相同的参数顺序与返回形状,这是两套内核可以互相替换的前提。

五、兼容性边界:何时仍然走 Numba

当前 Rust 引擎面向 NumPy 数组 与 确定性、数组导向的内核。以下情况会有意保留 Numba 路径:

  • 接受回调的函数:如 dispatch.apply(...) 这类将 Python 回调应用于数组的函数,Rust 无法保留其行为,会标记为不支持;显式传 engine="rust" 时抛出 ValueError(测试见 tests/test_engine.py);
  • 不支持的输入组合:如不支持的 dtype(无法安全转换)、形状不匹配、越界参数(如 minp > window、置信水平超出 [0, 1]、负整数等)在 auto 下回退 Numba;
  • 随机函数:auto 模式保持 Numba 随机流。

换句话说,auto 的设计目标是在不改变任何语义的前提下尽量加速:凡是 Rust 能保证一致的结果就用 Rust,否则无缝回退。

六、测试:如何验证引擎正确性

6.1 运行引擎相关测试

从仓库根目录执行:

pytest tests/test_engine.py

运行完整测试套件:

pytest

6.2 跳过机制与强制启用

依赖 Rust 的测试在 vectorbt-rust 未安装或版本不兼容时会被自动跳过,例如:

@pytest.mark.skipif(not _engine.is_rust_available(), reason="vectorbt-rust is not installed or version-compatible")

要本地强制启用这些路径,先用 maturin develop 安装扩展即可(即上文源码构建步骤)。

6.3 测试覆盖的核心验证点

测试文件 体现了引擎的正确性保障体系:

  • 引擎解析行为:TestEngineResolution 覆盖各兼容性判定函数与 resolve_engine 的三种模式及错误路径;
  • Numba/Rust 输出一致性(parity):TestGenericRustParity、TestReturnsRustParity、TestSignalsRustParity 等将同一批确定性输入分别喂给 dispatch.xxx(..., engine="rust") 与对应的 nb.xxx_nb,用 assert_allclose(..., equal_nan=True) 逐对比对。仅 generic 域就覆盖了 mask 赋值、fillna、shift、diff、pct_change、ffill/bfill、nan 系列归约、rolling/expanding/ewm、分组扁平化、区间与回撤记录等数十个内核;
  • 布局敏感性:同时以 C 连续(ascontiguousarray)与 Fortran 连续(asfortranarray)布局输入,验证两种内存布局下输出一致;还包含空列、空行、0 行数组等边界场景;
  • 数值稳定性:test_rust_rolling_std_stability 用 1e8 量级的大均值数据(窗口 4000、跨度 7000)对比 pandas rolling 结果,atol=1e-12,验证滚动标准差算法的数值稳定性;
  • 随机性:同种子可复现、auto 走 Numba、显式 rust 用 ChaCha8;
  • 记录型输出:find_ranges、get_drawdowns 返回的记录数组与 Numba 版本在 dtype、itemsize、数值上完全一致;
  • 访问器与全局引擎:df.vbt.*、returns 访问器方法支持 engine 参数,且 vbt.settings["engine"] = "rust" 全局生效。

七、基准测试:量化 Rust 内核的加速效果

基准脚本位于 benchmarks 目录。它们是正确性感知的微基准:以确定性输入成对执行 Numba 与 Rust 函数,可选校验输出一致性,并输出 CSV 或 Markdown 报告(详见 benchmarks/README.md)。

7.1 单次基准运行

从仓库根目录:

python benchmarks/bench_engine.py --rows 5000 --cols 50 --check

--check 会在计时前校验 Numba 与 Rust 输出一致。默认输出 CSV 格式(列:function,numba_s,rust_s,speedup)。

7.2 生成 Markdown 基准矩阵

python benchmarks/bench_matrix.py

bench_matrix.py 会跨多种配置运行 bench_engine.py(100x1、1Kx1、10Kx1、100Kx1、100x10、1Kx10、10Kx10、100Kx10、1Kx100、10Kx100 等 10 种尺寸),每配置重复 5 次、预热 2 次、窗口 20、种子 42,支持 contiguous / view / copy-included 三种布局与 core / extended 两套用例,最后汇总生成 Markdown 表格(含 min/median/mean/max 统计量)。

发布任何基准数字前务必使用 release 构建;另外请注意:生成的报告属于基准输出而非权威行为说明,在 Rust、dispatch 或用例发生实质变更后应重新生成。

八、新增 Rust 内核的标准流程

如果你要在仓库中扩展新的 Rust 内核,rust/README.md 给出了明确的六步流程:

  1. 以 Numba 为参照:把 nb.py 中的 Numba 实现当作行为基准;
  2. 实现 Rust 内核:保持与 Numba 相同的参数顺序与返回形状;
  3. 注册 PyO3 函数:在对应 Rust 子模块中注册函数,并在 src/lib.rs 中挂接新子模块;
  4. 添加 dispatch 包装:在 Python 侧 dispatch 层新增引擎中立包装函数;
  5. 补齐测试:添加一致性(parity)、回退(fallback)、显式报错(explicit-error)与布局敏感(layout-sensitive)四类测试;
  6. 添加基准用例:一致性稳定后再补充基准测试用例。

两条工程纪律(源码与文档共同强调):

  • 保持改动窄而机械(narrow and mechanical),避免大范围重构;
  • 不要在 nb.py 中导入 Rust,也不要让公开调用方直接导入 vectorbt_rust——所有 Rust 调用必须经由 dispatch 层间接完成,从而保证 auto 回退机制始终生效。

九、小结

vectorbt-rust 的价值在于:它让 vectorbt 在不改动公开 API、不改变数值语义的前提下,将计算内核从 Numba 切换到 Rust。其工程实现有三个关键设计:

  1. 引擎中立 dispatch 层:vectorbt/_engine.py 提供统一解析器与参数兼容性判定,vectorbt/generic/dispatch.py 等各域 dispatch 层按调用解析结果路由到 Rust 或 Numba;
  2. 透明回退:auto 模式保证"能用 Rust 就用、不能用就回退",且随机函数默认保持 Numba 随机流;
  3. 严格正确性验证:以 Numba 为参照的 parity 测试 + 布局敏感测试 + 数值稳定性测试 + 基准矩阵,保证加速不以正确性为代价。

作为使用者的你,只需记住两件事:pip install "vectorbt[rust]" 安装,然后 vbt.settings["engine"] = "rust" 或逐调用传 engine="rust" 即可开启加速;其余交给 dispatch 层透明处理。

登录后查看全文
vectorbt