TextGen 图像生成功能实战指南：从模型加载到 API 调用的完整技术解析-二趣网

TextGen 图像生成功能实战指南：从模型加载到 API 调用的完整技术解析

【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen

本文以 TextGen（textgen）仓库的 Image Generation Tutorial 为骨架，系统讲解其内置的 diffusion 文生图功能：如何通过 Web UI 下载并加载diffusers模型（以 Z-Image-Turbo 为例）、各量化选项对应的 VRAM 占用、模型专属生成参数、LLM Prompt Variations 创意增强，以及如何通过 OpenAI 兼容 API 生成图片。结合 modules/image_models.py、modules/ui_image_generation.py 与 modules/api/images.py 的源码实现，你还能理解每个配置项背后的底层调用链与实际落盘行为。

安装与环境要求

图像生成功能依赖diffusers等额外依赖，因此仅 "full" 版 Web UI 可用，Releases 页面中的.zip便携版不支持图像生成。官方推荐的安装方式：

克隆仓库：

git clone https://github.com/oobabooga/textgen

使用一键安装脚本：
- Windows：双击start_windows.bat
- Linux：运行./start_linux.sh
- macOS：运行./start_macos.sh

从源码看，full 版的依赖清单位于 requirements/full/requirements.txt，而便携版使用 requirements/portable/requirements.txt，两者差异正是图像生成在便携版不可用的根源。图像功能相关的命令行参数定义在 modules/shared.py 中，包括--image-model、--image-model-dir、--image-dtype、--image-attn-backend、--image-cpu-offload、--image-compile、--image-quant等，其中--image-model-dir默认指向user_data/image_models（仓库中该目录由 user_data/image_models/ 占位文件提示用途）。

下载模型

安装完成后按以下步骤下载模型：

打开http://127.0.0.1:7860/；
点击左侧 "Image AI" 页签；
点击顶部的 "Model" 子页签；
在 "Download model" 输入框中粘贴https://huggingface.co/Tongyi-MAI/Z-Image-Turbo，点击 "Download"；
等待下载完成（约 31 GB）。

源码层面的对应实现是 modules/ui_image_generation.py 中的download_image_model_wrapper：它剥离 HuggingFace URL 前缀，支持user/model:branch语法指定分支（默认main），然后调用huggingface_hub.snapshot_download将模型快照下载到user_data/image_models/<模型名>（/替换为_）。下载完成后会自动刷新下拉框并选中该模型。

模型目录的发现逻辑在 modules/utils.py 的get_available_image_models：它扫描image_model_dir下的子目录（而非单个文件）作为可选模型——这与文本模型以 GGUF 文件为单位的机制不同。

加载模型与量化配置

在 "Model" 页签选择量化选项后点击 "Load" 即可加载。官方文档给出的Z-Image-Turbo各量化档位的 VRAM 占用如下：

量化方式	VRAM 占用
None (FP16/BF16)	25613 MiB
bnb-8bit	16301 MiB
bnb-8bit + CPU Offload	16235 MiB
bnb-4bit	11533 MiB
bnb-4bit + CPU Offload	7677 MiB

量化选项的源码实现

UI 提供的量化选项为none、bnb-8bit、bnb-4bit、torchao-int8wo、torchao-fp4、torchao-float8wo（见 modules/ui_image_generation.py 的image_quant下拉框）。其解析逻辑在 modules/image_models.py 的get_quantization_config中：

bnb-8bit：为transformer与text_encoder两个子模块分别构造BitsAndBytesConfig(load_in_8bit=True)，打包成PipelineQuantizationConfig；
bnb-4bit：采用 NF4 量化类型、bfloat16 计算精度并开启双重量化（bnb_4bit_use_double_quant=True）；
torchao 系列：将torchao-int8wo / torchao-fp4 / torchao-float8wo映射为int8wo / fp4_e2m1 / float8wo，通过TorchAoConfig应用。

文档特别指出：torchao选项支持torch.compile以获得更快的生成速度，其中float8wo在 RTX 40 系及更新显卡上可获得原生硬件加速。

其他加载选项

"Model" 页签还有以下可配置项，默认值来自 modules/shared.py：

