HivisionIDPhotos 完整使用指南：环境搭建、Python 推理与 API 服务部署

HivisionIDPhotos 完整使用指南：环境搭建、Python 推理与 API 服务部署

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

HivisionIDPhotos 是一个轻量级的 AI 证件照制作算法项目，通过一套完整的 AI 模型工作流完成人像抠图、尺寸裁剪、背景更换与排版照生成。本指南以 README_EN.md 为主线，结合仓库源码，系统讲解从环境准备、模型权重下载、五种 Python 推理模式到 API 服务与 Docker 部署的完整链路，读者学完后可独立搭建一套支持 CPU 纯离线推理的证件照制作服务。

项目定位与核心能力

HivisionIDPhotos 的目标是开发一套实用、系统化的证件照智能生成算法，其能力清单如下：

1. 轻量级抠图：纯离线运行，仅用 CPU 即可快速推理；
2. 标准证件照与六寸排版照生成：基于不同尺寸规格自动生成标准照和排版照；
3. 纯离线或边缘-云推理：不依赖外部服务（除可选的 Face++ 在线接口）；
4. 美颜效果（规划中）；
5. 智能正装换装（规划中）。

从源码结构看，核心处理逻辑集中在 hivision/creator 目录，入口类IDCreator定义了完整的证件照处理流水线（hivision/creator/init.py）：输入图像首先被缩放到最长边 2000 像素，随后依次执行人像抠图（matting）、美颜（beauty）、人脸检测（face detection）、可选的人脸对齐（face alignment）与图像后调整（adjust），最终输出标准照、高清照以及排版参数。每一步都打印耗时日志，便于定位性能瓶颈。

环境准备

1. 克隆项目

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

2. 安装依赖

项目要求Python >= 3.7（官方主要在 Python 3.10 上测试），支持Linux / Windows / MacOS。建议使用 conda 创建 Python 3.10 虚拟环境后执行：

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

其中 requirements.txt 为核心推理依赖（opencv-python、onnxruntime、numpy、mtcnn-runtime、starlette 等），requirements-app.txt则包含 Gradio Demo 与 API 服务（FastAPI）所需的额外依赖。

3. 下载模型权重

方法一：脚本一键下载

python scripts/download_model.py --models all

scripts/download_model.py 内置了全部模型的下载地址与落盘位置，支持按名称单独下载（如--models hivision_modnet rmbg-1.4），且已存在的文件会自动跳过，适合断点续传场景。

方法二：手动下载放置

将权重文件放入hivision/creator/weights目录：

| 权重文件 | 大小 | 说明 | | -- | -- | -- | |modnet_photographic_portrait_matting.onnx| 24.7MB | MODNet 官方权重，通用抠图 | |hivision_modnet.onnx| 24.7MB | 针对纯色背景替换优化适配性更好的抠图模型 | |rmbg-1.4.onnx| 176.2MB | BRIA AI 开源的抠图模型（需重命名为rmbg-1.4.onnx） | |birefnet-v1-lite.onnx| 224MB | BiRefNet 开源抠图模型（需重命名），当前版本中唯一支持 NVIDIA GPU 加速的模型 |

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

| 扩展人脸检测模型 | 说明 | 使用方式 | | -- | -- | -- | | MTCNN |离线人脸检测模型，CPU 推理性能高，默认模型，检测精度较低 | 克隆项目后直接可用 | | RetinaFace |离线人脸检测模型，CPU 推理速度中等（秒级），精度高 | 下载retinaface-resnet50.onnx放入hivision/creator/retinaface/weights目录 | | Face++ | 旷视推出的在线人脸检测 API，精度更高 | 使用方法见 docs/face++_EN.md |

模型与处理函数的绑定关系可在 hivision/creator/choose_handler.py 中确认：choose_handler会根据matting_model_option与face_detect_option为IDCreator注入对应的抠图处理器与检测器，未命中的配置会回退到默认实现（extract_human/detect_face_mtcnn）。

5. 性能参考

官方在 Mac M1 Max 64GB（无 GPU 加速）上、以 512×715 与 764×1146 两张测试图测得：

