PhotoMaker 保姆级部署教程：上传一张人像照片，秒级生成保持 ID 一致性的真人写真

本文所有命令与配置均照搬 PhotoMaker 官方仓库 README（github.com/TencentARC/PhotoMaker，main 分支）与官方模型卡（huggingface.co/TencentARC/PhotoMaker），未作任何改动与发挥。信息核验日期：2026-11-01。

一、项目介绍

PhotoMaker 是腾讯 ARC 实验室（Tencent ARC Lab）联合南开大学 MCG-NKU 团队开源的人脸定制图像生成项目，论文《PhotoMaker: Customizing Realistic Human Photos via Stacked ID Embedding》已被 CVPR 2024 收录。官方 README 对其定位是：通过"堆叠 ID 嵌入（Stacked ID Embedding）"技术，在数秒内完成真人照片定制，无需额外 LoRA 训练，即可在保持高 ID 保真度的同时，提供文本可控、多样且高质量的生成结果。

项目提供 V1 与 V2 两个版本：V2（2024-07-22 发布）进一步提升了 ID 保真度，并保持了 V1 的生成质量、可编辑性以及与 ControlNet、T2I-Adapter、IP-Adapter、LoRA 等插件的兼容性。它既可以作为独立的 diffusers Pipeline 使用，也可以作为 Adapter 与其他 SDXL 基座模型配合。项目在 GitHub（TencentARC/PhotoMaker）持续活跃维护，官方同时在 Hugging Face 上提供在线 Demo（PhotoMaker、PhotoMaker-Style、PhotoMaker-V2）与模型权重下载。

二、功能拆解

按官方 README「Key Features」与「Examples」一节，PhotoMaker 核心能力如下：

功能	说明
秒级人像定制	数秒内生成，无需为每个人单独训练 LoRA
高 ID 保真	通过堆叠 ID 嵌入，多参考图联合约束身份一致性
文本可控	通过 prompt 自由控制服装、场景、姿态、风格
作为 Adapter	可与社区 LoRA 模块、ControlNet、T2I-Adapter、IP-Adapter 组合使用
写实 / 风格化双模式	写实写真走默认基座；风格化切换风格化基座并叠加对应 LoRA
diffusers 原生 Pipeline	提供 `PhotoMakerStableDiffusionXLPipeline`，可像使用 diffusers 一样调用
Gradio 本地 Demo	一行命令启动本地 Web 界面，上传参考图 + 输入 prompt 即可生成

三、官方/GitHub 链接

GitHub 仓库：https://github.com/TencentARC/PhotoMaker
项目主页（论文/演示视频）：https://photo-maker.github.io
论文页：https://huggingface.co/papers/2312.04461
模型权重（Hugging Face）：https://huggingface.co/TencentARC/PhotoMaker
在线 Demo（写实）：https://huggingface.co/spaces/TencentARC/PhotoMaker
在线 Demo（V2）：https://huggingface.co/spaces/TencentARC/PhotoMaker-V2
在线 Demo（风格化）：https://huggingface.co/spaces/TencentARC/PhotoMaker-Style
V2 说明文档：https://github.com/TencentARC/PhotoMaker/blob/main/README_pmv2.md
Mac GPU 环境指南：https://github.com/TencentARC/PhotoMaker/blob/main/MacGPUEnv.md

四、环境要求

官方 README「Dependencies and Installation」一节明确：

Python 版本：Python >= 3.8（官方推荐使用 Anaconda 或 Miniconda 管理环境，示例用 3.10）。
PyTorch 版本：PyTorch >= 2.0.0。
GPU 显存：官方 2024-01-20 更新公告明确——"PhotoMaker 的最低 GPU 显存要求为 11G"。不支持 bfloat16 的 GPU（如 V100）需将代码中 torch_dtype = torch.bfloat16 改为 torch.float16，官方实测 V100 上单张图生成时间可由 1 分钟缩短到 14 秒。
操作系统：官方未限定操作系统；README 提供 macOS GPU 单独指南（MacGPUEnv.md），Windows 用户可参考官方列出的社区维护版本（bmaltais/PhotoMaker、sdbds/PhotoMaker-for-windows）。
模型权重：首次运行时通过 huggingface_hub.hf_hub_download 自动下载 photomaker-v1.bin；也可从模型卡手动下载。
磁盘：需预留 SDXL 基座模型 + PhotoMaker 权重 + 依赖环境空间，官方未给具体数值。