选项	取值	默认值	说明
Data Type	`bfloat16`/`float16`	`bfloat16`	官方建议现代 GPU 使用 bfloat16
Attention Backend	`sdpa`/`flash_attention_2`	`sdpa`	Flash Attention 需要兼容 GPU
Compile Model	勾选框	关闭	首次运行慢，之后推理更快
CPU Offload	勾选框	关闭	低显存 GPU 适用，速度慢但省显存

加载主流程load_image_model（modules/image_models.py）的关键步骤：以DiffusionPipeline.from_pretrained自动识别流水线类型（支持ZImagePipeline与QwenImagePipeline，见get_pipeline_type），按需注入量化配置，未开启 CPU Offload 时将整管移至 GPU，按需设置 Flash Attention 后端并调用transformer（或unet）的compile()，最后把 pipeline 挂到shared.image_model全局变量上。卸载时unload_image_model会释放对象并调用clear_torch_cache清理显存缓存。

关于自动加载：下次启动 Web UI 后，当你尝试生成图像时，系统会自动按上次保存的设置加载模型，无需再到 Model 页签手动点击 "Load"。这一点在源码中也有印证——generate函数（modules/ui_image_generation.py）会先检查shared.image_model is None，为空时用当前界面状态调用load_image_model完成隐式加载。

生成图像

Generate 页签的核心控件

保持在 "Image AI" 页面，切换到 "Generate" 子页签，输入 prompt 后点击 "Generate"。该页签的控件与默认值（均可通过user_data/settings.yaml持久化）如下：

控件	取值范围 / 默认	说明
Prompt / Negative Prompt	多行文本	负提示词在 CFG Scale 为 0 时会被忽略
LLM Prompt Variations	勾选框（默认关）	见下文
Width / Height	256–2048，步进 16，默认 1024	与宽高比联动，另带 "⇄ Swap" 交换按钮
Aspect Ratio	`1:1 Square`/`16:9 Cinema`/`9:16 Mobile`/`4:3 Photo`/`Custom`	切换时按 16 像素对齐自动重算宽高
Steps	1–100，默认 9	扩散去噪步数
CFG Scale	0.0–10.0，默认 0.0	界面提示：Z-Image Turbo 用 0.0，Qwen 用 4.0
Seed	数字，默认 -1	-1 表示随机
Batch Size	1–32，默认 1	并行批量，显存开销大
Sequential Count	1–128，默认 1	顺序重复生成 N 次

宽高比的处理逻辑在 modules/ui_image_generation.py：ASPECT_RATIOS定义了预设比例，apply_aspect_ratio依据当前宽高中较长的一边按 16 像素步进（STEP = 16）计算另一边，并把结果钳制在 256–2048 区间。

生成流程的源码走读

generate函数（modules/ui_image_generation.py）是 UI 与 API 共用的核心生成器，其流程为：

隐式加载：若shared.image_model为空，按当前 dtype/attention/量化等状态自动加载模型；
种子解析：image_seed为 -1 时取random.randint(0, 2**32 - 1)，解析结果写回state['image_seed_resolved']供 API 层读取；每个顺序批次使用seed + batch_idx；
流水线类型适配：按get_pipeline_type的结果决定 CFG 参数名——qwenimage用true_cfg_scale，其余（如 zimage）用guidance_scale；
进度回调：通过callback_on_step_end把每步进度推入队列，主线程以Batch i/N — Step s/total形式渲染 HTML 进度条，并响应 Stop 按钮（shared.stop_everything→pipe._interrupt）；
结果落盘：生成的每批图片以TGW_时间戳_seed_序号.png命名保存到user_data/image_outputs/日期/，并把完整生成参数（prompt、负提示词、宽高、比例、steps、seed、cfg、模型名、生成时间）以image_gen_settings键嵌入 PNG 元数据（PngInfo）。

"Gallery" 子页签基于image_outputs目录实现分页浏览（每页 32 张），点击历史图片可读取元数据查看参数，并通过 "Send to Generate" 一键回填到 Generate 页签复现出图；也支持拖入外部 PNG 查看其内嵌的生成设置。

模型专属设置

