告别影楼和付费 App，5 分钟本地搭一个证件照自由平台｜HivisionIDPhotos 开箱实测

本文摘自：码录集 - CoderLog 中文技术博客

一、你有没有被证件照"坑"过？

• 入职前一天才发现照片用完了，楼下照相馆 30 元 8 张还要等 1 小时；
• 手机上 App Store 搜「证件照」，下载一堆发现要么分辨率不够、要么水印满天飞，导出高清版还要付 9.9 元/次；
• 报名考试对底色、像素、分辨率、DPI 都有硬要求，自己用 Photoshop / 美图折腾半天仍然不合格；
• 最难受的：照片给了第三方服务，人脸和身份信息到底去了哪里，你根本不知道。

大家好，我是码农刚子。如果你也有过上述任意一种经历，那么这篇开箱的主角——HivisionIDPhotos，可能就是你电脑里值得常备的一款小工具。它是一个开源证件照智能生成项目，纯本地离线推理、CPU 就能跑、不向任何云端上传你的照片，从抠图、换底色、排版到美颜，一条龙搞定。

二、它到底能做什么？先看效果

项目把能力做成了一个 Gradio Web UI，打开浏览器就能操作。核心能力清单：

能力	说明
🎯 智能抠图	4 种人像分割模型可选（HivisionModNet / ModNet / RMBG-1.4 / BiRefNet-Lite），头发丝边缘清晰
📐 规格生成	内置常见证件照尺寸（一寸、二寸、护照、签证、社保…），也支持毫米/像素自定义
🎨 智能换底色	白、红、蓝、渐变蓝、渐变灰、美式证件照底色，支持 HEX 任意色号
🖼️ 排版照输出	六寸相纸、五寸相纸、A4、3R、4R 五种排版，带裁剪线
✨ 美颜功能	磨皮、美白、瘦脸三项参数可调
🔄 人脸对齐	自动旋转对齐，防止证件照歪头
🏷️ 分享模板照	六种经典模板（驾照风格、工牌风格等）一键合成
🌐 多语言	中文、English、日本語、한국어 四种界面语言
🎛️ 野兽模式	可选的内存策略，批量处理时更稳定

官方案例图就已经很能打了：9 张图的排版输出 + 颜色切换，肉眼看边缘基本不糊。

三、开箱！从零到启动的完整流程

3.1 环境准备

• Python：推荐 3.10 及以上（项目本身兼容 3.8+，但 Gradio 6.x 建议新一点）
• 操作系统：Windows / macOS / Linux 都没问题，下面以 Windows 为例
• 磁盘：至少预留 500MB（抠图模型权重文件较大，BiRefNet-Lite 约 214MB）

3.2 拉取代码 + 安装依赖

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

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

注意：requirements.txt 是推理核心依赖（OpenCV、ONNXRuntime、MTCNN 等），requirements-app.txt 多了 Gradio 和 FastAPI，不要漏掉。如果你只做 API 部署可以不装 Gradio，但我们开箱肯定要 UI。

3.3 下载模型权重

第一次运行前必须下载模型，项目贴心提供了下载脚本：

python scripts/download_model.py --models hivision_modnet modnet_photographic_portrait_matting rmbg-1.4 birefnet-lite

或者图省事直接全量：

python scripts/download_model.py --models all

下载完成后，模型会分别落到：

hivision/creator/weights/hivision_modnet.onnx
hivision/creator/weights/modnet_photographic_portrait_matting.onnx
hivision/creator/weights/rmbg-1.4.onnx
hivision/creator/weights/birefnet-v1-lite.onnx
hivision/creator/retinaface/weights/retinaface-resnet50.onnx

⚠️ 小提醒：.gitignore 已忽略 .onnx / .mnn 文件，所以模型权重不会被误提交到 Git。如果你想把整个项目 fork 到自己仓库，这是好事；但如果你换机器部署，记得在新机器上重新跑一次下载脚本。

3.4 启动 Demo

python app.py

预期输出：

Running on local URL:  http://127.0.0.1:7860

浏览器打开后就能看到界面。

四、⚠️ 开箱实测的小坑（已帮你踩过）

我的实际运行环境是 Python 3.12 + Gradio 6.26.0，启动时遇到了一个拦路虎：

TypeError: Blocks.launch() got an unexpected keyword argument 'show_api'

