在C++后端系统中引入oneDNN（曾用名DNNL）可以显著降低卷积、内积等算子的计算延迟。该库针对x86架构做了指令集层面的优化，并抽象出引擎、内存、原语三类核心对象，开发者无需手写汇编也能获得接近极限的吞吐。下面以Linux平台为例，说明从编译到调用的完整流程。
一、环境准备与编译链接
oneDNN支持源码构建与包管理器安装。若使用源码，推荐开启DNNL_CPU_RUNTIME=OMP以利用OpenMP多线程。CMake配置时可指定安装路径，便于后续在项目中引用头文件与静态库。
在C++工程里，需要链接dnnl库以及线程库。以g++为例，编译命令类似：g++ main.cpp -ldnnl -fopenmp -o app。如果系统未预装，可将构建出的libdnnl.a与include目录加入工程搜索路径。注意，oneDNN的API大部分位于dnnl命名空间，头文件为dnnl.hpp。
#include <dnnl.hpp>
#include <vector>
#include <iostream>
using namespace dnnl;
int main() {
// 创建CPU引擎
engine eng(engine::kind::cpu, 0);
stream s(eng);
std::cout << "engine created" << std::endl;
return 0;
}
二、核心概念与内存布局
oneDNN用memory对象描述张量，其关键属性是维度与格式标签。格式标签如nchw、nhwc、any决定了数据在内存中的排布。很多初学者直接传入任意布局，导致库内部插入重排操作，性能反而下降。最佳实践是先用任意格式让库挑选最优布局，再将输入数据按该布局填充。
原语（primitive）是具体的计算单元，比如卷积前向、内积、池化。每个原语在创建时需要描述符（descriptor），描述输入输出内存格式与算法。执行时通过stream提交，支持异步与顺序模式。理解这三者的关系，是写好C++调用代码的基础。
2.1 内存描述符示例
下面代码展示如何定义四维输入的内存描述符，并指定为任意格式交给库优化。实际部署中，常将权重预转换为库选定格式，避免每次推理都重排。
// 定义输入张量 1x3x224x224
memory::dims src_dims = {1, 3, 224, 224};
auto src_md = memory::desc(
src_dims,
memory::data_type::f32,
memory::format_tag::any); // 让库选择最优布局
三、卷积前向推理实战
以浮点32位卷积为例，需要分别构造源、权重、偏置、目标的内存描述符，再创建卷积前向描述符并指定算法。随后通过原语描述符生成可执行原语，分配实际内存后执行。以下片段省略错误处理，仅展示主链路。
在执行前，若输入内存格式与原语期望不一致，应先用reorder原语转换。生产环境通常把权重reorder一次后缓存，每次仅对输入做必要转换，从而控制延迟。线程数可通过set_num_threads控制，避免容器化部署时过度订阅。
memory::dims weights_dims = {16, 3, 3, 3};
memory::dims bias_dims = {16};
memory::dims dst_dims = {1, 16, 222, 222};
memory::dims strides = {1, 1};
memory::dims padding = {1, 1};
auto conv_src_md = memory::desc(src_dims, memory::data_type::f32, memory::format_tag::nchw);
auto conv_weights_md = memory::desc(weights_dims, memory::data_type::f32, memory::format_tag::oihw);
auto conv_bias_md = memory::desc(bias_dims, memory::data_type::f32, memory::format_tag::x);
auto conv_dst_md = memory::desc(dst_dims, memory::data_type::f32, memory::format_tag::nchw);
auto conv_desc = convolution_forward::desc(
prop_kind::forward_inference,
algorithm::convolution_direct,
conv_src_md, conv_weights_md, conv_bias_md, conv_dst_md,
strides, padding, padding);
auto conv_prim_desc = convolution_forward::primitive_desc(conv_desc, eng);
auto src_mem = memory(conv_prim_desc.src_desc(), eng);
auto weights_mem = memory(conv_prim_desc.weights_desc(), eng);
auto bias_mem = memory(conv_prim_desc.bias_desc(), eng);
auto dst_mem = memory(conv_prim_desc.dst_desc(), eng);
auto conv = convolution_forward(conv_prim_desc);
conv.execute(s, {
{DNNL_ARG_SRC, src_mem},
{DNNL_ARG_WEIGHTS, weights_mem},
{DNNL_ARG_BIAS, bias_mem},
{DNNL_ARG_DST, dst_mem}});
s.wait();
四、常见误区与优化建议
第一个误区是忽视格式标签，用nhwc数据直接喂给期望nchw的原语，触发隐藏reorder。第二个误区是在短请求服务中频繁创建原语，应将primitive_desc与原语缓存为全局对象。第三个误区是未限制线程，在协程或微服务中造成核争用。
优化上，建议对权重做一次性重排并复用，使用内存池减少分配；批量维度较小时可尝试bf16降低带宽；在支持AVX512的机器上，oneDNN会自动派发对应内核，无需额外编码。掌握这些细节后，C++项目便能稳定获得高性能推理能力。
| 对比项 | 原生循环实现 | oneDNN调用 |
|---|---|---|
| 开发成本 | 高，需手写优化 | 低，调用原语 |
| 单图延迟 | 较高 | 降低数倍 |
| 可维护性 | 差 | 好 |