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本文以 TextGentextgen仓库的 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.batLinux运行./start_linux.shmacOS运行./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 MiBbnb-8bit16301 MiBbnb-8bit CPU Offload16235 MiBbnb-4bit11533 MiBbnb-4bit CPU Offload7677 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_8bitTrue)打包成PipelineQuantizationConfigbnb-4bit采用 NF4 量化类型、bfloat16 计算精度并开启双重量化bnb_4bit_use_double_quantTruetorchao 系列将torchao-int8wo / torchao-fp4 / torchao-float8wo映射为int8wo / fp4_e2m1 / float8wo通过TorchAoConfig应用。文档特别指出torchao选项支持torch.compile以获得更快的生成速度其中float8wo在 RTX 40 系及更新显卡上可获得原生硬件加速。其他加载选项Model 页签还有以下可配置项默认值来自 modules/shared.py选项取值默认值说明Data Typebfloat16/float16bfloat16官方建议现代 GPU 使用 bfloat16Attention Backendsdpa/flash_attention_2sdpaFlash Attention 需要兼容 GPUCompile Model勾选框关闭首次运行慢之后推理更快CPU Offload勾选框关闭低显存 GPU 适用速度慢但省显存加载主流程load_image_modelmodules/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 / Height256–2048步进 16默认 1024与宽高比联动另带 ⇄ Swap 交换按钮Aspect Ratio1:1 Square/16:9 Cinema/9:16 Mobile/4:3 Photo/Custom切换时按 16 像素对齐自动重算宽高Steps1–100默认 9扩散去噪步数CFG Scale0.0–10.0默认 0.0界面提示Z-Image Turbo 用 0.0Qwen 用 4.0Seed数字默认 -1-1 表示随机Batch Size1–32默认 1并行批量显存开销大Sequential Count1–128默认 1顺序重复生成 N 次宽高比的处理逻辑在 modules/ui_image_generation.pyASPECT_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若尚未包含调用后再还原原始 promptmodules/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_variationmodules/ui_image_generation.py把用户 prompt 与 Variation Prompt 文本框中的指令默认指令见 modules/shared.py拼成一条消息走generate_chat_promptgenerate_reply的标准对话生成链路生成时强制关闭思考模式enable_thinkingFalse、reasoning_effortlow并对结果做了防御性清洗——剥离/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.pyAPI 服务默认监听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 请求体由ImageGenerationRequestmodules/api/typing.py定义字段与默认值如下字段类型 / 默认值说明promptstr必填图像提示词negative_promptstr默认负提示词sizestr默认1024x1024WIDTHxHEIGHT格式解析失败时回退 1024x1024stepsint默认 9≥1去噪步数cfg_scalefloat默认 0.0≥0与 UI 的 CFG Scale 对应image_seedint默认 -1-1 为随机batch_sizeint默认取n≥1并行批量显存开销大nint默认 1OpenAI 兼容的batch_size别名未显式传batch_size时由校验器回填batch_countint默认 1顺序批量数response_formatstr默认b64_json决定返回b64_json或>model/user可选OpenAI 兼容占位字段响应与行为细节处理函数generationsmodules/api/images.py复用 UI 的generate(state, save_imagesFalse)生成器并取最终结果行为要点前置条件必须先通过 UI 加载图像模型否则返回ServiceUnavailableErrorNo image model loaded. Load a model via the UI first.——API 层本身不加载模型shared.image_model为空即报错每张图自带元数据响应中的每个 base64 PNG 都内嵌与 UI 一致的image_gen_settings元数据且按批次递增 seedbase_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），仅供参考