HivisionIDPhotos v1.3.1 介绍与选型指南

目标：本篇面向想把「AI 证件照制作」私有化到自家服务器的读者——无论是一次性应急、批量给员工/学生出照，还是把证件照能力以 API 形式集成进人事/校园系统。基于 HivisionIDPhotos 官方 GitHub 仓库、Releases、API 中文文档、Docker Hub 发行页与 shields.io 徽章的联网溯源（查询日期 2026-10-25），加上本站已在本地跑通的双服务实测产物（Web UI + API 全接口回显素材），讲清 HivisionIDPhotos 是什么、架构与功能边界如何、图像数据是否会离开你的机器，并与 Idify、rembg 及付费在线证件照服务做选型对比，帮助读者快速判断「HivisionIDPhotos 适不适合我」。逐步部署、配置与运维的完整实测内容见本专栏后续部署篇。

一、环境信息

本篇是「联网溯源 + 本地实测素材验证」型认知篇。文中全部事实均来自官方渠道与本地实测产物，来源与查询日期逐条标注：

• 查询日期：2026-10-25
• 官方仓库：https://github.com/Zeyi-Lin/HivisionIDPhotos （Apache-2.0 许可证）
• 官方 API 中文文档：仓库内 docs/api_CN.md
• 官方在线体验：SwanHub Demo、HuggingFace Spaces、ModelScope 三个平台均有官方 Demo（链接见文末参考）
• 官方 Docker 发行：linzeyi/hivision_idphotos（Docker Hub，发布 v1.3.1 版本）
• 社区热度取证方式：GitHub 星数通过 shields.io 徽章接口（img.shields.io/github/stars/...）取证，未直连 api.github.com 计数接口

当前官方渠道的版本信息（2026-10-25 实查，双源印证）：

💡 源码 release 与 Docker 发行版本号完全一致（均为 v1.3.1），不存在「仓库已更新、发行未跟进」的版本漂移问题。需要说明的是，该项目自 v1.3.1（2025-01-21）后未再发布新版本，属「功能完整、迭代放缓」型项目——对自托管用户反而是稳定性利好。

本站实测环境（部署篇将给出完整过程）：

二、软件概述

HivisionIDPhotos 是一款开源的 AI 证件照智能制作工具（Apache-2.0 协议，作者 Zeyi-Lin 及其 SwanLab 团队）。它用一套完善的 AI 模型工作流，实现「上传任意生活照 → 自动人像抠图 → 按规格生成标准证件照与六寸排版照」的完整链路，官方自述其能力为：轻量级抠图（纯离线，仅需 CPU 即可快速推理）、按不同尺寸规格生成标准证件照与六寸排版照、支持纯离线或端云推理、美颜，以及规划中的智能换正装。

它解决的是一个非常具体的痛点：证件照要么花钱拍、要么要把人脸照片上传到来路不明的在线服务。应急场景下（考试报名、签证材料、入职材料临门一脚），HivisionIDPhotos 让你用一张手机生活照 + 一台自己的服务器，几十秒内拿到带标准底色的证件照，且图像全程不经过第三方。

截至 2026-10-25，GitHub 星数 22k（shields.io 实查），是 AI 证件照细分领域社区热度最高的开源项目；项目最大的软实力之一是原生中文生态：中文 README、中文 API 文档、中文社区教程（群晖 NAS 部署教程、微信小程序衍生项目等），对中文用户的学习成本远低于同类海外项目。

一句话定位：如果你要的是「证件照能力在自己机器上、图像不出网、还能以 API 塞进自己业务系统」，HivisionIDPhotos 目前几乎没有对手；如果你只是偶尔手机上应急一次、不想搭任何服务，往下看第七章对比。

三、核心架构

HivisionIDPhotos 是「模型推理核心 + 双服务形态」的架构，代码为 Python，推理引擎基于 onnxruntime：

• 模型推理核心：hivision/creator 内封装「人像抠图 + 人脸检测 + 尺寸裁剪」流水线，全部模型为 ONNX 格式，默认 CPU 推理即可工作，无需 GPU。
• Web UI 服务（Gradio）：面向人的交互界面，源码入口 app.py。单个页面内完成上传、抠图模型/人脸检测模型选择、尺寸/底色/渲染模式、高级参数、美颜、水印、打印排版全部操作，支持中英文界面切换。
• API 服务（FastAPI）：面向系统的集成入口，源码入口 deploy_api.py，提供 7 个 REST 接口（见第四章），请求/响应均为 multipart/form-data 或 base64，方便任何语言对接。
• 两服务共用同一套模型与代码，仅启动方式不同——同一份官方发行可分别以两种命令拉起（本站实测即双服务并存）。

抠图模型族（官方 README 模型表 + 本地发行内权重文件清点双证，2026-10-25）：

