3步走离线做证件照：免费AI证件照工具HivisionIDPhotos实战-平芜编程栈

3步走离线做证件照：免费AI证件照工具HivisionIDPhotos实战

【免费下载链接】HivisionIDPhotos⚡️HivisionIDPhotos: a lightweight and efficient AI ID photos tools. 一个轻量级的AI证件照制作算法。项目地址: https://gitcode.com/GitHub_Trending/hiv/HivisionIDPhotos

周一要交报名照，手头的照片却是奶茶店门口的自拍。开源项目 HivisionIDPhotos 专门处理这种场景：传入一张随手拍的普通照片，它会把人从背景里分离出来、调整头身比例、换上标准底色，输出一张可打印的证件照，全程离线，纯 CPU 就能跑。

📦 从零到出图：三步装完跑起来

第一步，拿代码

git clone https://gitcode.com/GitHub_Trending/hiv/HivisionIDPhotos cd HivisionIDPhotos

第二步，装依赖、下模型

环境要求 Python 3.7 及以上（官方在 3.10 上测试），依赖很轻，主要是 OpenCV 和 ONNX Runtime：

pip install -r requirements.txt pip install -r requirements-app.txt python scripts/download_model.py --models all

脚本会把抠图模型权重统一放进hivision/creator/weights目录。默认的 MODNet + MTCNN 组合完全走 CPU 推理，不需要任何 GPU。

第三步，出图

python app.py

浏览器打开 http://127.0.0.1:7860 就能用图形界面操作；不想开界面，也可以直接用命令行入口inference.py，传入输入图片路径和--height、--width目标尺寸即可。

内部四道工序：从生图到成照

项目自带几张测试照片，demo/images/下的图可以直接拿来试：

第一道：把人和背景分开

这就是"抠图"——按像素把人从原始背景里切出来，得到一张带透明通道的 PNG。项目内置了 4 个可选模型：MODNet（24.7MB，CPU 上飞快）、针对纯色换底调优的 hivision_modnet、rmbg-1.4，以及分割精度最高但体积最大的 birefnet-v1-lite（224MB）。具体逻辑在人像分离的实现里。

第二道：定位人脸，顺手查一下有没有歪

证件照要求人脸居中且占比达标。默认用 MTCNN，CPU 上毫秒级；精度要求高时换 RetinaFace；对准确性更苛刻的场景还能接 Face++ 的云端检测。人脸倾斜时可通过face_alignment参数旋转回正，检测器实现在 face_detector.py 中。

第三道：裁出标准画幅

检测完成之后，裁剪框由三个参数决定：期望的"人脸面积占全图比例"、人脸中心所处的纵向位置、头顶距离画布顶端的允许区间。这套裁剪算法在 photo_adjuster.py，三项数值都可以按需覆盖，方便贴合不同机构的具体要求。

第四道：换底色，再收一遍妆

裁好的透明图与目标背景色合成，之后走一遍美颜管线：美白、磨皮、瘦脸、亮度和对比度，全部强度可调、可不开，避免处理过头失真，代码位于 hivision/plugin/beauty/。最终同时产出标准尺寸证件照和一张高清透明底 PNG。

三种角色，各选一个入口

只想要结果的：用 Gradio 界面。上传照片、挑尺寸和底色、点生成，一步到位。界面上还有"打印排版"页签，支持五寸、六寸、A4、3R、4R 五种排版输出。

想接进自己系统的开发者：核心类是IDCreator，一行实例化后把 OpenCV 读入的图像传进去，creator(image, size=(413, 295))就能拿到标准图和高清图两个结果。类上暴露了before_all、after_matting、after_detect、after_all四个钩子，想替换抠图或检测步骤，替换对应的 handler 即可，不必动主流程。

要把服务跑起来的运维：官方镜像linzeyi/hivision_idphotos支持三种启动姿势——docker run -d -p 7860:7860起 Web 界面，-p 8080:8080加python3 deploy_api.py起 API 后端，docker compose up -d两个一起起。环境变量可以注入 Face++ 的密钥、设置RUN_MODE=beast（野兽模式，模型常驻内存换取更快的二次推理，建议 16GB 以上内存）。API 的请求格式和示例见 API 文档。

不同模型组合的实测差异

以下数据来自 Mac M1 Max、纯 CPU 无加速的测试：

| 抠图 + 人脸检测 | 内存占用 | 512×715 输入 | 764×1146 输入 | | -- | -- | -- | -- | | MODNet + MTCNN | 410MB | 0.207s | 0.246s | | MODNet + RetinaFace | 405MB | 0.571s | 0.971s | | BiRefNet + RetinaFace | 6.20GB | 7.063s | 7.128s |

怎么选：日常使用默认 MODNet + MTCNN 即可，单张亚秒级；觉得发丝边缘不够干净时，把抠图换成 birefnet-v1-lite，有 16GB 左右显存的机器再装 onnxruntime-gpu 让 BiRefNet 走 GPU 加速；内存紧张的机器不建议硬上大图。

💡 用得顺手再折腾

加尺寸：往demo/assets/size_list_CN.csv里追加一行（名称、高、宽），重启app.py生效；
换背景色：同目录的color_list_CN.csv里改 HEX 值；
加社交媒体模板照：把四通道透明 PNG 放进hivision/plugin/template/assets/，并在template_config.json里登记透明区域四个锚点坐标；
改打印排版：编辑demo/locales.py中的print_switch字典。

两个容易踩的坑：

birefnet 的 onnx 权重下载后要重命名为birefnet-v1-lite.onnx再放入 weights 目录，忘了改名会直接找不到模型；
RetinaFace 的权重有独立目录hivision/creator/retinaface/weights，和通用 weights 目录不通用，放错位置等于没装。

社区侧也有不少扩展：ComfyUI 工作流、微信小程序（原生与 uniapp 两版）、浏览器 Web 版、C++ 移植、Windows 桌面端，以及群晖 NAS 部署教程，都可以按各自形态取用。