fft npainting lama API文档生成：Swagger集成实战

1. 背景与目标

你可能已经用过fft npainting lama这个图像修复工具——它能轻松实现图片重绘、物品移除、水印清除等操作，界面友好，效果惊艳。但如果你正在做二次开发，比如想把它集成到自己的系统中，或者提供给团队调用，光靠WebUI点击可不够。

我们需要的是API。

更进一步，我们还需要一份清晰、可交互的API文档，让前端、测试甚至客户都能快速理解怎么调用接口。这时候，Swagger 就派上用场了。

本文将带你从零开始，在fft npainting lama的基础上，集成 Swagger 自动生成 API 文档，完成一次实用的工程化升级。整个过程不依赖复杂框架改造，适合已有 WebUI 项目的快速接入。

2. 系统架构与技术选型

2.1 原有系统分析

fft npainting lama的 WebUI 是基于 Gradio 构建的，核心启动文件是app.py，其本质是一个 Python 函数封装 + Gradio 接口暴露的模式。

关键点：

图像上传 → 画笔标注（mask）→ 模型推理 → 返回修复图
所有逻辑集中在predict或类似函数中
当前只支持 UI 交互，无标准 HTTP 接口

我们要做的，是在不影响原有功能的前提下，新增一个 FastAPI 服务层，把核心修复能力包装成 RESTful 接口，并通过 Swagger 展示。

2.2 技术组合：FastAPI + Swagger

为什么选 FastAPI？

自带 Swagger UI（默认路径/docs）
类型提示友好，自动校验参数
性能高，适合图像处理类服务
与 Python 生态无缝集成

最终架构如下：

[客户端] ↓ (HTTP POST /api/inpaint) [FastAPI Server] → 调用 [lama 修复核心函数] ↓ 返回 base64 或 图片 URL

Swagger 自动生成文档，开发者打开/docs即可测试。

3. 核心改造步骤

3.1 提取图像修复核心函数

首先，我们要把app.py中的图像修复逻辑独立出来，变成一个可复用的函数。

假设原始代码中有类似这样的函数：

def process_image(image, mask): # image: numpy array, HWC, BGR # mask: 2D binary array # 返回修复后的图像（numpy array） ... return result_image

我们将这个函数保存为inpaint_core.py：

# inpaint_core.py import cv2 import numpy as np def load_model(): # 模型加载逻辑（只加载一次） pass def process_image(image_bgr: np.ndarray, mask: np.ndarray) -> np.ndarray: """ 图像修复主函数 :param image_bgr: 输入图像 (H, W, 3), BGR格式 :param mask: 修复区域掩码 (H, W), 0表示保留，255表示修复 :return: 修复后图像 (H, W, 3), BGR格式 """ # 这里调用 lama 的实际推理逻辑 # 示例伪代码： # pred_img = model.infer(image_bgr, mask) pred_img = image_bgr.copy() # 替换为真实逻辑 return pred_img

注意：确保模型只加载一次，避免每次调用都初始化。

3.2 创建 FastAPI 服务入口

新建api_server.py，引入 FastAPI 并注册路由：

# api_server.py from fastapi import FastAPI, UploadFile, File from fastapi.responses import JSONResponse import uvicorn import numpy as np import cv2 import base64 from io import BytesIO from PIL import Image from inpaint_core import process_image app = FastAPI( title="FFT Lama 图像修复 API", description="基于 fft npainting lama 的图像修复接口，支持物品移除、水印清除等", version="1.0.0" ) @app.post("/api/inpaint", tags=["图像修复"]) async def inpaint_image( image: UploadFile = File(..., description="原始图像"), mask: UploadFile = File(..., description="修复区域掩码（白色为修复区）") ): """ 执行图像修复 - **image**: 原始图像（PNG/JPG） - **mask**: 标注掩码图（单通道或三通道，白色区域将被修复） - 返回修复后的图像 base64 编码 """ # 读取图像 img_data = await image.read() mask_data = await mask.read() img = cv2.imdecode(np.frombuffer(img_data, np.uint8), cv2.IMREAD_COLOR) mask_img = cv2.imdecode(np.frombuffer(mask_data, np.uint8), cv2.IMREAD_GRAYSCALE) if img is None or mask_img is None: return JSONResponse({"error": "图像解码失败"}, status_code=400) # 调整mask大小以匹配图像 mask_img = cv2.resize(mask_img, (img.shape[1], img.shape[0])) _, mask_binary = cv2.threshold(mask_img, 127, 255, cv2.THRESH_BINARY) # 执行修复 result = process_image(img, mask_binary) # 编码为 base64 返回 _, buffer = cv2.imencode(".png", result) img_base64 = base64.b64encode(buffer).decode('utf-8') return JSONResponse({ "success": True, "result": f"data:image/png;base64,{img_base64}" }) if __name__ == "__main__": uvicorn.run("api_server:app", host="0.0.0.0", port=8000, reload=False)