| 模型组合 | 内存占用 | 推理耗时 (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 推理加速（可选）

当前版本中可被 NVIDIA GPU 加速的模型为birefnet-v1-lite，需保证约16GB 显存。确认已安装 CUDA 与 cuDNN 后，按 onnxruntime-gpu 文档安装对应版本：

# 以 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

提示：CUDA 安装是向后兼容的。例如你的 CUDA 是 12.6，而 torch 当前最高只匹配到 12.4，仍然可以在本机安装 12.4 版本。

启动 Gradio 交互 Demo

python app.py

运行后会在本地生成一个网页，可对证件照进行可视化交互操作。Demo 近期的核心功能更新包括：打印排版（六寸、五寸、A4、3R、4R）、排版照裁剪线、Beast Mode、DPI 参数、分享模板照片、美式风格背景、自定义背景 HEX 颜色输入、人脸旋转矫正、自定义尺寸支持毫米、以及亮度/对比度/锐化调节等。

Python 命令行推理

核心参数：

• -i：输入图像路径
• -o：输出图像路径
• -t：推理类型，可选idphoto、human_matting、add_background、generate_layout_photos、idphoto_crop
• --matting_model：抠图模型权重选择
• --face_detect_model：人脸检测模型选择

其余参数可运行python inference.py --help查看。从 inference.py 的参数定义可知，--height/--width默认 413/295，--color默认638cce，--dpi默认 300，--render支持 0（纯色）、1（上下渐变）、2（中心渐变），--face_align默认关闭。

1. 证件照制作（idphoto）

输入 1 张照片，输出 1 张标准证件照和 1 张四通道透明 PNG 高清照：

python inference.py -i demo/images/test0.jpg -o ./idphoto.png --height 413 --width 295

2. 人像抠图（human_matting）

输入 1 张照片，输出 1 张四通道透明 PNG：

python inference.py -t human_matting -i demo/images/test0.jpg -o ./idphoto_matting.png --matting_model hivision_modnet

3. 为透明图像添加背景色（add_background）

输入 1 张四通道透明 PNG，输出 1 张带背景色的三通道图像：

python inference.py -t add_background -i ./idphoto.png -o ./idphoto_ab.jpg -c 4f83ce -k 30 -r 1

其中-c为十六进制背景色，-k为目标文件 KB 值（仅换底与排版照生效），-r为底色合成模式。结合 inference.py 源码可见，-k存在时通过resize_image_to_kb压缩至目标体积，否则按--dpi直接保存。

4. 生成六寸排版照（generate_layout_photos）

输入 1 张三通道照片，输出 1 张六寸排版照：

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

5. 证件照裁剪（idphoto_crop）

输入 1 张四通道照片（抠图后的图像），输出 1 张标准证件照和 1 张四通道透明高清照：

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

部署 API 服务

启动后端

python deploy_api.py

deploy_api.py 基于 FastAPI 构建，默认开放跨域（CORS），并将表单字段与上传文件上限分别设为 10MB / 20MB。目前对外提供/idphoto、/human_matting、/add_background等接口，/idphoto支持input_image_base64表单参数直接传入 base64 图片（见 deploy_api.py），其请求字段与命令行参数一一对应，还额外暴露了whitening_strength（美白）、brightness_strength（亮度）、contrast_strength（对比度）、sharpen_strength（锐化）、saturation_strength（饱和度）等美颜强度参数。

请求 API

详细请求方式见 docs/api_EN.md，包含 cURL 请求示例 与 Python 请求示例。

Docker 部署

1. 拉取或构建镜像（三选一）

方法一：拉取最新镜像

docker pull linzeyi/hivision_idphotos

方法二：直接基于 Dockerfile 构建

需先在hivision/creator/weights目录放置至少一个抠图模型权重，然后在项目根目录执行：

docker build -t linzeyi/hivision_idphotos .

方法三：Docker Compose 构建

同样先放置至少一个抠图模型权重，再执行：

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

3. 环境变量

| 环境变量 | 类型 | 说明 | 示例 | |--|--|--|--| |FACE_PLUS_API_KEY| 可选 | 从 Face++ 控制台获取的 API Key |7-fZStDJ····| |FACE_PLUS_API_SECRET| 可选 | 与 API Key 对应的 Secret |VTee824E····| |RUN_MODE| 可选 | 运行模式，取值为beast（野兽模式）。野兽模式下人脸检测与抠图模型不释放内存，二次推理速度更快，建议内存至少 16GB |beast|

Docker 中使用环境变量的示例：

docker run -d -p 7860:7860 \ -e FACE_PLUS_API_KEY=7-fZStDJ···· \ -e FACE_PLUS_API_SECRET=VTee824E···· \ -e RUN_MODE=beast \ linzeyi/hivision_idphotos

常见问题（Q&A）

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

• 尺寸：修改 demo/assets/size_list_EN.csv 后重新运行app.py。第一列为尺寸名称，第二列为高度，第三列为宽度。仓库预置了一寸（413×295）、二寸（626×413）、小二寸（531×413）、大二寸（626×413）、五寸（1499×1050）等常见规格。
• 颜色：修改 demo/assets/color_list_EN.csv 后重新运行app.py。第一列为颜色名称，第二列为 Hex 值，预置了蓝（628bce）、白（ffffff）、红（d74532）、黑（000000）、深蓝（4b6190）、浅灰（f2f0f0）。加载逻辑见 demo/config.py。

2. 如何更换水印字体？

1. 将字体文件放入hivision/plugin/font文件夹；
2. 修改 hivision/plugin/watermark.py 中font_file参数的值为字体文件名。

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

1. 将模板图放入hivision/plugin/template/assets文件夹，模板图需为四通道透明 PNG；
2. 在 hivision/plugin/template/assets/template_config.json 中添加最新模板信息：width为模板图宽（px），height为模板图高（px），anchor_points为模板中透明区域四个角的坐标（px），rotation为透明区域相对竖直方向的旋转角，>0 为逆时针，<0 为顺时针；
3. 将最新模板名称添加到 demo/processor.py 中_generate_image_template函数的TEMPLATE_NAME_LIST变量中。

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

修改 demo/assets/title.md 文件即可。

社区生态与引用

社区基于本算法构建了丰富的衍生项目，包括 ComfyUI 证件照工作流、微信证件照小程序（weapp 与 uniapp 前端）、C++ 版本、Windows GUI 客户端以及群晖 NAS 部署教程等，均以仓库社区栏目中展示的应用截图和说明为准。

项目引用与致谢了 MTCNN、MODNet 等开源工作，本仓库基于Apache-2.0 License开源（见 LICENSE）。如有问题可通过 README 中的邮箱联系作者。

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