简介:本文面向开发者、算法工程师与运维人员,给出可落地的开源4K文生图部署调用方案。内容覆盖环境准备、真实依赖安装、权重下载、显存配置、文生图与图像编辑代码、验收清单、排错优化和合规建议,帮助读者快速搭建本地或云端图像生成服务。
本教程面向希望快速落地高分辨率文生图能力的开发者、算法工程师与运维人员,目标是在本地或云端环境中完成一套可复用的开源文生图流程:通过文本生成基础图像,再输出 4096×4096、约 16MP 的 4K 图像;同时覆盖图像编辑、结果验证、性能排错与生产优化。
读者完成本文后,应能够:
需要说明:本教程不承诺固定生成速度。生成耗时受显卡型号、显存大小、分辨率、步数、并发数、模型是否常驻内存等因素影响,必须以实际环境测试为准。
高分辨率文生图常见有两类路线:
对于大多数开源文生图模型,直接原生生成 4096×4096 对显存要求极高,且容易出现显存溢出、推理缓慢、细节不稳定等问题。因此,本文采用更稳妥、更易复现的方案:
该方案的优点:
如果你需要原生 4096×4096 生成,建议单独评估显存、模型分块策略、CPU Offload、量化推理等方案,并预留更充分的测试时间。
以下配置按“1024 基础图生成 + 4x 上采样到 4096×4096”的目标给出。
| 配置级别 | 建议显存 | 适用场景 | 说明 |
|---|---|---|---|
| 最低可用 | 12GB | 开发调试、单次生成 | 建议使用 fp16、batch size 为 1 |
| 推荐 | 16GB 及以上 | 稳定开发、轻量服务 | 可常驻模型,响应更稳定 |
| 生产推荐 | 24GB 及以上 | 批量任务、云端服务 | 可预留余量应对并发与监控开销 |
如果显卡显存低于 12GB,建议使用 CPU Offload、降低分辨率、减少步数,或改用云端 GPU 实例。
云端部署建议优先选择带独立 GPU 的计算实例,例如 L4、A10、4090 等常见图形或计算卡实例。采购或租用实例时,应重点关注显存容量,而不是仅关注 CPU 核数。
推荐使用以下软件组合:
读者最好具备以下基础:
建议单独创建虚拟环境,避免与其他项目依赖冲突。
python3 -m venv venvsource venv/bin/activatepip install --upgrade pip
安装 PyTorch。以下示例适配 CUDA 12.1:
pip install torch==2.3.1 torchvision==0.18.1 --index-url https://download.pytorch.org/whl/cu121
安装其余依赖:
pip install diffusers==0.30.2 transformers==4.44.2 accelerate==0.33.0pip install safetensors==0.4.5 huggingface-hub==0.24.6 pillow==10.4.0pip install fastapi==0.115.2 uvicorn==0.30.6
如果所在网络无法直接访问 Hugging Face,可配置镜像环境变量,或使用可访问的代理。若模型仓库需要登录,请在 Hugging Face 网站接受对应模型协议后,再执行登录命令。
执行:
huggingface-cli login
下载文生图基础模型:
huggingface-cli download stabilityai/stable-diffusion-xl-base-1.0 \--local-dir ./models/sdxl
下载 4 倍上采样模型:
huggingface-cli download stabilityai/stable-diffusion-x4-upscaler \--local-dir ./models/sd-x4-upscaler
下载图像编辑模型:
huggingface-cli download diffusers/stable-diffusion-xl-1.0-inpainting-0.1 \--local-dir ./models/sdxl-inpaint
如果下载失败,建议检查三件事:
权重文件通常会占用数 GB 到数十 GB,请预留充足存储空间。
在运行模型前,先执行算力自检,确认 PyTorch 能识别显卡。
import torchif not torch.cuda.is_available():raise RuntimeError("未检测到可用 GPU,请检查 NVIDIA 驱动、CUDA 和 PyTorch 安装")print("PyTorch:", torch.__version__)print("GPU:", torch.cuda.get_device_name(0))print("显存总量:", torch.cuda.get_device_properties(0).total_memory / 1024**2, "MB")
如果这里报错,应优先排查驱动、CUDA、PyTorch 版本,而不是怀疑模型本身。
以下代码使用 Stable Diffusion XL 生成 1024×1024 基础图。固定随机种子便于复现。
import torchfrom diffusers import StableDiffusionXLPipelinemodel_path = "./models/sdxl"pipe = StableDiffusionXLPipeline.from_pretrained(model_path,torch_dtype=torch.float16)if torch.cuda.is_available():pipe = pipe.to("cuda")pipe.enable_vae_slicing()else:# 无 GPU 时使用 CPU Offload,速度较慢,仅用于调试pipe.enable_model_cpu_offload()prompt = "a cinematic product photo of a silver smartwatch on a marble table, soft studio lighting, high detail, clean background"negative_prompt = "blurry, low quality, watermark, text, extra fingers, distorted logo, oversaturated"generator = torch.Generator("cuda").manual_seed(42) if torch.cuda.is_available() else torch.Generator("cpu").manual_seed(42)image = pipe(prompt=prompt,negative_prompt=negative_prompt,height=1024,width=1024,num_inference_steps=30,guidance_scale=7.0,generator=generator).images[0]image.save("base_1024.png")
参数建议:
基础图生成后,使用真实上采样模型生成 4K 图像。
import torchfrom PIL import Imagefrom diffusers import StableDiffusionUpscalePipelinebase_image = Image.open("base_1024.png").convert("RGB")upscaler = StableDiffusionUpscalePipeline.from_pretrained("./models/sd-x4-upscaler",torch_dtype=torch.float16)if torch.cuda.is_available():upscaler = upscaler.to("cuda")else:upscaler.enable_model_cpu_offload()upscale_generator = torch.Generator("cuda").manual_seed(42) if torch.cuda.is_available() else torch.Generator("cpu").manual_seed(42)upscaled = upscaler(prompt=prompt,image=base_image,num_inference_steps=20,guidance_scale=0.0,generator=upscale_generator).images[0]upscaled.save("output_4096.png")
此时输出图像尺寸应为 4096×4096,即约 16MP。
如果需要在参考图上局部修改,例如替换背景、移除元素、增加商品道具,可使用 Inpainting 模型。
准备两张图:
source.png:原始图像;mask.png:遮罩图,白色区域表示需要重绘的区域,黑色区域保持不变。示例:
import torchfrom PIL import Imagefrom diffusers import AutoPipelineForInpaintingedit_pipe = AutoPipelineForInpainting.from_pretrained("./models/sdxl-inpaint",torch_dtype=torch.float16)if torch.cuda.is_available():edit_pipe = edit_pipe.to("cuda")else:edit_pipe.enable_model_cpu_offload()source_image = Image.open("source.png").convert("RGB").resize((1024, 1024))mask_image = Image.open("mask.png").convert("L").resize((1024, 1024))edited_image = edit_pipe(prompt="replace the background with a warm sunset by the sea",negative_prompt="blurry, low quality, distorted objects",image=source_image,mask_image=mask_image,height=1024,width=1024,num_inference_steps=30,guidance_scale=7.5,generator=torch.Generator("cuda").manual_seed(42)).images[0]edited_image.save("edited_1024.png")
编辑完成后再调用上采样模型,即可获得 4096×4096 编辑结果。
可将生成能力封装为 FastAPI 接口,便于业务系统调用。以下示例仅生成 1024 基础图,生产环境应补充认证、限流、日志和审核。
from fastapi import FastAPIfrom pydantic import BaseModelimport torchfrom diffusers import StableDiffusionXLPipelineapp = FastAPI()pipe = StableDiffusionXLPipeline.from_pretrained("./models/sdxl",torch_dtype=torch.float16).to("cuda")class GenerateRequest(BaseModel):prompt: strnegative_prompt: str = ""steps: int = 30guidance: float = 7.0seed: int = 42@app.post("/generate")def generate(req: GenerateRequest):generator = torch.Generator("cuda").manual_seed(req.seed)image = pipe(prompt=req.prompt,negative_prompt=req.negative_prompt,height=1024,width=1024,num_inference_steps=req.steps,guidance_scale=req.guidance,generator=generator).images[0]output_path = f"outputs/{req.seed}.png"image.save(output_path)return {"status": "ok","path": output_path,"base_size": "1024x1024","next_step": "call upscale pipeline to generate 4096x4096"}
启动服务:
uvicorn app:app --host 0.0.0.0 --port 8000
调用示例:
curl -X POST http://127.0.0.1:8000/generate \-H "Content-Type: application/json" \-d '{"prompt":"a futuristic electric car in a city at night","seed":123}'
| 参数 | 作用 | 调整建议 | 对速度、质量、显存的影响 |
|---|---|---|---|
| prompt | 正向提示词 | 描述主体、场景、光线、风格、镜头 | 越具体通常越符合预期 |
| negative_prompt | 负向提示词 | 抑制模糊、低质量、水印、畸变等 | 对画面瑕疵抑制有明显帮助 |
| num_inference_steps | 去噪步数 | 调试 20~30,生产 30~40 | 步数越多通常细节更多,但耗时增加 |
| guidance_scale | 提示词引导强度 | 常见 6~8,过高易僵硬 | 影响提示词贴合度和画面自然度 |
| seed | 随机种子 | 固定种子用于复现 | 固定后可比较不同参数效果 |
| height/width | 输出分辨率 | 基础图建议 1024 或 1536 | 分辨率越高越耗显存和算力 |
| batch size | 批大小 | 显存不足时设为 1 | 越大吞吐越高,但显存压力越大 |
| torch_dtype | 计算精度 | 优先 fp16/bf16 | 可降低显存占用,略微增加精度风险 |
完成生成后,建议按以下清单验收。
| 验收项 | 检查方法 | 通过标准 |
|---|---|---|
| 文件是否生成 | 查看输出路径 | 文件存在且可打开 |
| 分辨率是否达标 | 用 Pillow 检查尺寸 | 最终输出为 4096×4096 |
| 画面是否符合提示词 | 人工抽检 | 主体、风格、场景基本符合要求 |
| 随机种子是否可复现 | 固定 seed 重复生成 | 参数一致时结果稳定一致 |
| 单次耗时是否可记录 | 记录开始和结束时间 | 能形成基线数据 |
| 显存峰值是否可接受 | 使用 nvidia-smi 观察 | 未频繁触发 OOM 或降级 |
| 失败样例是否留存 | 保存 prompt、seed、参数 | 便于后续复盘和优化 |
检查图像尺寸示例:
from PIL import Imageim = Image.open("output_4096.png")print(im.size)
预期输出:
(4096, 4096)
观察显存使用:
watch -n 1 nvidia-smi
记录耗时示例:
/usr/bin/time -v python generate.py
常见表现:进程中断、CUDA out of memory、生成到一半失败。
排查建议:
num_inference_steps;batch size 保持为 1;pipe.enable_model_cpu_offload();可能原因:
优化建议:
检查以下事项:
seed;建议为每次生成记录:prompt、negative_prompt、steps、guidance、seed、模型版本、依赖版本。
可能原因:
建议:
检查:
huggingface-cli login;生产环境中必须补充以下内容:
本文基于真实开源模型和依赖版本,给出了一套可落地的 4K 文生图方案:
上线前建议完成以下落地清单:
requirements.txt;