stable-diffusion.cpp 中 PuLID-Flux 人脸身份保持(Face Identity Preservation)完整指南

发布时间:2026/11/16 5:50:34

stable-diffusion.cpp 中 PuLID-Flux 人脸身份保持(Face Identity Preservation)完整指南 人工智能大模型本地部署推理引擎媒体生成【免费下载链接】stable-diffusion.cppDiffusion model(SD,Flux,Wan,Qwen Image,Z-Image,...) inference in pure C/C项目地址https://gitcode.com/GitHub_Trending/st/stable-diffusion.cpp点击查看免费下载导读本文基于 stable-diffusion.cpp 的 PuLID-Flux 身份保持文档 展开完整讲解如何在纯 C/C 推理栈上为 Flux.1schnell / dev叠加 PuLID-Flux 人脸身份注入技术从架构原理20 个PerceiverAttentionCA交叉注意力钩子、身份嵌入.pulidembd的预计算与 gguf 容器格式到三个--pulid-*命令行参数的组合规则、内存预算、后端选型与 SHA-256 验证方法。读完本文你将能独立完成“单张人像 → 任意场景/姿态/提示词下保持同一人脸”的 Flux 生成流水线搭建并规避已知的 SLG 冲突、v1.1 权重不兼容、1024 分辨率显存不足等坑。1. PuLID-Flux 是什么stable-diffusion.cpp 如何支持它PuLID-FluxPuLID: Pure and Lightning ID Customization via Contrastive Alignment是一种在 Flux.1 扩散模型之上工作的身份注入identity-injection技术给定一张源人像后续生成的新图可以保留该人物的脸部特征同时自由改变场景、姿态和提示词。在 stable-diffusion.cpp 中该功能面向 Flux.1schnell与dev两个变体实现。它与同为身份保持方案的 PhotoMaker 存在关键区别对比维度PhotoMakerPuLID-Flux本实现身份提取时机在推理过程中从一批图像中提取一次性离线预计算得到固定 embedding身份提取栈推理期较轻较重insightface ArcFace EVA-CLIP-L IDFormer 编码器C 端负担需处理多图输入只消费一个预计算张量跨后端能力—提取之后全部是 C/ggml 计算从源码结构看src/extensions/pulid_extension.cpp中PuLIDExtension是一个标准的GenerationExtension扩展组件它把预计算的id_embedding与id_weight写入FluxDiffusionExtra见 src/model/diffusion/model.hpp再由 Flux 图构建阶段真正注入。由于身份提取栈ArcFace、EVA-CLIP-L、IDFormer过于庞大难以移植到 C/ggml因此本实现刻意选择了**“消费外部预计算身份嵌入”**的跨厂商cross-vendor方案一次人像只需离线提取一次之后所有生成环节都运行在纯 C 推理栈上可跑在 Vulkan、CUDA、Metal、ROCm、CPU 等任意后端。2. 架构20 个交叉注意力钩子如何注入 Flux 去噪循环PuLID-Flux 对 Flux 去噪循环的改造本质上是在 Flux transformer 块之间插入一层小型交叉注意力模块栈——PerceiverAttentionCA。stable-diffusion.cpp 的实现与其对齐19 个 double-stream 块每 2 个块插入 1 个钩子共 10 个注入点pulid_double_interval 238 个 single-stream 块每 4 个块插入 1 个钩子共 10 个注入点pulid_single_interval 4合计 20 个交叉注意力层对应源码 src/model/diffusion/flux.hpp 中的pulid_enabled、pulid_double_interval、pulid_single_interval配置权重按pulid_ca.i命名加载见 flux.hpp 与 flux.hpp。每个交叉注意力层的数据流为取当前图像 tokenimage tokens作为 Query取32 token × 2048 维的身份嵌入作为 Key Value输出经id_weight典型值 1.0缩放后加回图像 tokenimg img scale(ca_out, pulid_id_weight)上述加回操作在 flux.hppdouble-stream 分支与 flux.hppsingle-stream 分支中均有体现并伴随ggml_graph_cut标记以配合自动图切分。单层模块PuLIDPerceiverAttentionCA的定义位于 src/model/adapter/pulid.hpp内部为 norm →to_q2048 维→to_kv3072 维→ attention →to_out的结构即一个轻量的感知机式交叉注意力单元。关键设计当pulid_id nullptr或权重为空时pulid_active为 false整条路径被跳过见 flux.hpp即 PuLID 完全可裁剪、不改变非 PuLID 运行的行为。3. 所需权重在三件套之外还需要什么在标准 Flux 权重集transformer VAE clip_l t5xxl配置方式与 docs/flux.md 完全一致之外PuLID 还需要三个文件Flux 基础权重transformer、VAE、CLIP-L、T5-XXL与普通 Flux 生成完全相同PuLID 权重pulid_flux_v0.9.0.safetensors或pulid_flux_v0.9.1.safetensors。本实现针对 v0.9.1 验证通过推荐使用 v0.9.1身份嵌入.pulidembd由下面的预计算工具生成一次人像只需一份。⚠️重要兼容性提示pulid_v1.1.safetensorsv1.1暂不支持。v1.1 使用了重命名后的键id_adapter_attn_layers.*而非pulid_ca.*模块结构也可能不同属于待实现的未来工作Future PR。下载时请务必选择 v0.9.x 版本。从加载路径看PuLID 权重路径通过上下文参数pulid_weights_path传入见 include/stable-diffusion.h该参数在 CLI 侧由--pulid-weights解析见 examples/common/common.cpp。4. 预计算身份嵌入一次性离线提取由于身份提取栈无法移植进 Cstable-diffusion.cpp 采用“每个源人像运行一次外部 Python 工具”的方式把提取结果固化成一个(32, 2048)的嵌入张量并写入.pulidembd二进制文件fp16 存储约 131 KB。同一个文件可被任意次生成复用。仓库在 scripts/pulid_extract_id.py 提供了参考 Python 脚本其运行环境要求可用的 CUDA / CPU PyTorch 栈insightface、facexlib、eva-clip、torchvision、opencv-python、huggingface_hub、gguf等依赖ToTheBeginning/PuLID 仓库中的pulid/包含pulid/pipeline_flux.py与eva_clip/包需加入PYTHONPATHflux/包不需要——因为get_id_embedding()不会真正运行 Flux 去噪脚本内部用SimpleNamespace()构造了一个 dummy Flux 对象见 pulid_extract_id.py从而避免引入整套 Flux 骨架。运行方式python pulid_extract_id.py \ --portrait /path/to/source-photo.jpg \ --pulid-weights /path/to/pulid_flux_v0.9.1.safetensors \ --out /path/to/source.pulidembd脚本逻辑可对照 pulid_extract_id.py 阅读自动探测 CUDA选择device cuda/ ONNX providergpu否则回退 CPU用PuLIDPipeline(ditdummy, device, weight_dtypebfloat16, onnx_provider)构造管线并以versionv0.9.1加载 PuLID 权重读取人像自动转 RGB调用get_id_embedding(face_img)得到身份嵌入若结果带有 batch 维shape[1, num_tokens, token_dim]会去掉该维校验形状为二维(num_tokens, token_dim)后写入 gguf。可选参数--dtype支持fp16默认约 131 KB、bf16、fp32三种存储精度对应脚本write_embd()中的三个分支见 pulid_extract_id.py。注意人像必须包含清晰可见的人脸。insightface 的antelopev2检测器在首次运行时会被自动下载。5. 身份嵌入的文件格式gguf 容器.pulidembd是一个标准gguf容器仅含单个张量tensor name : pulid_id shape : [token_dim, num_tokens] (ggml 顺序典型 [2048, 32]) type : F16 (也接受 F32 / BF16) metadata : general.architecture pulid, pulid.version 1C 端加载逻辑见 src/extensions/pulid_extension.cpp使用标准 gguf 读取器gguf_init_from_file打开没有定制解析器查找名为pulid_id的张量校验形状合理性token_dim在 1~65536、num_tokens在 1~1024 且ne[2] ne[3] 1支持 F32直接 memcpy、F16 / BF16逐元素转换为 fp32三种类型其他类型拒绝加载加载时统一转为 fp32供后续 ggml 图使用。写入侧则由 scripts/pulid_extract_id.py 的GGUFWriter完成archpulid、pulid.version1、张量名pulid_id与读取端完全对应。6. 命令行用法让 Flux 生成保持指定人脸以 Windows 下的sd-cli.exe为例Linux/macOS 将路径与可执行名替换即可.\bin\Release\sd-cli.exe \ --diffusion-model models\flux1-schnell-Q4_K_S.gguf \ --vae models\ae.safetensors \ --clip_l models\clip_l.safetensors \ --t5xxl models\t5xxl_fp16.safetensors \ --pulid-weights models\pulid_flux_v0.9.1.safetensors \ --pulid-id-embedding source.pulidembd \ --pulid-id-weight 1.0 \ -p candid photograph of a young woman on a beach at sunset \ --cfg-scale 1.0 --sampling-method euler --steps 4 -W 512 -H 512 \ --seed 42 --clip-on-cpu \ -o out.png若使用 Flux Dev而非 Schnell追加--guidance 3.5并把步数提到--steps 20。参数解析位于 examples/common/common.cpp--pulid-weights见 L530-L534--pulid-id-embedding见 L1116-L1119--pulid-id-weight见 L1286最终汇入sd_pulid_params_t见 include/stable-diffusion.h再经 src/pipeline/request.cpp 拷贝到扩展上下文。6.1 三个参数必须同时出现Flag作用默认值/取值范围--pulid-weights pathpulid_flux_v0.9.x.safetensors的路径随模型一起加载无--pulid-id-embedding p预计算工具产出的.pulidembd二进制路径无--pulid-id-weight f身份注入强度典型 0.7–1.2默认 1.0三条规则务必理解三个 flag 必须同时设置才会激活 PuLID只设--pulid-weights而不设 embedding权重被加载但运行时不注入PuLIDExtension以pulid_weights_path非空作为enabled条件而prepare_condition在 embedding 为空时不会写入flux_extra见 pulid_extension.cpp设--pulid-id-weight 0注入贡献被置零——这正是官方推荐的“证伪测试falsification test”手段相同 seed 下输出应与完全不带 PuLID 的跑法逐字节一致。7. 内存预算与 1024 分辨率下的显存处理官方在 512×512、4 步Schnell、12 GB 消费级显卡Flux Schnell Q4 GGUF CPU 卸载的 clip_l / t5xxl GPU 常驻 VAE上实测20 个交叉注意力层对去噪时间的影响约10%峰值显存几乎不增加——因为交叉注意力只在 token 序列上做轻量投影不引入大的中间缓存。但在1024×1024 Flux Dev Q4 20 步 PuLID场景下VAE 解码的计算缓冲区在 12 GB 卡上放不下即使加了--vae-on-cpu也不行。原因在于--vae-on-cpu只是把 VAE 权重卸载到 CPU计算图仍留在默认后端这是 stable-diffusion.cpp 的既有行为并非 PuLID 专属问题。正确解法是把 VAE 的计算也显式路由到 CPU 后端--backend diffusionvulkan0,vaecpu8. 后端选择随主扩散模型走PuLID 交叉注意力层与主扩散模型运行在同一后端因此复用标准的--backend参数。常见组合# AMD Vulkan --backend diffusionvulkan0,vaecpu # NVIDIA Vulkan --backend diffusionvulkan1,vaecpu # CUDA --backend diffusioncuda0,vaecpu需要说明的边界该实现是纯 ggml 图构建理论上可在 CUDA、ROCm、Metal 上工作但截至文档写作时仅 Vulkan 与 CPU 后端经过原作者实测其余后端欢迎用户验证。9. 验证方法三路 SHA-256 对照测试在新组合模型 后端 硬件首次跑通时官方推荐用三路 SHA-256 对照作为健康检查跑法预期哈希关系A不带任何--pulid-*flag基线baselineB带 PuLID flag但--pulid-id-weight 0.0与 A 逐字节一致C带 PuLID flag--pulid-id-weight 1.0与 A、B 均不同且输出保持源人脸判定逻辑如果 A 与 C 不同但 A 与 B 也不同说明注入路径在权重为 0 时仍在分配或计算某些东西——很可能是个 bug。这一约定与第 6.1 节的“置零即无注入”语义互相印证是排查实现正确性的有力手段。10. 限制与暂不支持的功能务必提前知晓--skip-layersskip-layer-guidance / SLG与 PuLID 不可同用。pulid_ca的索引按“未被跳过的块”推进一旦有块被跳过交叉注意力权重的分配就会相对训练区间静默错位参考 PyTorch 实现本身也没有 SLG不存在可模拟的既定行为。源码层面同样明确skip_layers非空时pulid_run会被置为 false见 flux.hpp。请二者择一使用。PuLID v1.1 权重pulid_v1.1.safetensors键名已重排暂不支持请使用 v0.9.x。多张 ID 图参考 PyTorch 实现可将多张人像融合为更强的单一嵌入本实现接受的是外部预计算工具从一张或多张图产出的单个嵌入文件。CFG 的 negative-prompt 分支PuLID 仅在正条件positive conditioning路径注入与已发布参考实现一致。Flux 的蒸馏式引导distilled guidance正常使用时不跑独立的 uncond 分支因此该限制只影响--true-cfg这类非 Flux 标准工作流。后端覆盖除 Vulkan 与 CPU 外未经原作者实测其他后端依赖用户验证。11. 快速上手指南从零到首张保脸图汇总全文搭建 PuLID-Flux 生成的最小路径准备 Flux 基础权重transformer GGUF如flux1-schnell-Q4_K_S.gguf、VAE、CLIP-L、T5-XXL参考 docs/flux.md下载 PuLID 权重pulid_flux_v0.9.1.safetensors勿用 v1.1搭建 Python 预计算环境安装 PyTorch 与insightface、facexlib、eva-clip等依赖将 ToTheBeginning/PuLID 的pulid/与eva_clip/包加入PYTHONPATH生成.pulidembd运行python scripts/pulid_extract_id.py --portrait xxx.jpg --pulid-weights pulid_flux_v0.9.1.safetensors --out source.pulidembd一次完成、永久复用运行sd-cli三个--pulid-*flag 同时给出Schnell 用 4 步、Dev 追加--guidance 3.5与 20 步验证按第 9 节做三路 SHA-256 对照确认注入真实生效且零权重路径干净。整个 PuLID 链路中只有第 3、4 步是 Python/PyTorch 一次性工作从 embedding 文件加载到去噪注入、再到出图全部由 src/extensions/pulid_extension.cpp 与 src/model/diffusion/flux.hpp 中的 C/ggml 实现完成因而可以自由跑在 Vulkan、CUDA、Metal、ROCm 与纯 CPU 环境下。赞分享人工智能大模型本地部署推理引擎媒体生成【免费下载链接】stable-diffusion.cppDiffusion model(SD,Flux,Wan,Qwen Image,Z-Image,...) inference in pure C/C项目地址https://gitcode.com/GitHub_Trending/st/stable-diffusion.cpp点击查看免费下载相关推荐智能地址解析实战3大核心技巧提升数据处理效率智能地址解析实战3大核心技巧提升数据处理效率 中文地址智能解析工具chinese_province_city_area_mapper简称cpca是一个强大NLPTestableMock快速入门从零开始编写第一个Mock测试TestableMock快速入门从零开始编写第一个Mock测试 什么是TestableMock TestableMock是一款特立独行的轻量Mock工具它YOLOv8-face人脸检测技术完整指南YOLOv8 face人脸检测技术完整指南 YOLOv8 face是基于Ultralytics YOLOv8框架专门优化的人脸检测模型提供高效准确的人脸识别能人工智能计算机视觉深度学习上一篇为什么你的ComfyUI-Impact-Pack安装不完整完整安装指南与功能解析下一篇Irony Mod ManagerParadox游戏模组管理的终极解决方案创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/15 19:44:30