Z-Image-Turbo：请务必保持CFG Scale = 0、Steps = 9，且不要填写 Negative Prompt——该 CFG 值下负提示词会被直接忽略（与界面 info 提示 "Z-Image Turbo: 0.0 | Qwen: 4.0" 一致）。

从源码还能看到一个 Qwen-Image 专属细节：generate在调用 pipeline 前会为 qwenimage 流水线的 prompt 自动追加魔法后缀", Ultra HD, 4K, cinematic composition"（若尚未包含），调用后再还原原始 prompt（modules/ui_image_generation.py）。

LLM Prompt Variations

该功能让已加载的 LLM 在每次生成前自动改写你的提示词，显著提升画面创意度。前提是在左侧主 "Model" 页签加载一个文本 LLM。官方推荐的上手方案：

下载Qwen3-4B-Q3_K_M.gguf到textgen/user_data/models目录；
在 "Model" 页签的下拉框中选中该模型；
点击 Load。

然后回到 "Image AI" 页面勾选 "LLM Prompt Variations"。此后每次生成图片时 prompt 都会被 LLM 自动更新；若 "Sequential Count" 大于 1，则每个顺序批次都会重新生成一条新 prompt。

实现上，generate_prompt_variation（modules/ui_image_generation.py）把用户 prompt 与 "Variation Prompt" 文本框中的指令（默认指令见 modules/shared.py）拼成一条消息，走generate_chat_prompt+generate_reply的标准对话生成链路；生成时强制关闭思考模式（enable_thinking=False、reasoning_effort='low'），并对结果做了防御性清洗——剥离</think>、Qwen 风格的<|start|>assistant...思考块以及包裹引号。若未加载 LLM，会记录警告并直接沿用原始 prompt，不会中断出图。

文档以 promptPhoto of a beautiful woman at night under moonlight给出的对比示例显示，开启 LLM 变体后画面的细节丰富度与构图创意有明显提升（原图见 docs/Image Generation Tutorial.md 中的对比拼图）。

通过 API 生成图像

项目内置了 OpenAI 兼容的图像生成 API。启动方式二选一：

给 start 脚本追加--api标志，如./start_linux.sh --api；
或把--api写入 user_data/CMD_FLAGS.txt 后重启 Web UI。

--api相关参数定义在 modules/shared.py：API 服务默认监听5000 端口（--api-port可改），还支持--api-key鉴权等选项。调用示例（即文档原例）：

curl http://127.0.0.1:5000/v1/images/generations \ -H "Content-Type: application/json" \ -d '{ "prompt": "an orange tree", "steps": 9, "cfg_scale": 0, "batch_size": 1, "batch_count": 1 }'

请求参数详解

API 请求体由ImageGenerationRequest（modules/api/typing.py）定义，字段与默认值如下：

字段	类型 / 默认值	说明
`prompt`	str，必填	图像提示词
`negative_prompt`	str，默认`""`	负提示词
`size`	str，默认`"1024x1024"`	`WIDTHxHEIGHT`格式；解析失败时回退 1024x1024
`steps`	int，默认 9，≥1	去噪步数
`cfg_scale`	float，默认 0.0，≥0	与 UI 的 CFG Scale 对应
`image_seed`	int，默认 -1	-1 为随机
`batch_size`	int，默认取`n`，≥1	并行批量（显存开销大）
`n`	int，默认 1	OpenAI 兼容的`batch_size`别名，未显式传`batch_size`时由校验器回填
`batch_count`	int，默认 1	顺序批量数
`response_format`	str，默认`b64_json`	决定返回`b64_json`或>`model`/`user`	可选	OpenAI 兼容占位字段

响应与行为细节

处理函数generations（modules/api/images.py）复用 UI 的generate(state, save_images=False)生成器并取最终结果，行为要点：

前置条件：必须先通过 UI 加载图像模型，否则返回ServiceUnavailableError（"No image model loaded. Load a model via the UI first."）——API 层本身不加载模型，shared.image_model为空即报错；
每张图自带元数据：响应中的每个 base64 PNG 都内嵌与 UI 一致的image_gen_settings元数据，且按批次递增 seed（base_seed + idx // batch_size），便于溯源复现；
返回值：data数组中每个元素含revised_prompt与b64_json（或url形式的 contenteditable="false">【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析