五、部署步骤

以下命令全部照搬官方 README「Dependencies and Installation」一节。

命令 1：创建并激活 Conda 环境

conda create --name photomaker python=3.10
conda activate photomaker
pip install -U pip

逐段解释：conda create --name photomaker python=3.10 用 Miniconda/Anaconda 创建一个名为 photomaker、Python 版本为 3.10 的隔离环境；conda activate photomaker 激活该环境（后续所有 pip 命令都在该环境内执行）；pip install -U pip 升级 pip 到最新版。

执行成功后预期输出参考： conda 解析依赖后提示 done，命令行提示符前出现 (photomaker) 前缀。

命令 2：安装项目依赖

pip install -r requirements.txt

逐段解释：先 git clone 仓库到本地（如尚未克隆），进入仓库根目录后执行该命令；-r requirements.txt 表示按仓库根目录下 requirements.txt 中列出的版本清单安装 diffusers、transformers、gradio 等运行时依赖。

执行成功后预期输出参考： pip 依次下载并安装依赖包，结束时输出 Successfully installed ... 之类的提示。

命令 3：以可编辑模式安装 photomaker 包

pip install git+https://github.com/TencentARC/PhotoMaker.git

逐段解释：pip install git+... 直接从 GitHub main 分支拉取源码并安装 Python 包；安装后即可在 Python 中 from photomaker import PhotoMakerStableDiffusionXLPipeline 导入官方 Pipeline。

执行成功后预期输出参考： pip 输出 Successfully installed photomaker-x.x.x（版本号以实际发布为准）。

命令 4（可选）：验证 import

from photomaker import PhotoMakerStableDiffusionXLPipeline

逐段解释：官方 README 原文"Then you can run the following command to use it"。在 Python REPL 或脚本中执行该 import 语句，无报错即说明包安装成功。

执行成功后预期输出参考： 命令行回到 >>> 提示符，无任何异常输出。

命令 5：启动本地 Gradio Demo

python gradio_demo/app.py

逐段解释：官方 README「Start a local gradio demo」原文命令；gradio_demo/app.py 是仓库内置的 Gradio 启动脚本，首次运行会自动从 Hugging Face 下载 PhotoMaker 权重与默认 SDXL 基座，并在本地起一个 Web 界面。脚本可按需自行修改（官方 README 注明"You could customize this script in this file"）。

执行成功后预期输出参考： Gradio 启动后输出形如 Running on local URL: http://127.0.0.1:7860 的提示，浏览器打开该地址即可使用。

macOS 用户注意：官方 README 明确"If you want to run it on MAC, you should follow this Instruction (MacGPUEnv.md) and then run the app.py"——macOS 下需先按 https://github.com/TencentARC/PhotoMaker/blob/main/MacGPUEnv.md 配置环境，再执行 python gradio_demo/app.py。

六、配置参数详解

PhotoMaker 主要通过 Python API 与 Gradio 界面参数进行配置，官方 README 给出的关键项如下：

1. 模型自动下载（官方原文）：

from huggingface_hub import hf_hub_download
photomaker_path = hf_hub_download(repo_id="TencentARC/PhotoMaker", filename="photomaker-v1.bin", repo_type="model")

逐段解释：hf_hub_download 从 Hugging Face 拉取 photomaker-v1.bin 权重；repo_type="model" 表示这是模型仓库。官方也允许手动从 https://huggingface.co/TencentARC/PhotoMaker 下载后放到本地。

