说实话接到 Qwen-Image-2.1 的云端部署任务时我一开始是有点轻敌的。毕竟这些年跑过的生成模型不少了心想无非是装个驱动、拉个权重、起个服务。真上手才发现光是把环境理干净、让请求稳定返回就够喝一壶的。这篇笔记我希望写得“足够傻”把选机型、算显存、装驱动、下权重、写服务、压测、上生产这几件事全部串起来每一步都有命令、有参数、有我踩过的坑。这篇内容适合两类人第一次在云上部署这类图像生成模型的新手以及被环境折腾到怀疑人生的老手。目标就一个——让你从零开始在一台空的 GPU 云服务器上把 Qwen-Image-2.1 这套服务跑起来并且能稳定对外提供图片生成接口。1. 动手部署前先算清楚这笔“显存账”1.1 模型体积和精度选择部署图像生成模型第一件事不是敲命令而是算账。Qwen-Image-2.1 的模型仓库里一般会同时提供 BF16 权重和量化权重。BF16 文件体积大但效果最稳量化版本体积小、加载快但在复杂构图和细节纹理上会有细微变化。你至少要预留模型文件两倍以上的磁盘空间因为加载到 GPU 时还会额外生成序列化缓存和临时文件。以我这次部署的实例为例权重在 40GB 左右精度选 BF16加载后显存大约占 50GB 上下如果选量化版本权重能降到 16GB 以内但推理时部分层仍会用 BF16 计算实际占用会略高于文件体积。这个数字会因为版本分支不同而变化不用死记。关键是学会看仓库里的config.json和index.json里面声明了参数规模和依赖项。我的建议是如果没有多机需求优先选原始 BF16 权重不要一上来就量化。想省显存后面随时可以换量化版本代码上的改动通常只是替换文件路径。提示以上数字只是参考一切以你从模型托管平台仓库看到的实际文件清单为准。不要照抄别人的绝对路径要学会看仓库结构。1.2 GPU 实例选型与成本估算云服务器选型显存是第一硬指标。跑 Qwen-Image-2.1 这类模型我建议至少 24GB 显存起步。如果 24GB 的卡装不下就上 48GB 或 80GB。选实例时看三个维度GPU 显存、CPU 核数、数据盘大小。模型加载本身不吃 CPU但图像后处理、中文文本编码、并发调度都会吃 CPU建议至少配 8 核。数据盘建议 300GB 起步因为权重文件之外模型加载时的临时目录也可能吃掉几十 GB。成本上按量付费适合技术验证包月包年适合长期跑服务。很多人只盯着 GPU 单价忘了三笔隐藏费用快照费用、公网 IP 费用、跨区域流量费。一台 GPU 实例关机后系统盘和数据盘仍然按容量计费公网 IP 如果不释放也一样收钱。所以如果你只是阶段测试记得把数据备份后释放实例或选择支持“关机不收费”的套餐能省不少钱。我习惯先把最小配置跑通再根据压测结果横向扩容。1.3 磁盘、带宽和镜像规划镜像区域和实际使用区域要放在一起。这里有个容易忽略的细节主流云平台往往有多个可用区镜像和快照只能在同一区域使用。如果别人帮你开通了某个区域的 GPU 配额但你在另一个区域创建实例会发现根本选不到那个 GPU 型号。我建议先确认目标区域的 GPU 库存再创建自定义镜像不要把顺序搞反。带宽方面图像生成服务的出站流量很大。一张 1024x1024 的图PNG 体积就可能到 10MB 以上。如果业务并发高带宽没买够用户会感觉“生成很快但下载很慢”。建议按“单图大小 × 每秒请求数”粗算再额外留 20% 余量。数据盘用 SSD模型加载时 IOPS 很重要机械盘容易把首字延迟拖长。2. 系统初始化从空机器到能跑模型的那几步2.1 系统镜像与 NVIDIA 驱动安装系统镜像我选 Ubuntu 22.04 LTS原因很简单开源框架对它的支持最好遇到问题搜到的解决方案也最多。拿到机器后第一步是更新系统包然后装 NVIDIA 驱动。不要依赖云平台控制台的“自动安装驱动”那个版本经常滞后后面跑框架时容易出兼容问题。自己装更可控sudo apt update sudo apt upgrade -y sudo apt install -y build-essential dkms linux-headers-$(uname -r) sudo ubuntu-drivers install --gpgpu装完用nvidia-smi确认 GPU 能被识别。新版驱动自带 CUDA 运行时不需要再单独下载大而全的 CUDA Toolkit。这里有个坑如果你先安装了 conda 再装驱动PATH 里的nvcc可能来自 conda 的 stub版本和驱动对不上。建议先装驱动再建 conda 环境在环境内通过 pip 依赖拿到匹配的 CUDA 库。我实测在驱动 545 和 550 上跑同样的模型推理速度差异不明显但 550 对后续部署相关框架的兼容性更好。如果你准备用官方 docker 方案直接按镜像要求的驱动最低版本装不用追新。驱动装好后重启一次确认nvidia-smi稳定显示再继续往下走。2.2 conda 环境与 Python 版本选择接下来创建 conda 环境。很多教程让直接pip install torch但 torch 版本和 CUDA 的匹配问题往往在运行时才暴露。我建议先把 conda 装好再隔离一个干净环境# 从 Miniconda 官方渠道获取最新版安装脚本 bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3 source $HOME/miniconda3/bin/activate conda create -n qwenimg python3.11 -y conda activate qwenimgPython 选 3.10 或 3.11 都可以不建议用太老的版本也别为了尝鲜选刚发布的新版本。记住一个原则不要在系统 Python 里直接 pip install因为后面装依赖时会互相污染。conda 环境的好处是万一环境搞坏了直接删掉重建不用动驱动。注意很多云厂商自带的镜像里已经有 Anaconda但那个是系统级的权限和路径容易乱。我建议额外装 Miniconda把conda activate base写进.bashrc这样每次登录进入干净环境后面所有操作都发生在用户目录下可控性高很多。2.3 SSH 免密登录与终端复用对远程服务器来说SSH 免密是刚需。用ssh-keygen -t ed25519生成密钥然后把公钥追加到服务器的~/.ssh/authorized_keys。之后建议用tmux保持长任务因为下载 40GB 权重和加载模型都是长时间操作SSH 断线一次任务就没了。我吃过亏权重下载到 80% 时 SSH 断开整个重来。后续所有耗时命令我都会放进tmuxtmux new -s download # 在 session 里执行耗时命令 tmux detach # 下次用 tmux attach -t download 回来这个习惯在安装依赖、跑压测时能救你很多次。另外把本地私钥加入ssh-agent可以免去每次输入 passphrase 的烦恼。远程操作时不要轻易关终端窗口宁可多用tmux包一层。3. 下载模型权重用托管平台拉取国内节点最稳3.1 安装工具并拉取权重在云服务器上下载 Qwen-Image-2.1 权重我首选 ModelScope。理由很实际国内节点直连速度快而且有断点续传机制。先装工具pip install -U modelscope然后查看模型仓库 ID例如Qwen/Qwen-Image-2.1执行modelscope download --model Qwen/Qwen-Image-2.1 --local_dir /data/models/Qwen/Qwen-Image-2.1--local_dir是重点。默认情况下权重会下载到~/.cache/modelscope但临时目录空间经常不够而且系统重装后缓存直接没了。指定到数据盘后后续做软链接也方便。下载过程中仔细观察日志模型仓库会先拉一个元信息 JSON再并发下载分片。中途失败没关系重复执行同一条命令会从断点继续。3.2 目录组织与软链接技巧我强烈建议把模型放在一个独立的目录树里不要散落在各处。例如/data/models/ Qwen/ Qwen-Image-2.1/ config.json model.safetensors ...以后换机器时直接把/data/models整体迁移即可。如果多台实例共享同一块网络存储可以用符号链接把模型目录指向实际存储位置ln -s /mnt/nfs/models/qwen-image-2.1 /data/models/Qwen/Qwen-Image-2.1这样推理代码不需要改路径。另外下载工具会在目录里保留一些缓存文件部署时不要因为“看不到模型文件”就随手删掉。有些校验逻辑依赖它。我见过有人为了省空间把模型目录里的非 safetensors 文件全删掉结果加载时因为缺少 tokenizer 配置直接崩掉。3.3 校验文件完整性下载完成后别急着启动服务。先校验一遍文件完整性。最省事的做法是重新执行一次下载命令日志里会显示“文件已存在、跳过”这样能确认没有缺包。如果想精确校验看仓库是否提供校验文件用md5sum -c批量检查。我碰到过一次诡异情况权重文件大小都对但加载到一半报unexpected key in module。后来发现是并发下载工具把某个文件名写成了小写后缀Linux 下被系统判定为不同文件。解决方法不复杂对照仓库文件列表把文件名统一修正重新加载就正常了。所以这里提醒你完整性校验这一步真的不能跳过。4. 用推理库把模型跑通最小可用路径4.1 推理依赖安装权重就绪后先做最小验证不要一上来就写 HTTP 服务。安装依赖pip install torch2.1 diffusers0.30 transformers accelerate safetensors sentencepiece安装完检查 torch 能否调用 GPUpython -c import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))看到True加显卡型号就说明正常。如果torch.cuda.is_available()返回False不要怀疑 GPU多半是 conda 环境里残留了 CPU 版 torch直接卸载重装对应 CUDA 版本的 torch 即可。4.2 写一个最小生成脚本以官方仓库示例为参考我这里给一个通用结构import torch from diffusers import AutoPipelineForText2Image pipe AutoPipelineForText2Image.from_pretrained( /data/models/Qwen/Qwen-Image-2.1, torch_dtypetorch.bfloat16, ) pipe.to(cuda) prompt 一只穿着宇航服的短毛猫站在月球环形山边缘远景是地球电影感光线 image pipe( promptprompt, num_inference_steps30, guidance_scale3.5, ).images[0] image.save(test.png)如果AutoPipelineForText2Image识别不了这个仓库就用官方 README 里给的 pipeline 类名。参数部分不要照抄因为你下载的可能是量化版本torch_dtype应该改成float16或对应量化类型的加载方式。跑出图就算通了如果报错八成是缺依赖或 dtype 不匹配。4.3 显存不足与加速设置验证跑通后再看显存占用。用nvidia-smi观察。如果直接 OOM按顺序试这几招把num_inference_steps降下来比如从 50 降到 30把torch_dtype从bfloat16换成float16显存占用更低再不行就用pipe.enable_model_cpu_offload()把不参与当前计算的层暂存到内存。图像生成是典型的延迟敏感任务。我实测启用torch.compile在某些模型上收益并不明显反而第一次执行会多几十秒的编译时间。如果你的目标是先跑通 API不建议默认开启如果追求极限吞吐单独压测后再决定。5. 把单机脚本变成在线服务FastAPI 封装5.1 实现一个图像生成接口最小跑通之后需要对外提供 HTTP 接口。我习惯用 FastAPI 封装自带 Swagger 文档和参数校验代码量少。接口大致长这样from fastapi import FastAPI from pydantic import BaseModel import torch, io, base64 from diffusers import AutoPipelineForText2Image app FastAPI() pipe None class GenerateRequest(BaseModel): prompt: str num_inference_steps: int 30 guidance_scale: float 3.5 width: int 1024 height: int 1024 app.on_event(startup) def load_model(): global pipe pipe AutoPipelineForText2Image.from_pretrained( /data/models/Qwen/Qwen-Image-2.1, torch_dtypetorch.bfloat16, ) pipe.to(cuda) app.post(/generate) def generate(req: GenerateRequest): if pipe is None: return {error: model not loaded} image pipe( promptreq.prompt, num_inference_stepsreq.num_inference_steps, guidance_scalereq.guidance_scale, widthreq.width, heightreq.height, ).images[0] buf io.BytesIO() image.save(buf, formatPNG) encoded base64.b64encode(buf.getvalue()).decode(utf-8) return {image_base64: encoded}这里的app.on_event(startup)在最新 FastAPI 里已标记为废弃但很多生产代码仍能运行。如果使用新版本可以改成 lifespan 事件。关键点模型加载必须在进程启动时完成不能在第一个请求时才加载否则首次响应会超时。5.2 并发控制与队列设计GPU 做图像生成时多个并发请求同时进来会互相抢占显存甚至 OOM。FastAPI 本身是异步框架但它调用的 PyTorch 是同步阻塞的多 worker 反而会拖垮显存。最简单的做法是加一个信号量把并发数限制为 1import asyncio from fastapi import HTTPException sem asyncio.Semaphore(1) app.post(/generate) async def generate(req: GenerateRequest): if sem.locked(): raise HTTPException(status_code503, detailbusy) async with sem: return await asyncio.to_thread(run_generate, req)这里把核心生成函数放到run_generate里用to_thread避免阻塞事件循环。并发设为 1 虽然牺牲了吞吐但胜在稳定。如果你的 GPU 显存实在充裕可以把模型放进多卡环境用专门的连续批处理框架来提升并发。不过对图像生成场景第一优先级是单请求延迟稳定之后再谈并发。5.3 启动、自测与压测启动服务uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1注意--workers 1不要开多个 worker。多个 worker 会各自加载一份模型到显存立刻 OOM。自测用 curlcurl -X POST http://127.0.0.1:8000/generate \ -H Content-Type: application/json \ -d {prompt:一只戴帽子的企鹅} \ -o resp.json然后用 Python 解码 JSON 里的 base64 字段保存图片。压测可以用wrk或写简单脚本。我自己的记录是单请求平均 8 秒左右4 并发时显存已经接近上限加上信号量之后反而更稳定。如果你需要更高的 QPS建议横向加 GPU 实例而不是增加 worker 数量。6. 生产化鉴权、代理、监控与省钱6.1 暴露接口前的鉴权服务跑在0.0.0.0:8000如果直接开公网端口等于裸奔。至少加一层 API Key。最简单的是在 FastAPI 里加依赖from fastapi import Header, HTTPException API_KEY your-random-api-key def check_key(authorization: str Header(default)): if authorization ! fBearer {API_KEY}: raise HTTPException(status_code401, detailunauthorized)然后在路由里加上dependencies[Depends(check_key)]。更稳妥的做法是让 Caddy 或 Nginx 做 TLS 终止和反向代理FastAPI 不直接暴露公网。我比较推荐 Caddy配置极简自动申请证书三行配置就能把8000端口包起来。6.2 监控与进程守护生产环境不要靠人盯着。用 systemd 托管 uvicorn 进程崩溃自动拉起[Unit] Descriptionqwen-image api Afternetwork.target [Service] Userubuntu WorkingDirectory/home/ubuntu/qwen-api EnvironmentPATH/home/ubuntu/miniconda3/envs/qwenimg/bin ExecStart/home/ubuntu/miniconda3/envs/qwenimg/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1 Restartalways RestartSec5 [Install] WantedBymulti-user.target监控指标至少看四个GPU 显存占用、GPU 利用率、推理队列长度、平均响应时间。可以用nvidia-smi --query-gpumemory.used,utilization.gpu --formatcsv -l 1输出到日志再交给监控平台。如果只是小规模使用写一个定时脚本检查/health接口失败就重启服务或触发告警也够用。6.3 云成本控制技巧最后说省钱。GPU 按量付费很贵我的经验是把验证、压测、正式发布拆成三张账单。验证期用最小卡型加量化权重能跑通就行压测期再用目标卡型跑满 30 分钟记录真实吞吐正式上线前把机器做成自定义镜像这样以后扩容新实例时不用重装环境和权重十分钟就能拉起一台新的。如果你的业务有明显波峰波谷可以用定时任务在每天低峰期关机、高峰期开机。不要小看这个操作一个月能省一半钱。但关机前记得把生成的图片归档到外部存储因为本地数据盘的快照照常收费。另外公网 IP 尽量绑定使用每次释放再申请都会换 IP会影响回调地址排查问题也很麻烦。最后再分享一个我自己的实操习惯所有修改过的配置文件都放进 Git 仓库并且把/data/models目录做成只读挂载。这样万一哪次升级框架把环境搞坏直接用镜像重建十分钟恢复服务不用再从零拉权重。希望这篇教程能帮你免掉那些我踩过的坑顺利把服务跑起来。
