企业官网建设流程全解析

HivisionIDPhotos 抠图模型选型手册：4种AI抠图方案实测

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

HivisionIDPhotos 是一个轻量级 AI 证件照制作工具，输入一张照片即可完成抠图、换底与排版。本文带你在本地跑通 Gradio Demo，实测 4 种抠图模型的差异，并给出按硬件条件选择模型的判断规则。

执行链路：一张照片如何变成证件照

输入：原始照片先被 resize 到最大边长 2000px，控制后续算力开销。

# hivision/creator/__init__.py ctx.processing_image = U.resize_image_esp(image, 2000) ctx.origin_image = ctx.processing_image.copy()

处理：IDCreator按"抠图→美颜→人脸检测→图像调整"四步串行执行。抠图相当于给图片贴了一张蒙版，背景变成透明通道；人脸检测要求恰好检出 1 张脸，否则抛出FaceError。所有步骤共享一个Context上下文对象，各步骤通过它读写中间结果。

# hivision/creator/choose_handler.py if matting_model_option == "modnet_photographic_portrait_matting": creator.matting_handler = extract_human_modnet_photographic_portrait_matting elif matting_model_option == "rmbg-1.4": creator.matting_handler = extract_human_rmbg # ... 省略 birefnet-v1-lite 与 mnn 分支

模型切换的本质就是替换matting_handler函数，这是全文档最重要的一个入口。

输出：一次推理产出标准照与高清照两张透明四通道 PNG，标准照尺寸等于size参数（默认 413x295，即一寸）。

# inference.py result = creator(input_image, size=(413, 295), face_alignment=args.face_align) save_image_dpi_to_bytes(result.standard, args.output_image_dir, dpi=args.dpi) save_image_dpi_to_bytes(result.hd, new_file_name, dpi=args.dpi)

透明底的设计是为了让前端频繁切换底色时只做合成，不再重跑模型。

完整操作流程：从零跑通 Demo

第一步：克隆仓库并安装依赖

目的：拿到可运行的代码环境，Python 建议 3.10（最低 3.7）。

git clone https://gitcode.com/GitHub_Trending/hiv/HivisionIDPhotos cd HivisionIDPhotos pip install -r requirements.txt pip install -r requirements-app.txt

预期输出：pip 全部安装成功。requirements.txt覆盖推理核心依赖（onnxruntime、mtcnn-runtime 等），requirements-app.txt额外安装 Gradio 界面依赖。

依赖就绪后，模型权重不在仓库内，需要单独拉取。

第二步：下载抠图模型权重

目的：把 ONNX 权重放到正确目录，app.py启动时会扫描该目录决定下拉框里出现哪些模型。

python scripts/download_model.py --models all # 也可只下载单个模型 # python scripts/download_model.py --models modnet_photographic_portrait_matting

预期输出：终端打印Download completed. Save to: .../hivision/creator/weights/hivision_modnet.onnx。权重统一存到 hivision/creator/weights/；若下载 RetinaFace，则存到 hivision/creator/retinaface/weights/。

权重落盘后，Gradio Demo 一条命令即可启动。

第三步：启动 Gradio Demo

目的：在浏览器里完成"上传照片→选模型→出证件照"的完整交互。

python app.py # 可选参数：--port 7860 --host 127.0.0.1

预期输出：浏览器打开 http://127.0.0.1:7860，上传照片后在"抠图模型"与"人脸检测模型"两个下拉框选择方案，点击开始制作即可得到标准照、高清照与六寸排版照。

界面适合调参体验；要批量处理或接入自己的系统，改用命令行推理。

第四步：CLI 推理与 API 服务

目的：跳过界面，直接用脚本产出结果，方便集成到工作流。

python inference.py -i demo/images/test0.jpg -o ./idphoto.png --height 413 --width 295 python deploy_api.py # 启动 8080 端口的 FastAPI 服务

预期输出：inference.py在当前目录生成idphoto.png与idphoto_hd.png两张透明 PNG，终端打印各阶段耗时（[1] Human Matting Time: 0.xxxs）。deploy_api.py启动后，接口参数详见 API 文档。

参数与配置：推理关键项一览

• 处理 4K 大图时不必手动压缩，输入会被自动 resize 到 2000px
• 输出文件超过冲印店上传限制时，用-k参数把文件压到指定 KB
• 批量处理且模型组合固定时，建议开野兽模式，省掉每轮的模型加载开销

选型参考：抠图与检测模型横向对比

抠图模型权重体积与官方实测性能（Mac M1 Max 纯 CPU，测试图 512x715 / 764x1146）：

人脸检测三选一，直接决定链路里耗时最低或最高的一环：

三条判断规则：

• 如果你的机器只有 CPU 且要批量跑，选modnet_photographic_portrait_matting+mtcnn，0.2 秒级出图
• 如果追求发丝边缘精度且显存约 16GB，选birefnet-v1-lite，并安装onnxruntime-gpu启用 GPU 加速
• 如果目标照片有遮挡或人脸偏小导致检测失败，先把检测模型换成retinaface-resnet50，再考虑换脸模检测走 face++

踩坑记录：高频故障速查

现象：提示"人脸数量不等于 1，请上传单张人脸的图像"，证件照未生成。

原因：FaceError被触发，检测到了 0 张或多张人脸。

解法：换一张单人正脸照片；或执行python inference.py -t idphoto -i 照片路径 -o 输出路径 --face_detect_model retinaface-resnet50提升检出稳定性。

现象：启动app.py直接报错"未找到任何存在的人像分割模型"。

原因：hivision/creator/weights目录下没有任何 .onnx 或 .mnn 文件。

解法：执行python scripts/download_model.py --models all下载全部权重后重启；rmbg-1.4 手动下载后必须重命名为rmbg-1.4.onnx。

现象：Gradio 界面"抠图模型"下拉框只有两三个选项，少了 birefnet 等模型。

原因：app.py启动时动态扫描权重目录，只展示已下载的模型。

解法：把缺失权重补进hivision/creator/weights，重新运行python app.py，无需改任何代码。

现象：birefnet-v1-lite在 CPU 上单张要跑 7 秒以上，批量处理不可接受。

原因：它是四个模型中体积最大的（224MB），纯 CPU 推理天然慢。

解法：安装 GPU 版运行时pip install onnxruntime-gpu==1.18.0（需约 16GB 显存与匹配的 CUDA）；显存不够就换 modnet 系模型，代码零改动。

进阶扩展：二次开发入口

• 美颜管线：美白、瘦脸、磨皮等处理在 hivision/plugin/beauty/，通过beauty_handler接入主流程
• 社交模板照：透明 PNG 模板 + 配置文件的组合方案，见 hivision/plugin/template/
• 水印功能：文字水印的参数与渲染逻辑在 hivision/plugin/watermark.py
• API 集成：FastAPI 后端 deploy_api.py 与 Docker 编排 docker-compose.yml，接口字段详见 API 文档

抠图模型按硬件条件选择、检测模型按照片质量选择，是 HivisionIDPhotos 提速的全部诀窍。更完整的接口参数与社区应用，查阅 项目文档 即可。

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