Lens 模型推理指南：在 stable-diffusion.cpp 中运行 Lens 与 Lens Turbo 文生图-开发者社区

人工智能
大模型
本地部署
推理引擎
媒体生成

【免费下载链接】stable-diffusion.cpp

Diffusion model(SD,Flux,Wan,Qwen Image,Z-Image,...) inference in pure C/C++

项目地址：https://gitcode.com/GitHub_Trending/st/stable-diffusion.cpp

Lens 是 stable-diffusion.cpp 中一类以Lens 扩散 Transformer + FLUX.2 VAE + GPT-OSS-20B 文本编码器组合而成的新型文生图模型。本文以仓库 docs/lens.md 为主线，完整介绍权重下载、GPT-OSS 外部 tokenizer 配置、CLI 实战命令与关键参数，并结合 src/model/diffusion/lens.hpp 的源码剖析其网络结构与推理实现，帮助你在一套纯 C/C++ 推理框架中稳定跑通 Lens 和蒸馏版 Lens Turbo。

模型架构总览

Lens 的组成非常明确，文档给出了三块核心组件：

组件	用途	说明
Lens 扩散 Transformer	去噪主干网络	采用类似 Flux 的双流（图像/文本联合注意力）DiT 结构
FLUX.2 VAE	图像自编码器	负责 latent 与像素空间的相互转换，与 FLUX.2 共用`flux2_ae`权重
GPT-OSS-20B	LLM 文本编码器	以大型语言模型取代传统 CLIP/T5，语义理解能力更强

从源码看，Lens 的扩散主干被完整实现在 src/model/diffusion/lens.hpp 的Lens::LensModel与Lens::LensRunner中，并在 src/pipeline/model_builders.cpp 中通过sd_version_is_lens(version)判定后，以LLMEmbedder（文本编码侧）+Lens::LensRunner（扩散侧）的组合构建管线，与文档所述的三段式架构完全吻合。

权重下载清单

Lens 推理共需要 4 类权重文件，请按下列清单逐一准备：

Lens 扩散模型（safetensors）
- 从 Comfy-Org/Lens 仓库的diffusion_models目录下载lens_bf16.safetensors（普通版）与lens_turbo_bf16.safetensors（Turbo 蒸馏版）。
FLUX.2 VAE（safetensors）
- 从 black-forest-labs/FLUX.2-dev 目录下载flux2_ae.safetensors，即 docs/flux2.md 中使用的同一 VAE。
GPT-OSS-20B 文本编码器（gguf）
- 从 unsloth/gpt-oss-20b-GGUF 下载 GGUF 量化版，例如gpt-oss-20b-UD-Q8_K_XL.gguf。
GPT-OSS-20B 的tokenizer.json
- 从 openai/gpt-oss-20b 目录下载，保存为tokenizer_gpt_oss.json，必须与所选 GPT-OSS 检查点匹配。

推荐将文件按以下目录结构组织，便于命令行引用：

models/ ├── diffusion_models/ │ ├── lens_bf16.safetensors │ └── lens_turbo_bf16.safetensors ├── text_encoders/ │ └── gpt-oss-20b-UD-Q8_K_XL.gguf ├── vae/ │ └── flux2_ae.safetensors └── tokenizers/ └── tokenizer_gpt_oss.json

为什么 Lens 必须使用外部 tokenizer.json

与大多数自带 tokenizer 的模型不同，Lens 和 Lens Turbo 的 GPT-OSS tokenizer 并未内嵌在 sd.cpp 中。文档明确指出：保存为tokenizer_gpt_oss.json后必须通过--tokenizer显式传入，初始化时若缺少主 tokenizer 会直接失败。

这背后的实现约束可以从源码得到印证：src/model/te/llm.hpp 中明确抛出异常——"GPT-OSS, Gemma 2 and LLaDA2 require an external tokenizer.json in the main tokenizer slot"，且GPT_OSS_20B被列入LLMArch架构枚举（见 src/model/te/llm.hpp）。

