HivisionIDPhotos 完整使用指南环境搭建、Python 推理与 API 服务部署【免费下载链接】HivisionIDPhotos⚡️HivisionIDPhotos: a lightweight and efficient AI ID photos tools. 一个轻量级的AI证件照制作算法。项目地址: https://gitcode.com/GitHub_Trending/hiv/HivisionIDPhotosHivisionIDPhotos 是一个轻量级的 AI 证件照制作算法项目通过一套完整的 AI 模型工作流完成人像抠图、尺寸裁剪、背景更换与排版照生成。本指南以 README_EN.md 为主线结合仓库源码系统讲解从环境准备、模型权重下载、五种 Python 推理模式到 API 服务与 Docker 部署的完整链路读者学完后可独立搭建一套支持 CPU 纯离线推理的证件照制作服务。项目定位与核心能力HivisionIDPhotos 的目标是开发一套实用、系统化的证件照智能生成算法其能力清单如下轻量级抠图纯离线运行仅用 CPU 即可快速推理标准证件照与六寸排版照生成基于不同尺寸规格自动生成标准照和排版照纯离线或边缘-云推理不依赖外部服务除可选的 Face 在线接口美颜效果规划中智能正装换装规划中。从源码结构看核心处理逻辑集中在 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 HivisionIDPhotos2. 安装依赖项目要求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 allscripts/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-gpu1.18.0 pip install torch --index-url https://download.pytorch.org/whl/cu121提示CUDA 安装是向后兼容的。例如你的 CUDA 是 12.6而 torch 当前最高只匹配到 12.4仍然可以在本机安装 12.4 版本。启动 Gradio 交互 Demopython 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 2952. 人像抠图human_matting输入 1 张照片输出 1 张四通道透明 PNGpython inference.py -t human_matting -i demo/images/test0.jpg -o ./idphoto_matting.png --matting_model hivision_modnet3. 为透明图像添加背景色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 2005. 证件照裁剪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.pydeploy_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 build2. 运行服务启动 Gradio Demo 服务本地访问 http://127.0.0.1:7860docker 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 -d3. 环境变量| 环境变量 | 类型 | 说明 | 示例 | |--|--|--|--| |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_KEY7-fZStDJ···· \ -e FACE_PLUS_API_SECRETVTee824E···· \ -e RUN_MODEbeast \ linzeyi/hivision_idphotos常见问题QA1. 如何修改预设尺寸与颜色尺寸修改 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. 如何更换水印字体将字体文件放入hivision/plugin/font文件夹修改 hivision/plugin/watermark.py 中font_file参数的值为字体文件名。3. 如何添加社交媒体模板照片将模板图放入hivision/plugin/template/assets文件夹模板图需为四通道透明 PNG在 hivision/plugin/template/assets/template_config.json 中添加最新模板信息width为模板图宽pxheight为模板图高pxanchor_points为模板中透明区域四个角的坐标pxrotation为透明区域相对竖直方向的旋转角0 为逆时针0 为顺时针将最新模板名称添加到 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HivisionIDPhotos 完整使用指南：环境搭建、Python 推理与 API 服务部署
HivisionIDPhotos 完整使用指南环境搭建、Python 推理与 API 服务部署【免费下载链接】HivisionIDPhotos⚡️HivisionIDPhotos: a lightweight and efficient AI ID photos tools. 一个轻量级的AI证件照制作算法。项目地址: https://gitcode.com/GitHub_Trending/hiv/HivisionIDPhotosHivisionIDPhotos 是一个轻量级的 AI 证件照制作算法项目通过一套完整的 AI 模型工作流完成人像抠图、尺寸裁剪、背景更换与排版照生成。本指南以 README_EN.md 为主线结合仓库源码系统讲解从环境准备、模型权重下载、五种 Python 推理模式到 API 服务与 Docker 部署的完整链路读者学完后可独立搭建一套支持 CPU 纯离线推理的证件照制作服务。项目定位与核心能力HivisionIDPhotos 的目标是开发一套实用、系统化的证件照智能生成算法其能力清单如下轻量级抠图纯离线运行仅用 CPU 即可快速推理标准证件照与六寸排版照生成基于不同尺寸规格自动生成标准照和排版照纯离线或边缘-云推理不依赖外部服务除可选的 Face 在线接口美颜效果规划中智能正装换装规划中。从源码结构看核心处理逻辑集中在 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 HivisionIDPhotos2. 安装依赖项目要求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 allscripts/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-gpu1.18.0 pip install torch --index-url https://download.pytorch.org/whl/cu121提示CUDA 安装是向后兼容的。例如你的 CUDA 是 12.6而 torch 当前最高只匹配到 12.4仍然可以在本机安装 12.4 版本。启动 Gradio 交互 Demopython 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 2952. 人像抠图human_matting输入 1 张照片输出 1 张四通道透明 PNGpython inference.py -t human_matting -i demo/images/test0.jpg -o ./idphoto_matting.png --matting_model hivision_modnet3. 为透明图像添加背景色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 2005. 证件照裁剪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.pydeploy_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 build2. 运行服务启动 Gradio Demo 服务本地访问 http://127.0.0.1:7860docker 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 -d3. 环境变量| 环境变量 | 类型 | 说明 | 示例 | |--|--|--|--| |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_KEY7-fZStDJ···· \ -e FACE_PLUS_API_SECRETVTee824E···· \ -e RUN_MODEbeast \ linzeyi/hivision_idphotos常见问题QA1. 如何修改预设尺寸与颜色尺寸修改 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. 如何更换水印字体将字体文件放入hivision/plugin/font文件夹修改 hivision/plugin/watermark.py 中font_file参数的值为字体文件名。3. 如何添加社交媒体模板照片将模板图放入hivision/plugin/template/assets文件夹模板图需为四通道透明 PNG在 hivision/plugin/template/assets/template_config.json 中添加最新模板信息width为模板图宽pxheight为模板图高pxanchor_points为模板中透明区域四个角的坐标pxrotation为透明区域相对竖直方向的旋转角0 为逆时针0 为顺时针将最新模板名称添加到 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考