人脸检测模型：mtcnn（默认，离线，CPU 毫秒级，精度较低）、retinaface-resnet50（离线，秒级，精度较高）、face_plusplus（旷视在线 API，精度高——唯一会把图像送出本机的选项）。

官方性能参考（README，测试环境 Mac M1 Max 64GB、无 GPU 加速）：

🔒 数据与隐私结论：官方明示抠图为「纯离线，仅需 CPU」推理；本地实测编排中无任何外部数据上报配置。据此可确认：默认模型链路下，图像数据全部在本机处理、不出网；唯一的例外是用户主动在 UI/API 中选择 face_plusplus 在线人脸检测模型——此时图像会上传至旷视的第三方接口。对隐私敏感场景，坚持默认模型组合即可。

四、功能特性

以下功能清单取自官方 README 与 API 文档（2026-10-25 查询），标注 （实测） 的条目同时经本站本地部署实测验证（回显素材齐全）：

• 标准证件照 + 高清证件照生成：输入一张 RGB 照片，输出标准照与高清照两张四通道透明 PNG（接口 idphoto，参数含 hd、dpi、face_alignment 等 15 项）（实测：run_idphoto.json 返回 status:true 与两组 base64 图，标准照/高清照均已落盘）。
• 背景替换：透明底图一键加底色，支持纯色/上红下白渐变/中心渐变三种渲染模式，内置常用底色列表，也支持自定义 RGB/HEX （实测：run_bg.json/run_bg.jpg，红底、蓝底、渐变均正常）。
• 六寸排版照：将单张证件照按印刷排版生成六寸相纸大图，支持六寸、五寸、A4、3R、4R 五种排版尺寸，可带裁剪线（接口 generate_layout_photos）（实测：run_layout.json/run_layout.jpg，六寸 300DPI 排版照生成正常）。另有「美式证件照」背景选项与社交媒体模板照插件（README 更新日志与发行内模板资源可见）。
• 自定义尺寸与 KB 控制：尺寸支持预设列表（一寸/二寸/各类签证等，CSV 可自行扩充）+ 自定义像素（px）+ 自定义毫米（mm）；文件体积可指定目标 KB 值（考试报名系统常见硬性要求），DPI 支持 72–600 （实测：run_setkb.json 指定 50KB 生成成功）。
• 水印：可平铺文字水印，支持文字/颜色/字号/透明度/角度/间距六项参数，适合给预览稿加防盗用标记 （实测：run_wm.json 返回 status:true，run_wm.jpg 水印平铺正常）。
• 人像抠图单独导出：可只做抠图、输出四通道透明 PNG，供其他图像流程复用（接口 human_matting）（实测：run_matting.json/run_matting.png）。
• 人脸旋转对齐：face_alignment 参数开启后对侧脸/歪头做旋转校正 （实测：run_align_align_true.json 与默认结果对比生成成功）。
• 美颜：美白、亮度、对比度、饱和度、锐化五项滑杆，Web UI 与 API 参数双端可用（v1.3.0 加入 API）。
• 异常路径：未检测到人脸、输入格式错误时接口返回 status:false 而非崩溃 （实测：err_noface.txt/err_crop_jpg.txt 两个错误场景均得到结构化响应）。
• UI 中英文双语：界面语言可切换，DEFAULT_LANG 环境变量可设默认语言 （实测：Web 首页与英文页均正常返回）。
• API 全家桶：idphoto、add_background、generate_layout_photos、human_matting、watermark、set_kb、idphoto_crop 共 7 个接口，官方提供 cURL 与 Python 请求示例 （实测：7 接口全部请求成功）。
• 社区生态：官方收录的衍生项目覆盖 ComfyUI 工作流、微信小程序（两种）、uniapp 多端、Windows 客户端、C++ 版本、群晖 NAS 部署教程——二开起点高。

五、快速开始（最小可用示例）

以下为官方 README 给出的两种启动方式（2026-10-25 查询自仓库首页；本站逐步实测回显见本专栏部署篇）：

方式一：源码运行（Python ≥ 3.7，官方主要测试 3.10）：

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          # 启动 Gradio Web UI（本地 7860 端口）
python deploy_api.py   # 启动 FastAPI 服务（本地 8080 端口）

方式二：官方 Docker 发行（发行名 linzeyi/hivision_idphotos，官方发布 v1.3.1 版本）：

docker pull linzeyi/hivision_idphotos

# 按官方仓库自带的编排文件，一并拉起 Web UI（7860）与 API（8080）两个服务
docker compose up -d

💡 官方 README 还给出了纯前端体验入口（SwanHub / HuggingFace Spaces / ModelScope 在线 Demo），零部署即可试用效果；但正式使用、尤其是对图像隐私有要求时，建议自托管。本站实测采用官方发行 v1.3.1 的双服务编排（Web UI 8138、API 8139），完整编排文件、参数与环境变量（FACE_PLUS_API_KEY、RUN_MODE=beast 野兽模式、DEFAULT_LANG 等）见部署篇。

