HivisionIDPhotos：开源轻量级 AI 证件照工具，实现离线抠图与多规格证件照一站式生成

一、HivisionIDPhotos是什么

HivisionIDPhotos是一款由Zeyi Lin和SwanLab团队联合开发的开源轻量级AI证件照制作工具，其核心定位是通过AI模型构建的自动化工作流，解决用户在求职、考试、签证、入职等场景下的证件照应急制作需求。该项目基于Python技术栈开发，遵循Apache-2.0开源许可证，允许个人与商业场景下的自由使用、修改和分发，同时具备纯离线运行能力，无需依赖高性能GPU和网络环境，既保障了用户的图像隐私，又降低了硬件使用门槛。

不同于传统在线证件照工具的云端处理模式，HivisionIDPhotos构建了“人脸检测-人像抠图-尺寸适配-底色替换-排版输出”的全流程本地化能力，同时支持端云结合的混合推理方案，可灵活适配不同用户的使用场景。截至目前，项目已衍生出ComfyUI工作流、微信小程序、Windows客户端、群晖NAS部署方案等多个社区生态应用，GitHub社区星标量已突破10k，成为开源证件照工具领域的标杆项目。

二、功能特色

HivisionIDPhotos的功能体系围绕“易用性、实用性、扩展性”三大核心设计，覆盖从基础证件照制作到专业级定制的全场景需求，其核心特色可分为以下六大模块：

1. 轻量级离线抠图能力

抠图是证件照制作的核心环节，HivisionIDPhotos突破了传统工具对GPU的依赖，实现纯CPU环境下的快速推理，在Mac M1 Max设备上，基础模型的单次抠图耗时仅0.2-0.9秒。同时项目内置多套抠图模型，用户可根据需求平衡“速度”与“精度”：

• MODNet/hivision_modnet：官方默认模型，模型体积仅24.7MB，适配纯色背景场景，内存占用仅410MB，是普通电脑的首选方案；

• RMBG-1.4：BRIA AI开源模型，抠图边缘更精细，适合复杂背景人像；

• BiRefNet-v1-lite：高精度分割模型，对发丝、半透明衣物等边缘处理效果最优，但内存占用达6.2GB，推理时长约7秒，适合专业级需求。

2. 多规格证件照生成体系

项目内置覆盖国内及国际通用的证件照尺寸库，同时支持自定义尺寸配置，满足多样化场景需求：

• 标准尺寸覆盖：包含1寸、2寸、小2寸、大1寸、护照（33mm×48mm）、签证等数十种预设尺寸，且支持毫米与像素单位的自动换算；

• 自定义尺寸配置：用户可通过修改sizes.json或size_list_CN.csv文件，添加个性化尺寸，配置项包含宽度、高度、DPI参数，适配特殊场景需求；

• 高DPI输出：默认支持300DPI高清输出，满足照相馆级别的打印精度要求，同时可自定义调整DPI数值，平衡文件大小与打印质量。

3. 灵活的底色与排版功能

在证件照的视觉定制与落地环节，项目提供了丰富的个性化选项：

• 多模式底色替换：支持红底、蓝底、白底、渐变蓝底等预设底色，同时开放HEX颜色码输入，用户可自定义任意背景色，且支持透明背景图导出，方便二次编辑；

• 多规格排版打印：内置六寸、五寸、A4、3R、4R五种排版尺寸，可自动将证件照排列为打印相纸适配的版式，并添加裁剪辅助线，用户生成后可直接送至打印店使用，省去手动排版的繁琐；

• 基础美颜优化：提供轻量级美颜功能，可自动调整人像肤色、亮度与对比度，优化证件照面部呈现效果，且API接口已开放美颜参数，支持开发者定制美颜强度。

4. 智能人脸校正能力

针对用户拍摄时的角度偏差问题，项目集成了人脸检测与对齐功能：

• 多模型人脸检测：支持MTCNN（默认）、RetinaFace、Face++三种检测方案，其中MTCNN为纯离线模型，CPU推理可达毫秒级，能快速定位人脸关键点；RetinaFace精度更高但耗时稍长；Face++为在线API，适合超高精度需求场景；

