部署一個開源的證件照系統

以下數據來自官方網站,記錄下來,方便自己

項目簡介

🚀 謝謝你對我們的工作感興趣。您可能還想查看我們在圖像領域的其他成果，歡迎來信:zeyi.lin@swanhub.co.

HivisionIDPhoto 旨在開發一種實用、系統性的證件照智能制作算法。

它利用一套完善的AI模型工作流程，實現對多種用戶拍照場景的識別、摳圖與證件照生成。

HivisionIDPhoto 可以做到：

輕量級摳圖（純離線，僅需?CPU?即可快速推理）
根據不同尺寸規格生成不同的標準證件照、六寸排版照
支持純離線或端云推理
美顏
智能換正裝（waiting）

?編輯

如果 HivisionIDPhoto 對你有幫助，請 star 這個 repo 或推薦給你的朋友，解決證件照應急制作問題！

🏠 社區

我們分享了一些由社區構建的HivisionIDPhotos的有趣應用和擴展：

HivisionIDPhotos-ComfyUI	HivisionIDPhotos-wechat-weapp
?編輯	?編輯
ComfyUI證件照處理工作流	證件照微信小程序（JAVA后端+原生前端）

HivisionIDPhotos-Uniapp	HivisionIDPhotos-web
?編輯	?編輯
證件照微信小程序（uniapp）	證件照應用網頁版

HivisionIDPhotos-cpp: HivisionIDphotos C++版本，由?zjkhahah?構建
ai-idphoto:?HivisionIDPhotos-wechat-weapp?的uniapp多端兼容版，由?wmlcjj?貢獻
HivisionIDPhotos-uniapp-WeChat-gpto1: 由gpt-o1輔助完成開發的證件照微信小程序，由?jkm199?貢獻
HivisionIDPhotos-windows-GUI：Windows客戶端應用，由?zhaoyun0071?構建
HivisionIDPhotos-NAS: 群暉NAS部署中文教程，由?ONG-Leo?貢獻

🔧 準備工作

環境安裝與依賴：

Python >= 3.7（項目主要測試在 python 3.10）
OS: Linux, Windows, MacOS

1. 克隆項目

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

2. 安裝依賴環境

建議 conda 創建一個 python3.10 虛擬環境后，執行以下命令

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

3. 下載人像摳圖模型權重文件

方式一：腳本下載

python scripts/download_model.py --models all
# 如需指定下載某個模型
# python scripts/download_model.py --models modnet_photographic_portrait_matting

方式二：直接下載

模型均存到項目的hivision/creator/weights目錄下：

人像摳圖模型	介紹	下載
MODNet	MODNet官方權重	下載(24.7MB)
hivision_modnet	對純色換底適配性更好的摳圖模型	下載(24.7MB)
rmbg-1.4	BRIA AI?開源的摳圖模型	下載(176.2MB)后重命名為`rmbg-1.4.onnx`
birefnet-v1-lite	ZhengPeng7?開源的摳圖模型，擁有最好的分割精度	下載(224MB)后重命名為`birefnet-v1-lite.onnx`

如果下載網速不順利：前往SwanHub下載。

4. 人臉檢測模型配置（可選）

拓展人臉檢測模型	介紹	使用文檔
MTCNN	離線人臉檢測模型，高性能CPU推理（毫秒級），為默認模型，檢測精度較低	Clone此項目后直接使用
RetinaFace	離線人臉檢測模型，CPU推理速度中等（秒級），精度較高	下載后放到`hivision/creator/retinaface/weights`目錄下
Face++	曠視推出的在線人臉檢測API，檢測精度較高，官方文檔	使用文檔

5. 性能參考

測試環境為Mac M1 Max 64GB，非GPU加速，測試圖片分辨率為 512x715(1) 與 764×1146(2)。

模型組合	內存占用	推理時長(1)	推理時長(2)
MODNet + mtcnn	410MB	0.207s	0.246s
MODNet + retinaface	405MB	0.571s	0.971s
birefnet-v1-lite + retinaface	6.20GB	7.063s	7.128s

6. GPU推理加速（可選）

在當前版本，可被英偉達GPU加速的模型為birefnet-v1-lite，并請確保你有16GB左右的顯存。

如需使用英偉達GPU加速推理，在確保你已經安裝CUDA與cuDNN后，根據onnxruntime-gpu文檔找到對應的onnxruntime-gpu版本安裝，以及根據pytorch官網找到對應的torch版本安裝。

# 假如你的電腦安裝的是CUDA 12.x, cuDNN 8
# 安裝torch是可選的，如果你始終配置不好cuDNN，那么試試安裝torch
pip install onnxruntime-gpu==1.18.0
pip install torch --index-url https://download.pytorch.org/whl/cu121

完成安裝后，調用birefnet-v1-lite模型即可利用GPU加速推理。

TIPS: CUDA 支持向下兼容。比如你的 CUDA 版本為 12.6，torch?官方目前支持的最高版本為 12.4（<12.6），torch仍可以正常使用CUDA。

