PyTorch C++ API 开发者指南：LibTorch 中的张量计算、Autograd、模型编写与链接打包

PyTorch 的核心能力并不仅限于 Python：其 C++ 前端（常称 LibTorch，即 libtorch 运行时库）提供了与 Python API 高度对应的张量运算、自动微分与神经网络建模能力。本文以 docs/source/cpp_index.md 的能力框架为主线，结合本仓库的 C++ 前端源码（torch/csrc/api/、aten/src/ATen/），完整介绍 C++ 环境下三类核心支持——张量与 Autograd、纯 C++ 模型编写、以及 libtorch 的安装与 ABI 链接选择，帮助你在不依赖 Python 解释器的场景下（如服务端推理、嵌入式部署、性能敏感管线）直接使用 PyTorch。

一、C++ 能力总览：按需选择

官方文档（即关联文档）给出了一条清晰的选择路径：PyTorch 为 C++ 提供的能力并非单点功能，而是按使用层次划分的三个面：

能力层次	涵盖内容	适用场景
Tensor 与 Autograd	torch::Tensor 运算、C++ 张量索引、torch::autograd	张量计算、微分图构建、算子实验
模型编写	torch::nn / torch::nn::functional / torch::optim	纯 C++ 构建与训练神经网络
打包与链接	libtorch 库的安装、链接与 ABI 选择	将上述 API 编译进你的 C++ 程序

这三个层次正好对应本仓库中的三块源码结构：

• 张量与算子核心位于 aten/（ATen 张量库）与 torch/csrc/api/include/torch/torch.h 聚合头之下的若干模块头；
• C++ 前端（模型与优化器）位于 torch/csrc/api/include/torch/，其实现位于 torch/csrc/api/src/；
• 面向部署的链接能力由整个 libtorch 构建产物承载，本仓库根目录的 CMakeLists.txt 与 setup.py 负责产出该库。

值得一提的是，本仓库在 docs/cpp/ 目录下保留了整套 C++ API 文档的源文件（基于 Sphinx/Doxygen），例如 docs/cpp/source/index.md、docs/cpp/source/frontend.md，可作为继续深入每个组件的仓库内第一手参考资料。

二、C++ 中的张量与 Autograd

大多数 PyTorch Python API 中的张量与自动微分操作，在 C++ API 中都有对应实现。这层能力正是 PyTorch 在 C++ 中“能用起来”的地基。

2.1 torch::Tensor 方法集

Python 中形如 t.add(...)、t.reshape(...)、t.clone(...) 的张量方法，在 C++ 中以 torch::Tensor 的成员函数形式提供。torch::Tensor 的定义与核心操作集中在 ATen 层（aten/src/ATen/），它是 Python 张量与 C++ 张量共用的底层张量类型。也就是说，Python API 与 C++ API 最终都落到同一套 ATen 算子上，因此两者在行为与数值结果上保持一致。

使用 C++ 前端时，通常先引入聚合头：

#include <torch/torch.h>

从源码看，torch/csrc/api/include/torch/torch.h 本身只做了两件事：包含覆盖全部 C++ 前端能力的 torch/all.h，以及在需要绑定 Python 扩展时包含 torch/extension.h。因此一行 #include <torch/torch.h> 即可拿到张量、神经网络模块、优化器、序列化等全量 API 的声明。

2.2 与 Python 保持一致的 C++ 张量索引

C++ API 提供了一套“看起来与用起来都和 Python 一致”的张量索引接口。其实现位于 aten/src/ATen/TensorIndexing.h 与 aten/src/ATen/TensorIndexing.cpp。

这套接口支持诸如切片（slice）、None/Ellipsis、整数索引、torch::indexing::Slice 等接近 Python 语义的写法，并复用 Python 相同的索引规则（如负索引、步长、布尔/张量掩码的对应物），使得从 Python 迁移到 C++ 的索引代码心智负担大大降低。其 Python 端行为可对照 torch/_tensor.py 中的索引相关逻辑理解，但 C++ 侧是一个独立的、位于 ATen 层的实现，不依赖 Python 运行时。

