Hugging Face 一键AI证件照在线制作！支持离线、换装、美颜等 HivisionIDPhotos

HivisionIDPhotos 是一款功能强大的开源证件照生成工具。用户只需上传一张人像照片，它就能智能裁剪为一寸、两寸等标准尺寸，同时自动去除背景并渲染新的背景颜色，例如蓝色、白色、红色，还支持渐变色和自定义颜色。生成的证件照会自动排版为标准的六寸规格，方便用户打印和批量制作。

未来，HivisionIDPhotos 计划推出更多实用功能，例如美颜优化、一键更换正装等，让证件照制作变得更加高效和便捷。目前，该工具已在 Huggingface 等平台上免费开放，懂编程的用户还可以将其部署到本地，享受更个性化的使用体验。

HivisionIDPhoto 特性：

轻量级抠图（纯离线，仅需 CPU 即可快速推理）
根据不同尺寸规格生成不同的标准证件照、六寸排版照
支持纯离线或端云推理
美颜
智能换正装（waiting）

2、本地安装部署

环境安装与依赖：

Python >= 3.7（项目主要测试在 python 3.10）
OS: Linux, Windows, MacOS

1. 克隆项目

git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.gitcd  HivisionIDPhotos

2. 安装依赖环境

pip install -r requirements.txtpip install -r requirements-app.txt

建议 conda 创建一个 python3.10 虚拟环境后，执行以下命令

3. 下载人像抠图模型权重文件

python scripts/download_model.py --models all# 如需指定下载某个模型# python scripts/download_model.py --models modnet_photographic_portrait_matting

方式二：直接下载

模型均存到项目的hivision/creator/weights目录下：

人像抠图模型	介绍	下载
MODNet	MODNet官方权重	下载(24.7MB)
hivision_modnet	对纯色换底适配性更好的抠图模型	下载(24.7MB)
rmbg-1.4	BRIA AI 开源的抠图模型	下载(176.2MB)后重命名为`rmbg-1.4.onnx`
birefnet-v1-lite	ZhengPeng7 开源的抠图模型，拥有最好的分割精度	下载(224MB)后重命名为`birefnet-v1-lite.onnx`

如果下载网速不顺利：前往SwanHub下载。

4. 人脸检测模型配置（可选）

拓展人脸检测模型	介绍	使用文档
MTCNN	离线人脸检测模型，高性能CPU推理（毫秒级），为默认模型，检测精度较低	Clone此项目后直接使用
RetinaFace	离线人脸检测模型，CPU推理速度中等（秒级），精度较高	下载后放到`hivision/creator/retinaface/weights`目录下
Face++	旷视推出的在线人脸检测API，检测精度较高，官方文档	使用文档

5. 性能参考

测试环境为Mac M1 Max 64GB，非GPU加速，测试图片分辨率为 512×715(1) 与 764×1146(2)。

模型组合	内存占用	推理时长(1)	推理时长(2)
MODNet + mtcnn	410MB	0.207s	0.246s
MODNet + retinaface	405MB	0.571s	0.971s
birefnet-v1-lite + retinaface	6.20GB	7.063s	7.128s

6. GPU推理加速（可选）

在当前版本，可被英伟达GPU加速的模型为birefnet-v1-lite，并请确保你有16GB左右的显存。

如需使用英伟达GPU加速推理，在确保你已经安装CUDA与cuDNN后，根据onnxruntime-gpu文档找到对应的onnxruntime-gpu版本安装，以及根据pytorch官网找到对应的torch版本安装。

# 假如你的电脑安装的是CUDA 12.x, cuDNN 8# 安装torch是可选的，如果你始终配置不好cuDNN，那么试试安装torchpip install onnxruntime-gpu==1.18.0pip install torch --index-url https://download.pytorch.org/whl/cu121

完成安装后，调用birefnet-v1-lite模型即可利用GPU加速推理。

TIPS: CUDA 支持向下兼容。比如你的 CUDA 版本为 12.6，torch 官方目前支持的最高版本为 12.4（<12.6），torch仍可以正常使用CUDA。

⚡️ 运行 Gradio Demo

python app.py

运行程序将生成一个本地 Web 页面，在页面中可完成证件照的操作与交互。

🚀 Python 推理

核心参数：

-i: 输入图像路径
-o: 保存图像路径
-t: 推理类型，有idphoto、human_matting、add_background、generate_layout_photos可选
--matting_model: 人像抠图模型权重选择
--face_detect_model: 人脸检测模型选择

更多参数可通过python inference.py --help查看

1. 证件照制作

输入 1 张照片，获得 1 张标准证件照和 1 张高清证件照的 4 通道透明 png

python inference.py -i demo/images/test0.jpg -o ./idphoto.png --height 413 --width 295

2. 人像抠图

输入 1 张照片，获得 1张 4 通道透明 png

python inference.py -t human_matting -i demo/images/test0.jpg -o ./idphoto_matting.png --matting_model hivision_modnet

3. 透明图增加底色

输入 1 张 4 通道透明 png，获得 1 张增加了底色的 3通道图像

python inference.py -t add_background -i ./idphoto.png -o ./idphoto_ab.jpg  -c 4f83ce -k 30 -r 1

4. 得到六寸排版照

python inference.py -t generate_layout_photos -i ./idphoto_ab.jpg -o ./idphoto_layout.jpg  --height 413 --width 295 -k 200

5. 证件照裁剪

python inference.py -t idphoto_crop -i ./idphoto_matting.png -o ./idphoto_crop.png --height 413 --width 295

Docker 一键部署

docker pull linzeyi/hivision_idphotos

2. 运行服务

启动 Gradio Demo 服务

运行下面的命令，在你的本地访问 http://127.0.0.1:7860 即可使用。

docker run -d -p 7860:7860 linzeyi/hivision_idphotos

启动 API 后端服务

docker run -d -p 8080:8080 linzeyi/hivision_idphotos python3 deploy_api.py

两个服务同时启动

docker compose up -d

环境变量

本项目提供了一些额外的配置项，使用环境变量进行设置：

环境变量	类型	描述	示例
FACE_PLUS_API_KEY	可选	这是你在 Face++ 控制台申请的 API 密钥	`7-fZStDJ····`
FACE_PLUS_API_SECRET	可选	Face++ API密钥对应的Secret	`VTee824E····`
RUN_MODE	可选	运行模式，可选值为`beast`(野兽模式)。野兽模式下人脸检测和抠图模型将不释放内存，从而获得更快的二次推理速度。建议内存16GB以上尝试。	`beast`
DEFAULT_LANG	可选	Gradio Demo启动时的默认语言	`en`

docker使用环境变量示例：

docker run  -d -p 7860:7860 \
    -e FACE_PLUS_API_KEY=7-fZStDJ···· \
    -e FACE_PLUS_API_SECRET=VTee824E···· \
    -e RUN_MODE=beast \
    -e DEFAULT_LANG=en \
    linzeyi/hivision_idphotos