InsightFace ArcFace-Paddle 基础训练预测功能测试（TIPC）完整指南

InsightFace ArcFace-Paddle 基础训练预测功能测试（TIPC）完整指南

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface

本文是 InsightFace 仓库中 ArcFace-Paddle（PaddlePaddle 版人脸识别）在 Linux 端基础训练预测功能测试（TIPC，Test In Paddle Cloud）的实战指南，围绕recognition/arcface_paddle/test_tipc/docs/test_train_inference_python.md展开，完整讲解基于 Python 的模型训练、评估、导出与推理全链路测试流程。读完本文，你将掌握 TIPC 五种运行模式的使用方法、测试配置文件train_infer_python.txt的编写规范、环境搭建细节，以及如何通过results_python.log快速定位测试失败环节。

1. TIPC 是什么：一文看懂基础训练预测功能测试

TIPC（Test In Paddle Cloud）是 PaddlePaddle 生态用于验证模型从训练到预测全流程可用性的标准化测试框架。在 ArcFace-Paddle 中，Linux 端基础训练预测功能测试的主程序为 test_train_inference_python.sh，它可以一键测试基于 Python 实现的模型训练、评估、导出、推理四项基本功能，覆盖单机单卡、单机多卡、多机多卡等多种硬件拓扑，以及 CPU/GPU、MKLDNN、TensorRT、多线程等推理加速组合。

整个测试围绕两个脚本展开：

• prepare.sh：测试前置准备，负责解压小数据集、拷贝验证集文件；
• test_train_inference_python.sh：测试主程序，根据配置文件驱动训练、评估、导出、推理各环节。

测试配置由 train_infer_python.txt 这样的纯文本文件描述，脚本通过解析该文件自动生成并执行命令，因此新增一个模型的 TIPC 测试只需要编写一份对应的配置文件即可。

2. 测试结论汇总：训练与预测能力一览

原文档给出了本次功能测试的结论汇总，明确了 ArcFace + MobileFace 在训练侧与预测侧的覆盖范围。

2.1 训练能力结论

算法名称	模型名称	单机单卡	单机多卡	多机多卡	模型压缩（单机多卡）
ArcFace	mobileface	正常训练	正常训练	正常训练	-

可以看出，MobileFace 网络在单机单卡、单机多卡、多机多卡三种分布式训练形态下均支持正常训练；模型压缩（PACT 量化 / FPGM 剪枝 / 蒸馏）在该配置下暂不启用（表中为 “-”）。

2.2 预测能力结论

模型类型	device	batchsize	tensorrt	mkldnn	cpu多线程
正常模型	GPU	1	fp32	-	-
正常模型	CPU	1	-	fp32	支持

预测侧覆盖两类组合：

• GPU 推理：batch_size=1，可选开启 TensorRT，精度为 fp32；
• CPU 推理：batch_size=1，可选开启 MKLDNN，精度为 fp32，支持 CPU 多线程设置。

对应到 train_infer_python.txt 的推理参数段，即--use_gpu:True|False、--enable_mkldnn:True|False、--cpu_threads:1|6、--use_tensorrt:False|True、--precision:fp32这几个参数组合的笛卡尔积遍历。

3. 运行环境准备（TIPC 环境搭建）

运行环境配置请参考 install.md 的内容搭建 TIPC 运行环境。下面给出关键步骤。

3.1 推荐环境组合

原文档推荐如下环境版本：

• CUDA 10.1 / 10.2
• CUDNN 7.6 / cudnn8.1
• TensorRT 6.1.0.5 / 7.1 / 7.2

环境配置有两种途径：Docker 镜像安装或本地 Python 环境构建。推荐使用 Docker 镜像安装，可以避免繁琐的环境配置问题。

3.2 方式一：Docker 镜像安装

使用 nvidia-docker 创建容器，将当前目录映射到镜像中的/paddle目录，并安装带 TensorRT 的 Paddle 安装包：

