为 Nova Carter 上的 Isaac Perceptor 重建 TensorRT Engine

这是一份分步指南，用于修复 NVIDIA Isaac 环境中 Isaac Perceptor 模型（「Engine」）的兼容性问题。虽然是在 NVIDIA Nova Carter 机器人上开发和测试的，但同样适用于 Isaac Sim 等环境。

在 Perceptor 用于 3D 场景重建的节点和软件包中，有一组「engine」和「plan」文件，它们是 Perceptor 组件（如 nvblox）用于物体识别、语义分割、图像视差计算等的实际神经网络模型。

问题：不兼容的「engine」文件。

当运行 Isaac ROS Perceptor 节点时，会出现以下错误：

Error Code 6: API Usage Error (The engine plan file is not compatible with this version of TensorRT, expecting library version 10.7.0.23)

根本原因：.engine 文件是预编译的通用 CUDA 运行时，基于运行 Perceptor 的系统上安装的特定 TensorRT 版本构建。由于 Perceptor 通常在 Docker 容器中运行，而不是在主机原生 Jetpack 安装中运行，因此容器运行的 Docker 镜像与主机 Jetpack 之间经常存在一些版本漂移。

解决方案：幸运的是，NVIDIA 提供了专门用于处理 CUDA、在不同格式和 NVIDIA 硬件平台之间构建和转换模型的工具。我们可以使用 trtexec 工具重建不兼容的 .engine 文件。

在容器内使用针对容器 TensorRT 版本编译的 trtexec 重建 engine，并启用「full」运行时优化。

注意：我们稍后会看到为什么「full」很重要。这里先说明一下：它与解决以下错误消息有关：

Error Code 4: API Usage Error (Cannot deserialize engine with lean runtime...

分步解决方案

这一切都需要在你最终将运行 Isaac Perceptor 的容器内完成。 请按顺序从上到下完成所有步骤，最好在 screen(1) 会话中运行。

1. 访问正在运行的容器

docker exec -it <container_name> /bin/bash

2. 为兼容性重建 trtexec

# 导航到 TensorRT 源码
cd /usr/src/tensorrt

# 清理并重建 trtexec
sudo make clean
sudo make -j$(nproc) trtexec

# 验证新的 trtexec 版本
./bin/trtexec --version

3. 重新安装 ISAAC_ROS 资源

# 重新安装必要的模型软件包
sudo apt-get install --reinstall isaac_ros_ess_models_install
# 根据需要添加其他模型软件包

4. 删除旧的 Engine 文件

# 导航到资源目录
cd $ISAAC_ROS_ASSETS

# 删除所有现有的 engine 文件
find . -name "*.engine" -delete
find . -name "*.plan" -delete

5. 修改模型安装脚本

对于每个模型安装脚本（/opt/isaac_ros_assets/install_scripts/*.sh）：

# 编辑 trtexec 命令以添加 --useRuntime=full
sed -i 's/trtexec --onnx=/trtexec --useRuntime=full --onnx=/' install_script.sh

6. 使用完整运行时重新生成 Engine

# 运行每个修改后的安装脚本
sudo /opt/isaac_ros_assets/install_scripts/isaac_ros_ess_models_install.sh
# 根据需要重复其他模型脚本

7. 提交容器更改

# 在主机系统上
docker ps  # 获取容器 ID/名称
docker commit <container_name> nova_carter_with_new_engines

8. 启动 Perceptor

# 在容器内
ros2 launch nova_carter_bringup perceptor.launch.py

如果 Perceptor 成功读取新的 .engine 文件，你应该会在控制台上看到类似下面的输出（每个相机都会出现）：

[component_container_mt-9] [INFO] [1765602288.918936247] [right_stereo_camera.left.rectify_node]: Negotiating
[INFO] [launch_ros.actions.load_composable_nodes]: Loaded node '/right_stereo_camera/ess_node' in container 'nova_container'
[component_container_mt-9] [INFO] [1765602288.919007703] [right_stereo_camera.right.rectify_node]: Negotiating
[component_container_mt-9] [INFO] [1765602288.920391927] [nova_container]: Load Library: /opt/ros/humble/lib/libvisual_slam_node.so

由于 .engine 模型被多个节点使用，例如 dnn_stereo_disparity 和 nvblox，成功的 Perceptor 运行会产生大量控制台输出，但最终会安静下来并持续运行。