• 自动旋转对齐：通过人脸关键点计算人像倾斜角度，自动完成旋转校正，确保输出证件照的人脸保持正面姿态，符合证件照的官方规范要求。

5. 多样化部署与调用方式

为适配不同用户群体，项目提供了多套使用入口，兼顾普通用户与开发者需求：

• Gradio可视化界面：提供图形化操作页面，用户可通过上传图片、选择参数、一键生成证件照，无需编写代码；

• Python API调用：开放RESTful API接口，支持base64图像输入与参数定制，方便集成到第三方应用；

• 命令行工具：支持批量处理证件照，适合有批量制作需求的企业或机构；

• Docker容器部署：提供官方镜像，可实现一键部署，简化环境配置流程，同时支持Docker Compose编排多服务实例。

6. 高度可扩展的生态体系

作为开源项目，HivisionIDPhotos具备极强的二次开发属性，官方与社区已衍生出多个扩展应用：

• 多端适配版本：包含C++语言版本、Windows GUI客户端、微信小程序（JAVA/Uniapp双版本）、网页版等；

• 专业工具集成：推出HivisionIDPhotos-ComfyUI工作流，可无缝接入ComfyUI的图像编辑体系；

• 私有部署方案：提供群晖NAS部署教程，满足企业与家庭用户的局域网私有化使用需求。

三、技术细节

HivisionIDPhotos的技术架构采用“模块化流水线”设计，将证件照制作拆解为人脸检测、图像分割、图像处理、交互服务四大核心模块，各模块独立解耦且可灵活替换，其底层技术栈与实现逻辑如下：

1. 核心技术栈

2. 核心流程实现逻辑

（1）人脸检测与校正

当用户上传图片后，系统首先调用人脸检测模型，以默认的MTCNN为例，其会通过“候选框生成-边界框校准-关键点定位”三步流程，输出人脸的边界坐标与眼、鼻、嘴等关键点位置。若检测到人脸存在倾斜，系统会根据关键点的相对角度，自动计算旋转矩阵并完成图像校正，确保人脸姿态符合证件照规范。

（2）人像抠图

完成人脸校正后，图像会被送入选定的分割模型。以MODNet为例，该模型采用“低分辨率分支-高分辨率分支-融合分支”的三层结构，先通过低分辨率分支快速定位人像区域，再通过高分辨率分支优化边缘细节，最终输出带透明通道的RGBA图像，实现人像与背景的分离。整个过程在ONNX Runtime的支撑下，可实现毫秒级的CPU推理。

（3）证件照生成与排版

抠图完成后，系统会根据用户选择的尺寸参数，对人像进行裁剪与比例适配，同时将透明背景替换为指定颜色。若用户选择排版功能，系统会读取排版尺寸配置（如六寸相纸为152mm×102mm），自动计算单页可容纳的证件照数量，完成网格排列并添加裁剪线，最终生成可直接打印的排版图。

3. 性能表现

项目在Mac M1 Max（64GB内存，无GPU加速）环境下的性能测试数据如下表所示，可直观体现不同模型组合的效率差异：

从数据可知，基础模型组合可在0.3秒内完成证件照全流程处理，即使是高精度模型，也能在10秒内完成推理，完全满足普通用户的应急需求。

四、应用场景

HivisionIDPhotos的功能特性使其可覆盖个人、开发者、企业/机构三大用户群体的多元需求，具体应用场景如下：

1. 个人用户应急使用

对于普通个人用户，该工具可解决“临时需要证件照但没时间去照相馆”的痛点。例如毕业生求职时需要多版本简历证件照、学生报考考试需要指定尺寸报名表照片、居民办理证件时的应急底版制作等场景，用户只需用手机拍摄一张正面照，通过Gradio界面即可在本地生成符合要求的证件照，既节省时间与金钱，又避免了在线工具的隐私泄露风险。

2. 开发者二次开发与集成

针对技术开发者，项目的开源属性与模块化架构提供了充足的定制空间。前端开发者可基于现有API接口，快速搭建证件照制作小程序、网页应用；算法工程师可替换内置的抠图或人脸检测模型，提升特定场景的处理精度；运维人员可通过Docker实现私有化部署，为企业内部系统提供证件照制作能力。例如社区已实现的微信小程序版本，就是基于项目核心API，结合鉴黄、图片上色等扩展能力打造的商用级应用。