原因：项目要求 Gradio ≥ 4.43.0，但 show_api 参数在 Gradio 5.x 已标记废弃，Gradio 6.x 中被直接移除。老代码 app.py 里 demo.launch(..., show_api=False) 就会炸。

修复方式（一行）：打开 app.py 第 73~79 行附近，删掉 show_api=False 即可：

# 修改前
demo.launch(
    server_name=args.host,
    server_port=args.port,
    favicon_path=os.path.join(root_dir, "assets/hivision_logo.png"),
    root_path=args.root_path,
    show_api=False,   # ← Gradio 6.x 不认识这个参数，删掉
)

# 修改后
demo.launch(
    server_name=args.host,
    server_port=args.port,
    favicon_path=os.path.join(root_dir, "assets/hivision_logo.png"),
    root_path=args.root_path,
)

改完重启就正常了。个人推测等上游仓库合并 PR 之后，这个修复会被包含，读者朋友未来拉到最新版可能不用手动改。

五、核心功能逐项实测

5.1 证件照生成（主流程）

操作流程是"三步走"，非常直觉：

1. 上传照片：任意正面照都行，手机拍的也可以。光线均匀、五官清晰效果最好。
2. 选尺寸+底色：下拉选一寸（295×413）、二寸（413×579）、护照等，或者点「自定义」直接输入毫米数。
3. 选抠图模型 → 点生成：

各模型主观感受如下（都是 CPU 跑的，i7-10750H）：

模型	大小	速度	抠图质量	推荐场景
hivision_modnet	~25MB	0.2s/张	⭐⭐⭐⭐	日常一寸二寸首选，速度快
modnet_photographic_portrait_matting	~25MB	0.2s/张	⭐⭐⭐⭐	针对照相馆照片风格优化
rmbg-1.4	~176MB	0.8s/张	⭐⭐⭐⭐⭐	头发丝、透明边缘效果最佳
birefnet-v1-lite	~214MB	1.2s/张	⭐⭐⭐⭐⭐	复杂背景效果惊艳

💡 我的经验：日常一寸红底用 hivision_modnet 就行；照片背景复杂（比如室外、有窗帘）、或者对边缘要求高（报名考试）切换到 birefnet-v1-lite 或 rmbg-1.4。

5.2 美颜（加分项）

• 磨皮：默认 0~100，推到 60 左右自然不夸张，不会像网红那样磨成塑料脸。
• 美白：0100，亚洲黄皮建议 3050，再高就和脖子脱节了。
• 瘦脸：0~100，证件照不建议超过 20，否则识别不过就尴尬了。

5.3 排版照打印

输出格式支持：六寸 / 五寸 / A4 / 3R / 4R，选好规格后直接会把 N 张证件照整齐排到一张相纸上，自带裁剪虚线，打印完直接剪下来就能用。

我测试了一寸红底 × 六寸排版，输出正好 8 张，完全够一次入职或考试用——算下来比照相馆 30 元省 29 元。

5.4 人脸旋转对齐

这个功能我觉得被低估了。手机自拍你永远不知道自己头到底歪了多少，打开「人脸对齐」后，程序会先做人脸关键点检测，把图像自动旋转到双眼水平，再生成证件照——这一步能让你自己都感觉"照片怎么突然顺眼多了"。

六、隐私！隐私！隐私！

我把这一项单独拎一节，因为证件照本身就是高敏感信息。

市面上大部分在线证件照服务的链路是：你上传照片 → 服务器抠图/处理 → 返回结果。这意味着你那张带着身份证号/工牌/护照规格的照片，全程在别人机房里跑了一圈，可能留存、可能被训练，你完全没感知。

HivisionIDPhotos 的核心优势就在这里：

• ✅ 纯本地运行：模型在你自己电脑上推理，不上传任何字节
• ✅ 支持断网使用：人脸检测默认离线 MTCNN，仅当你选择「face++」才联网（且是你主动选）
• ✅ 代码公开：核心抠图/美颜/排版逻辑全在 hivision/ 下，你可以审计
• ✅ 输出保留 DPI：结果是 300 DPI 高分辨率 PNG/JPG，可直接打印

对于需要处理护照、签证照片的朋友，这一点可能比效果还重要。

七、缺点也要明说：客观评价

开箱好用，但不代表没有瑕疵：

