1. 项目概述为什么现在必须亲手部署 Qwen-Image-2.1 到云端Qwen-Image-2.1 是通义实验室发布的多模态大模型它不是简单的“图片识别工具”而是一个能真正理解图像语义、生成高质量描述、执行跨模态推理比如“把这张街景图改写成一段符合新闻稿风格的文字”、甚至支持可控图像编辑的视觉语言联合模型。我去年在做电商商品图智能打标系统时试过本地跑 Qwen-Image-1.5结果发现它对服饰纹理、包装细节这类高精度视觉特征的理解偏差很大——同一张连衣裙图模型会把“雪纺材质”识别成“棉麻”把“金属拉链头”说成“塑料扣件”。直到 Qwen-Image-2.1 发布后我在 ModelScope 上跑 demo发现它对材质、光影、构图逻辑的建模明显更扎实尤其在中文语境下的描述习惯上用词更自然比如不会生硬套用英文直译的“sleeveless top”而是准确输出“无袖上衣”还带上下文判断“适合夏季通勤穿着”。但问题来了ModelScope 官方 demo 页面虽然开箱即用却存在三个硬伤。第一是并发限制——当团队里五个人同时上传测试图页面直接卡死在“加载中”后台日志显示请求被限流第二是隐私风险所有上传的图片都会经过 ModelScope 的 CDN 节点而我们客户明确要求“图像数据不出内网”第三是定制化缺失比如我们需要把模型输出强制接入企业微信机器人但官方 Gradio 界面根本不提供 Webhook 配置入口。所以“云端部署”不是为了赶时髦而是解决真实业务瓶颈的刚需既要保留公有云的弹性算力又要掌控数据流向、接口协议和响应逻辑。这里说的“云端”特指阿里云 ECS 实例 NAS 共享存储 SLB 负载均衡的组合方案而不是泛泛而谈的“上云”。为什么选阿里云不是因为品牌而是实测对比同样配置的 4×A10 GPU 实例在阿里云上跑 Qwen-Image-2.1 的单图推理耗时比 AWS g4dn.xlarge 平均快 1.8 秒关键在于阿里云的 RDMA 网络对多卡 NCCL 通信优化更激进我们在做分布式推理时8 卡并行的通信开销比 AWS 低 37%。至于 Gradio 和 ModelScope它们不是可选项而是必选项——Gradio 提供了最轻量级的 Web UI 快速验证能力ModelScope 则是 Qwen-Image-2.1 官方模型权重和依赖包的唯一可信源所有 GGUF 格式量化版本包括你搜到的 “qwen-image-2.1 uncensored gguf”都必须从 ModelScope 下载校验否则模型加载会报 SHA256 不匹配错误。我见过太多人直接从第三方论坛下载 GGUF 文件结果跑起来全是乱码输出最后查了一周才发现 checksum 对不上。这个教程的目标很明确让你在 2 小时内从零开始在阿里云上搭起一个稳定、可扩展、带基础鉴权的 Qwen-Image-2.1 服务端。它不教你怎么调参也不讲模型原理只聚焦一件事——让模型在你的云服务器上“活下来”并且能被你自己的业务系统调用。适合三类人需要快速验证模型效果的算法工程师、要集成到内部系统的后端开发、以及负责 AI 基础设施运维的 SRE。如果你还在用本地笔记本跑 demo或者只依赖 ModelScope 网页版那这篇就是为你写的。2. 整体架构设计与技术选型逻辑2.1 为什么放弃 Docker Compose坚持裸机部署看到标题里“保姆级教程”很多人第一反应是“肯定用 Docker”。但我在实际落地 7 个客户项目后明确放弃了 Docker Compose 方案。原因很实在Qwen-Image-2.1 的显存占用太“贪”。官方文档说最低需要 24GB 显存但实测发现当 batch_size1 且输入图分辨率超过 1024×1024 时A10 卡24GB会触发 CUDA out of memory而 A10040GB在 batch_size2 时也接近临界值。Docker 默认的 cgroups 内存限制机制在 GPU 资源调度上存在不可控延迟——容器启动后NVIDIA Container Toolkit 分配显存的时间波动在 300ms~1.2s 之间这导致 Gradio 的 health check 经常误判服务未就绪进而反复重启容器。我们曾在一个生产环境里连续 3 天出现“服务启动成功但首次请求超时”的问题最后抓取 nvidia-smi 日志才发现容器内核模块加载比预期晚了 800ms。所以最终方案是ECS 实例裸装 Python 环境 systemd 服务管理。好处有三一是显存分配确定性高nvidia-smi -L输出的设备列表和CUDA_VISIBLE_DEVICES环境变量能 100% 对应二是进程级监控更直接systemctl status qwen-image能立刻看到 Python 进程 PID 和 GPU 显存占用三是调试链路极短出问题直接journalctl -u qwen-image -f查日志不用进容器再查一层。当然裸机部署的代价是环境一致性变差所以我们用 requirements.txt 锁死所有依赖版本并在初始化脚本里加入pip install --force-reinstall强制覆盖避免系统自带的旧版 torch 干扰。2.2 Gradio 为何必须加身份验证不加会怎样Gradio 默认是“谁都能访问”的这在内网测试没问题但一旦暴露到公网就是灾难。去年有个客户把 Gradio 服务绑了 SLB 公网 IP没加任何认证结果三天后发现 API 调用量暴增到每天 2 万次——全是来自境外的爬虫专门批量上传色情图片测试模型鲁棒性。更麻烦的是这些请求触发了阿里云的 DDoS 防护阈值导致整个 SLB 实例被临时封禁 2 小时连带影响了其他业务。所以本教程强制要求 Gradio 启用auth参数。但注意不是简单设个用户名密码就完事。Gradio 的基础 auth 只做 HTTP Basic Auth明文传输必须配合 Nginx 反向代理做 TLS 加密。我们的方案是Gradio 服务监听 localhost:7860Nginx 在 443 端口接收 HTTPS 请求做两件事一是终止 SSL二是转发前插入Authorization头。这样既利用了 Gradio 的 auth 框架又规避了密码明文风险。有人问“能不能用阿里云 RAM 子账号做鉴权”——不行。RAM 是云资源权限体系和应用层 API 鉴权是两套逻辑强行对接会增加复杂度且无法控制单个 API 调用的速率。2.3 ModelScope 的正确使用姿势不是“下载模型”而是“注册模型”很多人把 ModelScope 当成 GitHub以为ms download --model qwen/Qwen-Image-2.1下载完就能用。错。ModelScope 的核心价值在于它的ModelScope Hub机制——它不是一个静态文件仓库而是一个动态模型注册中心。Qwen-Image-2.1 的权重文件.bin或.safetensors本身不包含推理代码真正的“模型”是modelscope包里定义的Model类它封装了 tokenizer 加载、device 分配、forward 流程等所有逻辑。如果你跳过 ModelScope直接用 Hugging Face 的transformers加载权重会遇到两个致命问题一是 tokenizer 的中文分词规则不一致Qwen 系列用的是自研的 QwenTokenizerHF 的 AutoTokenizer 会默认走 Llama 分词逻辑二是多模态输入处理缺失HF 没有QwenImageProcessor这个类你得自己写图像 resize、归一化、patch embedding 的代码而 ModelScope 已经把这些都封装好了。所以正确流程是先用modelscope login登录用阿里云主账号或子账号均可再通过snapshot_downloadAPI 下载模型快照最后用AutoModel.from_pretrained加载。这个过程会自动解析configuration.json里的model_type匹配到qwen_image从而实例化正确的模型类。我特意测试过如果用 HF 的from_pretrained加载同一个路径model.config.model_type返回的是qwen而不是qwen_image导致后续调用model.generate时抛出AttributeError: QwenModel object has no attribute vision_tower。2.4 为什么不用阿里云函数计算FC或 Serverless 应用引擎SAE看到“云端部署”不少人会想到 Serverless。但 Qwen-Image-2.1 的冷启动时间决定了它不适合 FC。我们实测过在 FC 上部署首次请求平均耗时 8.2 秒其中 6.5 秒花在模型加载上从 OSS 下载权重 初始化 vision tower。而 ECS 方案服务常驻内存首请求耗时稳定在 1.3 秒以内。SAE 虽然支持常驻实例但它强制要求容器镜像又绕回了前面说的 Docker 显存问题。更重要的是SAE 的 GPU 实例计费模式是“按秒计费”但最小计费单位是 1 分钟而 Qwen-Image 的单次推理通常在 2~5 秒这意味着每处理 10 次请求就有 50 秒是纯浪费。ECS 的包年包月模式算下来每千次推理成本比 SAE 低 63%。这不是理论值是我们客户真实账单对比。3. 核心细节解析与实操要点3.1 ECS 实例选型A10 还是 A100显存不是唯一指标阿里云目前提供两种主流 GPU 实例gn7iA10和 gn7eA100。很多教程直接推荐 A100理由是“显存大”。但这是典型的经验主义陷阱。我们做过一组对照实验用相同 batch_size1输入图尺寸 1024×1024分别跑 Qwen-Image-2.1 的 captioning 任务。实例类型显存平均推理耗时显存峰值占用每小时费用按量gn7i (A10)24GB1.82s21.3GB¥12.5gn7e (A100)40GB1.45s36.7GB¥38.9A100 快了 0.37 秒但贵了 3.1 倍。更关键的是A100 的 40GB 显存根本没被充分利用——36.7GB 的峰值意味着还有 3.3GB 余量但这点余量不足以支撑 batch_size2需要 42.1GB。所以 A100 的“大显存”在这里是冗余的。反观 A1021.3GB 的占用率 88.8%说明资源被高效压榨。而且 A10 的 PCIe 4.0 x16 带宽64GB/s比 A100 的 PCIe 4.0 x1664GB/s并无差异但 A10 的功耗只有 150WA100 是 400W这对 ECS 的散热和稳定性有直接影响。我们线上集群里A100 实例的 GPU 温度常年在 82℃~85℃而 A10 稳定在 68℃~71℃高温导致 A100 的 NVLink 通信错误率高出 4.2 倍。因此本教程默认选择 gn7iA10实例。配置建议4 核 CPU 32GB 内存 1×A10 GPU。CPU 核数不能太少因为 Qwen-Image 的 tokenizer 是 CPU 密集型操作特别是长文本生成时tokenize 耗时占总耗时的 18%。内存 32GB 是底线因为模型权重加载后约占用 12GBGradio UI 占用 2GB剩余 18GB 要留给 Linux page cache加速图像文件读取。3.2 ModelScope 模型下载避开网络超时和校验失败ModelScope 的模型下载经常失败根本原因不是网速而是它的 CDN 节点调度策略。当你用ms download命令时它会根据你的公网 IP 归属地分配最近的 CDN 节点但这个节点可能恰好在维护。我们观察到华东 1 区域的用户有 37% 的概率被调度到杭州节点而该节点在每日 02:00~04:00 有例行维护期间下载成功率低于 5%。解决方案是绕过 ms CLI直接用 snapshot_download API并指定镜像源。代码如下from modelscope.hub.snapshot_download import snapshot_download import os # 设置环境变量强制走阿里云内网源ECS 实例内网 IP 可直连 os.environ[MODELSCOPE_CACHE] /mnt/nas/models os.environ[MODELSCOPE_PARALLEL_DOWNLOAD] 4 model_dir snapshot_download( model_idqwen/Qwen-Image-2.1, revisionv1.0.0, # 必须指定否则默认 latest 可能不稳定 local_files_onlyFalse, cache_dir/mnt/nas/models, # 关键指定镜像源避免 CDN 调度 mirrorhttps://modelscope.oss-cn-beijing.aliyuncs.com )这里/mnt/nas/models是挂载的阿里云 NAS 文件系统路径。NAS 的优势在于所有 ECS 实例共享同一份模型文件避免每台机器重复下载且 NAS 支持 NFSv4.1 协议读取速度比本地 SSD 快 2.3 倍实测 1.2GB/s vs 520MB/s因为模型文件是大量小文件tokenizer 的 vocab.json、merges.txt 等NAS 的元数据缓存机制对此类 IO 更友好。提示revisionv1.0.0必须写死。ModelScope 的latest标签会指向最新 commit而 Qwen-Image-2.1 的 v1.0.0 和 v1.0.1 在 vision tower 的 patch size 上有差异v1.0.1 用了 14×14v1.0.0 是 16×16如果代码里 hardcode 了patch_size16而下载了 v1.0.1就会报RuntimeError: Input image size doesnt match patch size。3.3 Gradio 配置深度调优不只是改端口Gradio 的launch()方法表面简单但隐藏着大量影响生产环境的参数。默认shareFalse是对的但server_name0.0.0.0和server_port7860只是基础。真正关键的是这四个参数enable_queueTrue必须开启。Qwen-Image-2.1 的单次推理耗时波动大1.2s~3.5s如果关闭 queue高并发时会直接 502。开启后Gradio 内部用 asyncio.Queue 管理请求最大并发数由max_threads控制。max_threads4这是核心调优点。A10 单卡最多安全承载 4 个并发推理线程。超过 4显存碎片化加剧OOM 概率飙升。我们测试过 max_threads8结果在第 6 个请求时torch.cuda.memory_allocated()突然暴涨 8GB然后 crash。ssl_keyfile和ssl_certfile必须配。即使你后面用 Nginx 做 TLS 终止Gradio 层也要配因为 Nginx 转发时会检查后端是否支持 HTTPS。不配的话Nginx 会报upstream SSL certificate verify failed。auth(admin, your_strong_password)密码必须强。Gradio 的 auth 是 base64 编码的 Basic Auth没有加密所以密码强度直接决定安全性。我们要求至少 12 位含大小写字母、数字、特殊字符且不能是字典单词。另外Gradio 的examples参数别滥用。官方 demo 里放了 10 个示例图但每个图都会在服务启动时预加载到内存占用额外 1.2GB 显存。生产环境建议删掉examples改用cache_examplesFalse让示例图按需加载。3.4 Nginx 反向代理配置不止是转发更是安全网关Nginx 不只是把 443 端口的请求转给 localhost:7860它承担着三重角色SSL 终止、请求过滤、速率限制。以下是精简后的 nginx.conf 核心段upstream qwen_backend { server 127.0.0.1:7860; keepalive 32; # 保持长连接减少 TCP 握手开销 } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; location / { proxy_pass https://qwen_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 关键注入 Basic Auth 头Gradio 才能识别 proxy_set_header Authorization Basic YWRtaW46eW91ci1zdHJvbmctcGFzc3dvcmQ; # 限制单 IP 每分钟最多 60 次请求防爬虫 limit_req zoneqwen burst20 nodelay; # 超时设置必须大于 Gradio 的最长推理时间 proxy_connect_timeout 30s; proxy_send_timeout 120s; proxy_read_timeout 120s; } }其中limit_req zoneqwen burst20 nodelay是重点。burst20表示允许突发 20 个请求nodelay意味着这 20 个请求立即通过不排队。这样设计是为了兼顾用户体验——用户点一次“生成”按钮前端可能发 3~5 个请求预检、上传、轮询这 5 个请求应该被允许。而真正的恶意爬虫会持续发送超出 60 次/分钟就会被 503。注意proxy_set_header Authorization的值是admin:your_strong_password的 base64 编码。不要手算用echo -n admin:your_strong_password | base64生成。如果填错Gradio 会返回 401但日志里只显示Unauthorized很难排查。4. 实操过程与核心环节实现4.1 环境初始化从 ECS 创建到 Python 环境搭建第一步创建 ECS 实例。登录阿里云控制台选择地域推荐华东 1 杭州实例规格选gn7i-c4g1m324 核 32GB 内存 1×A10镜像选Ubuntu 22.04 LTS官方长期支持兼容性最好。关键设置安全组规则必须放行443/tcpHTTPS和22/tcpSSH其他端口一律拒绝系统盘选ESSD PL1性能平衡容量 100GB数据盘挂载/mnt/nas用于存放模型和日志。第二步连接实例并更新系统。# SSH 连接后执行 sudo apt update sudo apt upgrade -y sudo apt install -y python3-pip python3-venv git curl wget unzip # 安装 NVIDIA 驱动阿里云已预装但需验证 nvidia-smi # 应显示 A10 和驱动版本 535.104.05第三步创建 Python 虚拟环境并安装核心依赖。绝对不要用系统 Python因为 Ubuntu 22.04 自带的 pip 版本太老会导致 torch 安装失败。python3 -m venv /opt/qwen-env source /opt/qwen-env/bin/activate pip install --upgrade pip setuptools wheel # 安装 PyTorch必须指定阿里云镜像源否则下载极慢 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # 安装 ModelScope 和 Gradio同样走阿里云镜像 pip install modelscope gradio --index-url https://mirrors.aliyun.com/pypi/simple/这里--index-url是提速关键。PyTorch 官方源在国外国内直连平均下载速度 200KB/s阿里云镜像源稳定在 12MB/s。我们实测安装 torch 从 25 分钟缩短到 90 秒。第四步配置 NAS 挂载。进入阿里云 NAS 控制台创建一个通用型 NAS 实例添加挂载点VPC 内网地址然后在 ECS 上执行sudo apt install -y nfs-common sudo mkdir -p /mnt/nas # 替换为你的 NAS 挂载地址格式nas-xxxx.cn-hangzhou.nas.aliyuncs.com:/path sudo mount -t nfs -o vers4.1,rsize1048576,wsize1048576,hard,timeo600,retrans2,noacl,nolock,prototcp,port2049 nas-xxxx.cn-hangzhou.nas.aliyuncs.com:/ /mnt/nas # 写入 fstab 实现开机自动挂载 echo nas-xxxx.cn-hangzhou.nas.aliyuncs.com:/ /mnt/nas nfs vers4.1,rsize1048576,wsize1048576,hard,timeo600,retrans2,noacl,nolock,prototcp,port2049 0 0 | sudo tee -a /etc/fstab提示NAS 挂载后务必执行ls -la /mnt/nas确认权限。默认挂载是 root 可写但 Gradio 进程将以www-data用户运行所以需要sudo chown -R www-data:www-data /mnt/nas。4.2 模型下载与验证确保权重完整可用激活虚拟环境执行模型下载脚本download_model.py#!/usr/bin/env python3 from modelscope.hub.snapshot_download import snapshot_download import os os.environ[MODELSCOPE_CACHE] /mnt/nas/models os.environ[MODELSCOPE_PARALLEL_DOWNLOAD] 4 try: model_dir snapshot_download( model_idqwen/Qwen-Image-2.1, revisionv1.0.0, cache_dir/mnt/nas/models, mirrorhttps://modelscope.oss-cn-beijing.aliyuncs.com ) print(f✅ 模型下载成功路径{model_dir}) # 验证关键文件是否存在 required_files [ os.path.join(model_dir, configuration.json), os.path.join(model_dir, pytorch_model.bin), os.path.join(model_dir, tokenizer.model), os.path.join(model_dir, preprocessor_config.json) ] for f in required_files: if not os.path.exists(f): raise FileNotFoundError(f缺失关键文件{f}) print(✅ 关键文件校验通过) except Exception as e: print(f❌ 下载失败{e}) exit(1)运行python download_model.py。正常情况会在/mnt/nas/models/qwen/Qwen-Image-2.1下生成约 12.7GB 的文件。验证环节不能跳过。我们曾遇到一次 CDN 传输中断pytorch_model.bin只下载了 8.2GB但snapshot_download没报错直到加载模型时才在torch.load()报EOFError。所以必须手动校验文件大小ls -lh /mnt/nas/models/qwen/Qwen-Image-2.1/pytorch_model.bin # 正确大小应为 11.8G4.3 Gradio 服务编写不只是 demo而是生产级 API创建app.py这是整个服务的核心#!/usr/bin/env python3 import gradio as gr from modelscope.pipelines import pipeline from modelscope.utils.constant import Tasks from modelscope.outputs import OutputKeys import torch # 1. 模型加载关键指定 device 和 torch_dtype model_id /mnt/nas/models/qwen/Qwen-Image-2.1 pipe pipeline(taskTasks.image_captioning, modelmodel_id, devicecuda:0, torch_dtypetorch.float16) # 2. 定义推理函数 def generate_caption(image, prompt请用中文描述这张图片的内容要求简洁准确不超过50字。): try: # 图像预处理由 pipeline 内部完成我们只传原始 PIL.Image result pipe(image, promptprompt) caption result[OutputKeys.CAPTION] return caption except Exception as e: return f❌ 推理失败{str(e)} # 3. Gradio 界面定义 with gr.Blocks() as demo: gr.Markdown(# Qwen-Image-2.1 图像描述生成服务) with gr.Row(): with gr.Column(): image_input gr.Image(typepil, label上传图片) prompt_input gr.Textbox(value请用中文描述这张图片的内容要求简洁准确不超过50字。, label提示词Prompt) submit_btn gr.Button(生成描述) with gr.Column(): caption_output gr.Textbox(label生成结果, interactiveFalse) submit_btn.click( fngenerate_caption, inputs[image_input, prompt_input], outputscaption_output ) # 4. 启动参数生产环境必须项 if __name__ __main__: demo.launch( server_name0.0.0.0, server_port7860, shareFalse, enable_queueTrue, max_threads4, ssl_keyfile/opt/qwen-env/ssl/key.pem, ssl_certfile/opt/qwen-env/ssl/cert.pem, auth(admin, your_strong_password_here), favicon_path/mnt/nas/static/favicon.ico # 可选提升专业感 )注意几个生产级细节devicecuda:0显式指定 GPU 设备避免多卡时自动选择错误设备torch_dtypetorch.float16是必须的Qwen-Image-2.1 官方只支持 FP16 推理用float32会 OOMfavicon_path指向 NAS 上的图标文件让浏览器标签页显示自定义 logo这是专业服务的细节。4.4 systemd 服务配置让服务真正“永生”创建 systemd 服务文件/etc/systemd/system/qwen-image.service[Unit] DescriptionQwen-Image-2.1 Service Afternetwork.target [Service] Typesimple Userwww-data WorkingDirectory/opt/qwen-env ExecStart/opt/qwen-env/bin/python /opt/qwen-env/app.py Restartalways RestartSec10 EnvironmentPATH/opt/qwen-env/bin EnvironmentMODELSCOPE_CACHE/mnt/nas/models EnvironmentCUDA_VISIBLE_DEVICES0 # 关键限制内存防止失控 MemoryLimit30G OOMScoreAdjust-500 # 日志配置 StandardOutputjournal StandardErrorjournal SyslogIdentifierqwen-image [Install] WantedBymulti-user.target然后启用服务sudo systemctl daemon-reload sudo systemctl enable qwen-image sudo systemctl start qwen-image sudo systemctl status qwen-image # 应显示 active (running)OOMScoreAdjust-500是保命设置。当系统内存不足时Linux OOM Killer 会优先杀死 score 高的进程-500是最低值意味着这个进程几乎不会被 kill。MemoryLimit30G是硬限制超过 30GB 内存占用systemd 会直接 kill 进程而不是等它把整个系统拖垮。4.5 Nginx 部署与 HTTPS 配置用免费证书搞定安全安装 Nginx 并申请免费 SSL 证书sudo apt install -y nginx sudo systemctl enable nginx sudo systemctl start nginx # 安装 Certbot sudo apt install -y certbot python3-certbot-nginx # 申请证书替换 your-domain.com sudo certbot --nginx -d your-domain.com # Certbot 会自动修改 nginx.conf添加 SSL 配置Certbot 生成的证书路径是/etc/letsencrypt/live/your-domain.com/。我们前面app.py里指定的ssl_keyfile和ssl_certfile就是指向这里的privkey.pem和fullchain.pem。最后把 Nginx 的默认配置/etc/nginx/sites-enabled/default替换为我们的qwen.conf然后sudo nginx -t sudo systemctl reload nginx。此时访问https://your-domain.com应该能看到 Gradio 界面并弹出 Basic Auth 登录框。5. 常见问题与排查技巧实录5.1 问题速查表高频故障与一键修复现象可能原因排查命令修复方案nvidia-smi不显示 GPUNVIDIA 驱动未加载dmesggrep -i nvidiaImportError: No module named torch虚拟环境未激活which python确认python指向/opt/qwen-env/bin/pythonOSError: [Errno 2] No such file or directory: /mnt/nas/models/...NAS 未挂载或权限不足mountgrep nasbrls -ld /mnt/nasGradio 启动后立即退出journalctl显示CUDA out of memorymax_threads设置过高sudo journalctl -u qwen-image -n 50编辑app.py将max_threads4改为3重启服务访问域名返回502 Bad GatewayNginx 无法连接 Gradiocurl -v http://127.0.0.1:7860检查sudo systemctl status qwen-image确认服务 running检查 netstat -tuln输入图片后输出None或空字符串模型加载失败或 prompt 格式错误sudo journalctl -u qwen-image -f在app.py的generate_caption函数里加print(fDebug: image type{type(image)})确认传入的是 PIL.Image5.2 独家避坑技巧那些文档里不会写的细节技巧一Gradio 的cache_examples陷阱很多教程教你在gr.Examples里放示例图说“提升用户体验”。但在生产环境这是个定时炸弹。cache_examplesTrue默认时Gradio 会在启动时把每个示例图都 run 一遍generate_caption并把结果缓存。这意味着10 个示例图 10 次完整推理显存瞬间被占满新请求进来直接 OOM。正确做法cache_examplesFalse并在gr.Examples里只放图片路径如[/mnt/nas/examples/cat.jpg]让 Gradio 按需加载。技巧二torch_dtype必须和模型权重精度一致Qwen-Image-2.1 的权重是 FP16 格式但pipeline默认用torch.float32。如果你不显式指定torch_dtypetorch.float16pipeline会尝试把权重 cast 到 float32这需要额外 12GB 显存直接触发 OOM。实测数据指定float16时显存占用 21.3GB不指定则 33.7GB。技巧三server_port和proxy_pass端口必须严格一致Nginx 的proxy_pass地址写成http://127.0.0.1:7860那么 Gradio 的server_port就必须是