3. 企业与机构批量制作

对于企业、学校、社区等集体单位，工具的批量处理能力可大幅提升证件照制作效率。例如企业新员工入职时的工牌照片统一制作、学校为学生批量生成学籍证件照、社区为居民办理民生业务时的证件照采集等场景，管理员可通过命令行工具批量导入照片，配置统一的尺寸与底色，实现标准化输出，同时本地化部署可保障人员信息的隐私安全。

五、使用方法

HivisionIDPhotos支持多种使用方式，以下为不同场景下的详细操作步骤，满足从新手到专业开发者的使用需求：

1. 环境准备

项目的基础运行环境要求为Python≥3.7（建议3.10版本），同时需安装对应依赖包，具体前置步骤如下：

1. 克隆项目仓库

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

2. 创建并激活虚拟环境

# Windows系统
python -m venv venv
venv\Scripts\activate
# Linux/MacOS系统
python -m venv venv
source venv/bin/activate

3. 安装依赖包

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

4. 下载模型权重 通过官方脚本一键下载所有模型，或手动下载后放置到指定目录：

python scripts/download_model.py --models all

2. 新手友好：Gradio可视化界面

这是最适合普通用户的使用方式，无需编写代码，操作步骤如下：

1. 启动Gradio服务：

python web_ui.py

2. 打开浏览器访问http://127.0.0.1:7860，进入操作界面；

3. 上传本地照片（或通过摄像头拍摄），选择证件照尺寸、背景颜色、抠图模型；

4. 勾选“美颜”“排版打印”等附加功能，点击“开始制作”；

5. 预览生成结果，确认无误后下载证件照原图或排版图。

3. 开发者常用：Python API调用

若需集成到第三方应用，可通过内置API进行调用，示例代码如下：

from hivisionidphoto import IDPhotoMaker

# 初始化证件照生成器
maker = IDPhotoMaker()

# 配置生成参数
result = maker.make_id_photo(
  image_path="user_photo.jpg", # 输入图片路径
  size="2寸",         # 证件照尺寸
  bg_color="#4f83ce",     # 背景色（HEX码）
  beautify=True,        # 开启美颜
  need_layout=True       # 生成排版图
)

# 保存结果
result.save("output_idphoto.jpg")
result.save_layout("output_layout.jpg")

4. 批量处理：命令行工具

适合批量制作场景，基础命令格式如下：

# 基础用法：生成单张证件照
python cli.py --input input.jpg --size 1寸 --bg-color 蓝色

# 高级用法：批量生成并开启美颜
python cli.py --input ./photo_dir --output ./result_dir --size 小2寸 --bg-color 白色 --beautify

5. 便捷部署：Docker容器方式

为简化环境配置，官方提供了Docker镜像，操作步骤如下：

1. 拉取官方镜像

docker pull linzeyi/hivision_idphotos

2. 启动Gradio服务容器

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

3. 启动API服务容器（可选）

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

启动后即可通过对应端口访问服务，无需本地配置Python环境。

六、常见问题解答

七、相关链接

1. 项目源码仓库：https://github.com/Zeyi-Lin/HivisionIDPhotos

2. Docker镜像地址：https://hub.docker.com/r/linzeyi/hivision_idphotos

八、总结

HivisionIDPhotos是一款兼顾实用性、易用性与扩展性的开源AI证件照制作工具，其以轻量级离线推理为核心优势，集成多套先进的抠图与人脸检测模型，实现了从人像处理到证件照生成、排版的全流程本地化能力，既解决了个人用户的应急证件照需求，又为开发者提供了充足的二次开发空间，同时适配企业与机构的批量制作场景。该项目的模块化架构、多样化部署方案与活跃的社区生态，使其在开源证件照工具领域形成了独特的竞争力，而Apache-2.0许可证则为其商业与非商业使用提供了充足的灵活性，是一款真正意义上“普惠且安全”的证件照制作解决方案。