优惠券网站要怎么做推广与网站刚建好怎么做能让百度收录对比

优惠券网站推广避坑指南:安全加固需多少钱 模板网站太丑且功能残缺,直接导致用户流失,更致命的是其内置的安全漏洞,让推广费打水漂。很多老板问做安全加固要多少钱,这取决于你的业务量级,但基础防护成本并不高,关键在于别让攻击者白嫖你的流量。…

2026/11/12 11:24:16

零代码用Codex:普通人任务翻译实战指南

1. 项目概述:一个非程序员的真实Codex使用手记“不会编程的人,到底能不能用 Codex?”——这个问题我问了自己整整三天。不是因为犹豫要不要试,而是因为身边太多人一听到“Codex”就自动划归到“程序员专属工具”的认知牢笼里&…

2026/11/16 12:15:43

众车网是哪家公司网站?一文搞懂备案避坑指南

众车网是哪家公司网站?一文搞懂备案避坑指南 很多刚入行的朋友或者准备上线新站点的老板,一听到“ICP备案”这四个字,心里就犯嘀咕:流程到底多复杂?会不会被卡住?其实, 备案流程一头雾水…

2026/11/16 13:04:04

中级电工证没联网官方回应:过期如何延期复审

中级电工证没联网官方回应:过期如何延期复审 证书过期了不知道怎么复审延期?现在很多人拿着中级电工证,发现系统查不到信息,以为是“中级电工证没联网”,结果一拖就错过了复审时间。其实,这类问题官方已经给出回应,关键是要知道怎么操作。别急,下面详…