详细的 CLI 与 C API 用法请参阅 docs/tokenizers.md，要点如下：

--tokenizer FILE作用于"主 LLM/BPE 编码器"槽位（Gemma 2/3、Qwen 2/3、Mistral、GPT-OSS 等），普通路径等价于main=FILE；
可以多槽位组合，如--tokenizer main=main.json,clip-l=clip_l.json；
JSON 文件的 vocabulary/merges/added tokens 必须与文本编码器检查点匹配，仅凭"ID 不超出 embedding 表"无法证明词汇表语义一致；
文件加载发生在文本编码器创建时，此时不会加载内嵌词表。

CLI 实战：运行 Lens

文档给出的 Lens 完整命令（Windows 路径）如下：

.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\lens_bf16.safetensors --llm "..\models\text_encoders\gpt-oss-20b-UD-Q8_K_XL.gguf" --tokenizer ..\models\tokenizers\tokenizer_gpt_oss.json --vae ..\models\vae\flux2_ae.safetensors --cfg-scale 5.0 -p "A crystal dragon soaring through an aurora borealis sky, its entire body made of transparent faceted crystal refracting the green and purple aurora light into rainbow spectra, ice particles trailing from its wings, high fantasy digital art" --diffusion-fa -v

在 Linux/macOS 上等价写法为（按上文目录结构，且bin/sd-cli为编译产物所在目录）：

./bin/sd-cli --diffusion-model models/diffusion_models/lens_bf16.safetensors \ --llm models/text_encoders/gpt-oss-20b-UD-Q8_K_XL.gguf \ --tokenizer models/tokenizers/tokenizer_gpt_oss.json \ --vae models/vae/flux2_ae.safetensors \ --cfg-scale 5.0 \ -p "A crystal dragon soaring through an aurora borealis sky, its entire body made of transparent faceted crystal refracting the green and purple aurora light into rainbow spectra, ice particles trailing from its wings, high fantasy digital art" \ --diffusion-fa -v

CLI 实战：运行 Lens Turbo

Lens Turbo 是蒸馏加速版本，核心差异是--cfg-scale必须降到 1.0，并配合--steps 4使用极少的去噪步数：

.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\lens_turbo_bf16.safetensors --llm "..\models\text_encoders\gpt-oss-20b-UD-Q8_K_XL.gguf" --tokenizer ..\models\tokenizers\tokenizer_gpt_oss.json --vae ..\models\vae\flux2_ae.safetensors --cfg-scale 1.0 -p "A crystal dragon soaring through an aurora borealis sky, its entire body made of transparent faceted crystal refracting the green and purple aurora light into rainbow spectra, ice particles trailing from its wings, high fantasy digital art" --diffusion-fa -v --steps 4

关键参数详解

参数	取值示例	作用与建议
`--diffusion-model`	`lens_bf16.safetensors`/`lens_turbo_bf16.safetensors`	指定 Lens/Lens Turbo 扩散模型权重
`--llm`	`gpt-oss-20b-UD-Q8_K_XL.gguf`	指定 GPT-OSS-20B 文本编码器 GGUF
`--tokenizer`	`tokenizer_gpt_oss.json`	指定外部 GPT-OSS tokenizer，必填
`--vae`	`flux2_ae.safetensors`	指定 FLUX.2 VAE 权重
`--cfg-scale`	Lens 用`5.0`，Lens Turbo 用`1.0`	无分类器引导强度；Turbo 蒸馏模型必须为 1.0
`--steps`	Turbo 用`4`	采样步数，蒸馏版建议极少步数
`--diffusion-fa`	-	为扩散模型启用 Flash Attention，降低显存/内存压力
`-v`	-	输出详细日志，便于观察加载与推理过程

补充说明：

