企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 预训练

本篇技术指南围绕 PaddleSeg 的本地推理（Inference）部署方案展开，讲解如何使用飞桨推理的 Python 接口，在服务器端（Nvidia GPU 或 X86 CPU）完成分割模型的加载、推理与结果保存。读者将掌握从导出预测模型、准备部署环境，到运行deploy/python/infer.py并理解其全部关键参数的完整链路，同时了解 TensorRT 加速、动态 Shape 自动调优等进阶用法，可直接将分割能力集成进自己的服务。

1. 部署方案说明

PaddleSeg 训练得到的模型默认输出的是 logits（形状为N*C*H*W），要将其用于线上服务，通常需要先导出为预测模型，再借助飞桨的推理库在服务器端执行推理。本文介绍的方案使用的是飞桨推理（Paddle Inference）的 Python 接口，其核心优势在于：

• 该接口集成在 PaddlePaddle 安装包中，安装 PaddlePaddle 即可获得，无需额外引入推理库；
• 通过少量配置与代码即可把模型集成到自己的服务中，完成图像分割任务；
• 支持 X86 CPU 与 Nvidia GPU 两种服务器端部署形态，GPU 端还支持 TensorRT 加速。

Paddle Inference 官方文档系统性地介绍了部署步骤、多种 API 接口与示例，本文聚焦于 PaddleSeg 仓库内实际配套的 Python 推理脚本 deploy/python/infer.py 及其完整用法。

2. 前置准备：导出预测模型与准备测试数据

2.1 导出预测模型

部署前必须先将训练好的模型导出为预测模型。请使用 PaddleSeg 的模型导出工具 tools/export.py 导出您的模型，或者直接下载官方提供的样例预测模型（bisenet 演示模型）用于测试。

python tools/export.py \ --config configs/pp_liteseg/pp_liteseg_stdc1_cityscapes_1024x512_scale0.5_160k.yml \ --model_path model.pdparams \ --save_dir output/inference_model

导出脚本的核心参数如下（详见 docs/model_export_cn.md）：

| 参数名 | 用途 | 是否必选项 | 默认值 | |-|-|-|-| | config | 训练配置文件的路径 | 是 | - | | model_path | 模型权重（.pdparams）路径 | 否 | - | | save_dir | 预测模型保存目录 | 否 |./output/inference_model| | input_shape | 固定模型输入 Shape（N*C*H*W），如--input_shape 1 3 1024 1024；不设置时默认导出输入为[-1, 3, -1, -1]| 否 | None | | output_op | 模型末端附加的输出算子，可选argmax、softmax、none| 否 | argmax | | for_fd | 是否导出为 FastDeploy 兼容格式 | 否 | False |

从源码看，导出时会在网络末端追加输出算子：paddleseg/deploy/export.py 中的WrappedModel对模型输出执行paddle.argmax(out, axis=1, dtype='int32')（argmax模式，输出每像素类别，维度N*H*W、类型 int32）或softmax（输出每像素各类别概率，维度N*C*H*W、类型 float32）。默认argmax意味着预测模型直接产出分割类别图。

注意：如果导出时指定了input_shape，那么后续传给推理脚本的图片尺寸（或经过 deploy.yaml 中预处理变换后的尺寸）必须与input_shape保持一致，否则会出现 shape 相关的报错。

2.2 准备测试图片

导出（或下载）预测模型后，还需要准备一张测试图片。官方提供 cityscapes 验证集中的一张演示图片；如果您的模型是使用其他数据集训练的，请自行准备测试图片。

# 在 PaddleSeg 根目录下 wget https://paddleseg.bj.bcebos.com/dygraph/demo/cityscapes_demo.png

3. 部署环境准备

Paddle Inference 的 Python 接口集成在 PaddlePaddle 中，因此只需要安装对应版本的 PaddlePaddle 即可。PaddleSeg 的其他依赖库请参考 docs/install_cn.md 安装。

3.1 X86 CPU 部署环境

在 X86 CPU 上部署时，安装 CPU 版本的 PaddlePaddle（推荐版本 ≥ 2.1）。需根据 X86 CPU 机器是否支持 AVX 指令，选择安装正确版本的安装包。

3.2 Nvidia GPU 部署环境

GPU 端支持两种计算方式：

• Naive 方式：常规 GPU 推理，准备 CUDA 环境并安装 GPU 版本的 PaddlePaddle（推荐版本 ≥ 2.1），例如：

# CUDA10.1 对应的 PaddlePaddle python -m pip install paddlepaddle-gpu==2.1.2.post101 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html

