HivisionIDPhotos

⚡️HivisionIDPhotos: a lightweight and efficient AI ID photos tools. 一个轻量级的AI证件照制作算法。

项目简介

在求职、考试、办理各类证件的场景中，"证件照"几乎是一个绕不开的刚需。传统流程是去线下照相馆拍完再修图，耗时且价格不菲；如果自己用手机自拍，又会遇到背景不规整、人物不居中、尺寸不符合要求等问题。HivisionIDPhotos 正是为解决这些痛点而生的开源工具——它是一个轻量级的 AI 证件照智能制作算法，借助一整套模型工作流，实现对用户上传照片的识别、抠图、尺寸裁剪与背景替换，最终输出符合规范的标准证件照。

项目的核心理念是"实用 + 轻量"：模型推理在纯 CPU 环境下即可完成，无需昂贵的 GPU；同时它支持本地离线运行，从源头上保障了用户照片的隐私安全。对于个人开发者、HR 团队、在线教育平台、政务系统开发者而言，它都是一个开箱即用的证件照生产工具。截至目前，仓库已收获超过 21,000 Star，社区生态也从 Python 版本延伸到了 C++、微信小程序、UniApp、NAS 部署、Windows GUI 等多个方向，足以印证它的受欢迎程度。

核心功能与架构

核心能力一览

HivisionIDPhotos 围绕"证件照"这一场景构建了完整的功能矩阵，主要包括以下几个方面：

第一，轻量级人像抠图。这是整个工具的基石，采用了 MODNet 等成熟的人像抠图模型，纯离线、CPU 可跑，2~3 秒内即可完成一张图片的抠图，输出透明背景的 PNG。

第二，多尺寸标准证件照生成。内置常见的一寸、二寸、小一寸、小二寸等尺寸规格，同时支持自定义宽高（甚至支持以"毫米"为单位输入），满足不同国家和不同证件类型的需求。

第三，智能换底色。支持红底、蓝底、白底等常见背景色，并允许通过 HEX 值自定义任意颜色，方便适配护照、签证、简历等不同场景。

第四，六寸/五寸/A4 排版照输出。这是项目近期更新的亮点之一，可以将多张证件照排版到一张相纸上，方便用户直接去打印店冲印。

第五，人脸检测与对齐。使用 MTCNN 进行人脸关键点检测，结合 Face++（可选）实现更精确的人脸对齐，保证最终输出的证件照人物位置居中、五官比例协调。

第六，美颜与美化。2024 年 11 月新增的 API 美颜参数，可以在生成证件照的同时进行轻度美颜处理。

技术架构剖析

整个项目可以分为三个层次：模型层、服务层、应用层。模型层由抠图模型（MODNet）、人脸检测模型（MTCNN）以及可选的 Face++ API 组成；服务层使用 FastAPI 封装 RESTful 接口，对外暴露抠图、裁剪、换底等原子能力；应用层则通过 Gradio 构建了一个开箱即用的 Web 界面，零代码用户也能直接使用。

值得称道的是，作者在架构上做了良好的解耦。如果你只想用抠图能力，可以直接调用 Python API；如果想集成到自己的 Web 服务中，可以部署 FastAPI；如果想给非技术同事使用，直接跑 Gradio Demo 即可。这种灵活性让项目在 GitHub 上衍生出了丰富的社区版本——有人做了 Windows 桌面客户端，有人做了微信小程序，还有人把它部署到群晖 NAS 上。

快速上手

下面进入实战环节，从零开始把 HivisionIDPhotos 跑起来。

环境准备

建议使用 Conda 创建一个独立的 Python 3.10 虚拟环境，避免和系统已有的库产生冲突：

conda create -n hivision python=3.10 -y
conda activate hivision

然后克隆项目并安装依赖：

git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.git
cd HivisionIDPhotos
pip install -r requirements.txt
pip install -r requirements-app.txt

接下来需要下载人像抠图模型的权重文件。项目提供了自动化脚本，下载全部模型只需一行命令：

python scripts/download_model.py --models all

如果只想体验核心功能，可以只下载主要的抠图模型：

python scripts/download_model.py --models modnet_photographic_portrait_matting

下载完成后，权重文件会存放在 hivision/creator/weights 目录下。

启动 Gradio Web 界面

对于大多数用户而言，Gradio Demo 是最简单直观的使用方式。在项目根目录执行：

python app.py

启动成功后，终端会输出一个本地 URL（通常是 http://127.0.0.1:7860），用浏览器打开就能看到完整的证件照生成界面。整个流程非常顺畅：上传照片 → 选择尺寸与底色 → 点击生成 → 预览与下载。

Python 推理调用

如果想把证件照生成能力集成到自己的脚本中，可以直接调用底层的 Python 接口：

from hivision import IDPhotos

creator = IDPhotos()

# 一行代码完成证件照生成
result = creator(
    input_image="test.jpg",
    size=(413, 295),  # 一寸证件照尺寸
    change_bg=True,
    bg_color=(0, 0, 255),  # 蓝色背景
)

# 保存标准照和排版照
result.standard.save("id_photo.png")
result.layout.save("id_photo_layout.png")

这种"几行代码搞定一切"的体验，是 HivisionIDPhotos 区别于传统图像处理工具的重要优势。

部署 API 服务

对于需要对外提供证件照生成服务的场景（例如嵌入到 HR 系统或小程序后端），可以单独部署 FastAPI 服务：

python deploy_api.py

服务启动后，默认监听 8000 端口。通过 POST 请求即可调用证件照生成接口：

curl -X POST "http://127.0.0.1:8000/idphoto" \
  -F "input_image=@test.jpg" \
  -F "size=413,295" \
  -F "bg_color=(255,255,255)"

接口会返回生成的标准照高清文件，默认输出 300 DPI 的 JPEG，可以直接送印。

Docker 一键部署

如果不想在本地折腾环境，官方还提供了 Docker 镜像，几行命令就能完成部署：

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

需要自定义配置时，可以通过环境变量注入。例如启用"野兽模式"（保持模型常驻内存以加速二次推理）：

docker run -d -p 7860:7860 \
  -e RUN_MODE=beast \
  -e DEFAULT_LANG=en \
  linzeyi/hivision_idphotos

使用场景

HivisionIDPhotos 的应用场景非常广泛，涵盖个人、企业与开发者三类典型用户

项目信息

参考链接

• GitHub 仓库
• 项目主页