如何在Python中快速调用LongCat-Image-Edit图像编辑服务:实战完整教程
如何在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
脚本会自动完成四件事:
- 检查模型路径和 NPU 设备
- 构建 Docker 镜像(基于 Dockerfile 中的 CANN 基础镜像)
- 启动容器并配置 NPU 设备(见 entrypoint.sh 的启动流程)
- 显示服务状态和访问地址
⚠️ 注意:需要先将模型文件下载到脚本约定的本地路径,且服务器已安装昇腾 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_scale4.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 调用的全流程:
- 用部署脚本或 Makefile 一键启动服务
- 通过
/health接口确认模型就绪 - 用
requests发送 JSON 或表单请求完成以文改图 - 通过步数、guidance_scale、seed 等参数微调效果
这套方案将模型能力封装为标准 HTTP 接口,任何支持 HTTP 的语言都可以接入,是本地私有化部署图像编辑能力的实用选择。