nvidia-docker run --name paddle -it -v $PWD:/paddle paddlepaddle/paddle:latest-dev-cuda10.1-cudnn7-gcc82 /bin/bash cd /paddle # 安装带TRT的paddle pip3.7 install https://paddle-wheel.bj.bcebos.com/with-trt/2.1.3/linux-gpu-cuda10.1-cudnn7-mkl-gcc8.2-trt6-avx/paddlepaddle_gpu-2.1.3.post101-cp37-cp37m-linux_x86_64.whl

注意：上述命令中以https://paddle-wheel.bj.bcebos.com/...开头的 wheel 包地址为原文档给出的历史版本安装示例，实际使用时请以当前可用的 PaddlePaddle 官方安装源为准。

3.3 方式二：本地 Python 环境构建

非 Docker 环境下推荐的环境组合为：

• CUDA10.1 + CUDNN7.6 + TensorRT 6
• CUDA10.2 + CUDNN8.1 + TensorRT 7
• CUDA11.1 + CUDNN8.1 + TensorRT 7

下面以 CUDA10.2 + CUDNN8.1 + TensorRT 7 为例说明配置流程。

3.3.1 安装 CUDNN

如果当前环境满足 CUDNN 版本要求可跳过此步。以 CUDNN 8.1 为例，需要下载三个 deb 包：cuDNN Runtime Library、cuDNN Developer Library、cuDNN Code Samples，然后依次安装并验证：

sudo dpkg -i libcudnn8_x.x.x-1+cudax.x_arm64.deb sudo dpkg -i libcudnn8-dev_8.x.x.x-1+cudax.x_arm64.deb sudo dpkg -i libcudnn8-samples_8.x.x.x-1+cudax.x_arm64.deb # 验证是否正确安装 cp -r /usr/src/cudnn_samples_v8/ $HOME cd $HOME/cudnn_samples_v8/mnistCUDNN make clean && make ./mnistCUDNN

若运行mnistCUDNN提示成功则表示安装成功；若出现 freeimage 相关报错，需要安装 freeimage 库：

sudo apt-get install libfreeimage-dev sudo apt-get install libfreeimage

3.3.2 安装 TensorRT

从 Nvidia 官网 TensorRT 板块下载 TensorRT（原文档选用 7.1.3.4 版本，建议选择 TAR package 安装包），注意选择与系统版本和 CUDA 版本匹配的包。解压后按如下步骤安装：

# 设置环境变量，<TensorRT-${version}/lib> 为解压后的TensorRT的lib目录 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<TensorRT-${version}/lib> # 安装TensorRT的Python wheel包 cd TensorRT-${version}/python pip3.7 install tensorrt-*-cp3x-none-linux_x86_64.whl

3.3.3 安装 PaddlePaddle

下载支持 TensorRT 版本的 Paddle 安装包，注意安装包内置的 TensorRT 版本需与本地 TensorRT 版本一致。原文档给出的示例为 CUDA10.2 + CUDNN8.1 对应的 Python3.7 安装包：

wget https://paddle-wheel.bj.bcebos.com/with-trt/2.1.1-gpu-cuda10.2-cudnn8.1-mkl-gcc8.2/paddlepaddle_gpu-2.1.1-cp37-cp37m-linux_x86_64.whl pip3.7 install -U paddlepaddle_gpu-2.1.1-cp37-cp37m-linux_x86_64.whl

同样，wheel 地址为原文档历史示例，实际安装请选用与当前环境匹配的 PaddlePaddle 版本（主文档要求PaddlePaddle >= 2.2）。

3.4 安装项目依赖与 AutoLog

在 install.md 中，AutoLog（规范化日志输出工具）通过源码方式安装；而主文档 test_train_inference_python.md 给出的是更简洁的 pip 直装方式，两者等价，任选其一：

# 方式一（主文档）：直接 pip 安装 AutoLog pip3 install git+https://github.com/LDOUBLEV/AutoLog --force-reinstall # 方式二（install.md）：源码构建 git clone https://github.com/LDOUBLEV/AutoLog cd AutoLog pip3.7 install -r requirements.txt python3.7 setup.py bdist_wheel pip3.7 install ./dist/auto_log-1.0.0-py3-none-any.whl

随后进入 arcface_paddle 目录安装项目依赖：