GPT-OSS-20B 是约 200 亿参数级别的 MoE 语言模型，建议使用 Q8_K 等高保真量化 GGUF；若显存不足，可参考其他文档中常见的--offload-to-cpu选项将部分权重驻留 CPU；
--cfg-scale与--steps的取值直接影响生成质量：Lens 普通版用 5.0 保持提示词遵循度，Lens Turbo 则必须用 1.0 才能与蒸馏权重匹配，切勿混用。

源码级实现剖析

配置自动探测

Lens::LensConfig::detect_from_weights（src/model/diffusion/lens.hpp）会在加载权重时自动推导超参数：由img_in.weight得到in_channels（默认 128），由proj_out.weight与 patch size 推导out_channels（默认 32），由transformer_blocks.0.attn.norm_q.weight得到attention_head_dim（默认 64），并按txt_in.weight与joint_attention_dim（2880）之比得到selected_layer_count（默认 4）。其默认配置为 48 层 Transformer、24 个注意力头、axes_dim = {8, 28, 28}、RoPEtheta = 10000。

双流联合注意力 Transformer

LensTransformerBlock（src/model/diffusion/lens.hpp）与LensJointAttention（src/model/diffusion/lens.hpp）展示了核心结构：图像序列与文本序列各自投影出 Q/K/V，经 RMSNorm 归一化后拼接在一起做联合注意力，再按图像/文本视图拆开分别输出；块内以 AdaLN 调制（img_mod.1/txt_mod.1输出 6 组调制系数）与 Gated MLP（LensGateMLP，即 SwiGLU 变体）完成特征变换。这解释了为什么 Lens 需要 LLM 级别的文本编码——txt_in的输入维度是joint_attention_dim * selected_layer_count（2880×4），即拼接了 GPT-OSS 多个层的隐状态来驱动条件注入。

图构建与位置编码

LensRunner::build_graph（src/model/diffusion/lens.hpp）以LENS_GRAPH_SIZE = 40960开辟计算图，调用Rope::gen_lens_pe依据图像分辨率与文本长度生成轴向位置编码，并将x、timesteps、context三路输入送入LensModel::forward，经过 patch 化（patch size 2）、img_in/txt_in投影、48 层联合注意力与 AdaLN 归一化后由proj_out还原为 latent。get_desc()返回"lens"，供日志与调试区分。

管线注册

在 src/pipeline/model_builders.cpp 中，Lens 分支使用LLMEmbedder作为 conditioner（负责调用 GPT-OSS 编码提示词），配合Lens::LensRunner完成去噪；模型版本VERSION_LENS与判定函数sd_version_is_lens定义于 src/model.h 与 src/model.h。

C API 使用提示

如果你通过 C API 集成 Lens，需要把外部 tokenizer 路径写入sd_ctx_params_t::tokenizer。该字段接受与 CLI--tokenizer相同的字符串（如main=tokenizer_gpt_oss.json），TokenizerConfig会在文本编码器初始化时解析并校验；对 Lens/PiD 这类模型，主 tokenizer 路径必须非空，否则初始化失败（详见 docs/tokenizers.md）。

sd_ctx_params_t params; sd_ctx_params_init(&params); params.tokenizer = "main=tokenizer_gpt_oss.json";

常见问题与注意事项

缺少 tokenizer 导致初始化失败：必须下载 openai/gpt-oss-20b 的tokenizer.json并重命名为tokenizer_gpt_oss.json，用--tokenizer传入主槽位；这是 Lens 与 PiD 等模型的内嵌约束，无法省略。
Turbo 版输出异常：确认--cfg-scale 1.0与--steps 4均已设置；蒸馏模型对这两项参数有严格要求。
文本编码器与 tokenizer 不匹配：请从同一来源下载配套的 GPT-OSS 检查点与词表，避免 ID 映射错位导致生成内容漂移。
VRAM 限制：GPT-OSS-20B 体量较大，可在命令中加入--offload-to-cpu并配合--diffusion-fa降低显存占用，具体以你机器实际可用显存为准。