# Qwen-Image-Edit **Repository Path**: alan-ding/qwen-image-edit ## Basic Information - **Project Name**: Qwen-Image-Edit - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-11 - **Last Updated**: 2026-01-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Qwen/Qwen-Image-Edit 本地部署指南 ## 一、部署前置准备 ### 1. 硬件要求(最低/推荐) - 最低配置:NVIDIA GPU(显存 ≥ 10GB,支持 CUDA 11.7+)、8GB 内存、50GB 可用磁盘空间 - 推荐配置:NVIDIA GPU(显存 ≥ 16GB,A10/T4/V100 更佳)、16GB 以上内存、固态硬盘(加快模型加载) - 说明:该模型不支持纯 CPU 部署(推理速度极慢且资源占用过高),必须依赖 NVIDIA 显卡的 CUDA 加速。 ### 2. 软件环境搭建 #### (1)安装基础依赖(Python + CUDA) - Python 版本:推荐 **3.9~3.11**(兼容性最佳,避免 3.12+ 版本的依赖兼容问题) - CUDA 版本:**11.7 或 12.1**(需与后续 PyTorch 版本匹配,优先 11.7) - 下载地址:[CUDA 11.7](https://developer.nvidia.com/cuda-11.7.0-download-archive) - 验证:安装完成后,终端输入`nvcc -V` 查看是否显示版本信息。 #### (2)安装核心Python库 创建并激活虚拟环境(可选但推荐,避免污染全局环境),然后执行以下命令安装依赖: ```bash # 1. (可选)创建虚拟环境 conda create -n qwen-image-edit python=3.10 conda activate qwen-image-edit # 2. 安装PyTorch(带CUDA支持,必须匹配已安装的CUDA版本) # 若CUDA 11.7 pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117 # 若CUDA 12.1 pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 3. 安装Qwen相关核心依赖 pip install transformers accelerate pillow sentencepiece protobuf torchvision # 4. 安装可选依赖(提升推理速度/便捷性) pip install optimum onnxruntime-gpu # 支持ONNX加速 pip install gradio # 用于搭建可视化网页界面(后续演示) ``` #### (3)验证环境 终端运行以下Python代码,验证CUDA是否可用: ```python import torch print(f"PyTorch版本:{torch.__version__}") print(f"CUDA是否可用:{torch.cuda.is_available()}") print(f"GPU设备数量:{torch.cuda.device_count()}") print(f"GPU设备名称:{torch.cuda.get_device_name(0) if torch.cuda.is_available() else '无'} ``` 若输出 `CUDA是否可用:True`,则环境搭建成功。 ## 二、获取Qwen-Image-Edit模型 Qwen-Image-Edit 模型托管在 **Hugging Face Hub**,有两种获取方式,任选其一即可: ### 方式1:通过transformers自动下载(推荐,简单便捷) 运行代码时,`transformers` 会自动从Hugging Face Hub下载模型权重和配置文件,默认缓存到 `~/.cache/huggingface/hub/` 目录。 - 模型仓库地址:[Qwen/Qwen-Image-Edit](https://huggingface.co/Qwen/Qwen-Image-Edit) - 说明:首次运行会下载约数GB的模型文件,需保证网络通畅,下载完成后后续运行会复用缓存。 ### 方式2:手动下载(适合网络不稳定场景) 1. 访问模型Hugging Face仓库:[https://huggingface.co/Qwen/Qwen-Image-Edit](https://huggingface.co/Qwen/Qwen-Image-Edit) 2. 点击右侧「Files and versions」,下载所有文件(重点包含 `pytorch_model.bin`、`config.json`、`tokenizer.json`等) 3. 本地创建文件夹(如 `./qwen-image-edit-model/`),将所有下载文件放入该文件夹 4. 后续代码中指定模型路径为该本地文件夹路径即可。 ## 三、核心部署步骤(两种运行方式) ### 方式1:命令行/脚本推理(基础部署,无可视化界面) 创建Python脚本 `qwen_image_edit_demo.py`,内容如下,可直接运行实现图像编辑: ```python from transformers import AutoProcessor, AutoModelForCausalLM import torch from PIL import Image # 1. 加载模型和处理器 # 自动下载模型(首次运行较慢) processor = AutoProcessor.from_pretrained("Qwen/Qwen-Image-Edit") model = AutoModelForCausalLM.from_pretrained( "Qwen/Qwen-Image-Edit", torch_dtype=torch.bfloat16, # 节省显存,提升推理速度(支持bfloat16的GPU优先) device_map="auto", # 自动分配模型到可用设备(GPU优先) trust_remote_code=True ) # 若使用本地手动下载的模型,替换为以下路径 # processor = AutoProcessor.from_pretrained("./qwen-image-edit-model/") # model = AutoModelForCausalLM.from_pretrained( # "./qwen-image-edit-model/", # torch_dtype=torch.bfloat16, # device_map="auto", # trust_remote_code=True # ) # 2. 准备输入数据(原始图像 + 编辑指令) # 替换为你的本地图像路径(支持jpg、png等格式) original_image = Image.open("./test_image.jpg").convert("RGB") # 图像编辑指令(中文/英文均可,推荐中文清晰描述) edit_instruction = "将图片中的天空改为深蓝色,添加几朵白云,保持其他景物不变" # 3. 预处理输入 inputs = processor( images=original_image, text=edit_instruction, return_tensors="pt" ).to(model.device) # 将输入数据移至模型所在设备(GPU) # 4. 模型推理(生成编辑后的图像) with torch.no_grad(): # 禁用梯度计算,节省显存 outputs = model.generate(**inputs, max_new_tokens=1024) # 5. 后处理,获取编辑后的图像 edited_image = processor.decode_image(outputs[0]) # 6. 保存并显示结果 edited_image.save("./edited_image.jpg") print("图像编辑完成,结果已保存为 ./edited_image.jpg") edited_image.show() # 自动打开编辑后的图像(本地环境支持) ``` #### 运行脚本: ```bash python qwen_image_edit_demo.py ``` #### 关键说明: - `torch.bfloat16`:若你的GPU不支持bfloat16(如老款GTX系列),可替换为 `torch.float16`。 - 推理完成后,编辑后的图像会保存为 `./edited_image.jpg`,同时自动打开预览。 - 若显存不足,可添加 `load_in_4bit=True`(需额外安装 `bitsandbytes` 库:`pip install bitsandbytes`),开启4位量化进一步节省显存。 ### 方式2:Gradio可视化界面部署(推荐,操作更友好) 搭建网页可视化界面,支持上传图像、输入编辑指令、实时查看结果,创建脚本 `qwen_image_edit_gradio.py`: ```python from transformers import AutoProcessor, AutoModelForCausalLM import torch from PIL import Image import gradio as gr # 1. 全局加载模型和处理器(仅启动时加载一次,提升后续推理速度) processor = AutoProcessor.from_pretrained("Qwen/Qwen-Image-Edit") model = AutoModelForCausalLM.from_pretrained( "Qwen/Qwen-Image-Edit", torch_dtype=torch.bfloat16, device_map="auto", trust_remote_code=True ) # 2. 定义图像编辑函数(对接Gradio界面) def image_edit_function(original_image, edit_instruction): if original_image is None: return None, "请先上传一张原始图像!" if not edit_instruction: return None, "请输入图像编辑指令!" try: # 预处理输入 inputs = processor( images=Image.fromarray(original_image).convert("RGB"), text=edit_instruction, return_tensors="pt" ).to(model.device) # 模型推理 with torch.no_grad(): outputs = model.generate(**inputs, max_new_tokens=1024) # 解码获取编辑后的图像 edited_image = processor.decode_image(outputs[0]) return edited_image, "图像编辑成功!" except Exception as e: return None, f"编辑失败,错误信息:{str(e)}" # 3. 搭建Gradio界面 with gr.Blocks(title="Qwen-Image-Edit 本地可视化部署") as demo: gr.Markdown("# Qwen/Qwen-Image-Edit 本地部署演示") gr.Markdown("上传一张图像,输入编辑指令,即可获得编辑后的结果") with gr.Row(): # 左侧:输入区域 with gr.Column(scale=1): input_image = gr.Image( type="numpy", label="上传原始图像", height=400 ) edit_text = gr.Textbox( label="输入编辑指令", placeholder="示例:将天空改为深蓝色,添加几朵白云;将人物的衣服改为红色...", lines=3 ) submit_btn = gr.Button("开始编辑", variant="primary") # 右侧:输出区域 with gr.Column(scale=1): output_image = gr.Image( label="编辑后的图像", height=400 ) status_text = gr.Textbox( label="运行状态", interactive=False ) # 绑定按钮点击事件 submit_btn.click( fn=image_edit_function, inputs=[input_image, edit_text], outputs=[output_image, status_text] ) # 4. 启动Gradio服务 if __name__ == "__main__": demo.launch( server_name="0.0.0.0", # 允许局域网内其他设备访问 server_port=7860, # 端口号,可自定义(如7861、7862) share=False # 设为True可生成公网临时链接(需网络通畅) ) ``` #### 运行脚本: ```bash python qwen_image_edit_gradio.py ``` #### 访问界面: 运行成功后,终端会输出访问地址(如 `http://0.0.0.0:7860` 或 `http://127.0.0.1:7860`),打开浏览器访问该地址即可: 1. 点击「上传原始图像」,选择本地图片 2. 在文本框输入编辑指令(如「将草地改为鲜绿色,添加几只蝴蝶」) 3. 点击「开始编辑」,等待几秒(根据图像大小和GPU性能) 4. 右侧会显示编辑后的图像和运行状态,支持下载结果。 ## 四、常见问题与注意事项 ### 1. 显存不足报错(Out of Memory) - 解决方案1:开启4位量化,安装 `bitsandbytes` 后,在 `from_pretrained` 中添加 `load_in_4bit=True`。 - 解决方案2:减小输入图像尺寸(将图像压缩至512×512或256×256)。 - 解决方案3:使用 `torch.float32` 替换 `torch.bfloat16`(仅作为兜底,显存占用会增加)。 ### 2. 模型下载缓慢/失败 - 解决方案:配置Hugging Face镜像源,终端执行以下命令(临时生效): `export HF_ENDPOINT=https://hf-mirror.com` - 或手动下载模型(方式2),避免在线下载的网络问题。 ### 3. 推理速度过慢 - 确保模型已加载到GPU(通过 `model.device` 验证,输出应为 `cuda:0`)。 - 安装 `optimum` 库,使用ONNX加速推理(需额外转换模型格式)。 - 关闭其他占用GPU资源的程序(如其他深度学习任务、游戏等)。 ### 4. 图像编辑结果不符合预期 - 优化编辑指令,尽量清晰、具体(避免模糊描述,如「美化图片」→「将人物皮肤磨平,保留五官细节,提升图片亮度10%」)。 - 确保输入图像质量清晰,避免低分辨率、模糊的原始图像。 ## 五、总结 1. 本地部署Qwen-Image-Edit的核心流程:**环境搭建(Python+CUDA+依赖库)→ 模型获取(自动/手动下载)→ 模型加载与推理(脚本/可视化界面)**。 2. 推荐优先使用「Gradio可视化部署」,操作更友好,适合快速验证效果;脚本推理适合集成到其他项目中。 3. 显存不足是核心痛点,优先通过「bfloat16/FP16量化」「4位量化」「图像压缩」三种方式解决。 4. 模型仅支持NVIDIA GPU部署,不支持纯CPU和AMD GPU(暂不兼容ROCm)。 > (注:文档部分内容可能由 AI 生成)