问题	说明	应对方式
启动前必须下模型	权重文件大，首次下载要等几分钟	用脚本批量下，网络不畅可挂代理
Gradio 版本兼容	Gradio 6.x 移除了 show_api 参数（本坑已踩）	等上游 PR 合并，或按本文第四节手改
美颜参数比较"粗"	只有三项，没有精细分区调整	真要精修，把结果导出进 Lightroom / PS 再润色
正装合成仍未上线	README 里写了「智能换正装（waiting）」	目前只能靠自己后期 / 或用模板照
RetinaFace 模型需额外下载	比 MTCNN 更准但不是默认自带	跑 download_model.py --models all 就有
野兽模式默认关闭	连续处理上百张才有用	批量跑时加环境变量 RUN_MODE=beast

八、和同类方案横向对比

维度	HivisionIDPhotos	照相馆	手机付费 App	在线抠图网站
价格	免费（开源）	2050 元/次	10 元左右/次	520 元/次
隐私安全	⭐⭐⭐⭐⭐ 100% 本地	⭐⭐ 数据在店家设备	⭐⭐⭐ 上传到 App 服务器	⭐⭐ 全流程联网
可用速度	⭐⭐⭐⭐ 立刻可用	⭐ 等 30 分钟~1 天	⭐⭐⭐⭐ 立等可取	⭐⭐⭐⭐ 立等可取
规格丰富度	⭐⭐⭐⭐⭐ 内置 + 自定义	⭐⭐⭐⭐ 常见齐全	⭐⭐⭐⭐ 常见齐全	⭐⭐⭐ 一般
美颜/排版	⭐⭐⭐⭐ 够用	⭐⭐⭐⭐⭐ 专业修图师	⭐⭐⭐ 简单参数	⭐⭐ 基本没有
质量可控	⭐⭐⭐⭐ 可微调重试	⭐⭐⭐⭐ 取决于师傅	⭐⭐⭐ 算法自动	⭐⭐⭐ 算法自动

结论：如果你偶尔需要做证件照、在意隐私、愿意花 10 分钟配置环境，HivisionIDPhotos 是不二之选。如果你完全不碰技术、又急着要照片，那还是去照相馆比较省心（贵点但省时间）。

九、进阶玩法：不止是网页

这个项目不仅能当网页工具用，官方还提供了两种部署形式，按需选：

1. 纯 Python 推理脚本（适合做自动化批处理）

   # inference.py 就是脚本入口，传图路径 + 尺寸参数即可
   from hivision import create_id_photo
   

2. API 服务部署（适合接入你自己的业务系统）

   python deploy_api.py
   

   启动后是 FastAPI，支持 POST 传 base64 或文件流，返回抠图层 + 标准照 + 排版照，官方文档在 docs/api_CN.md。

3. Docker 一键部署

   docker-compose up -d
   

   仓库里带了 Dockerfile 和 docker-compose.yml，服务器上直接起就行。

十、总结：值得推荐吗？

我的答案：非常值得，建议收藏。

它不是完美的——需要懂一点 Python、第一次要下模型、Gradio 新版本还有个小兼容要处理。但考虑到：

• 🔥 零使用成本：开源免费，没有次数限制
• 🔒 绝对隐私：100% 本地，照片不外流
• 🛠️ 规格齐全：一寸到六寸排版全部覆盖
• ⚡ CPU 可跑：显卡不是必须，笔记本就能跑
• 🌱 社区活跃：GitHub 5k+ stars，ComfyUI 插件、微信小程序、前端网页版等社区扩展已经出现

这几项叠加起来，足以让 HivisionIDPhotos 成为「开发者 / 技术爱好者电脑里常备工具」的一员。

快速启动速查表（附在文末）

怕记不住？把这段截图存下来，下次照做就行：

# 1. 拉代码
git clone https://github.com/shenchuanchao/HivisionIDPhotos.git
cd HivisionIDPhotos

# 2. 装依赖
pip install -r requirements.txt
pip install -r requirements-app.txt

# 3. 下模型（建议 all，省得后面缺）
python scripts/download_model.py --models all

# 4. [可选] 如果你装了 Gradio 6.x，去掉 app.py 中 launch 的 show_api=False 一行

# 5. 启动
python app.py
# → 浏览器访问 http://127.0.0.1:7860

祝大家 证件照自由，底色自由，排版自由 🎉

如果你觉得这篇评测有用，欢迎去原作者仓库 Zeyi-Lin/HivisionIDPhotos 点个 Star，也欢迎在 shenchuanchao 的 fork 仓库 评论交流。