HivisionIDPhotos：一句话生成标准证件照，自托管的 AI 证件照工具

先说结论

如果你做的是「证件照生成」这类单一功能，HivisionIDPhotos 是目前少见的、能真正自托管跑起来并且出片可用的开源方案。它不需要 GPU，8 核 CPU 上单张标准照 2 秒内出图，Docker 一把梭就能上线。但它是专有 REST API，不是 OpenAI 兼容服务——想直接接到现有 LLM 网关上是接不通的，得自己包一层。每月出图量低于 3000～4000 张，别折腾自建，直接买云端 API 更便宜。

下面是我在本地完整部署 + 压测的记录。仓库：Zeyi-Lin/HivisionIDPhotos，Apache 2.0，Python 实现，当前 21.6k star / 2.5k fork，最近提交 2026-07-03，维护节奏正常。

部署过程

Step 1：环境确认

# 测试机：阿里云 ecs.g7，8 vCPU / 16 GB / Ubuntu 22.04，无 GPU
$ python3 -V
Python 3.10.12
$ nvidia-smi
-bash: nvidia-smi: command not found   # 纯 CPU 压测，不依赖 CUDA

Step 2：拉代码装依赖

$ git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.git
$ cd HivisionIDPhotos
$ python3 -m venv .venv && source .venv/bin/activate
$ pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 实测：耗时 2 分 41 秒，venv 体积 1.6 GB
# 主要重量来自 onnxruntime / opencv-python / gradio / fastapi

Step 3：模型权重

权重不随仓库分发。首次调用时会自动拉取（也可手动执行下载脚本），落在 hivision/creator/weights/。

# 合计约 260 MB（人脸检测 retinaface/mtcnn + 抠图 modnet）
# 实测下载耗时 38 秒，内网缓存后基本无感
$ du -sh hivision/creator/weights/
260M    hivision/creator/weights/

Step 4：启动 API 服务

$ python3 deploy_api.py -p 8080 -H 0.0.0.0

INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
# 进程启动 → 就绪：7.5 秒，其中模型加载占 5.2 秒
# 冷启动首请求额外 +0.4 秒

Step 5：冒烟测试

$ curl -X POST "http://127.0.0.1:8080/idphoto" \
    -F "input_image=@test.jpg" \
    -F "height=413" -F "width=295" \
    -F "human_matting_model=hivision_modnet" \
    -F "face_detect_model=mtcnn" -F "hd=true" \
    -o out.json
# 返回 base64 的标准照 / 高清照 / 六寸排版照，本次耗时 1.9 s
# 另有 WebUI：python3 app.py → :7860，手机浏览器也能用

兼容性实测

结论先说：它和 OpenAI 生态完全不兼容，别抱期待。它提供的是自己的 FastAPI 接口，好在有自动生成的 OpenAPI 文档，接起来不难。

性能基准

测试环境：8 vCPU / 16 GB / Ubuntu 22.04 / 纯 CPU，输入为 3000×4000 手机人像照，输出 DPI 300。每项 200 次请求取分位值。

瓶颈明确在抠图模型的前向推理。并发从 4 加到 8，吞吐只涨 18%，延迟翻倍——8 核机器上并发开到 4 就是甜点，再往上纯粹是排队。GPU 版本本次没测，社区反馈单张可压到 0.5 s 量级，仅作量级参考。

资源占用分析

CPU

空闲几乎为 0；单请求推理期间会吃满约 700%（onnxruntime 默认按物理核数开 intra-op 线程）。如果和别的服务混部，建议用 OMP_NUM_THREADS 限制，否则会把同机其他进程饿死。

内存

模型加载完成、空闲 RSS 820 MB；并发 8 压测峰值 RSS 1.9 GB。没有明显内存泄漏，压测 3 小时后回落到 870 MB。4 GB 内存能跑，但留不出系统页缓存，建议 8 GB 起。

磁盘

仓库 40 MB + venv 1.6 GB + 权重 260 MB ≈ 2 GB，Docker 镜像 2.9 GB。图片不落盘（接口直接返 base64），所以业务盘需求很小，20 GB 足够。

配置建议

2C4G：能跑，单张 6～8 s，个人偶尔用可以，别做服务。
4C8G：单张 2.5～3 s，个人/小团队最舒服的档位。
8C16G：并发 4 稳定输出，可以对外提供 API。
加一张 T4 / 3060：量级提升明显，但属于另一个部署路径，需要自己改推理后端。

成本对比

注意这张表没算隐私收益——对很多人来说那才是自建的真正理由。

结论

适合自建的场景：证件照是产品内的固定功能、月出图量 4000 张以上；人像照片不能出内网（政务、医疗、HR 系统、校园）；需要定制规格（各国签证尺寸、DPI、排版张数）或想改抠图模型。这些场景下，HivisionIDPhotos 的 Apache 2.0 许可和纯 CPU 可跑这两点很实在。

别折腾的场景：月出图量几百张、只是偶尔给同事做张简历照——4C8G 一台机器的钱够你买几千张云端 API，还省掉模型更新和调参。另外如果你的架构是围绕 OpenAI 兼容接口搭的，这个项目接不进去，得先写一层适配服务，把成本算进去再决定。