HivisionIDPhoto

HivisionIDPhoto

🚀 共绩算力开源技术方案

HivisionIDPhoto 是一套基于共绩算力理念的开源技术方案，旨在为证件照制作提供高效、可扩展的AI解决方案。通过共享计算资源和优化算法，我们实现了轻量级、高性能的证件照处理能力，支持多种部署方式，特别适合需要快速部署和使用的场景。

✨ 核心特性：

即开即用：提供完整的Docker镜像，无需复杂配置即可快速部署

算力共享：支持分布式部署，可充分利用多节点计算资源

轻量高效：纯CPU推理，内存占用低，推理速度快

开源开放：完整的源代码和模型权重，支持二次开发和定制

多端适配：支持Web界面、API服务、移动端等多种使用方式

项目简介

HivisionIDPhoto 旨在开发一种实用、系统性的证件照智能制作算法。

它利用一套完善的AI模型工作流程，实现对多种用户拍照场景的识别、抠图与证件照生成。

HivisionIDPhoto 可以做到：

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

如果 HivisionIDPhoto 对你有帮助，请 star 这个 repo 或推荐给你的朋友，解决证件照应急制作问题！

🚀 共绩算力方案

技术架构

HivisionIDPhoto 采用共绩算力架构设计，通过以下技术手段实现高效的计算资源利用：

1. 分布式计算支持

负载均衡：支持多实例部署，自动分配计算任务
资源池化：将计算资源统一管理，提高利用率
弹性扩展：根据需求动态调整计算节点

2. 轻量化设计

模型优化：采用ONNX格式，支持CPU高效推理
内存管理：智能内存分配，支持低配置环境运行
并行处理：多线程处理，充分利用多核CPU

3. 容器化部署

Docker镜像：提供完整的运行环境，一键部署
微服务架构：模块化设计，支持独立扩展
环境隔离：避免依赖冲突，保证运行稳定性

应用场景

1. 企业级部署

证件照制作服务：为政府机构、学校、企业提供批量证件照处理
云服务集成：作为SaaS服务的基础组件
边缘计算：在本地服务器上部署，保护数据隐私

2. 开发者集成

API服务：提供RESTful API接口，便于第三方集成
SDK开发：支持多种编程语言的SDK封装
插件系统：可扩展的插件架构，支持功能定制

3. 社区贡献

开源生态：完整的开源代码，支持社区贡献
模型共享：预训练模型权重开源，降低使用门槛
文档完善：详细的技术文档和使用教程

⚡ 快速开始

方式一：共绩算力平台部署（最推荐）

零配置部署，即开即用，支持GPU加速：

登录共绩算力控制台，点击"弹性部署服务"
选择GPU型号：推荐 NVIDIA RTX 4090
选择预制镜像：搜索并选择 HivisionIDPhotos 官方镜像
一键部署：点击"部署服务"即可

部署完成后，通过公网链接即可访问Web界面（端口7860）或API服务（端口8080）。

方式二：本地Docker镜像

本地部署，无需复杂配置：

# 拉取最新镜像
docker pull linzeyi/hivision_idphotos

# 启动Web界面服务
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

访问 http://127.0.0.1:7860 即可使用Web界面，或通过 http://127.0.0.1:8080 调用API服务。

方式二：源码部署

如果您需要自定义开发或部署到特定环境，可以参考以下步骤：

# 克隆项目
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 app.py  # Web界面
python deploy_api.py  # API服务

方式三：云端部署

我们提供了多个云端部署选项：

Hugging Face Spaces：在线体验
ModelScope：模型社区
Modelers：AI平台

🏠 社区

我们分享了一些由社区构建的HivisionIDPhotos的有趣应用和扩展：

[HivisionIDPhotos-ComfyUI][community-hivision-comfyui]	[HivisionIDPhotos-wechat-weapp][community-hivision-wechat]

ComfyUI证件照处理工作流	证件照微信小程序（JAVA后端+原生前端）

[HivisionIDPhotos-Uniapp][community-hivision-uniapp]	HivisionIDPhotos-web

证件照微信小程序（uniapp）	证件照应用网页版

HivisionIDPhotos-cpp: HivisionIDphotos C++版本，由 zjkhahah 构建
ai-idphoto: HivisionIDPhotos-wechat-weapp 的uniapp多端兼容版，由 wmlcjj 贡献
HivisionIDPhotos-uniapp-WeChat-gpto1: 由gpt-o1辅助完成开发的证件照微信小程序，由 jkm199 贡献
HivisionIDPhotos-windows-GUI：Windows客户端应用，由 zhaoyun0071 构建
HivisionIDPhotos-NAS: 群晖NAS部署中文教程，由 ONG-Leo 贡献

🔧 准备工作

环境安装与依赖：

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

1. 克隆项目

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