2. Pipeline 加载关键参数（官方示例）：

参数	官方示例值	说明
`base_model_path`	任意 SDXL 基座路径	可切换为任何基于 SDXL 的基座模型
`torch_dtype`	`torch.bfloat16`	不支持 bfloat16 的 GPU 改为 `torch.float16`（官方 2024-01-20 公告）
`use_safetensors`	`True`	使用 safetensors 格式加载
`variant`	`"fp16"`	加载 fp16 变体以节省显存
`weight_name`	`photomaker-v1.bin`	PhotoMaker 权重文件名
`trigger_word`	`"img"`	触发词，prompt 中须紧跟类别词之后
`start_merge_step`	`10`	从第 10 步开始合并 ID 嵌入

3. LoRA 联合加载（官方注释示例）：

# pipe.load_lora_weights(os.path.dirname(lora_path), weight_name=lora_model_name, adapter_name="xl_more_art-full")
# pipe.set_adapters(["photomaker", "xl_more_art-full"], adapter_weights=[1.0, 0.5])

逐段解释：load_lora_weights 加载额外 LoRA；set_adapters 同时启用 photomaker 与该 LoRA，权重分别为 1.0 与 0.5。

4. Prompt 书写规则（官方 Usage Tips）：
- 触发词 img 必须紧跟在类别词之后，例如 a half-body portrait of a man img wearing the sunglasses in Iron man suit。
- 输入亚裔面孔时，可在类别词前加 Asian，如 Asian woman img。
- 风格化时若生成人脸过于写实，可在 Gradio 界面把 Style strength 调到 30–50；数值越大 ID 保真度越低但风格化越强。

七、启动与运维

前台启动：python gradio_demo/app.py，日志直接打印在终端；Ctrl+C 停止。
后台常驻 / 开机自启：官方 README 未提供后台常驻、开机自启或 systemd 配置方式。如需后台运行，可自行借助 Linux 通用机制（如 nohup python gradio_demo/app.py & 或 systemd unit），但这不属于官方文档内容。
修改端口：官方未在 README 中给出端口配置项；如需修改 Gradio 监听地址/端口，请在 gradio_demo/app.py 中 Gradio launch 调用处自行指定（官方提示"You could customize this script in this file"）。
查看日志：启动终端即日志；Gradio 同时会把生成错误打印到该终端。
数据持久化：模型权重默认缓存到 Hugging Face 缓存目录（~/.cache/huggingface/），生成结果通过 images.save('out_photomaker.png') 保存到当前工作目录；官方未提供专门的数据目录配置。
显存优化：官方 README 2024-01-20 公告指向 discussions #114 提供节省显存的方法；不支持 bfloat16 的 GPU 改用 torch.float16 可大幅提速。

八、实操验证

完成上述 5 步后，终端出现 Gradio 的 Running on local URL: http://127.0.0.1:7860。
浏览器打开该地址（远程服务器部署则把 127.0.0.1 换成服务器 IP，并确保 7860 端口放行）。
在界面中上传 1 张或多张待定制人物的照片（官方 Usage Tips：上传越多张同人物照片，ID 保真度越好）。
在 prompt 输入框输入官方示例：a half-body portrait of a man img wearing the sunglasses in Iron man suit, best quality，负面 prompt 使用官方示例：(asymmetry, worst quality, low quality, illustration, 3d, 2d, painting, cartoons, sketch), open mouth, grayscale。
点击生成，数十秒后界面右侧出现生成图；该图人物面貌应与上传参考图保持一致，同时服装/场景按 prompt 变为钢铁侠战衣。
命令行方式验证（官方示例）：

images.save('out_photomaker.png')

逐段解释：将 Pipeline 输出的第一张图保存为当前目录下 out_photomaker.png。预期输出参考： 当前目录出现 out_photomaker.png，打开可见生成结果。

九、故障排查

