直接用 TensorRT Python API 构建引擎最可控；ONNX 转换路径最稳，支持动态 shape、FP16/INT8；trt.OnnxParser 需二进制读取 ONNX 文件。
直接用 tensorrt Python API 构建引擎并推理，是当前最可控、最贴近生产部署的方式；torch2trt 看似方便，但对模型结构敏感、调试困难，且不支持动态 shape 和 INT8 校准，实际项目中容易卡在转换失败或精度骤降上。
用 trt.Builder 从 ONNX 构建 engine 是最稳的路径
YOLOX、YOLOv8 等主流检测模型导出 ONNX 后，再用 TensorRT Python API 构建 engine，能完整控制 batch size、精度（FP16/INT8）、动态维度等关键参数。官方 trtexec 工具虽快，但封装太深，出错时无法定位是 parser 还是 builder 阶段的问题。
-
trt.OnnxParser必须读取二进制 ONNX 文件（open(..., 'rb')），传字符串路径会静默失败 - 显式 batch 模式（
1 ）是必须项，否则解析 YOLO 类多输出模型会报 <code>Assertion failed: inputs.size() == 1 - FP16 开关要同时设 builder 属性
builder.fp16_mode = True和 network 配置config.set_flag(trt.BuilderFlag.FP16)，只设其一无效 - 构建失败时，
parser.num_errors可能为 0，但network.num_layers == 0，此时需检查 ONNX 是否含 unsupported op（如torch.nn.functional.interpolate的 mode='bilinear' 在旧版 ONNX opset 中未对齐）
INT8 校准必须用真实数据，不能靠 dummy input
TensorRT 的 INT8 推理不是简单开关，它依赖校准数据集生成激活值分布直方图。用 torch.randn 生成的噪声输入会导致校准失败，engine 推理结果全为 NaN 或零输出。
Python 编程规范与最佳实践。强制 PEP 8 代码风格、语法校验、单元测试执行，适用于代码编写、审查和重构。触发词：Python、代码规范、py_compile、单元测试。
- 校准器（
trt.IInt8Calibrator）必须继承并实现get_batch，每次返回真实归一化后的图像 tensor（NHWC → NCHW，uint8 → float32，除以 255.0） - batch size 建议设为 1～4，太大易 OOM；总校准样本数建议 ≥ 500 张，少于 100 张时 mAP 通常掉点明显
- 校准过程不训练权重，但会运行前向传播并记录中间 tensor 的 max/min，因此输入数据分布必须和线上 inference 一致（例如：YOLOX 输入是 BGR 还是 RGB？是否做了 letterbox？这些必须和训练/部署 pipeline 完全对齐）
Python 推理时内存分配和同步极易出错
TensorRT Python API 不自动管理 GPU 显存生命周期，cuda.memcpy_htod 和 cuda.memcpy_dtoh 若顺序错、尺寸错、未同步，会得到脏数据或程序崩溃，错误信息常为 CUDA_ERROR_ILLEGAL_ADDRESS 或静默返回全零。
立即学习“Python免费学习笔记（深入）”；
- 输入输出 buffer 必须用
cuda.mem_alloc分配，不能用np.array().ctypes.data_as直接传 host 地址——后者是 CPU 内存，GPU 无法访问 - 执行
context.execute_v2前，必须确保输入数据已通过cuda.memcpy_htod拷贝到 device buffer；执行后，必须调用cuda.Context.synchronize()，否则memcpy_dtoh可能读到旧值 - 常见低级错误：
host_input是 float32 numpy array，但device_input分配了np.dtype(np.float32).itemsize * host_input.nbytes字节，而忘了host_input.nbytes已是字节数，重复乘导致分配过大，后续 memcpy 越界
真正难的不是写通第一版推理代码，而是让 engine 在不同 batch、不同分辨率、不同 GPU（T4 / A10 / L4）上都稳定输出正确结果——这要求你把 ONNX 导出逻辑、parser 错误检查、校准数据 pipeline、host/device buffer 生命周期全部串成闭环，任何一环松动都会在压测或上线时暴露。
