共计 2458 个字符，预计需要花费 7 分钟才能阅读完成。
项目简介（做什么 / 为什么）
- 定位 ：轻量级 AI 证件照生成与抠图工具，支持 纯离线、CPU 即可，按各类规格生成标准证件照与六寸排版照，并提供美颜、背景色替换等功能；可本地 GUI 体验、命令行、Docker 与 API 部署。(GitHub)
- 近期特性：Gradio Demo 增加打印排版（A4/3R/4R/ 五寸等）、自定义 HEX 背景、美式证件照背景、DPI/ 对齐等；API 支持 base64 输入与美颜参数。(GitHub)
- 许可证：Apache-2.0。(GitHub)
- 在线试用：官方在 ModelScope 提供了在线体验 Studio（适合先感受流程再本地部署）。(GitHub)
一、环境准备
- 系统：Linux / Windows / macOS
- Python：≥ 3.7（主要测试 3.10）(GitHub)
# 1) 克隆代码
git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.git
cd HivisionIDPhotos
# 2) 安装依赖（建议在 Python 3.10 的虚拟环境中）pip install -r requirements.txt
pip install -r requirements-app.txt
# 3) 下载模型权重（推荐一键脚本）python scripts/download_model.py --models all
# 也可按 README 手动下载到 hivision/creator/weights/（含 MODNet、rmbg-1.4、birefnet-v1-lite 等）（模型与可选人脸检测模型 MTCNN/RetinaFace/Face++ 的放置路径与说明，见 README“准备工作”。）(GitHub)
GPU 加速（可选）：
birefnet-v1-lite模型可用 NVIDIA GPU 加速，需约 16GB 显存，并按说明安装onnxruntime-gpu/（可选）torch对应 CUDA 版本。(GitHub)
二、本地 GUI（Gradio）一键跑通
python app.py
# 浏览器访问 http://127.0.0.1:7860 即可操作
（GUI 默认支持底色切换、尺寸选择、打印排版、DPI 等；README“⚡️运行 Gradio Demo”与“最近更新”有细节。）(GitHub)
三、命令行批处理（Python 推理）
常用任务与示例（更多参数见 python inference.py --help）：
# 1) 证件照制作（输出一张标准证件照 + 一张高清透明 PNG）python inference.py -i demo/images/test0.jpg -o ./idphoto.png --height 413 --width 295
# 2) 人像抠图（得透明 PNG）python inference.py -t human_matting -i demo/images/test0.jpg -o ./idphoto_matting.png --matting_model hivision_modnet
# 3) 给透明图加底色（-c 可用 HEX；-k 背景强度；-r 抗锯齿半径等）python inference.py -t add_background -i ./idphoto.png -o ./idphoto_ab.jpg -c 4f83ce -k 30 -r 1
# 4) 生成六寸排版照（可与冲印对接）python inference.py -t generate_layout_photos -i ./idphoto_ab.jpg -o ./idphoto_layout.jpg --height 413 --width 295 -k 200
# 5) 已抠图成品的证件照裁剪
python inference.py -t idphoto_crop -i ./idphoto_matting.png -o ./idphoto_crop.png --height 413 --width 295
（以上命令与参数来自官方 README“Python 推理”。）(GitHub)
四、Docker 快速部署
# 1) 拉取镜像（或在仓库根目录按 README 构建 /compose）docker pull linzeyi/hivision_idphotos
# 2) 运行本地 GUI（Gradio）docker run -d -p 7860:7860 linzeyi/hivision_idphotos
# 3) 运行 API 后端
docker run -d -p 8080:8080 linzeyi/hivision_idphotos python3 deploy_api.py
# 4) 两者同时（在仓库目录）docker compose up -d
（镜像名、端口与 compose 用法见 README“Docker 部署”。）(GitHub)
也可参考社区实战的 Docker 部署文章（以 Linux 为例）。(博客园)
五、API 部署与调用
# 启动后端
python deploy_api.py
API 提供 cURL / Python 示例与参数（含 美颜、dpi、face_alignment、base64 输入 等），详见项目 API 中文文档。(GitHub)
六、社区扩展（可选）
- Windows 桌面版（解压即用）：基于官方项目的 GUI 封装，适合不想装环境的用户（含下载链接 / 演示）。(GitHub)
- NAS 部署（群晖）：社区提供了图文教程。(GitHub)
- Web 前端示例：基于官方 API 的网页端源码，可自建替换为自己的后端。(GitHub)
七、实践小贴士
- 路径 / 文件名 ：建议将项目与输入图片放在 不含空格与中文 的路径，避免依赖解析异常（Windows 尤其）。
- 模型体积与内存：
birefnet-v1-lite更精准但占用更大；CPU 轻量场景可先试MODNet + MTCNN组合；README 给出了 CPU 性能参考。(GitHub) - DPI/ 打印：近期更新已默认支持 300 DPI、打印排版（五寸 /A4 等）；冲印与报名常见参数可直接在 GUI/CLI 指定。(GitHub)
- 隐私 ：如涉 身份证 / 护照 等敏感照片，建议 本地离线 处理，避免上传第三方站点（官方支持完全离线流程）。(GitHub)
正文完