案例 1：不支持 bfloat16 的 GPU（如 V100）生成极慢或报 dtype 错误

报错原文（常见形式）：RuntimeError: "addmm_impl_cpu_" not implemented for 'Half' 或生成速度约 1 分钟/张。
报错原因：官方 README 2024-01-20 公告明确——默认代码使用 torch_dtype=torch.bfloat16，而 V100 等较老架构不支持 bfloat16。
分步解决：① 打开 gradio_demo/app.py（官方公告链接定位到第 39 行）；② 把 torch_dtype = torch.bfloat16 改为 torch_dtype = torch.float16；③ 重启脚本。官方实测 V100 上由 1 min/img 提速到 14 s/img。

案例 2：首次启动卡在模型下载 / 下载失败

报错原文（常见形式）：ConnectionError: Could not reach huggingface.co 或长时间停留在下载进度条。
报错原因：官方通过 hf_hub_download 在线拉取 photomaker-v1.bin，国内网络访问 Hugging Face 不稳定。
分步解决：① 按官方 README"也可以选择从该 url 手动下载"，浏览器/aria2 从 https://huggingface.co/TencentARC/PhotoMaker 手动下载 photomaker-v1.bin；② 放到本地目录后，在 pipe.load_photomaker_adapter(os.path.dirname(photomaker_path), ...) 中把 photomaker_path 指向本地文件路径；③ 国内用户也可使用官方 Related Resources 中列出的 Wisemodel 始智、OpenXLab 镜像入口。

案例 3：生成图人物不像 / ID 漂移严重

报错现象：无报错，但生成结果与参考人脸差异大。
报错原因：官方 Usage Tips 明确——参考照片数量少、prompt 中漏写触发词 img、或风格化时 Style strength 过高。
分步解决：① 上传多张同人物不同角度照片；② 确认 prompt 中类别词后紧跟 img（如 a woman img）；③ 风格化场景把 Style strength 调到 30–50；④ 适当增加 num_inference_steps 并保持 start_merge_step=10（官方示例值）。

案例 4：GPU 显存不足（OOM）

报错原文（常见形式）：OutOfMemoryError: CUDA out of memory. Tried to allocate ...
报错原因：官方明确最低显存 11G；低于该值或同时加载了大基座时会 OOM。
分步解决：① 按官方 2024-01-20 公告切换 torch.float16；② 参考官方 discussions #114（README 原文链接"Please refer to this link for saving GPU memory"）中的省显存方案；③ 降低 num_images_per_prompt 与分辨率。

十、升级、回滚与卸载

升级： 官方未提供专门升级命令；按 pip 可编辑安装机制，在仓库目录执行 git pull 后重新 pip install -r requirements.txt 与 pip install git+https://github.com/TencentARC/PhotoMaker.git 即可更新到 main 分支最新代码。V2 用户参考 README_pmv2.md。

回滚： 官方未提供一键回滚；可 git checkout <旧 tag/commit> 后重新 pip install -e . 回退到历史版本。

卸载： 执行 pip uninstall photomaker 卸载 Python 包；删除 Conda 环境 conda env remove -n photomaker；删除 Hugging Face 缓存 ~/.cache/huggingface/（此操作会删除已下载模型权重，下次启动需重新下载）。

十一、商用许可合规说明

许可证：Apache License Version 2.0（官方 LICENSE 文件开头明确"PhotoMaker is licensed under the Apache License Version 2.0 except for the third-party components listed below"，版权所有 (C) 2024 THL A29 Limited, a Tencent company）。
Apache-2.0 允许自由使用、修改、分发与商用；分发时须保留版权声明与许可文本，修改过的文件须标注变更。
注意 LICENSE 文件列出的第三方组件按其各自许可证单独授权；生成内容涉及真人肖像时，用户须自行遵守当地法律法规与肖像权相关要求（官方 README Disclaimer 原文："Users are granted the freedom to create images using this tool, but they are expected to comply with local laws and utilize it responsibly"）。