?? 運行 Gradio Demo

python app.py

運行程序將生成一個本地 Web 頁面，在頁面中可完成證件照的操作與交互。

?編輯

🚀 Python 推理

核心參數：

-i: 輸入圖像路徑
-o: 保存圖像路徑
-t: 推理類型，有idphoto、human_matting、add_background、generate_layout_photos可選
--matting_model: 人像摳圖模型權重選擇
--face_detect_model: 人臉檢測模型選擇

更多參數可通過python inference.py --help查看

1. 證件照制作

輸入 1 張照片，獲得 1 張標準證件照和 1 張高清證件照的 4 通道透明 png

python inference.py -i demo/images/test0.jpg -o ./idphoto.png --height 413 --width 295

2. 人像摳圖

輸入 1 張照片，獲得 1張 4 通道透明 png

python inference.py -t human_matting -i demo/images/test0.jpg -o ./idphoto_matting.png --matting_model hivision_modnet

3. 透明圖增加底色

輸入 1 張 4 通道透明 png，獲得 1 張增加了底色的 3通道圖像

python inference.py -t add_background -i ./idphoto.png -o ./idphoto_ab.jpg  -c 4f83ce -k 30 -r 1

4. 得到六寸排版照

輸入 1 張 3 通道照片，獲得 1 張六寸排版照

python inference.py -t generate_layout_photos -i ./idphoto_ab.jpg -o ./idphoto_layout.jpg  --height 413 --width 295 -k 200

5. 證件照裁剪

輸入 1 張 4 通道照片（摳圖好的圖像），獲得 1 張標準證件照和 1 張高清證件照的 4 通道透明 png

python inference.py -t idphoto_crop -i ./idphoto_matting.png -o ./idphoto_crop.png --height 413 --width 295

?? 部署 API 服務

啟動后端

python deploy_api.py

請求 API 服務

詳細請求方式請參考?API 文檔，包含以下請求示例：

cURL
Python

🐳 Docker 部署

1. 拉取或構建鏡像

以下方式三選一

方式一：拉取最新鏡像：

docker pull linzeyi/hivision_idphotos

方式二：Dockrfile 直接構建鏡像：

在確保將至少一個摳圖模型權重文件放到hivision/creator/weights下后，在項目根目錄執行：

docker build -t linzeyi/hivision_idphotos .

方式三：Docker compose 構建：

在確保將至少一個摳圖模型權重文件放到hivision/creator/weights下后，在項目根目錄下執行：

docker compose build

2. 運行服務

啟動 Gradio Demo 服務

運行下面的命令，在你的本地訪問?http://127.0.0.1:7860?即可使用。

docker run -d -p 7860:7860 linzeyi/hivision_idphotos

啟動 API 后端服務

docker run -d -p 8080:8080 linzeyi/hivision_idphotos python3 deploy_api.py

兩個服務同時啟動

docker compose up -d

環境變量

本項目提供了一些額外的配置項，使用環境變量進行設置：

環境變量	類型	描述	示例
FACE_PLUS_API_KEY	可選	這是你在 Face++ 控制臺申請的 API 密鑰	`7-fZStDJ····`
FACE_PLUS_API_SECRET	可選	Face++ API密鑰對應的Secret	`VTee824E····`
RUN_MODE	可選	運行模式，可選值為`beast`(野獸模式)。野獸模式下人臉檢測和摳圖模型將不釋放內存，從而獲得更快的二次推理速度。建議內存16GB以上嘗試。	`beast`
DEFAULT_LANG	可選	Gradio Demo啟動時的默認語言	`en`

docker使用環境變量示例：

docker run  -d -p 7860:7860 \-e FACE_PLUS_API_KEY=7-fZStDJ···· \-e FACE_PLUS_API_SECRET=VTee824E···· \-e RUN_MODE=beast \-e DEFAULT_LANG=en \linzeyi/hivision_idphotos

FAQ

1. 如何修改預設尺寸和顏色？

尺寸：修改size_list_CN.csv后再次運行?app.py?即可，其中第一列為尺寸名，第二列為高度，第三列為寬度。
顏色：修改color_list_CN.csv后再次運行?app.py?即可，其中第一列為顏色名，第二列為Hex值。

2. 如何修改水印字體？

將字體文件放到hivision/plugin/font文件夾下
修改hivision/plugin/watermark.py的font_file參數值為字體文件名

3. 如何添加社交媒體模板照？

將模板圖片放到hivision/plugin/template/assets文件夾下。模板圖片是一個4通道的透明png。
在hivision/plugin/template/assets/template_config.json文件中添加最新的模板信息，其中width為模板圖寬度(px)，height為模板圖高度(px)，anchor_points為模板中透明區域的四個角的坐標(px)；rotation為透明區域相對于垂直方向的旋轉角度，>0為逆時針，<0為順時針。
在demo/processor.py的_generate_image_template函數中的TEMPLATE_NAME_LIST變量添加最新的模板名

?編輯