cd insightface/recognition/arcface_paddle pip3.7 install -r requirements.txt

3.5 常见问题（FAQ）

原文档记录了一个典型问题：“You are using Paddle compiled with TensorRT, but TensorRT dynamic library is not found.”

该问题通常有两种成因：

1. 当前安装的 Paddle 版本带 TensorRT，但本地环境找不到 TensorRT 预测库——需要下载 TensorRT 库并解压，然后设置环境变量LD_LIBRARY_PATH指向其 lib 目录，例如：

export LD_LIBRARY_PATH=/usr/local/python3.7.0/lib:/usr/local/nvidia/lib:/usr/local/nvidia/lib64:/paddle/package/TensorRT-6.0.1.5/lib

2. 下载的 TensorRT 版本与当前 Paddle 中编译的 TRT 版本不匹配——需要下载版本相符的 TensorRT 重新安装。

如果测试中不使用 TensorRT，该警告可以忽略。

4. 理解测试配置文件 train_infer_python.txt

测试脚本本身是通用的，真正的“测试说明书”是配置文件。以 train_infer_python.txt 为例，它按行组织、以:分隔键值，被test_train_inference_python.sh按固定行号读取解析。

4.1 配置文件三大分区

整个文件被##分隔为三个段落：train_params（训练参数）、eval_params（评估参数）、infer_params（导出与推理参数）。需要注意，脚本通过固定行号（awk 'NR==1, NR==51{print}'）读取前 51 行，因此行号位置不能随意调整。

4.2 train_params 分区

配置行	含义	示例值
model_name	模型名，也用于拼接推理模型文件名	MobileFaceNet_128
python	Python 解释器	python3.7
gpu_list	参与测试的 GPU 卡列表	0
--train_num	按模式取值的训练量（lite_train_lite_infer=1表示该模式下训练 1 步）	1
--output	训练输出目录	./output/
--batch_size	训练 batch size	2
--checkpoint_dir	预训练权重目录（此处为 null）	null
train_model_name	训练产物在输出目录中的相对路径，用于后续评估/导出定位权重	MobileFaceNet_128/0
train_infer_img_dir	推理环节使用的测试图片目录	./MS1M_v2/images
trainer	训练器列表，norm_train表示常规训练	norm_train
norm_train	常规训练完整命令模板	tools/train.py --config_file=configs/ms1mv2_mobileface.py ...
pact_train/fpgm_train/distill_train	PACT 量化 / FPGM 剪枝 / 蒸馏训练（此处为 null，未启用）	null

norm_train命令模板对应的是 tools/train.py 的可执行参数：

tools/train.py --config_file=configs/ms1mv2_mobileface.py --is_static=False --fp16=False --embedding_size=128 --dataset=MS1M_v2 --data_dir=MS1M_v2/ --label_file=MS1M_v2/label.txt --num_classes=85742 --log_interval_step=1

4.3 eval_params 分区

评估段只包含eval一个入口，指向 tools/validation.py：

eval:tools/validation.py --is_static=False --backbone=MobileFaceNet_128 --embedding_size=128 --data_dir=MS1M_v2 --val_targets=lfw --batch_size=2

--val_targets=lfw指定在 LFW 验证集上评估；从 validation.py 的默认参数看，val_targets支持逗号分隔的多个目标（如lfw,cfp_fp,agedb_30），batch_size默认 128。

4.4 infer_params 分区

导出与推理段包含三块内容：

导出命令（norm_export）：

norm_export:tools/export.py --is_static=False --export_type=paddle --backbone=MobileFaceNet_128 --embedding_size=128

对应 tools/export.py，--export_type支持paddle或onnx，--is_static决定走静态图还是动态图导出。

推理命令与参数组合：

inference:tools/inference.py --export_type=paddle --benchmark=True --use_gpu:True|False --enable_mkldnn:True|False --cpu_threads:1|6 --max_batch_size:1 --use_tensorrt:False|True --precision:fp32 --model_dir:null --image_path:MS1M_v2/images --benchmark:null

关键点说明：