• TensorRT 方式：需要准备 CUDA、cuDNN 与 TensorRT 环境（例如 CUDA10.1+cudnn7+trt6、CUDA10.2+cudnn8.1+trt7、CUDA11.1+cudnn8.1+trt7、CUDA11.2+cudnn8.2+trt8 等组合），并将 TensorRT 库路径加入LD_LIBRARY_PATH：

export LD_LIBRARY_PATH=/download/TensorRT-7.1.3.4/lib:${LD_LIBRARY_PATH}

然后安装联编 TensorRT 的 GPU 版本 PaddlePaddle（需按照 whl 包文件命名选择对应版本）。TensorRT 方式支持 fp32、fp16、int8 多种计算精度，通常比 Naive 方式计算速度更快。

4. 预测模型文件与部署配置

导出的预测模型格式如下（其中model.pdmodel可通过 Netron 打开进行模型可视化，借此查看输入输出的个数与数据类型，这些信息在调用 Paddle Inference 预测 API 时需要用到）：

output/inference_model ├── deploy.yaml # 部署相关的配置文件，主要说明数据预处理方式等信息 ├── model.pdmodel # 预测模型的拓扑结构文件 ├── model.pdiparams # 预测模型的权重文件 └── model.pdiparams.info # 参数额外信息，一般无需关注

deploy.yaml是部署的关键文件，它声明了模型文件名、权重文件名与推理时的数据预处理方式。推理脚本通过 paddleseg/deploy/infer.py 中的DeployConfig解析该文件：model与params字段给出相对于 deploy.yaml 所在目录的模型与权重文件名，transforms字段则通过manager.TRANSFORMS注册表逐条实例化预处理算子（如Normalize）并组合为T.Compose流水线。仓库中一份真实的部署配置示例如下（deploy.yaml 示例）：

Deploy: input_shape: - -1 - 3 - -1 - -1 model: model.pdmodel output_dtype: int32 output_op: argmax params: model.pdiparams transforms: - type: Normalize

5. 执行预测

在 PaddleSeg 根目录下，执行以下命令进行预测：

python deploy/python/infer.py \ --config ./pp_liteseg_infer_model/deploy.yaml \ --image_path ./cityscapes_demo.png

其中--config必须指向导出模型时生成的 deploy.yaml（而非configs/目录下的训练配置文件）。预测结果默认保存在output/目录下，与输入图片同名、扩展名为.png。

5.1 完整参数说明

以下参数表与 deploy/python/infer.py 中parse_args的实现一一对应：

| 参数名 | 用途 | 是否必选项 | 默认值 | |-|-|-|-| | config |导出模型时生成的配置文件（deploy.yaml），而非 configs 目录下的配置文件 | 是 | - | | image_path | 预测图片的路径、目录或者图片文件列表 | 是 | - | | batch_size | 单卡 batch size | 否 | 1 | | save_dir | 保存预测结果的目录 | 否 |./output| | device | 预测执行设备，可选cpu、gpu、xpu、npu、mlu| 否 |gpu| | use_trt | 是否开启 TensorRT 加速（仅当 device=gpu 时生效） | 否 | False | | precision | TensorRT 数值精度，可选fp32、fp16、int8（仅当 device=gpu 且 use_trt=True 时生效） | 否 |fp32| | min_subgraph_size | TensorRT 子图最小节点个数（仅当 device=gpu 且 use_trt=True 时生效） | 否 | 3 | | enable_auto_tune | 开启 Auto Tune，使用部分测试数据离线收集动态 Shape 用于 TRT 部署（需 device=gpu、use_trt=True，且 paddle 版本 ≥ 2.2） | 否 | False | | auto_tuned_shape_file | Auto Tune 产出的动态 Shape 临时文件 | 否 |auto_tune_tmp.pbtxt| | cpu_threads | CPU 推理线程数（仅当 device=cpu 时生效） | 否 | 10 | | enable_mkldnn | 是否使用 MKL-DNN 加速 CPU 推理（仅当 device=cpu 时生效） | 否 | False | | benchmark | 是否产出包含环境、模型、配置、性能信息的日志 | 否 | False | | model_name | 开启 benchmark 时显示的模型名称 | 否 | "" | | with_argmax | 对预测结果执行 argmax 操作 | 否 | False | | print_detail | 是否打印 Paddle Inference 的 GLOG 信息 | 否 | True |

说明：早期版本文档中使用的use_cpu、use_int8、use_mkldnn等布尔开关，在当前版本中已演进为device、precision、enable_mkldnn等参数，请以当前 deploy/python/infer.py 的 argparse 定义为准。

5.2 输入图片的三种形态

--image_path支持三种输入形态，由 paddleseg/utils/utils.py 中的get_image_list统一处理：