2026/11/16 13:04:04

大连高压电工证怎么查?网上查询攻略来了,工地太忙也能搞定

大连高压电工证怎么查?网上查询攻略来了,工地太忙也能搞定 工地太忙根本没时间复习考试,这话不是我说的,是无数特种作业人员的真实写照。尤其是像大连高压电工证这样的证书,不仅要考证,还要定期复审,流程复杂,时间紧迫。不过别担心,网上查询已经成了…

2026/11/16 13:04:04

铁路特种作业证考试题良心建议:实操考试心里没底怕挂科怎么办?

铁路特种作业证考试题良心建议:实操考试心里没底怕挂科怎么办? 你是不是也在为铁路特种作业证考试题发愁?实操考试心里没底怕挂科,这种焦虑很多人都有。尤其是像你这样在焦作劳务班组负责人的,天天和工人打交道,深知一个证对大家意味着什么。今天就从你…

2026/11/16 13:04:04

汉阳在哪里考电工证好保姆级教程:证书过期了不知道怎么复审延期?

汉阳在哪里考电工证好保姆级教程:证书过期了不知道怎么复审延期? 证书过期了不知道怎么复审延期,这事儿别慌!作为在汉阳地区从事电力相关工作的你,了解最新的电工证考试、复审流程,不仅关乎你能否正常上岗,更是关系到你职业发展的核心。今天这篇保姆级…

2026/11/16 12:53:58

大连焊工证电工证网上查询报名费多少钱?别被中介坑了!

大连焊工证电工证网上查询报名费多少钱?别被中介坑了! 你是不是也这样,拿着手机在网上查【大连焊工证电工证】,结果点开一堆信息,不是中介就是广告,不知道哪个靠谱?报名费贵不贵?考完能干什么?这些问题是不是一直困扰着你?别急,这篇文章就帮你解决…

2026/11/16 7:29:52

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/16 5:30:20

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/16 0:00:11

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱 你是不是也和我一样,想考电工证,但不知道去哪报名,怕被中介坑?最近网上有不少人问“黎城电工证查询报名费多少钱”,结果一查,信息五花八门,真假难辨。别担心,今天我就从一线从业者的角度…

2026/11/16 0:00:11

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来?

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来? 之前考的证在外省能不能转过来?这个问题困扰着很多在外地打工的电工,尤其是像南阳卧龙区的建筑工人,他们常年在工地作业,手上持有电工证是基本要求,但很多人因为工作流动性大,担心证书不能转到本…

2026/11/15 4:46:37

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/16 3:17:47

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