PaddleX 3.2 人脸识别实战：自定义人脸库 + CartoonFace 官方案例 Top-K 识别完整指南

一、前言

在使用PaddleX 3.2进行人脸识别时，开发者常面临两类典型场景：

• 真人/自定义人脸识别：返回labels = null，被判定为 Unknown
• 卡通/动漫/AI 生成人脸：返回多个候选身份（Top-K），但不知如何决策

本文将同时覆盖两种主流用法：

✅ 自定义人脸库构建（如：张三、李四）
✅ 官方 CartoonFace 动漫人脸示例
✅ GPU 环境搭建 + PaddleX 3.2 安装
✅ Top-K 结果深度解析
✅ 身份校验策略（含 Unknown 判定）

💡 适合人群：

• Linux / Ubuntu 用户
• 拥有 CUDA 11.8 GPU
• 使用 PaddleX 3.x
• 从事真人识别或动漫/AI 人脸相关开发

二、环境说明

⚠️强烈建议：PaddlePaddle 与 PaddleX版本严格对齐，避免兼容性问题！

三、安装 PaddlePaddle GPU 版本（CUDA 11.8）

python -m pipinstallpaddlepaddle-gpu==3.2.0\-i https://www.paddlepaddle.org.cn/packages/stable/cu118/

验证安装

importpaddleprint(paddle.__version__)# 应输出 3.2.0print(paddle.is_compiled_with_cuda())# 应输出 True

四、安装 PaddleX 3.2.0（CV 模块）

pipinstall"paddlex[cv]==3.2.0"

❗不要混装旧版（如 2.x）或 dev 版本，推荐使用虚拟环境隔离。

五、场景一：准备自定义人脸库（真人）

适用于员工考勤、门禁系统等真实人脸场景。

1️⃣ 创建目录并准备图片

mkdir-p face_demo_gallery

放入清晰正脸图：

• 001.png→ 张三
• 002.png→ 李四

2️⃣ 创建标签文件gallery.txt

001.png 张三 002.png 李四

📁 目录结构：

face_demo_gallery/ ├── 001.png ├── 002.png └── gallery.txt

六、场景二：准备 CartoonFace 官方示例数据（动漫）

适用于动漫角色、AI 生成头像等非真人场景。

1️⃣ 下载官方数据

wgethttps://paddle-model-ecology.bj.bcebos.com/paddlex/data/cartoonface_demo_gallery.tar

2️⃣ 解压

tar-xf cartoonface_demo_gallery.tar

📁 目录结构：

cartoonface_demo_gallery/ ├── gallery.txt ├── 0001.png ├── 0002.png ├── ... └── test_images/ └── cartoon_demo.jpg

📄gallery.txt内容示例：

0001.png 太一 0002.png 素娜 0003.png 大和 0004.png 美美

🔍 说明：同一角色可能有多张图（如“素娜”出现多次），因此 Top-K 中名字重复是正常现象，非 bug。

七、通用人脸识别 Pipeline 调用

无论哪种场景，调用方式一致！

✅ 示例代码（自定义人脸）

frompaddleximportcreate_pipelineimportos os.makedirs("output",exist_ok=True)pipeline=create_pipeline(pipeline="face_recognition")# 构建自定义索引index_data=pipeline.build_index(gallery_imgs="face_demo_gallery",gallery_label="face_demo_gallery/gallery.txt")# 预测（替换为你的测试图）results=pipeline.predict("your_test_image.jpg",index=index_data)forresinresults:res.print()res.save_to_img("output/")res.save_to_json("output/")

✅ 示例代码（CartoonFace 官方）

# 构建 CartoonFace 索引index_data=pipeline.build_index(gallery_imgs="cartoonface_demo_gallery",gallery_label="cartoonface_demo_gallery/gallery.txt")# 使用官方测试图results=pipeline.predict("cartoonface_demo_gallery/test_images/cartoon_demo.jpg",index=index_data)forresinoutput:res.print()res.save_to_img("./output/")res.save_to_json("./output/")