• 带|的取值表示测试时会遍历所有组合（例如--use_gpu:True|False会分别跑 GPU 与 CPU 两轮）；
• --max_batch_size:1、--precision:fp32为固定取值；
• --model_dir:null表示推理模型目录由脚本动态填充（实际运行时脚本会在命令尾部拼接--model_file=${model_dir}/MobileFaceNet_128.pdmodel --params_file=${model_dir}/MobileFaceNet_128.pdiparams）；
• infer_quant:False表示本次不做量化模型推理（若置为 True，则只允许 int8 精度配合 MKLDNN/TensorRT 推理）。

4.5 配置文件解析机制（common_func.sh）

配置文件之所以能用极简文本驱动复杂测试，依赖 common_func.sh 提供的一组解析函数：

• func_parser_key/func_parser_value：按:拆分行，分别取出参数名与参数值；
• func_parser_params：处理mode=value形式，按当前运行模式（如lite_train_lite_infer）挑选对应取值，例如--train_num:lite_train_lite_infer=1在 lite 模式下解析为 1；
• func_set_params：对值为null或空字符串的键返回空串，避免向命令中注入无效参数；
• status_check：根据上一条命令的退出码（$?或${PIPESTATUS[0]}）向results_python.log写入 “Run successfully” 或 “Run failed” 记录。

这解释了为什么配置中大量出现null:null占位行——它们保证关键参数保持在固定行号上，同时又不向实际命令注入任何内容。

5. 五种运行模式与 lite_train_lite_infer 实操

5.1 五种运行模式

test_train_inference_python.sh 的注释明确了五种模式，分别用于测试速度与精度：

模式	用途
lite_train_lite_infer	少量数据训练 + 少量数据推理，快速验证训练到预测全流程是否走通，不验证精度与速度
lite_train_whole_infer	少量数据训练 + 全量数据推理
whole_train_whole_infer	全量数据训练 + 全量数据推理，验证完整训练精度
whole_infer	仅全量推理（跳过训练，直接对已有模型做预测）
klquant_whole_infer	KL 量化模型全量推理（读取配置第 85~101 行的 klquant 段落，见脚本中的awk 'NR==85 NR==101'分支）

主文档只测试lite_train_lite_infer一种模式，本文也以此为例。

5.2 第一步：prepare.sh 准备小数据

lite_train_lite_infer模式不需要全量 MS1M 数据集，prepare.sh 会解压测试用小数据集：

# 在 recognition/arcface_paddle 目录下执行 bash test_tipc/prepare.sh ./test_tipc/configs/ms1mv2_mobileface/train_infer_python.txt 'lite_train_lite_infer'

该脚本在 lite 模式下会：

1. 创建MS1M_v2目录（rm -rf MS1M_v2; mkdir MS1M_v2）；
2. 将test_tipc/data/small_dataset.tar解压到MS1M_v2/（训练用小规模人脸图片）；
3. 将test_tipc/data/small_lfw.bin复制为MS1M_v2/lfw.bin（LFW 验证集二进制文件，评估环节使用）。

（prepare.sh还支持serving_infer模式，用于准备 Paddle Serving 推理环境，属于另一套测试流程，此处不展开。）

5.3 第二步：运行 test_train_inference_python.sh

bash test_tipc/test_train_inference_python.sh ./test_tipc/configs/ms1mv2_mobileface/train_infer_python.txt 'lite_train_lite_infer'

该模式会执行训练 → 评估 → 导出 → 推理的完整链条。执行完毕后，test_tipc/output目录下会保存所有运行日志。

6. 训练→评估→导出→推理的完整调用链

从源码层面看，测试脚本通过拼装命令依次调用四个 Python 入口，形成完整流水线。

6.1 训练入口 tools/train.py

tools/train.py 是训练入口：通过--is_static决定导入 dynamic/train.py（动态图）还是静态图训练模块；训练参数全部来自 configs/argparser.py 解析的命令行，而命令行默认值又来自配置脚本 configs/ms1mv2_mobileface.py。

以测试使用的ms1mv2_mobileface配置为例，关键训练超参包括：