2. 安装依赖环境

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

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

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加速，测试图片分辨率为 512x715(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，那么试试安装torch
pip install onnxruntime-gpu==1.18.0
pip 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. 得到六寸排版照

输入 1 张 3 通道照片，获得 1 张六寸排版照

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

5. 证件照裁剪

输入 1 张 4 通道照片（抠图好的图像），获得 1 张标准证件照和 1 张高清证件照的 4 通道透明 png

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

⚡️ 部署 API 服务

启动后端

python deploy_api.py

请求 API 服务

详细请求方式请参考 API 文档，包含以下请求示例：

cURL
Python

🐳 Docker 部署

方式一：本地 Docker 部署

1. 拉取或构建镜像

以下方式三选一

方式一：拉取最新镜像：

docker pull linzeyi/hivision_idphotos

方式二：Dockrfile 直接构建镜像：

在确保将至少一个抠图模型权重文件放到hivision/creator/weights下后，在项目根目录执行：

docker build -t linzeyi/hivision_idphotos .

方式三：Docker compose 构建：

在确保将至少一个抠图模型权重文件放到hivision/creator/weights下后，在项目根目录下执行：

docker compose build

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

方式二：共绩算力平台部署（推荐）

本指南详细阐述了在共绩算力平台上，高效部署与使用 HivisionIDPhotos 项目的技术方案。共绩算力平台提供预构建的 HivisionIDPhotos 容器镜像，用户无需本地复杂环境配置，可快速完成部署并启用服务。

1. 在共绩算力上运行 HivisionIDPhotos

1.1 创建部署服务

登录共绩算力控制台，在控制台首页点击"弹性部署服务"进入管理页面。首次使用需确保账户已开通弹性部署服务权限。

1.2 选择 GPU 型号

根据实际需求选择 GPU 型号：

初次使用或调试阶段：推荐配置单张 NVIDIA RTX 4090 GPU
生产环境：可根据并发需求选择更高配置

1.3 选择预制镜像

在"服务配置"模块切换至"预制服务"选项卡，搜索并选择 HivisionIDPhotos 官方镜像。

1.4 部署并访问服务

点击"部署服务"，平台将自动拉取镜像并启动容器。

部署完成后，在"快捷访问"中找到端口为 7860 的公网访问链接，点击即可在浏览器中使用 HivisionIDPhotos 的 Web 界面，或通过 8080 端口调用 API 服务。

2. 快速上手——快速抠图蓝底证件照

上传图片：可以点击或直接把要制作的图片拖入
选择参数：在下方选择相关参数（尺寸、背景色等）
开始制作：点击开始制作按钮
获取结果：几十秒后即可完成，左侧标准，右侧高清，下方还能生成 10 张排版的格式

展开下方栏目，还能看到同时生成了社交媒体模版照和抠图图像。

3. API 调用指南

HivisionIDPhotos 提供完整的 API 接口体系，支持通过编程方式实现照片创作全流程自动化。我们预制好的镜像中 8080 端口为 API 调用接口地址，可以在生产环境中直接使用。

3.1 环境准备

pip install requests

import requests
API_URL = "http://<您的部署 ID>.550c.cloud:8080/"

3.2 核心功能接口

生成透明底证件照（idphoto）

result = requests.post(
    f"{API_URL}idphoto",
    files={"input_image": open("test.jpg", "rb")},
    data={
        "height": 413,  # 标准高度（默认 295×413）
        "width": 295,   # 标准宽度
        "human_matting_model": "modnet_photographic_portrait_matting",  # 人像分割模型
        "hd": True,     # 是否生成高清版
        "head_measure_ratio": 0.2,  # 面部占比
        "head_height_ratio": 0.45   # 面部位置比例
    }
).json()

standard_photo = result["image_base64_standard"]  # 标准证件照（Base64）
hd_photo = result["image_base64_hd"]              # 高清证件照（Base64）

添加背景色（add_background）

result = requests.post(
    f"{API_URL}add_background",
    files={"input_image": open("transparent.png", "rb")},
    data={
        "color": "638cce",  # 蓝底 HEX 色值
        "render": 1,         # 渐变模式（0=纯色/1=上下渐变/2=中心渐变）
        "kb": 200            # 输出文件大小控制（KB）
    }
).json()

colored_photo = result["image_base64"]  # 带背景色的证件照

生成六寸排版照（generate_layout_photos）

result = requests.post(
    f"{API_URL}generate_layout_photos",
    files={"input_image": open("idphoto.jpg", "rb")},
    data={"kb": 500}  # 排版照文件大小控制
).json()

layout_photo = result["image_base64"]  # 6 寸排版照（含多张证件照）

3.3 高级控制参数

参数	作用	推荐值
human_matting_model	人像分割模型选择	modnet_photographic_portrait_matting（通用场景）
face_detect_model	人脸检测模型	mtcnn（快速）/retinaface-resnet50（高精度）
head_measure_ratio	面部占照片面积比例	0.15-0.25（标准 0.2）
head_height_ratio	面部中心到照片顶部的比例	0.4-0.5（标准 0.45）
render	背景渲染模式	0=纯色/1=上下渐变/2=中心渐变
kb	输出文件大小控制（KB）	50-300（根据用途调整）

3.4 全流程自动化示例

transparent = requests.post(f"{API_URL}idphoto", ...).json()
blue_bg = requests.post(
    f"{API_URL}add_background",
    files={"input_image_base64": transparent["image_base64_standard"]},
    data={"color": "638cce"}
).json()
layout = requests.post(
    f"{API_URL}generate_layout_photos",
    files={"input_image_base64": blue_bg["image_base64"]}
).json()

with open("blue_idphoto.jpg", "wb") as f:
    f.write(base64.b64decode(blue_bg["image_base64"]))
with open("6inch_layout.jpg", "wb") as f:
    f.write(base64.b64decode(layout["image_base64"]))

通过 API 集成，开发者可构建自动化生产线，结合透明底生成、动态换色、智能排版等功能，实现证件照制作全流程智能化。

环境变量

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

环境变量	类型	描述	示例
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

FAQ

1. 如何修改预设尺寸和颜色？

尺寸：修改size_list_CN.csv后再次运行 app.py 即可，其中第一列为尺寸名，第二列为高度，第三列为宽度。
颜色：修改color_list_CN.csv后再次运行 app.py 即可，其中第一列为颜色名，第二列为Hex值。

2. 如何修改水印字体？

将字体文件放到hivision/plugin/font文件夹下
修改hivision/plugin/watermark.py的font_file参数值为字体文件名

3. 如何添加社交媒体模板照？

将模板图片放到hivision/plugin/template/assets文件夹下。模板图片是一个4通道的透明png。
在hivision/plugin/template/assets/template_config.json文件中添加最新的模板信息，其中width为模板图宽度(px)，height为模板图高度(px)，anchor_points为模板中透明区域的四个角的坐标(px)；rotation为透明区域相对于垂直方向的旋转角度，>0为逆时针，<0为顺时针。
在demo/processor.py的_generate_image_template函数中的TEMPLATE_NAME_LIST变量添加最新的模板名

4. 如何修改Gradio Demo的顶部导航栏？

修改demo/assets/title.md

5. 如何添加/修改「打印排版」中的尺寸？

修改demo/locales.py中的print_switch字典，添加/修改新的尺寸名称和尺寸参数，然后重新运行python app.py

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.devcontainer		.devcontainer
.github/workflows		.github/workflows
assets		assets
demo		demo
docs		docs
hivision		hivision
scripts		scripts
test		test
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
README_JP.md		README_JP.md
README_KO.md		README_KO.md
app.py		app.py
app.spec		app.spec
deploy_api.py		deploy_api.py
docker-compose.yml		docker-compose.yml
inference.py		inference.py
requirements-app.txt		requirements-app.txt
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt

License

slmnb-lab/HivisionIDPhotos-GONGJI

Folders and files

Latest commit

History

Repository files navigation

HivisionIDPhoto

目录

最近更新

项目简介

🚀 共绩算力方案

技术架构

1. 分布式计算支持

2. 轻量化设计

3. 容器化部署

应用场景

1. 企业级部署

2. 开发者集成

3. 社区贡献

⚡ 快速开始

方式一：共绩算力平台部署（最推荐）

方式二：本地Docker镜像

方式二：源码部署

方式三：云端部署

🏠 社区

🔧 准备工作

1. 克隆项目

2. 安装依赖环境

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

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

5. 性能参考

6. GPU推理加速（可选）

⚡️ 运行 Gradio Demo

🚀 Python 推理

1. 证件照制作

2. 人像抠图

3. 透明图增加底色

4. 得到六寸排版照

5. 证件照裁剪

⚡️ 部署 API 服务

启动后端

请求 API 服务

🐳 Docker 部署

方式一：本地 Docker 部署

1. 拉取或构建镜像

2. 运行服务

方式二：共绩算力平台部署（推荐）

1. 在共绩算力上运行 HivisionIDPhotos

1.1 创建部署服务

1.2 选择 GPU 型号

1.3 选择预制镜像

1.4 部署并访问服务

2. 快速上手——快速抠图蓝底证件照

3. API 调用指南

3.1 环境准备

3.2 核心功能接口

3.3 高级控制参数

3.4 全流程自动化示例

环境变量

FAQ

1. 如何修改预设尺寸和颜色？

2. 如何修改水印字体？

3. 如何添加社交媒体模板照？

4. 如何修改Gradio Demo的顶部导航栏？

5. 如何添加/修改「打印排版」中的尺寸？

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages