vectorbt Rust 引擎(vectorbt-rust)完整指南:安装、引擎调度原理、源码构建与基准测试
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),其流程为:
- 调用
resolve_engine(engine, supports_rust=combine_rust_support(...))得到实际引擎; - 解析结果为
"rust"时,用prepare_array_for_rust将数组转成 Rust 期望的精确 dtype(float64/bool_); - 从
vectorbt_rust.generic导入set_by_mask_rs并调用; - 否则回退到
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 给出了明确的六步流程:
- 以 Numba 为参照:把
nb.py中的 Numba 实现当作行为基准; - 实现 Rust 内核:保持与 Numba 相同的参数顺序与返回形状;
- 注册 PyO3 函数:在对应 Rust 子模块中注册函数,并在 src/lib.rs 中挂接新子模块;
- 添加 dispatch 包装:在 Python 侧 dispatch 层新增引擎中立包装函数;
- 补齐测试:添加一致性(parity)、回退(fallback)、显式报错(explicit-error)与布局敏感(layout-sensitive)四类测试;
- 添加基准用例:一致性稳定后再补充基准测试用例。
两条工程纪律(源码与文档共同强调):
- 保持改动窄而机械(narrow and mechanical),避免大范围重构;
- 不要在
nb.py中导入 Rust,也不要让公开调用方直接导入vectorbt_rust——所有 Rust 调用必须经由 dispatch 层间接完成,从而保证auto回退机制始终生效。
九、小结
vectorbt-rust 的价值在于:它让 vectorbt 在不改动公开 API、不改变数值语义的前提下,将计算内核从 Numba 切换到 Rust。其工程实现有三个关键设计:
- 引擎中立 dispatch 层:
vectorbt/_engine.py提供统一解析器与参数兼容性判定,vectorbt/generic/dispatch.py等各域 dispatch 层按调用解析结果路由到 Rust 或 Numba; - 透明回退:
auto模式保证"能用 Rust 就用、不能用就回退",且随机函数默认保持 Numba 随机流; - 严格正确性验证:以 Numba 为参照的 parity 测试 + 布局敏感测试 + 数值稳定性测试 + 基准矩阵,保证加速不以正确性为代价。
作为使用者的你,只需记住两件事:pip install "vectorbt[rust]" 安装,然后 vbt.settings["engine"] = "rust" 或逐调用传 engine="rust" 即可开启加速;其余交给 dispatch 层透明处理。