HivisionIDPhotos 完整指南：一张生活照变标准证件照，免费开源的 AI 证件照制作工具
【免费下载链接】HivisionIDPhotos⚡️HivisionIDPhotos: a lightweight and efficient AI ID photos tools. 一个轻量级的AI证件照制作算法。项目地址: https://gitcode.com/GitHub_Trending/hiv/HivisionIDPhotos
周五下午五点半，同事发来一句"明天入职要交证件照"，而你的相册里只有一张去年团建时的随手拍。这样的场景并不少见：签证、考试、求职、社保卡……证件照的需求总是来得很急，而照相馆的档期往往不等人。HivisionIDPhotos 就是一个为此设计的开源工具——它基于 AI 算法，输入一张普通照片，自动完成抠图、人脸定位、尺寸裁剪和底色替换，输出符合一寸、二寸等标准规格的证件照，全程免费，且可以完全离线运行，普通 CPU 就能跑。
一张照片进来，AI 替你做了四件事
不需要了解算法细节也能用，但知道它背后在做什么，你才能判断输出结果是否靠谱。整个流程可以拆成四个环节。
第一步：把人和背景分开。这是整条流水线里最关键的一步，实现位于 hivision/creator/human_matting.py。项目内置了四个可选的抠图模型，按"快—准"的权衡排列：MODNet 和 hivision_modnet 都只有 24.7MB，在 CPU 上推理飞快，其中 hivision_modnet 对纯色背景适配更好；rmbg-1.4（176.2MB）介于两者之间；birefnet-v1-lite（224MB）分割精度最高，但体积和耗时都明显更大。头发丝、衣领边缘这类难处理区域，模型越强结果越干净。
第二步：找到人脸，并且摆正。定位逻辑在 hivision/creator/face_detector.py。默认使用离线模型 MTCNN，毫秒级出结果，适合大多数场景；如果照片里人脸较小或光线复杂，可以换成精度更高的离线模型 RetinaFace（CPU 上是秒级速度），或者调用 Face++ 的云端 API 拿到最精准的检测（配置方式见 docs/face++_CN.md）。照片如果有点歪，项目还会自动做人脸旋转对齐，把倾斜的脸扶正，这在 API 里对应face_alignment参数，默认是开启的。
第三步：按规格裁剪和排版。证件照和头像最大的区别在于"人该占多大的位置"。hivision/creator/photo_adjuster.py 会根据人脸框计算最佳裁剪区域，控制面部面积占比、人脸中心到照片顶部的距离等参数（API 中可分别调节），并支持生成六寸相纸的排版照、五寸相纸，默认输出 300DPI 的文件，直接满足冲印要求。
第四步：可选的美颜与底色合成。hivision/plugin/beauty/ 目录下是美颜模块，包含磨皮、美白、瘦脸，以及亮度、对比度、锐化、饱和度调整，所有参数都可以单独控制强度，不开就是原片质感。底色支持纯色和上下渐变、中心渐变两种渲染模式，还可以直接输入 HEX 自定义颜色。
三步跑起来：环境要求与模型下载
项目要求 Python 3.7 以上（官方主要在 3.10 上测试），Linux、Windows、macOS 都可以。整个准备过程只有三步：
git clone https://gitcode.com/GitHub_Trending/hiv/HivisionIDPhotos cd HivisionIDPhotos pip install -r requirements.txt -r requirements-app.txt python scripts/download_model.py --models all第二条命令装依赖，最后一条把所有抠图模型权重下载到hivision/creator/weights/目录。如果网速不理想，也可以只下载最常用的一个：python scripts/download_model.py --models modnet_photographic_portrait_matting。装完后，界面里会自动只显示你本地实际存在的那些模型，不会让你选到没下载的选项。
三种使用方式怎么选：网页、命令行还是 API
方式一：Gradio 网页界面（推荐大多数人）
python app.py然后浏览器打开 http://127.0.0.1:7860。界面上选抠图模型和人脸检测模型、挑尺寸（一寸 413×295、二寸 626×413、研究生考试、美国签证等常见规格都预置好了）、选背景色，点"开始制作"即可。界面同时给出标准照、高清照和六寸排版照三种输出，还有分享模版照等附加功能。
方式二：命令行调用（适合脚本化、批量任务）
核心入口是 inference.py，通过-t参数选择功能：生成证件照（idphoto）、单独抠图（human_matting）、给透明图加底色（add_background）、六寸排版（generate_layout_photos）、裁剪已抠好的透明图（idphoto_crop）。比如：
python inference.py -i demo/images/test0.jpg -o ./idphoto.png --height 413 --width 295一次命令同时输出一张标准证件照和一张高清透明底 PNG，方便后续自己换底色。
方式三：RESTful API 服务（适合集成到自己的产品里）
运行python deploy_api.py启动后端，之后就能通过 HTTP 请求所有功能，参数比命令行更细——比如head_measure_ratio（面部与照片面积比，默认 0.2）、top_distance_min/max（头顶留白的上下限）、dpi、美颜强度等都可以逐张调节，请求方式示例见 docs/api_CN.md。API 的设计上有个值得注意的细节：生成接口默认返回透明底的 RGBA 图像，前端切换底色时直接由浏览器合成，不用反复请求后端，体验更顺滑；等确定底色后再调add_background接口输出 JPG。
方式四（附赠）：Docker 部署
不想配环境的话，拉镜像docker pull linzeyi/hivision_idphotos后执行docker run -d -p 7860:7860 linzeyi/hivision_idphotos就能把网页服务跑起来；也可以用仓库里自带的 Dockerfile 或 docker-compose 自建。两个服务（网页 + API）可以组合同时启动，环境变量还支持RUN_MODE=beast的"野兽模式"——模型常驻内存不释放，二次推理更快，建议 16GB 以上内存再开。
进阶玩法：改尺寸、加模板、上 GPU
自定义尺寸和颜色不用改代码：预设规格存在 demo/assets/size_list_CN.csv，每行是"名称,高,宽"，加一行再重启app.py就生效；背景色同理，改 demo/assets/color_list_CN.csv 里的 HEX 值即可。界面里也可以直接输入 HEX 自定义底色，不走预设。
社交媒体模板照是个有点意思的附加功能：除了标准证件照，还能把照片嵌进设计好的模板里生成社交头像，效果如下。想加新模板的话，把 4 通道透明 PNG 放进hivision/plugin/template/assets/，在template_config.json里登记尺寸和透明区域的四个锚点坐标就行（README 的 FAQ 部分有完整步骤）。
GPU 加速目前主要针对 birefnet-v1-lite 这个最大、最准的抠图模型：装好 CUDA 和 cuDNN 后，按对应版本安装onnxruntime-gpu即可（README 里有按 CUDA 12.x 的具体版本示例），需要预留 16GB 左右的显存。如果你只用默认的 MODNet + MTCNN 组合，CPU 已经足够快，没必要折腾。
真实数据说话：性能、适用场景与局限
官方在 Mac M1 Max（64GB，非 GPU 加速）上给出的实测数据，测试图片分辨率为 512×715 和 764×1146：
| 模型组合 | 内存占用 | 小图推理时长 | 大图推理时长 |
|---|---|---|---|
| MODNet + MTCNN | 410MB | 0.207s | 0.246s |
| MODNet + RetinaFace | 405MB | 0.571s | 0.971s |
| birefnet-v1-lite + RetinaFace | 6.20GB | 7.063s | 7.128s |
这组数据说明了两件事：默认组合下整个流程不到半秒，"应急"绰绰有余；追求极致抠图精度时，birefnet 在纯 CPU 上要等 7 秒左右、吃 6GB+ 内存，上 GPU 才是它的正确打开方式。
它适合什么场景：临时补交证件照、批量生成员工/学籍照片、给自己的产品加"证件照制作"功能、群晖 NAS 等私有化部署（社区有人写过部署教程）。项目基于 Apache-2.0 协议，商业使用也没问题。社区还衍生出 ComfyUI 工作流、微信小程序、网页版、C++ 版、Windows 桌面客户端等扩展，可见这个轻量内核的可塑性。
它不适合什么：官方明确把"智能换正装"列在计划里而非已完成——也就是说你不能指望它帮你把 T 恤变西装，输入照片本身的着装还是得符合要求；对面部严重遮挡（口罩、大帽檐）的照片，任何人脸检测方案都会退步，这类输入建议先换一张；另外 Face++ 方案需要联网和 API 密钥，纯离线环境只能依赖 MTCNN/RetinaFace。
回到开头那个周五下午的场景：克隆仓库、装依赖、下模型，一杯水的工夫就能让本地网页服务跑起来，从生活照到可冲印的证件照，全程不出内网。急用是它的强项，而开源免费这一点，让"急用"的成本几乎为零。
【免费下载链接】HivisionIDPhotos⚡️HivisionIDPhotos: a lightweight and efficient AI ID photos tools. 一个轻量级的AI证件照制作算法。项目地址: https://gitcode.com/GitHub_Trending/hiv/HivisionIDPhotos
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
