如何在Python中快速调用LongCat-Image-Edit图像编辑服务:实战完整教程

原创2026-10-29 19:03:551,914 阅读
文章标签:人工智能深度学习大模型后端

如何在Python中快速调用LongCat-Image-Edit图像编辑服务:实战完整教程

LongCat-Image-Edit 是美团推出的开源图像编辑模型,本仓库将其部署为运行在华为昇腾 NPU 上的 REST API 服务,让你在 Python 中用几行代码就能完成"以文改图"。本教程将带你从零部署 LongCat-Image-Edit 图像编辑服务,并掌握用 Python 调用的完整流程。

LongCat-Image-Edit 能做什么?

在开始之前,先了解一下这个模型的核心能力 🌟:

  • 精确编辑:支持全局编辑、局部编辑、文字修改、参考引导编辑
  • 一致性保持:未编辑区域的布局、纹理、色调、主体身份保持不变
  • 双语指令:编辑指令支持中文和英文
  • SOTA 性能:在开源图像编辑模型中达到最先进水平

本仓库的技术栈为 FastAPI + Uvicorn + diffusers,硬件加速使用华为昇腾 910B NPU。核心代码结构如下:

模块 作用
api/main.py FastAPI 主入口,定义健康检查与图像编辑接口
api/inference.py 推理引擎,封装模型编辑调用
api/model_loader.py 模型加载器,支持 NPU/CUDA/CPU 自动回退
config/config.yaml 模型、设备、服务与推理参数配置
Makefile 构建、启动、测试等常用命令
docker-compose.yml 容器编排与 NPU 设备挂载配置
requirements.txt Python 依赖清单

一键部署:最快启动 LongCat-Image-Edit 服务

方式一:使用部署脚本(推荐)

克隆仓库后,执行 deploy_longcat_image_edit.sh 即可完成全部部署:

git clone https://gitcode.com/atomgit-ascend/LongCat-Image-Edit
cd LongCat-Image-Edit
./deploy_longcat_image_edit.sh

脚本会自动完成四件事:

  1. 检查模型路径和 NPU 设备
  2. 构建 Docker 镜像(基于 Dockerfile 中的 CANN 基础镜像)
  3. 启动容器并配置 NPU 设备(见 entrypoint.sh 的启动流程)
  4. 显示服务状态和访问地址

⚠️ 注意:需要先将模型文件下载到脚本约定的本地路径,且服务器已安装昇腾 NPU 驱动。

方式二:使用 Makefile 手动部署

如果你更习惯手动控制每一步,可以用 Makefile 提供的命令:

make build   # 构建 Docker 镜像
make run     # 启动 API 服务
make logs    # 查看实时日志
make health  # 健康检查

验证服务状态

服务启动后,先调用健康检查接口确认模型已加载成功:

curl http://localhost:18005/health

正常返回示例(接口定义见 api/main.py):

{"status": "ok", "model_loaded": true, "device": "npu:0"}

如果 model_loaded 为 false,说明模型还在加载中,稍等片刻再试即可。

Python 调用图像编辑 API:两种实战代码

服务就绪后,Python 端只需依赖 requests 库。下面介绍两种调用方式,任选其一即可。

方式 A:JSON 请求(Base64 图片)

适合图片已经在内存中(比如来自数据库、摄像头流)的场景。接口为 POST /v1/images/edits/json(定义见 api/main.py),输入输出都是 Base64:

import base64
import requests

API_BASE = "http://localhost:18005"

# 1. 读取本地图片并转为 base64
with open("input.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")

# 2. 发送图像编辑请求
resp = requests.post(
    f"{API_BASE}/v1/images/edits/json",
    json={
        "image": image_b64,
        "prompt": "将猫变成狗",
        "num_inference_steps": 50,
        "guidance_scale": 4.5,
        "seed": 43,
    },
    timeout=600,
)
resp.raise_for_status()
data = resp.json()