说明：为编译使用这套索引与张量算子，C++ 程序需链接 torch（含 torch_cpu 等底层库），即下文第三节所述的 libtorch 产物。

2.3 C++ Autograd 与 torch::autograd

构建动态神经网络离不开自动微分。C++ 前端提供 torch::autograd 包以及张量级 autograd API，使前向图与反向传播可以在纯 C++ 中完成。相关模块头在 torch/csrc/api/include/torch/autograd.h。

从功能结构看，C++ 侧自动微分建立在 torch/csrc/api/include/torch/ 之上的同时，与 ATen 的 Variable/Tensor 体系贯通——即带 requires_grad 的张量会记录前向计算图，调用 backward() 后沿图累积梯度。这与 Python 端动态图机制同源（Python 侧入口见 torch/autograd/ 与 torch/csrc/autograd/），因此“训练一个动态神经网络”这一 PyTorch 标志性能力在 C++ 中是完整可用的。

三、纯 C++ 编写与训练模型

PyTorch C++ 前端提供“纯 C++ 编写并训练神经网络”的完整能力，组件命名与 Python API 高度相似：torch::nn、torch::nn::functional、torch::optim。

3.1 组件与仓库源码对应关系

C++ 组件	Python 对应	仓库位置（头文件）	说明
torch::nn 模块容器	torch.nn	torch/csrc/api/include/torch/nn/	各类网络层与模块容器
torch::nn::functional	torch.nn.functional	torch/csrc/api/include/torch/nn/functional/	无状态函数式算子
torch::optim	torch.optim	torch/csrc/api/include/torch/optim/	SGD、Adam 等优化器
torch::nn::Module	torch.nn.Module	torch/csrc/api/include/torch/nn/module.h	模块基类（注册参数/子模块）

3.2 具体网络层在仓库中的形态

torch/csrc/api/include/torch/nn/modules/ 下按类别组织了与 Python 一一对应的模块实现，例如：

• 基础层：convolution/、linear.h、normalization/、dropout.h；
• 容器：container/sequential.h（对应 torch.nn.Sequential）等；
• 循环与注意力：rnn.h、transformer/。

每个模块的 C++ 实现位于 torch/csrc/api/src/nn/。仓库内测试位于 test/cpp/，可对照其 API 断言理解每个模块的约定行为。

3.3 一个典型建模流程的骨架

下面结合上述模块给出一个“纯 C++ 训练管线”的最小结构骨架，展示各组件如何拼装（参数与细节请按你的网络结构调整，具体各模块选项见 docs/cpp/source/api/nn/index.md 与 docs/cpp/source/api/optim/index.md 的源码文档）：

#include <torch/torch.h>

struct Net : torch::nn::Module {
  Net()
      : fc1(784, 128), fc2(128, 10) {
    register_module("fc1", fc1);
    register_module("fc2", fc2);
  }
  torch::Tensor forward(torch::Tensor x) {
    x = torch::relu(fc1->forward(x));          // 前向算子与函数式接口
    return fc2->forward(x);
  }
  torch::nn::Linear fc1, fc2;                   // 网络层模块
};

int main() {
  Net net;                                      // 构建模型
  torch::optim::SGD opt(net.parameters(), /*lr=*/0.01);  // 优化器

  for (int epoch = 0; epoch < 10; ++epoch) {
    opt.zero_grad();
    auto loss = torch::nn::functional::cross_entropy(  // 函数式损失
        net.forward(torch::randn({32, 784})),
        torch::randint(/*high=*/10, {32}));
    loss.backward();                            // Autograd 反向传播
    opt.step();                                 // 参数更新
  }
}

上例贯穿了前文全部要素：torch::Tensor 运算、torch::autograd 反向、torch::nn 模块注册、torch::nn::functional 函数式接口、torch::optim 优化器。其中 register_module 是 torch/csrc/api/include/torch/nn/module.h 提供的标准注册机制，保证子模块参数被 parameters() 收集；torch::randn、torch::randint、torch::relu 均为 ATen 提供的张量工厂/函数算子。