• 单张图片路径（支持.jpg、.jpeg、.bmp、.png后缀）；
• 一个目录：递归收集目录下所有合法后缀的图片；
• 一个文本文件列表：每行一条图片路径（若一行含多个字段，取第一个字段作为路径）。

5.3 预测结果示例

使用官方样例模型对 cityscapes 验证集图片进行预测的效果如下：左侧为原始街景输入，右侧为模型输出的语义分割可视化结果，不同颜色代表不同类别区域（道路、车辆、植被、建筑等）。

6. 部署场景与参数组合

根据硬件与加速诉求，推荐以下参数组合：

• X86 CPU 部署：必须设置--device cpu；可搭配--cpu_threads调节线程数（默认 10），以及--enable_mkldnn开启 MKL-DNN 加速。
• Nvidia GPU Naive 方式：设置--device gpu（默认即为 gpu）。
• Nvidia GPU TensorRT 方式：设置--device gpu --use_trt True，并按需指定--precision：
  • 加载常规预测模型 +--precision fp32：执行 fp32 数值精度；
  • 加载常规预测模型 +--precision fp16：执行 fp16 数值精度，可加快推理速度；
  • 加载量化预测模型 +--precision int8：执行 int8 数值精度，可加快推理速度。

从源码 deploy/python/infer.py 的_init_gpu_config可以看到：开启 TensorRT 时，脚本通过enable_tensorrt_engine配置workspace_size=1<<30、max_batch_size=1，并将precision映射为PrecisionType.Half / Float32 / Int8；同时会设置手动动态 Shape 范围（min_input_shape={"x": [1, 3, 100, 100]}、max_input_shape={"x": [1, 3, 2000, 3000]}、opt_input_shape={"x": [1, 3, 512, 1024]}）。当显式设置这些范围无法满足实际输入尺寸时，可改用 Auto Tune 自动收集动态 Shape。

6.1 动态 Shape 与 Auto Tune

使用 TensorRT 部署时若出现如下错误：

(InvalidArgument) some trt inputs dynamic shape info not set

说明手动设置的动态 Shape 范围未覆盖实际输入，此时可以设置--enable_auto_tune True。其原理（见 deploy/python/infer.py 的auto_tune函数）：

1. 读取DeployConfig并基于模型构建PredictConfig，启用 GPU 与collect_shape_range_info；
2. 从输入图片中取前 10 张（tune_img_nums = 10），经预处理后逐张送入 predictor 运行，离线收集 TRT 子图的动态 Shape 范围，写入auto_tuned_shape_file（默认auto_tune_tmp.pbtxt）；
3. 正式推理时，若检测到该文件存在，则通过enable_tuned_tensorrt_dynamic_shape加载已调优的动态 Shape（allow_build_at_runtime=True），否则退回手动设置动态 Shape 的分支。

需注意：Auto Tune 依赖PredictConfig提供collect_shape_range_info与enable_tuned_tensorrt_dynamic_shape两个接口（即 paddle 版本 ≥ 2.2），且仅在device=gpu && use_trt=True && enable_auto_tune=True时生效；少数模型暂不支持在 Nvidia GPU 上使用 TensorRT 方式部署。

6.2 基准测试（Benchmark）

设置--benchmark True会输出包含环境、模型、配置、性能信息的日志，用于评估推理耗时。脚本会按preprocess_time、inference_time、postprocess_time三个时间键统计，并在正式推理前做 5 次预热（见 deploy/python/infer.py）。开启 benchmark 需要安装auto_log依赖。

7. 注意事项

1. 量化模型加速的前提：使用量化模型预测时，需要同时开启 TensorRT 预测和 int8 精度（--use_trt True --precision int8）才会有加速效果。
2. TensorRT 依赖的 Paddle 版本：使用 TensorRT 需要安装支持 TRT 功能的 Paddle 库（联编 TensorRT 的 GPU 版本安装包），或从源码自行编译，普通 GPU 版本无法开启 TRT。
3. shape 一致性：导出模型时若指定了input_shape，推理时传入图片经过 deploy.yaml 预处理后的尺寸必须与该值一致。
4. 结果格式：默认导出模型自带argmax输出时，输出为N*H*W的 int32 类别图；若在推理脚本侧再叠加--with_argmax，则会对预测结果再次执行 argmax。

更多预测相关信息，可继续阅读 docs/deployment/inference/python_inference_cn.md，或直接研读 deploy/python/infer.py 脚本；若需 C++ 端部署，可参考同目录下的 cpp_inference_cn.md。

• 人工智能
• 计算机视觉
• 预训练