参数	值	说明
backbone	MobileFaceNet_128	骨干网络（MobileFaceNet，输出 128 维）
loss	ArcFace	损失函数
embedding_size	128	人脸特征维度
num_classes	85742	MS1M_v2 类别数（注释标明 MS1M_v3 为 93431）
lr/momentum/weight_decay	0.1/0.9/5e-4	优化器超参
train_unit	epoch	训练单位，可为 step 或 epoch
decay_boundaries	[10, 16, 22]	分段学习率衰减边界
batch_size	128	每个 rank 的 batch size

在lite_train_lite_infer模式下，脚本会通过--train_num=1只训练 1 步，以最快速度验证训练链路。GPU 分配通过export CUDA_VISIBLE_DEVICES=${gpu}环境变量控制；从 test_train_inference_python.sh 可以看到，单卡直接执行训练命令，多卡使用python -m paddle.distributed.launch --gpus=...，多机则在--gpus之外追加--ips=...指定节点 IP 列表，三种拓扑共用同一训练入口。

6.2 评估入口 tools/validation.py

训练完成后，脚本读取训练产出目录save_log/${train_model_name}（即.../norm_train_gpus_0_autocast_null/MobileFaceNet_128/0）作为--checkpoint_dir，调用 tools/validation.py 在--val_targets=lfw上评估。validation.py同样根据--is_static分派到 dynamic/validation.py 或静态图模块。

6.3 模型导出 tools/export.py

评估之后，脚本以训练产物为权重、以save_log为输出目录调用 tools/export.py 导出推理模型。--export_type=paddle时导出 Paddle Inference 格式的MobileFaceNet_128.pdmodel与MobileFaceNet_128.pdiparams两个文件；--export_type=onnx时则导出 ONNX 模型。导出产物位于save_log/inference目录（由配置行train_model:./inference指定）。

6.4 推理入口 tools/inference.py 与 CPU/GPU 分支

推理环节由 tools/inference.py 执行，它是 test_train_inference_python.sh 中func_inference函数驱动的。func_inference按use_gpu取值分成两个遍历分支：

CPU 分支（--use_gpu=False）：遍历enable_mkldnn、cpu_threads、batch_size、precision的组合。源码 init_paddle_inference_config 中，CPU 路径会config.disable_gpu()、通过set_cpu_math_library_num_threads设置数学库线程数，并在enable_mkldnn=True时开启 MKLDNN 并设置缓存容量为 10。两个跳过规则值得注意：

• 开启 MKLDNN 但 precision 为 fp16 的组合会被跳过；
• 量化模型（flag_quant=True）且 precision 非 int8 的组合会被跳过。

GPU 分支（--use_gpu=True）：遍历use_tensorrt、precision、batch_size的组合。开启 TensorRT 时，源码会配置动态 shape（输入名x，最小[1,3,10,10]、最大[1,3,1000,1000]、最优[1,3,112,112]，对应人脸识别标准输入 112×112），并根据precision选择Float32/Half/Int8精度模式。

推理的前处理在 paddle_inference 中完成：图片读取后执行(img - 127.5) * 0.00784313725归一化（等价于 mean=0.5、std=0.5），并做 BGR→RGB 通道转换与 NCHW 排布调整。--benchmark=True时还会借助 AutoLog 记录预处理、推理、后处理三段耗时并输出性能报告，因此 AutoLog 是推理测速的必需依赖。

6.5 底层测试框架逻辑

整个流程的编排逻辑位于 test_train_inference_python.sh 的 else 分支（训练类模式）：外层循环遍历gpu_list→autocast_list→trainer_list，内层依次执行训练、评估（eval_py != "null"时）、导出（run_export != "null"时）、推理四步，每一步都用status_check记录结果；若某 trainer 的训练命令为null（如本配置中的 pact/fpgm/distill），则直接跳过。由此形成“一套脚本 + 一份配置 + 多模式多组合”的高扩展性测试框架。

7. 输出日志与结果判定

7.1 test_tipc/output 目录结构

运行lite_train_lite_infer模式后，test_tipc/output目录下会生成以下内容（目录路径相对recognition/arcface_paddle）：