# 3. 解析返回的 base64 图片并保存
url = data["data"][0]["url"]           # 形如 data:image/png;base64,xxxx
with open("output.png", "wb") as f:
    f.write(base64.b64decode(url.split(",", 1)[1]))

print(f"编辑完成,耗时 {data['processing_time']} 秒")

返回值与 OpenAI 的 images 接口风格兼容,revised_prompt 字段会返回你使用的编辑指令。

方式 B:Form 表单上传(文件流)

适合直接上传本地图片文件的场景,默认直接返回编辑后的 PNG 文件,用起来更直观。接口为 POST /v1/images/edits(定义见 api/main.py):

import requests

API_BASE = "http://localhost:18005"

with open("input.png", "rb") as f:
    files = {"image": ("input.png", f, "image/png")}
    data = {
        "prompt": "把背景换成大海",
        "num_inference_steps": "50",
        "guidance_scale": "4.5",
        "seed": "43",
    }
    resp = requests.post(
        f"{API_BASE}/v1/images/edits",
        files=files,
        data=data,
        timeout=600,
    )

resp.raise_for_status()

# 默认返回图像文件,直接保存即可
with open("output.png", "wb") as f:
    f.write(resp.content)

💡 表单方式还支持 return_base64 参数:设置为 true 时改为返回 image_base64 字段的 JSON。

核心参数速查表

参数 类型 默认值 说明
image string / file 必填 输入图像(Base64 或文件)
prompt string 必填 编辑指令,支持中英文
negative_prompt string "" 负面提示词
num_inference_steps int 50 推理步数,越大越精细越慢
guidance_scale float 4.5 指令遵循强度
seed int 随机 随机种子,固定后可复现结果
num_images_per_prompt int 1 生成图像数量
image_format string "PNG" 输出图像格式(仅 JSON 接口)

这些参数最终会传入推理引擎的 edit_image 方法(见 api/inference.py),由 diffusers 的 LongCatImageEditPipeline 执行编辑。默认参数可在 config/config.yaml 中查看。

实战技巧与常见问题

📝 文字编辑必须加引号

对于涉及文本生成的编辑任务,必须将目标文本用引号括起来(中英文单双引号皆可),否则文字可能渲染不出来:

{"prompt": "将图中的文字改为'Hello World'"}

🎲 用 seed 复现编辑效果

想对同一张图反复调参对比效果时,固定 seed 可以保证每次生成结果可复现。推理引擎内部会通过 CPU generator 设置种子(见 api/inference.py)。

⚙️ 速度 vs 质量怎么平衡?

  • 快速预览:num_inference_steps 降到 30 左右
  • 精细出图:保持默认 50,配合固定的 guidance_scale 4.5

❓ 常见错误排查

现象 原因与解决
503 Model not loaded 模型尚未加载完成,等几分钟后重试;或查看 make logs 确认加载是否报错
连接被拒绝 确认服务端口与容器映射一致(默认宿主机端口见 deploy_longcat_image_edit.sh 中的 HOST_PORT)
编辑效果偏离指令 适当调大 guidance_scale,或用 negative_prompt 排除不想要的内容
NPU 相关报错 用 npu-smi info 检查设备状态;api/model_loader.py 会在 NPU 不可用时自动回退到 CUDA 或 CPU

小结

🎉 到这里,你已经完成了 LongCat-Image-Edit 图像编辑服务从部署到 Python 调用的全流程:

  1. 用部署脚本或 Makefile 一键启动服务
  2. 通过 /health 接口确认模型就绪
  3. 用 requests 发送 JSON 或表单请求完成以文改图
  4. 通过步数、guidance_scale、seed 等参数微调效果

这套方案将模型能力封装为标准 HTTP 接口,任何支持 HTTP 的语言都可以接入,是本地私有化部署图像编辑能力的实用选择。

登录后查看全文
LongCat-Image-Edit