RTNeural

一个用 C++ 编写的轻量级神经网络推理引擎（neural network inferencing engine）。该库专为实时系统（real-time systems）设计，特别适用于实时音频处理（real-time audio processing）。

当前支持的网络层（layers）：

• Dense（全连接层）
• GRU（门控循环单元）
• LSTM（长短期记忆网络）
• Conv1D（一维卷积层）
• Conv2D（二维卷积层）
• MaxPooling（最大池化层）
• BatchNorm1D（一维批量归一化）
• BatchNorm2D（二维批量归一化）

当前支持的激活函数（activations）：

• tanh
• ReLU
• Sigmoid
• SoftMax
• ELu
• PReLU

附加资源：

• RTNeural Discord
• API Reference
• Reference Paper
• Example Plugin
• Comparison Benchmarks
• Experimental Extensions

引用

如果您在学术工作中使用 RTNeural，请按以下方式引用：

@article{chowdhury2021rtneural,
        title={RTNeural: Fast Neural Inferencing for Real-Time Systems},
        author={Jatin Chowdhury},
        year={2021},
        journal={arXiv preprint arXiv:2106.03037}
}

使用方法

RTNeural 可以加载已训练好的神经网络权重并运行推理。简单示例请参见 examples/ 目录。

从训练好的网络导出权重

神经网络通常使用 Python 库（如 Tensorflow 或 PyTorch）进行训练。训练完成后，可以将网络权重导出为 json 文件供 RTNeural 读取。Tensorflow 顺序模型的导出示例在 python/model_utils.py 中实现，使用方法如下：

# 导入依赖
import tensorflow as tf
from tensorflow import keras
from model_utils import save_model

# 创建 Tensorflow 模型
model = keras.Sequential()
...

# 训练模型
model.train()

# 导出模型权重
save_model(model, 'model_weights.json')

PyTorch 模型导出示例请参见 此示例脚本。

创建模型

接下来，可以从导出的 json 文件中创建 C++ 推理引擎：

#include <RTNeural.h>
...
std::ifstream jsonStream("model_weights.json", std::ifstream::binary);
auto model = RTNeural::json_parser::parseJson<double>(jsonStream);

运行推理

运行推理前建议重置模型状态（如果模型有状态）：

model->reset();

然后运行推理：

double input[] = { 1.0, 0.5, -0.1 }; // 设置输入向量
double output = model->forward(input); // 计算输出

编译时 API

上述代码会在运行时动态创建推理引擎。如果模型架构在编译时固定，可以使用 RTNeural 的编译时 API 定义推理引擎类型，这能显著提升性能：

// 定义模型类型
RTNeural::ModelT<double, 8, 1,
    RTNeural::DenseT<double, 8, 8>,
    RTNeural::TanhActivationT<double, 8>,
    RTNeural::DenseT<double, 8, 1>
> modelT;

// 从 json 加载模型权重
std::ifstream jsonStream("model_weights.json", std::ifstream::binary);
modelT.parseJson(jsonStream);

modelT.reset(); // 重置状态

double input[] = { 1.0, 0.5, -0.1, 0.0, 0.4, 0.9, -0.2, -0.3 }; // 设置输入向量
double output = modelT.forward(input); // 计算输出

从 PyTorch 加载层

上述示例假设模型已从 TensorFlow 导出。对于 PyTorch 模型，RTNeural 的命名空间 RTNeural::torch_helpers 提供了加载 PyTorch 导出层的辅助函数。

// 从 json 加载模型权重
std::ifstream jsonStream("model_weights.json", std::ifstream::binary);
nlohmann::json modelJson;
jsonStream >> modelJson;

// 从静态模型加载层
RTNeural::ModelT<float, 1, 1, RTNeural::DenseT<float, 1, 1>> model;
RTNeural::torch_helpers::loadDense(modelJson, "name_of_layer.", model.get<0>());

更多示例请参见 examples/torch 目录。

使用 CMake 构建

RTNeural 使用 CMake 构建，最简单的链接方式是将其作为子模块包含：

...
add_subdirectory(RTNeural)
target_link_libraries(MyCMakeProject LINK_PUBLIC RTNeural)

如果项目未使用 CMake，请参见下方的非 CMake 构建说明。