四、libtorch 打包：安装、链接与 ABI 选择

模型编写完成后，最终产物是把上述 C++ API 编译链接进你自己的程序——这个承载所有 C++ API 的库即 libtorch。

4.1 两种可用的集成方式

• 源码构建：通过本仓库构建系统产出 libtorch。仓库根目录 CMakeLists.txt 定义了顶层构建目标，构建后即可在 CMake 项目里以 find_package(Torch REQUIRED) 方式引用；
• 二进制分发：官方发布的 libtorch 预编译包即为打包产物形态，覆盖 CPU 与 CUDA 等不同后端，可直接下载解压并在你的工程中链接。

4.2 Linux 上的 ABI 二选一（关键注意事项）

关联文档明确指出一个 Linux 使用者极易踩坑的点：官方在 Linux 上提供两种类型的 libtorch 二进制——

1. pre-cxx11 ABI 版本：使用 GCC 旧 ABI（即未启用 _GLIBCXX_USE_CXX11_ABI=0 编译的 libstdc++ 新字符串/容器 ABI）；
2. cxx11 ABI 版本：使用 GCC cxx11 ABI（_GLIBCXX_USE_CXX11_ABI=1，现代 GCC 默认）。

选择依据是你本地系统/工具链正在使用的 GCC ABI。如果你的编译环境以默认 cxx11 ABI 构建（现代发行版 GCC 默认即为 cxx11 ABI），则应选取 cxx11 ABI 版本的 libtorch；反之若工具链显式使用了旧 ABI 设置，则应匹配 pre-cxx11 ABI 版本。

原因在于：libtorch 是二进制库，其对外接口（尤其是公开头文件涉及的 std::string、std::list 等标准库类型）在两种 ABI 下布局不同。若库与调用方 ABI 不一致，轻则链接期符号不匹配报错，重则运行期出现难以排查的崩溃或内存错乱。判断你的编译器是否使用 cxx11 ABI，可通过预处理宏检查：现代 cxx11 ABI 环境下 _GLIBCXX_USE_CXX11_ABI 定义为 1。务必在下载 libtorch 之前先确认你的工具链该宏取值，再做选择。

4.3 选择正确 ABI 后的链接要点

确认 ABI 后，在你的 CMake 工程中链接 libtorch 的标准做法是：

cmake_minimum_required(VERSION 3.18 FATAL_ERROR)
project(MyTorchApp)

find_package(Torch REQUIRED)   # 指向你下载/构建出的 libtorch
add_executable(my_app main.cpp)
target_link_libraries(my_app "${TORCH_LIBRARIES}")
set_property(TARGET my_app PROPERTY CXX_STANDARD 17)

其中 TORCH_LIBRARIES 由 libtorch 附带的 TorchConfig.cmake 提供（该文件模板即仓库中的 cmake/TorchConfig.cmake.in）。请确保构建你的程序所用的 GCC ABI 与所选 libtorch 版本一致，即上文 4.2 节的匹配原则。

五、总结与进阶阅读路径

PyTorch C++ 生态可按“计算 → 建模 → 打包”三段式理解：

1. 张量与 Autograd：torch::Tensor + ATen 索引 + torch::autograd，实现动态图与微分（源码：torch/csrc/api/include/torch/autograd.h、aten/src/ATen/TensorIndexing.h）；
2. 模型编写：torch::nn / torch::nn::functional / torch::optim，实现纯 C++ 定义与训练（源码：torch/csrc/api/include/torch/nn/、torch/csrc/api/include/torch/optim/）；
3. 打包链接：选用匹配 GCC ABI 的 libtorch 并链接进自己的工程（配置模板：cmake/TorchConfig.cmake.in）。

若需更深入每个组件的 API 细节，建议优先在本仓库 docs/cpp/ 下按主题翻阅 C++ 文档源文件，例如 模型前端总览、nn 模块 API 索引、优化器 API 索引 以及 C++ 常见问题 FAQ；同时可配合 test/cpp/ 下的测试用例验证各模块的实际行为约定。