八、返回结果详解（JSON 格式）

示例输出（节选）

{"boxes":[{"labels":["素娜","素娜","太一","大和","美美"],"rec_scores":[0.4872,0.4471,0.4466,0.3857,0.3305],"det_score":0.7754,"coordinate":[423,91,468,147]}]}

字段说明

⚠️ 注意：

• 真人场景：若所有分数 < 0.35，labels可能为null→ 判定为 Unknown
• 卡通场景：始终返回 Top-K，即使分数很低，需自行判断

九、身份校验策略（关键！）

推荐阈值

通用校验代码

frompaddleximportcreate_pipelineimportosimportjsonimportwarnings# 忽略 Faiss 警告warnings.filterwarnings("ignore",message="HNSW32 method does not support")os.makedirs("output",exist_ok=True)# ===============================# 1. 创建人脸识别 Pipeline# ===============================pipeline=create_pipeline(pipeline="face_recognition")# ===============================# 2. 构建人脸索引（内存索引）# ===============================index_data=pipeline.build_index(gallery_imgs="face_demo_gallery",gallery_label="face_demo_gallery/gallery.txt",use_memory=True)# ===============================# 3. 执行人脸识别# ===============================results=pipeline.predict("文心一言AI作图_20260128165718.png",index=index_data)defunwrap_res_json(res_json):""" 兼容 PaddleX 不同版本返回结构 """if"res"inres_jsonandisinstance(res_json["res"],dict):returnres_json["res"]returnres_json# ===============================# 4. 人脸校验函数 正式的 threshold=0.4 值要调大 这里面模拟照片# ===============================defface_verification(res_json,threshold=0.4):faces=[]# 👉 关键修复点res_json=unwrap_res_json(res_json)forboxinres_json.get("boxes",[]):labels=box.get("labels")scores=box.get("rec_scores")# 检测到人脸，但无法识别身份iflabelsisNoneorscoresisNone:faces.append({"final_label":"Unknown","verify":False,"rec_score":None,"det_score":box.get("det_score"),"coordinate":box.get("coordinate")})continue# Top-1top1_label=labels[0]top1_score=float(scores[0])faces.append({"final_label":top1_labeliftop1_score>=thresholdelse"Unknown","verify":top1_score>=threshold,"rec_score":top1_score,"det_score":box.get("det_score"),"coordinate":box.get("coordinate")})returnfaces# ===============================# 5. 处理结果 & 保存# ===============================final_output=[]forresinresults:res_json=res.json verified_faces=face_verification(res_json,threshold=0.4)final_output.append({"input_path":res_json.get("input_path"),"faces":verified_faces})# 保存可视化与原始 JSONres.save_to_img("output/")res.save_to_json("output/")# ===============================# 6. 保存最终校验结果# ===============================withopen("output/result.json","w",encoding="utf-8")asf:json.dump(final_output,f,indent=2,ensure_ascii=False)print("✅ 人脸识别与校验完成")print("📁 可视化结果：output/")print("📄 最终校验 JSON：output/result.json")

返回结果

[{"input_path":null,"faces":[{"final_label":"李四","verify":true,"rec_score":0.5153087377548218,"det_score":0.746188223361969,"coordinate":[180.9373779296875,71.51338195800781,837.9351806640625,825.9351806640625]}]}]

十、总结

你已掌握：

✅ PaddlePaddle + PaddleX GPU 环境搭建
✅两种人脸库构建方式：自定义（真人） vs 官方（卡通）
✅ 统一调用face_recognitionPipeline
✅ Top-K 结果解析与Unknown 判定逻辑
✅ 工程级身份校验策略

🎯 本方案可直接用于：

• 企业员工识别系统
• 动漫角色检索
• AI 生成头像身份初筛
• 多模态内容审核