选择后端（Backend）

RTNeural 支持三种后端：

• Eigen（一个 C++ 线性代数库）
• xsimd（SIMD 向量化库）
• C++ STL

通过传递 -DRTNEURAL_EIGEN=ON、-DRTNEURAL_XSIMD=ON 或 -DRTNEURAL_STL=ON 到 CMake 配置中选择后端。默认使用 Eigen 后端。也可以在 CMake 配置中这样选择：

set(RTNEURAL_XSIMD ON CACHE BOOL "Use RTNeural with this backend" FORCE)
add_subdirectory(modules/RTNeural)

一般来说，Eigen 后端在大型网络中性能最佳，小型网络可能 XSIMD 表现更好。建议在目标平台上测试所有可用后端以获得最佳性能。更多信息请参见 基准测试结果。

请注意您选择的后端库的许可协议要求。

其他配置选项

如果你希望使用 AVX SIMD 扩展（Advanced Vector Extensions 单指令多数据扩展）构建 RTNeural，
可以通过 -DRTNEURAL_USE_AVX=ON 参数运行 CMake。请注意，
当编译目标平台不支持 AVX 指令时，此选项将无效。

构建测试套件

要构建 RTNeural 的测试套件，请运行 cmake -Bbuild -DBUILD_TESTS=ON，然后
执行 cmake --build build。要在 build 文件夹中运行完整测试套件，请运行 ctest。
更多信息请参见 tests/README.md。

构建性能基准测试

要构建性能基准测试，请运行
cmake -Bbuild -DBUILD_BENCH=ON，然后
执行 cmake --build build --config Release。要运行图层基准测试，请运行
./build/rtneural_layer_bench <layer> <length> <in_size> <out_size>。要
运行模型基准测试，请运行 ./build/rtneural_model_bench。

构建示例

要构建 RTNeural 示例，请运行：

cmake -Bbuild -DBUILD_EXAMPLES=ON
cmake --build build --config Release

示例程序将位于 build/examples_out/ 目录中，可从此处运行。

一个在实时音频插件中使用 RTNeural 的示例可在 GitHub
此处 找到。

不使用 CMake 构建

如果希望在非 CMake 项目中使用 RTNeural，
可以将其作为头文件库包含，并配合以下步骤：

1. 添加编译时定义以设置 RTNeural 的默认字节对齐方式。
   大多数情况下，定义应为以下之一：

   • RTNEURAL_DEFAULT_ALIGNMENT=16
   • RTNEURAL_DEFAULT_ALIGNMENT=32

2. 添加编译时定义以选择后端。
   如果使用 STL 后端，则无需定义。定义应为以下之一：

   • RTNEURAL_USE_EIGEN=1
   • RTNEURAL_USE_XSIMD=1

3. 添加所选后端的必要包含路径。路径应为以下之一：

   • <repo>/modules/Eigen
   • <repo>/modules/xsimd/include/xsimd

也可以参考
示例 Makefile。

贡献

欢迎为本项目做出贡献！
当前需要以下改进：

• 改进对二维输入/输出数据的支持。
• 改进无状态 Conv1D（一维卷积层）的支持。
• 更健壮的模型导出/加载支持。
• 增加更多激活层支持。
• 任何提升整体性能的修改。

代码维护和文档完善同样重要！请注意，如果实现新图层类型，
无需为所有后端提供支持，但建议至少提供一个使用 STL
后端的"回退"实现。

贡献者

感谢以下人员的重要贡献：

• wayne-chen: Softmax 激活层和通用 API 改进。
• hollance: RTNeural 标志。
• stepanmk: Eigen Conv1D 层优化。
• DamRsn: Conv2D 和 BatchNorm2D 层的 Eigen 实现。
• lHorvalds: Eigen 后端优化。
• davidtrevelyan: 测试框架升级。
• purefunctor: Conv1D 的 Groups 功能。

使用 RTNeural 的项目

RTNeural 目前被多个音频插件和其他项目使用：