3.3 集成 Swagger 文档

上面的 FastAPI 代码已经自带 Swagger！

启动服务后，访问：

http://你的服务器IP:8000/docs

你会看到自动生成的交互式文档页面，包含：

接口路径/api/inpaint
参数说明（image、mask 文件上传）
测试按钮（可直接上传图片试用）
返回示例结构
支持 cURL 命令导出

Swagger 界面长这样（文字描述）：

左侧是接口列表，点击展开
中间是请求参数表单，支持文件上传
底部是“Try it out”按钮，点击后发送请求
实时显示响应结果，包括 base64 图像预览

这就是我们想要的效果：无需写文档，代码即文档。

4. 与原有 WebUI 共存方案

你可能担心：加了 FastAPI，会不会影响原来的 Gradio WebUI？

不会。我们可以这样做：

4.1 双服务并行启动

修改start_app.sh，同时启动两个服务：

#!/bin/bash # 启动 FastAPI（后台） nohup python api_server.py > fastapi.log 2>&1 & # 启动 Gradio WebUI cd /root/cv_fft_inpainting_lama python app.py --server_port 7860 --share False

这样：

WebUI 继续运行在:7860
API 服务运行在:8000
互不干扰

4.2 统一入口建议（可选）

如果希望统一端口，可以用 Nginx 反向代理：

location / { proxy_pass http://127.0.0.1:7860; } location /api/ { proxy_pass http://127.0.0.1:8000/; } location /docs { proxy_pass http://127.0.0.1:8000/docs; }

这样所有流量走 80 端口，外部更整洁。

5. 接口使用示例

5.1 使用 curl 调用

curl -X POST "http://your-server:8000/api/inpaint" \ -F "image=@input.jpg" \ -F "mask=@mask.png" \ | jq -r '.result' | sed 's/^data:image\/png;base64,//' | base64 -d > output.png

5.2 使用 Python requests

import requests files = { 'image': open('input.jpg', 'rb'), 'mask': open('mask.png', 'rb') } response = requests.post('http://your-server:8000/api/inpaint', files=files) data = response.json() # 提取 base64 并保存 import re match = re.match(r"data:image\/png;base64,(.*)", data['result']) if match: with open("output.png", "wb") as f: f.write(base64.b64decode(match.group(1)))

前端也可以直接用<input type="file">+ fetch 调用。

6. 安全性与生产建议

虽然 Swagger 方便调试，但在生产环境要注意：

6.1 关闭调试接口（可选）

FastAPI 默认开启/docs和/redoc，如需关闭：

app = FastAPI(docs_url=None, redoc_url=None) # 完全关闭 # 或 app = FastAPI(docs_url="/apidocs" if DEBUG else None) # 仅开发环境开放

6.2 添加身份验证（推荐）

简单 token 验证：

from fastapi import Depends, HTTPException, Header def verify_token(x_token: str = Header(...)): if x_token != "your-secret-token": raise HTTPException(status_code=401, detail="Unauthorized") @app.post("/api/inpaint", dependencies=[Depends(verify_token)]) async def inpaint_image(...): ...

调用时需加头：

curl -H "x-token: your-secret-token" -F "image=..." http://.../api/inpaint

6.3 限制文件大小

防止大文件拖垮服务：

MAX_FILE_SIZE = 10 * 1024 * 1024 # 10MB async def read_upload_file(file: UploadFile): content = await file.read() if len(content) > MAX_FILE_SIZE: raise HTTPException(status_code=413, detail="文件过大") return content