test_tipc/output/ |- results_python.log # 运行指令状态的日志 |- norm_train_gpus_0_autocast_null_fp16_False/ # GPU 0号卡上正常训练（fp16关闭）的训练日志和模型保存文件夹 |- norm_train_gpus_0_autocast_null_fp16_True/ # GPU 0号卡上fp16训练的训练日志和模型保存文件夹 ...... |- python_infer_cpu_usemkldnn_True_threads_1_precision_fp32_batchsize_1.log # CPU开启MKLDNN、线程数1、batch_size=1的预测日志 |- python_infer_gpu_usetrt_True_precision_fp32_batchsize_1.log # GPU开启TensorRT、batch_size=1的预测日志 ......

日志命名规则非常直观：

• 训练/评估日志按${trainer}_gpus_${gpu}_autocast_${autocast}组织为目录，里面保存训练日志与模型权重；
• CPU 推理日志为python_infer_cpu_usemkldnn_{True|False}_threads_{n}_precision_{fp32}_batchsize_{1}.log；
• GPU 推理日志为python_infer_gpu_usetrt_{True|False}_precision_{fp32}_batchsize_{1}.log。

（注：上例中的fp16_False/fp16_True为原文档示例中的命名写法，实际目录名由脚本按${trainer}_gpus_${gpu}_autocast_${autocast}生成。）

7.2 results_python.log 成功与失败判定

results_python.log汇总了每一条指令的执行状态，是定位测试失败环节的第一入口。运行成功时输出：

Run successfully with command - python3.7 tools/train.py --config_file=configs/ms1mv2_mobileface.py --is_static=False --embedding_size=128 --fp16=False --dataset=MS1M_v2 --data_dir=MS1M_v2/ --label_file=MS1M_v2/label.txt --num_classes=85742 --log_interval_step=1 --output=./test_tipc/output/norm_train_gpus_0_autocast_null_fp16_True --train_num=1 --fp16=True! Run successfully with command - python3.7 tools/validation.py --is_static=False --backbone=MobileFaceNet_128 --embedding_size=128 --data_dir=MS1M_v2 --val_targets=lfw --batch_size=128 --checkpoint_dir=./test_tipc/output/norm_train_gpus_0_autocast_null_fp16_True/MobileFaceNet_128/0 ! ......

运行失败时输出：

Run failed with command - python3.7 tools/train.py --config_file=configs/ms1mv2_mobileface.py --is_static=False --embedding_size=128 --fp16=False --dataset=MS1M_v2 --data_dir=MS1M_v2/ --label_file=MS1M_v2/label.txt --num_classes=85742 --log_interval_step=1 --output=./test_tipc/output/norm_train_gpus_0_autocast_null_fp16_True --train_num=1 --fp16=True! Run failed with command - python3.7 tools/validation.py --is_static=False --backbone=MobileFaceNet_128 --embedding_size=128 --data_dir=MS1M_v2 --val_targets=lfw --batch_size=128 --checkpoint_dir=./test_tipc/output/norm_train_gpus_0_autocast_null_fp16_True/MobileFaceNet_128/0 ! ......

（上述示例中的fp16=True写法对应原文档日志样例，实际取值以配置文件中的--fp16参数为准。）每条失败记录都包含完整命令，可以直接复制该命令手动重跑定位问题。判定逻辑来自 common_func.sh 的status_check：退出码为 0 记录 “Run successfully”，否则记录 “Run failed”。

8. 更多教程

本文档定位为 TIPC 基础功能测试指南，侧重于验证训练到预测全流程的可用性；更丰富的模型训练与预测使用教程（包括完整数据集训练、精度调优、静态图/动态图切换等）请参考 模型训练与预测教程。

结合仓库中的 dynamic/ 与 static/ 两套实现，以及 tools/ 下的全部入口脚本，你还可以进一步扩展 TIPC 配置：例如为其他骨干网络（如configs/ms1mv3_r100.py、configs/ms1mv3_r50.py对应的 ResNet 系列）编写新的train_infer_python.txt，或开启whole_train_whole_infer模式验证完整训练精度。

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface