小黃老師嘿技術

1. HivisionIDPhotos 是什麼？

如果你曾經為了大頭照、履歷照、員工證照片、學生證照片、考試報名照片跑去照相館，應該會很懂那種感覺：只是想要一張白底或藍底證件照，卻要喬時間、排隊、等修圖、再拿檔案。現在很多人會想用手機拍一張，再找線上去背網站處理，但問題也跟著來了：照片會不會被上傳到不明伺服器？尺寸能不能符合需求？背景色準不準？能不能一次產生排版照？

HivisionIDPhotos 就是為了解決這類需求而出現的開源工具。它的定位很明確：不是拿 AI 憑空生成一張陌生人照片，而是把你提供的真實照片整理成符合證件照規格的圖片。它會做的事情包括人臉偵測、人像去背、照片裁切、換背景色、輸出透明 PNG、產生標準尺寸照片，以及進一步產生可列印的排版照。

用更生活化的方式說，你可以把它想成一間裝在你電腦裡的小型 AI 照相館。你把照片交給它，它先找出臉在哪裡，再把人從背景裡切出來，接著依照你指定的尺寸裁切，最後換上白底、藍底、紅底或自訂色。對一般使用者來說，它可以幫你快速做照片；對開發者來說，它更像是一組可以被網站、App、內部系統呼叫的證件照處理引擎。

2. 它到底有沒有用 AI？

有，而且是很實用的電腦視覺 AI。不過這裡的 AI 不是像 ChatGPT 這種聊天型 AI，也不是 Stable Diffusion 那種「輸入文字後生成圖片」的 AI。HivisionIDPhotos 主要使用的是「看得懂圖片輪廓、臉部位置與人像邊界」的模型。這類 AI 的任務不是寫文章，而是判斷哪裡是人、哪裡是背景、臉在哪個位置、頭部比例應該怎麼放。

它主要會碰到兩類模型。第一類是人像去背或人像分割模型，例如 MODNet、hivision_modnet、RMBG、BiRefNet 這類模型。它們的工作是把人物和背景分開，輸出像素級的透明遮罩。第二類是人臉偵測模型，例如 MTCNN、RetinaFace，或是可串接的 Face++ 線上服務。這些模型會協助系統知道照片中的臉在哪裡，進而判斷裁切位置是否合理。

這裡有一個非常重要的觀念：證件照 AI 不應該亂改你的長相。好的證件照處理工具重點是「保留真實人像，修正背景與規格」，而不是把你變成另一個人。所以 HivisionIDPhotos 比較像是 AI 修圖與規格化工具，不是 AI 換臉或 AI 生成人像工具。

3. 安裝前需要準備什麼？

如果你是第一次接觸 GitHub 開源專案，先不要被一堆指令嚇到。你只需要知道三件事：第一，GitHub 是放程式碼的地方；第二，Python 是執行這個工具需要的語言；第三，AI 模型權重是這個工具的大腦資料，沒有下載模型，就像裝了相機 App 卻沒有鏡頭一樣，功能會不完整。

建議的基本環境是 Windows 10/11、macOS 或 Linux；Python 建議使用 3.10；記憶體建議至少 8GB，如果能有 16GB 會更舒服。顯示卡不是絕對必要，因為輕量模型可以用 CPU 跑。不過如果你要使用較重的模型，或希望處理速度更快，NVIDIA GPU 會有幫助。對多數新手來說，第一步不要追求最快，先用預設或輕量模型跑成功，比較重要。

你可以選擇兩種安裝路線。一種是 Python 本機安裝，適合想學會細節、之後要開發整合的人。另一種是 Docker 安裝，適合想快速部署、避免 Python 套件衝突的人。如果你完全不知道 Docker 是什麼，可以先用 Python 方式；如果你已經在 NAS、雲端主機、Linux 伺服器上部署過服務，Docker 會更乾淨。

4. Python 安裝與網頁版啟動

這一段我們用最普通、最容易理解的方式安裝。請先安裝 Git、Python 3.10，並建議安裝 Miniconda 或 Anaconda。Conda 的好處是可以幫你建立獨立環境，避免你今天安裝 HivisionIDPhotos，明天又安裝別的工具，結果套件版本打架。

首先打開終端機。Windows 可以用 PowerShell 或 Anaconda Prompt；macOS 可以用「終端機」。接著輸入以下指令，把專案從 GitHub 下載到你的電腦：

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

接著建立一個叫做 hivision 的 Python 環境：

conda create -n hivision python=3.10 -y
conda activate hivision

然後安裝專案需要的套件：

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

再來是很關鍵的一步：下載 AI 模型權重。你可以先全部下載，最省心：

python scripts/download_model.py --models all

如果你只是想先跑起來，也可以只下載其中一個輕量模型，例如 MODNet。模型檔通常會放在專案的 weights 相關資料夾內。這些模型就是 HivisionIDPhotos 做人像去背、邊緣判斷與輸出透明背景時會用到的核心資料。

最後啟動網頁介面：

python app.py

成功後，你通常會看到一個本機網址，例如 http://127.0.0.1:7860。打開瀏覽器進去，就會看到可以上傳照片的介面。對 0 程度使用者來說，這是最推薦的第一站：先不要急著碰 API，也不要急著研究模型參數，先做出第一張證件照，建立信心最重要。

5. Docker 部署與 API 啟動

如果你不想處理 Python 套件，Docker 是另一條很舒服的路。你可以把 Docker 想成「把程式、環境、依賴套件包成一個盒子」。只要你的電腦或伺服器能跑 Docker，就可以比較穩定地啟動服務。這對 NAS、Linux 伺服器、公司內部主機或雲端 VM 特別實用。

如果只是要啟動網頁版，可以使用 Docker 映像檔：

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

接著打開 http://127.0.0.1:7860，就能進到網頁介面。如果你是想讓其他系統呼叫它，就要啟動 API 後端：

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

這樣 API 就會開在 http://127.0.0.1:8080。如果你在伺服器上部署，記得檢查防火牆、反向代理、HTTPS、上傳檔案大小限制與權限控管。證件照通常涉及個資與臉部照片，不建議隨便開成公開服務，除非你已經做好登入、限制、刪檔與安全控管。

6. 它的運作流程白話拆解

很多新手會以為 AI 證件照就是「上傳照片，AI 變魔術」。其實背後是一段很有邏輯的流程。第一步是讀取照片，這張照片可能是手機拍的，也可能是相機拍的。建議照片要正面、清楚、不要多人入鏡、不要有太誇張的濾鏡，背景雜亂沒關係，因為後面會去背，但人臉和頭髮邊緣要盡量清楚。

第二步是人臉偵測。系統會找出臉的位置，確認頭部大概在哪裡。證件照不是只要把人切出來就好，還要讓頭部比例、頭頂距離、臉部中心都在合理位置。這就是為什麼人臉偵測很重要。

第三步是人像去背。這時候人像分割模型會判斷哪些像素屬於人物、哪些像素屬於背景。理想狀態下，頭髮邊緣、肩膀、衣服輪廓都會被保留下來，背景則變成透明。這也是整個工具最像「AI 魔法」的地方。

第四步是裁切成指定尺寸。你可以指定高與寬，例如常見的證件照尺寸比例。系統會根據臉部位置、頭部比例與你設定的參數進行裁切。第五步是換背景。因為透明背景已經準備好了，所以要換成白底、藍底、紅底或 Tiffany 藍都很快。最後一步則是輸出成品或排版照，例如單張照片、六寸排版、A4 排版，方便後續列印。

7. API 怎麼用？

HivisionIDPhotos 對開發者很有吸引力的地方，就是它不只提供網頁操作，也能啟動 API。API 的意思是：你不一定要手動開網頁上傳，而是可以讓自己的程式把照片送過去，等它處理完再拿回結果。這樣就能把它接到網站、App、LINE Bot、公司內部系統、n8n 自動化流程，甚至是照相館的工作站。

啟動 API 的方式很簡單：

python deploy_api.py

主要常見端點可以這樣理解：/idphoto 負責產生透明背景的證件照；/add_background 負責把透明圖合成指定背景色；/generate_layout_photos 負責產生排版照；/human_matting 則可以單純做人像去背。

例如你可以用 cURL 測試產生證件照：

curl -X POST "http://127.0.0.1:8080/idphoto" -F "input_image=@demo/images/test0.jpg" -F "height=413" -F "width=295" -F "human_matting_model=modnet_photographic_portrait_matting" -F "face_detect_model=mtcnn" -F "hd=true" -F "dpi=300"

這段指令的意思是：把 demo/images/test0.jpg 這張照片上傳到本機 API，請它輸出高 413、寬 295、DPI 300 的證件照，並指定使用 MODNet 做人像去背、MTCNN 做人臉偵測。新手剛開始可以先照抄，等成功後再慢慢改尺寸與模型。

如果你已經拿到透明背景圖，想加上藍底，可以呼叫背景合成 API：

curl -X POST "http://127.0.0.1:8080/add_background" -F "input_image=@test.png" -F "color=638cce" -F "kb=200" -F "render=0" -F "dpi=300"

這裡的 color=638cce 是背景色碼。你想做白底就換成白色，想做紅底或 Tiffany 藍，也可以換成其他 HEX 色碼。當你理解這個概念後，就會發現它非常適合做成一個可客製化的線上工具。

8. Ollama、oMLX、ComfyUI 能不能接？

這題很多人會問，而且非常值得拆開講。先講結論：HivisionIDPhotos 本身就可以用本機 AI 模型處理證件照；但 Ollama 或 oMLX 不適合直接取代它內部的人像去背模型。它們比較適合放在外圍，做照片檢查、需求理解、聊天式控制、流程判斷。ComfyUI 則比較適合用節點式工作流整合影像處理流程。

Ollama 常被拿來在本機跑大型語言模型，也支援部分視覺語言模型。它可以看圖並用文字回答，例如「照片裡是不是只有一個人」、「背景會不會太亂」、「光線是不是偏暗」。但它通常不會直接輸出像素級透明 PNG，也不是專門做人像 alpha matting 的工具。換句話說，Ollama 很會「看圖說話」，但 HivisionIDPhotos 需要的是「看圖後切出精準人像」。這是兩種不同任務。

oMLX 也是偏向本機 LLM / VLM 推理服務，特別適合 Apple Silicon 使用者探索本地模型推理。它可以做語言理解、視覺問答、OCR 或類似 OpenAI API 的應用，但同樣不等於能直接取代 MODNet、RMBG、BiRefNet 這類人像去背模型。

比較聰明的做法是把 Ollama 或 oMLX 放在 HivisionIDPhotos 前面。舉例來說，使用者上傳照片後，先讓本機視覺模型檢查照片品質：是不是正面？是不是多人？有沒有戴帽子？光線夠不夠？如果檢查通過，再把照片送到 HivisionIDPhotos 做正式處理。如果檢查不通過，就回覆使用者：「這張照片光線偏暗，建議重拍」或「畫面中有多人，請裁切成單人照片」。

如果你已經在使用 ComfyUI，那方向又不一樣。ComfyUI 是節點式圖片工作流工具，適合把不同影像處理步驟串起來。社群也有與 HivisionIDPhotos 相關的 ComfyUI custom node，可以把證件照處理放進節點流程。這對已經熟悉 ComfyUI 的創作者或工程師很方便，但對完全新手來說，建議先從原本的網頁版開始，等理解流程後再進 ComfyUI。

9. 實際應用場景與新手路線

如果你只是個人使用，最簡單的場景就是臨時需要一張白底或藍底照片。你可以用手機靠窗拍一張清楚正面照，丟進 HivisionIDPhotos 網頁版，輸出後再檢查尺寸與背景。這比隨便找線上工具更安心，因為你可以把流程放在自己的電腦裡跑。

如果你是公司內部行政、人資或資訊人員，HivisionIDPhotos 可以拿來統一員工頭像。員工上傳原始照片後，系統自動去背、裁切、換成統一白底或品牌色背景，再輸出成內部系統需要的尺寸。這樣員工證、Slack 頭像、內網帳號照片都可以維持一致風格。

如果你是照相館或影像工作室，它也可以成為半自動化工具。攝影師拍完後，把照片丟進本地 API，快速得到初版去背、背景與排版照，再由人工進行細修。這樣可以節省大量重複性操作，也比較不會犧牲品質。

如果你是開發者，最有趣的是把它做成一個微服務。你的前端網站負責上傳照片和選擇尺寸，後端把照片送到 HivisionIDPhotos API，拿到結果後再回傳給使用者。你甚至可以在前面加上 Ollama 或 oMLX 做智慧檢查，讓使用者在送出前就知道照片是否適合。

10. 常見問題與免責聲明

Q：完全不會寫程式也能用嗎？
可以，建議從網頁版開始。只要安裝好環境並執行 python app.py，就能用瀏覽器上傳照片操作。不過第一次安裝仍會碰到終端機指令，所以建議照著步驟慢慢做，不要一次改太多東西。

Q：它可以完全離線嗎？
核心的人像去背與人臉偵測可以使用本機模型，但你需要先下載模型權重。若你選擇 Face++ 這類線上人臉偵測服務，就會需要外部 API。想要隱私性高，建議使用本機模型路線。

Q：Ollama 可以直接幫我去背嗎？
一般情況下不建議這樣設計。Ollama 適合做文字理解、看圖問答、照片品質判斷；HivisionIDPhotos 適合做真正的去背、裁切、換背景與輸出。兩者搭配會比硬要互相取代更合理。

Q：ComfyUI 版適合新手嗎？
如果你已經熟悉 ComfyUI，很值得研究；如果你是完全新手，先用 HivisionIDPhotos 原本的網頁版，會比較快建立概念。

Q：可以拿來做正式證件嗎？
技術上可以產生符合指定尺寸與背景的照片，但正式文件通常會有很細的規範，例如頭部比例、眼鏡、瀏海、陰影、背景、解析度、檔案大小等。最保險的方式是先確認申請單位最新要求，再用工具輸出並人工檢查。

總結來說，HivisionIDPhotos 是一套很適合本機部署的 AI 證件照工具。新手可以用網頁版快速做照片；開發者可以用 API 串接自己的服務；進階玩家可以搭配 Ollama、oMLX 或 ComfyUI 做更完整的自動化流程。真正的關鍵不是把所有 AI 混在一起，而是讓每個工具做它最擅長的事：語言模型負責理解需求，影像模型負責處理照片，工作流工具負責把流程串起來。