• 4000DB-NeuralAmp: 对 Akai 4000DB 磁带机前置放大器部分的神经模拟。
• AIDA-X: 支持 AU/CLAP/LV2/VST2/VST3 的音频插件，可加载 RTNeural 模型和音箱 IR。
• BYOD: 含多个机器学习效果的吉他失真插件。
• Chow Centaur: 使用实时循环神经网络的吉他效果器模拟插件。
• Chow Tape Model: 使用实时密集神经网络的模拟磁带模拟。
• cppTimbreID: 音频特征提取库。
• guitarix: 包含神经网络放大器模型的吉他效果套件。
• GuitarML: 使用机器学习模拟吉他放大器和效果的插件。
• MLTerror15: 使用循环神经网络深度学习的 Orange Tiny Terror 模拟器。
• neural-amp-modeler-lv2: 用于神经网络机器学习放大器模型的 LV2 插件。
• NeuralNote: 使用 Spotify 的 basic-pitch 模型的音频转 MIDI 插件。
• rt-neural-lv2: 使用 RTNeural 模拟吉他效果器和放大器的无界面 LV2 插件。
• stompbox: 吉他放大和效果踏板模拟。
• Tone Empire 插件:
  • LVL - 01: 基于 AI/ML 的压缩效果器。
  • TM700: 机器学习磁带模拟效果。
  • Neural Q: 使用循环神经网络的模拟双频段均衡器。
• ToobAmp: 适用于 Raspberry Pi 的吉他效果插件。

如果你的项目使用了 RTNeural，请告知我们，我们将将其添加到此列表！

许可证

RTNeural 是开源软件，采用
三条款 BSD 许可证（BSD 3-clause license）。

祝使用愉快！

RTNeural 快速上手指南

环境准备

• 系统要求：Linux/macOS/Windows（支持C++17编译器）
• 前置依赖：
  • CMake 3.14+
  • C++编译器（推荐GCC 9+/Clang 10+/MSVC 2019）
  • 可选依赖（根据后端选择）：
    • Eigen 3.4+（默认后端）
    • xsimd 8.0+（SIMD加速后端）

安装步骤

1. 克隆项目仓库

git clone https://github.com/jatinchowdhury18/RTNeural.git
cd RTNeural

2. 构建项目（推荐使用CMake）

mkdir build && cd build
cmake .. -DRTNEURAL_EIGEN=ON  # 使用Eigen后端（默认）
cmake --build . --config Release

3. 作为子模块集成到项目

# CMakeLists.txt配置示例
add_subdirectory(RTNeural)
target_link_libraries(your_project PRIVATE RTNeural)

基本使用

1. 导出模型权重（Python）

# 示例：TensorFlow模型导出
from model_utils import save_model

model = keras.Sequential([
    keras.layers.Dense(8, input_shape=(3,)),
    keras.layers.Tanh(),
    keras.layers.Dense(1)
])
model.train()  # 训练模型
save_model(model, 'model_weights.json')  # 导出权重

2. C++推理实现

#include <RTNeural.h>

int main() {
    // 动态加载模型
    std::ifstream jsonStream("model_weights.json", std::ifstream::binary);
    auto model = RTNeural::json_parser::parseJson<double>(jsonStream);
    
    model->reset();  // 重置状态
    
    double input[] = {1.0, 0.5, -0.1};
    double output = model->forward(input);  // 执行推理
    
    return 0;
}

3. 编译时优化（固定模型结构）

// 定义固定结构模型
RTNeural::ModelT<double, 8, 1,
    RTNeural::DenseT<double, 8, 8>,
    RTNeural::TanhActivationT<double, 8>,
    RTNeural::DenseT<double, 8, 1>
> modelT;

// 加载权重
std::ifstream jsonStream("model_weights.json", std::ifstream::binary);
modelT.parseJson(jsonStream);
modelT.reset();

double input[] = { /* 8个输入值 */ };
double output = modelT.forward(input);

4. 后端选择建议

• Eigen：适合大网络（默认）
• xsimd：适合小网络（SIMD加速）
• STL：通用兼容模式

# 示例：强制使用xsimd后端
set(RTNEURAL_XSIMD ON CACHE BOOL "Use XSIMD backend" FORCE)
add_subdirectory(RTNeural)

⚠️ 注意：使用AVX指令集需添加 -DRTNEURAL_USE_AVX=ON（仅限支持AVX的平台）