六、适用场景与限制

适合：

• 隐私敏感的自助证件照：签证、考试报名、入职材料等场景，人脸照片不愿意交给在线服务——HivisionIDPhotos 默认链路全程本地处理（见第三章隐私结论）。
• 批量出照与系统集成：人事系统、校园系统、考试报名平台可通过 7 个 REST 接口批量生成证件照，KB/DPI/尺寸参数齐全，正好覆盖报名系统常见的硬性格式校验。
• 内网/离线环境：默认 CPU 推理 + 纯离线模型，无外网依赖即可工作，适合合规要求严格的内网。
• 二次开发：Apache-2.0 协议宽松，模型流水线代码清晰，社区已有小程序/客户端/ComfyUI 等多形态衍生项目可参考。

不适合 / 已知限制：

• 不做各国规格合规性背书：内置尺寸库（CSV）覆盖常见规格，但工具本身不校验输出是否符合目标机构（使馆、考试院等）的官方要求，关键用途请自行核对规格。
• 人像质量依赖原图：正面、光线均匀的照片效果最好；侧脸、逆光、多人合照会影响抠图与裁剪质量（人脸检测以「恰好一张人脸」为前提）。
• 无编辑器级精修：提供美白/亮度/对比度等轻量调参，没有磨皮、修阴影、换发型这类专业修图能力；「智能换正装」在 README 中仍是规划中（waiting）状态。
• 高精度模型资源门槛高：birefnet-v1-lite 需约 6.2GB 内存、秒级推理（README 数据），低配机器建议用默认 MODNet 组合。
• API 服务无鉴权设计：官方 API 文档与接口实现中未见任何认证机制，公网暴露存在被滥用风险，建议只在内网或反向代理 + 访问控制之后使用。

七、同类选型对比

以下对比中，HivisionIDPhotos、Idify、rembg 的星数与协议均为 2026-10-25 通过 shields.io 实查，付费在线证件照服务一列仅做定性对比（无公开可取证数据，不列数字）：

💡 表格解读：rembg 星数虽高，但它是「抠图引擎」而非「证件照工具」——用它做证件照要自己写裁剪、排版、KB 控制逻辑，适合当 HivisionIDPhotos 模型层的替代件；Idify 的「零部署」形态最轻，但无服务端意味着无法批量出照、无法集成进业务系统；付费在线服务胜在省事与精修，代价是隐私与按次收费。HivisionIDPhotos 的独占生态位是「隐私 + 完整证件照链路 + 可编程 API」三者兼得。

「如果…则…」选型建议：

• 如果你需要在自家服务器/内网批量生成证件照，或要把证件照能力集成进人事/校园/报名系统 → HivisionIDPhotos（API 形态几乎无同类对手）。
• 如果你只是偶尔在手机/电脑上应急一张、完全不想部署任何服务 → Idify（浏览器打开即用）或付费在线服务。
• 如果你在自建图像处理管线、只需要人像抠图这一个环节 → rembg（引擎级组件）。
• 如果对隐私有硬性要求又想要精修效果 → HivisionIDPhotos 出标准照 + 专业图像编辑器人工微调的组合。

八、参考链接

• HivisionIDPhotos 官方仓库：https://github.com/Zeyi-Lin/HivisionIDPhotos （查询日期 2026-10-25）
• Releases 页：https://github.com/Zeyi-Lin/HivisionIDPhotos/releases （最新 v1.3.1，2025-01-21 发布）
• Releases 订阅源：https://github.com/Zeyi-Lin/HivisionIDPhotos/releases.atom
• API 中文文档：https://github.com/Zeyi-Lin/HivisionIDPhotos/blob/main/docs/api_CN.md
• 官方在线 Demo（SwanHub）：https://swanhub.co/ZeYiLin/HivisionIDPhotos/demo
• 官方在线 Demo（HuggingFace Spaces）：https://huggingface.co/spaces/TheEeeeLin/HivisionIDPhotos
• 官方在线 Demo（ModelScope）：https://modelscope.cn/studios/SwanLab/HivisionIDPhotos
• Docker 发行页：https://hub.docker.com/r/linzeyi/hivision_idphotos （v1.3.1）
• 星数取证（shields.io）：https://img.shields.io/github/stars/Zeyi-Lin/HivisionIDPhotos.json （22k，查询日期 2026-10-25）
• Docker 版本取证（shields.io）：https://img.shields.io/docker/v/linzeyi/hivision_idphotos.json （v1.3.1，查询日期 2026-10-25）
• Idify 仓库：https://github.com/zhbhun/Idify ；星数取证 https://img.shields.io/github/stars/zhbhun/Idify.json （1.1k，2026-10-25）
• rembg 仓库：https://github.com/danielgatis/rembg ；星数取证 https://img.shields.io/github/stars/danielgatis/rembg.json （25k，2026-10-25）