From d6b949969f96ad846114208b994874095f1cf2cf Mon Sep 17 00:00:00 2001 From: kicer Date: Sun, 25 Oct 2026 10:13:47 +0800 Subject: [PATCH] =?UTF-8?q?image=5Ftask=20=E5=9B=BE=E7=94=9F=E5=9B=BE?= =?UTF-8?q?=E6=94=B9=E8=B5=B0=20/images/edits=EF=BC=9A=E4=B8=8B=E8=BD=BD?= =?UTF-8?q?=E5=8F=82=E8=80=83=E5=9B=BE=E5=90=8E=20multipart=20=E4=B8=8A?= =?UTF-8?q?=E4=BC=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 文生图仍走 /images/generations,图生图改走 /images/edits(原先错发到 generations 的 images 数组) - X-Image-Task-Base-Url 统一剥离末尾 /images/generations 或 /images/edits,端点由模式决定 - 参考图先下载成字节再以 multipart 上传:60s 独立超时、20MB 流式上限、校验 image/* - 同步 README / mcp README / package.json 说明 --- README.md | 2 +- mcp/README.md | 7 +- mcp/image_task/README.md | 48 ++++++-- mcp/image_task/package.json | 2 +- mcp/image_task/src/mcp-server.js | 196 ++++++++++++++++++++++++++----- 5 files changed, 205 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 7e80cfb..b222b64 100644 --- a/README.md +++ b/README.md @@ -110,7 +110,7 @@ mcp_servers: # url: "http://mcp_image_task:3000/mcp" # headers: # Authorization: Bearer - # X-Image-Task-Base-Url: "https://open.bigmodel.cn/api/paas/v4" # 任意 OpenAI 兼容的 /images/generations 上游 + # X-Image-Task-Base-Url: "https://open.bigmodel.cn/api/paas/v4" # 任意 OpenAI 兼容的 images 上游(生成 /images/generations、编辑 /images/edits) # X-Image-Task-Model: "CogView-4" # mode: skill # - name: video_task diff --git a/mcp/README.md b/mcp/README.md index 368ee2c..db28114 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -5,7 +5,7 @@ | 目录 | 容器名 | 作用 | 容器内端口 | MCP 端点 | |---|---|---|---|---| | `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `3000` | `POST /` | -| `image_task/` | `mcp_image_task` | 图片生成 / 编辑(智谱原生或任意 OpenAI 兼容 `/images/generations`,单工具 op=create/get) | `3000` | `POST /mcp` | +| `image_task/` | `mcp_image_task` | 图片生成 / 编辑(文生图走 `/images/generations`,图生图走 `/images/edits`,单工具 op=create/get) | `3000` | `POST /mcp` | | `video_task/` | `mcp_video_task` | 智谱 CogVideo 视频生成(异步,单工具 op=create/get) | `3000` | `POST /mcp` | | `asr/` | `mcp_asr` | 语音转文字(上游 OpenAI 兼容 `/audio/transcriptions`),**额外带一个给输入框用的 `POST /transcribe`** | `3000` | `POST /mcp` | @@ -47,8 +47,9 @@ mcp_servers: `image_task` / `video_task` 的 token **不由服务端保存**——每个请求从 `Authorization` header 读取 (agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。`video_task` 用智谱 token; -`image_task` 走任意 OpenAI 兼容的 `/images/generations`,上游地址与模型分别由 -`X-Image-Task-Base-Url` / `X-Image-Task-Model` 指定(两者都必填)。所以这两个服务不用配任何密钥。 +`image_task` 走任意 OpenAI 兼容的 images 上游:文生图 `/images/generations`、图生图 `/images/edits`, +上游地址与模型分别由 `X-Image-Task-Base-Url` / `X-Image-Task-Model` 指定(两者都必填)。 +所以这两个服务不用配任何密钥。 `asr` 同理:上游的 key / base_url / model 全部由调用方随请求 header 带入 (`Authorization` / `X-ASR-Base-Url` / `X-ASR-Model`,agent 侧配在 `config.yml` 的 diff --git a/mcp/image_task/README.md b/mcp/image_task/README.md index 93950e4..fba0bdc 100644 --- a/mcp/image_task/README.md +++ b/mcp/image_task/README.md @@ -3,8 +3,8 @@ 一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成 / 编辑服务。 对外只有一个工具 `image_task`,用 `op` 区分动作(`create` / `get`),异步任务契约与 `video_task` 一致。 -上游必须是 OpenAI 兼容的 `/images/generations` 端点(智谱 `https://open.bigmodel.cn/api/paas/v4` -与各类网关走同一套协议)。`X-Image-Task-Base-Url` / `X-Image-Task-Model` / `Authorization` +上游必须是 OpenAI 兼容的 images 端点:文生图走 `/images/generations`,图生图走 `/images/edits` +(智谱、各类网关走同一套协议)。`X-Image-Task-Base-Url` / `X-Image-Task-Model` / `Authorization` 三个 header 都必填,服务不存密钥、也不预设厂商或默认模型。 - 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) @@ -75,8 +75,9 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r `image` 是模式开关: -- 不传 → **文生图**; -- 传一个公网 URL → **图生图 / 编辑**。 +- 不传 → **文生图**,请求 `POST /images/generations`; +- 传一个公网 URL → **图生图 / 编辑**,服务先把这张图拉下来,再以 multipart 上传到 + `POST /images/edits`。 本地图片先用 `mint_public_link` 换成公网 URL,再传给 `image`。 @@ -119,20 +120,36 @@ URL 由上游签名下发,**带有效期**(通常 24h),需要长期保 | Header | 必填 | 说明 | |---|---|---| | `Authorization` | ✅ | `Bearer `,原样作为上游 Bearer token | -| `X-Image-Task-Base-Url` | ✅ | 上游 base URL(完整 `http(s)` 地址);已给到 `/images/generations` 就直接用,否则自动补上 | +| `X-Image-Task-Base-Url` | ✅ | 上游 base URL(完整 `http(s)` 地址,如 `https:///v1`);若已给到 `/images/generations` 或 `/images/edits` 会自动剥回 base,再按模式拼端点 | | `X-Image-Task-Model` | ✅ | 模型名原样透传 | 地址与模型只由 header 决定,AI 看不到也填不了;换模型 = 改 header 后重启 core。 ### 图生图 -传了 `image` 时,请求体带 `images: [url]`(数组形式)。是否支持由上游模型决定——不支持时 -上游会回 4xx,`op=get` 里以 `task_status: FAIL` 呈现。 +图生图**不能**走 `/images/generations`,必须走 `/images/edits`。服务会先把 `image` URL 下载成字节 +(独立 60s 超时,单图上限 20MB,响应需是 `image/*`,如 png / jpeg / webp / gif / bmp),再以 multipart 上传: + +```text +POST /images/edits +Content-Type: multipart/form-data; boundary=... + +model=
+prompt= +image=@<下载到的参考图> # 字段名 image,文件名按 MIME 补扩展名 +n=1 +response_format=url +``` + +选 multipart 而不是 JSON + base64 data URL:参考图已经在本地手里,直接当文件传可省掉 base64 的 +1/3 体积膨胀,也避开网关对超大 JSON 体的限制。 ### 请求体 -固定 `{ model, prompt, n: 1, response_format: "url" }`,传图时追加 `images: [url]`。 -`size` / `quality` 一律不传,交给上游默认值。 +- 文生图:JSON `{ model, prompt, n: 1, response_format: "url" }` → `/images/generations` +- 图生图:multipart(字段见上)→ `/images/edits` + +`size` / `quality` 一律不传,交给上游默认值。两种模式的成功响应都按 `data[0].url` 取图。 --- @@ -170,13 +187,15 @@ URL 由上游签名下发,**带有效期**(通常 24h),需要长期保 | 缺 `X-Image-Task-Base-Url` / 不是完整 http(s) URL | `200`(MCP 工具返回) | `isError: true`,提示填完整地址 | | 缺 `X-Image-Task-Model` | `200`(MCP 工具返回) | `isError: true`,提示补 header | | `image` 不是公网 http(s) URL | `200`(MCP 工具返回) | `isError: true`,提示只接受公网 URL,不接受文件上传 / base64 | +| 参考图下载失败 / 超时(>60s)/ 超过 20MB / 不是图片 | `200`(MCP 工具返回) | 在 `op=get` 中以 `task_status: FAIL` 呈现,错误直述下载环节 | | `op=create` 缺 prompt / `op=get` 缺 task_id | `200`(MCP 工具返回) | `isError: true`,参数提示 | | `op=get` 查不到任务 | `200`(MCP 工具返回) | `isError: true`,提示 unknown task_id | | 上游 4xx/5xx | `200`(MCP 工具返回) | 在 `op=get` 中以 `task_status: FAIL` 呈现,正文含上游状态码和 body | | 上游只回 `b64_json` | `200`(MCP 工具返回) | `task_status: FAIL`,提示本服务只接受 URL | | 网络失败 / 超时(>180s) | `200`(MCP 工具返回) | `task_status: FAIL`,不会出现永久 PROCESSING 的僵尸任务 | -> JSON 请求体上限保持 2MB:`image` 只接受 URL,不接收文件或 base64。 +> JSON 请求体上限保持 2MB:工具参数里的 `image` 只接受 URL,不接收文件或 base64。 +> 参考图由服务自己下载后以 multipart 转发给上游,不经过 MCP 请求体。 --- @@ -303,7 +322,8 @@ image_task/ - token / 上游地址 / 模型在 `create` 那一刻从请求 header 捕获进闭包,后台完成前不再读取 - **每 session 一个 transport + server**:通过 `Mcp-Session-Id` 复用 - **模型 / 上游地址不入 schema**:只从 HTTP header 读取,AI 不可见 -- **`image` 单一开关**:不传 = 文生图,传一个公网 URL = 图生图;`image` 是单个字符串,只接受公网 `http(s)` URL +- **`image` 单一开关**:不传 = 文生图(`/images/generations`),传一个公网 URL = 图生图 + (下载后 multipart 上传 `/images/edits`);`image` 是单个字符串,只接受公网 `http(s)` URL - **URL 提取**:只接受 `data[].url` 形式的 http(s) URL;上游若回 `b64_json` 则记 `FAIL` 并给出明确错误 --- @@ -320,10 +340,12 @@ A: 不需要重建 session,但 core 的 `mcp_servers[].headers` 是启动时 A: 当前上游契约只稳定支持单张;`image` 因此是单个 URL 字符串。 **Q: 图生图报错?** -A: 是否支持取决于上游模型;不支持时上游回 4xx,在 `op=get` 里以 `task_status: FAIL` 呈现。换一个支持 `images` 字段的模型即可。 +A: 图生图走 `/images/edits` + multipart(字段名 `image`)。若上游模型不支持编辑、或网关不认这种入参, +上游会回 4xx,在 `op=get` 里以 `task_status: FAIL` 呈现。换一个支持 `/images/edits` 的模型即可。 **Q: 本地图片怎么传?** -A: 先调用 agent 内置的 `mint_public_link` 工具,把会话目录里的文件换成短期公网 URL,再传给 `image`。本服务不接受文件上传或 base64,上游服务器也无法访问你的本地路径。 +A: 先调用 agent 内置的 `mint_public_link` 工具,把会话目录里的文件换成短期公网 URL,再传给 `image`。 +本服务不接受文件上传或 base64(MCP 请求体不放图片字节),参考图由服务自己从这个 URL 拉取。 **Q: 上游是同步接口,为什么对外做成异步?** A: 和 `video_task` 保持同一套任务型契约;同时避免一次生图把 core 的 `tools/call` 拖超时。 diff --git a/mcp/image_task/package.json b/mcp/image_task/package.json index 41eceaf..ee7ff22 100644 --- a/mcp/image_task/package.json +++ b/mcp/image_task/package.json @@ -1,7 +1,7 @@ { "name": "mcp_image_task", "version": "1.0.0", - "description": "MCP server for image generation and editing via any OpenAI-compatible /images/generations endpoint (single tool image_task with op=create/get)", + "description": "MCP server for image generation and editing via any OpenAI-compatible images API (/images/generations and /images/edits), single tool image_task with op=create/get", "type": "module", "main": "src/mcp-server.js", "scripts": { diff --git a/mcp/image_task/src/mcp-server.js b/mcp/image_task/src/mcp-server.js index 37fafb3..e4ca98b 100644 --- a/mcp/image_task/src/mcp-server.js +++ b/mcp/image_task/src/mcp-server.js @@ -6,14 +6,19 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js"; import { z } from "zod"; -// 上游必须是 OpenAI 兼容的 /images/generations 端点:Base-Url / 模型 / 凭据全部由调用方 -// 随每个请求用 header 带入(X-Image-Task-Base-Url / X-Image-Task-Model / Authorization), -// 服务自己不存、也不预设任何厂商。 +// 上游必须是 OpenAI 兼容的端点:文生图走 /images/generations,图生图走 /images/edits。 +// Base-Url / 模型 / 凭据全部由调用方随每个请求用 header 带入(X-Image-Task-Base-Url / +// X-Image-Task-Model / Authorization),服务自己不存、也不预设任何厂商。 // 上游同步调用耗时上限(出图几十秒量级,留足余量)。 // 超时后任务记为 FAIL,避免上游挂而不回时永远卡在 PROCESSING。 const UPSTREAM_TIMEOUT_MS = 180_000; +// 图生图要先把参考图拉成字节再 multipart 上传:下载超时与体积都要单独兜底, +// 否则慢 CDN 会拖死任务、超大原图会顶满容器内存。 +const IMAGE_DOWNLOAD_TIMEOUT_MS = 60_000; +const MAX_IMAGE_BYTES = 20 * 1024 * 1024; + // ── 优雅退出 ────────────────────────────────────────────────────────────── // 容器里 node 以 PID 1 运行且未注册 SIGTERM 处理器时,内核不会对其执行默认 // 终止动作,docker stop/restart 会白等满 10s 宽限期才被 SIGKILL。 @@ -78,9 +83,10 @@ function pickModel(headers) { return pickHeaderString(headers, "x-image-task-model"); } -// 解析 Base-Url:必须是完整 http(s) URL。已经给到 /images/generations 就直接用, -// 否则补在 base 后面。 -function resolveEndpoint(rawBase) { +// 解析 Base-Url:必须是完整 http(s) URL。允许调用方直接填到 /images/generations 或 +// /images/edits(老配置、照抄文档的写法),统一剥回 base,端点由 mode 决定—— +// 否则图生图会被错发到 generations。 +function resolveBaseUrl(rawBase) { const base = String(rawBase || "").trim().replace(/\/+$/, ""); if (!base) { throw new Error( @@ -92,9 +98,12 @@ function resolveEndpoint(rawBase) { `Invalid X-Image-Task-Base-Url "${base}": must be a full http(s) URL.` ); } - return /\/images\/generations$/i.test(base) - ? base - : base + "/images/generations"; + return base.replace(/\/images\/(generations|edits)$/i, ""); +} + +// mode=edit 走 /images/edits(图生图),否则走 /images/generations(文生图)。 +function resolveEndpoint(base, mode) { + return base + (mode === "edit" ? "/images/edits" : "/images/generations"); } // 模型只由 header 决定,AI 看不到也填不了。不猜缺省值:猜错只会换来含义不明的 400。 @@ -114,29 +123,23 @@ function resolveTarget(headers) { throw new Error('Missing Authorization: use "Authorization: Bearer ".'); } return { - url: resolveEndpoint(pickBaseUrl(headers)), + base: resolveBaseUrl(pickBaseUrl(headers)), token, model: resolveModel(headers), }; } -async function callImagesGenerations({ url, token, model, prompt, image }) { - // 统一按 OpenAI 兼容协议:单图 + response_format=url(b64_json 几十 MB,既塞不进 - // 任务表也没法给模型看)。尺寸/质量一律不传,交给上游默认值。 - // 传了 image 就是图生图;上游字段是数组,所以这里包一层。 - const body = Object.assign( - { model, prompt, n: 1, response_format: "url" }, - image ? { images: [image] } : null - ); +// 统一的上游 POST:超时、错误体解析都在这层,JSON 与 multipart 共用。 +// contentType 为空表示交给 fetch 自己写(multipart 必须这样,boundary 由它生成)。 +async function postUpstream({ url, token, body, contentType }) { + const headers = { Authorization: `Bearer ${token}` }; + if (contentType) headers["Content-Type"] = contentType; let resp; try { resp = await fetch(url, { method: "POST", - headers: { - Authorization: `Bearer ${token}`, - "Content-Type": "application/json", - }, - body: JSON.stringify(body), + headers, + body, signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS), }); } catch (e) { @@ -165,6 +168,126 @@ async function callImagesGenerations({ url, token, model, prompt, image }) { return data; } +const MIME_TO_EXT = { + "image/png": "png", + "image/jpeg": "jpg", + "image/webp": "webp", + "image/gif": "gif", + "image/bmp": "bmp", +}; +const EXT_TO_MIME = { + png: "image/png", + jpg: "image/jpeg", + jpeg: "image/jpeg", + webp: "image/webp", + gif: "image/gif", + bmp: "image/bmp", +}; + +function urlExtension(url) { + try { + const m = /\.([a-z0-9]+)$/i.exec(new URL(url).pathname); + return m ? m[1].toLowerCase() : ""; + } catch { + return ""; + } +} + +// 判定参考图的 MIME:优先响应头,其次 URL 扩展名。响应头只要声明是 image/* 就放行 +// (avif / tiff 这类冷门格式交给上游判断),避免本地图片被我们提前拒掉。 +// 两者都不是图片就报错——典型情况是链接过期后拿到 HTML 错误页,继续上传只会换来 +// 上游一句难懂的 400。 +function pickImageMime(contentType, url) { + const ct = String(contentType || "").split(";")[0].trim().toLowerCase(); + if (/^image\/[a-z0-9.+-]+$/.test(ct)) return ct; + const mime = EXT_TO_MIME[urlExtension(url)]; + if (mime) return mime; + throw new Error( + `Reference image is not an image: content-type "${ct || "none"}" (${url}).` + ); +} + +// multipart 里的文件名按 MIME 补扩展名;冷门 image/* 就把子类型当年扩展名。 +function extensionForMime(mime) { + return ( + MIME_TO_EXT[mime] || + mime.slice("image/".length).replace(/[^a-z0-9]/g, "") || + "img" + ); +} + +// 图生图需要真实字节:先把 image URL 拉下来。带独立超时与体积上限,错误直述下载环节, +// 便于区分「参考图挂了」和「上游出图失败」。 +async function downloadImage(url) { + let resp; + try { + resp = await fetch(url, { + signal: AbortSignal.timeout(IMAGE_DOWNLOAD_TIMEOUT_MS), + }); + } catch (e) { + if (e?.name === "TimeoutError" || e?.name === "AbortError") { + throw new Error( + `Failed to download reference image: timed out after ${IMAGE_DOWNLOAD_TIMEOUT_MS} ms (${url})` + ); + } + throw new Error(`Failed to download reference image: ${e.message} (${url})`); + } + if (!resp.ok) { + throw new Error( + `Failed to download reference image: ${resp.status} ${resp.statusText} (${url})` + ); + } + const declared = Number(resp.headers.get("content-length") || 0); + if (declared > MAX_IMAGE_BYTES) { + throw new Error( + `Reference image is too large: ${declared} bytes (limit ${MAX_IMAGE_BYTES}) (${url})` + ); + } + // 不直接 arrayBuffer():没有 content-length 的响应会一路读进内存, + // 这里边读边计数,超限立刻中止(断掉上游连接)。 + const chunks = []; + let total = 0; + for await (const chunk of resp.body) { + total += chunk.length; + if (total > MAX_IMAGE_BYTES) { + throw new Error( + `Reference image is too large: >${MAX_IMAGE_BYTES} bytes (limit ${MAX_IMAGE_BYTES}) (${url})` + ); + } + chunks.push(chunk); + } + if (total === 0) { + throw new Error(`Reference image is empty (${url})`); + } + const buffer = Buffer.concat(chunks, total); + const mime = pickImageMime(resp.headers.get("content-type"), url); + return { buffer, mime, filename: `image.${extensionForMime(mime)}` }; +} + +// 文生图:JSON 体。response_format=url(b64_json 几十 MB,既塞不进任务表也没法给模型看)。 +// 尺寸/质量一律不传,交给上游默认值。 +async function callImagesGenerations({ url, token, model, prompt }) { + const body = JSON.stringify({ model, prompt, n: 1, response_format: "url" }); + return postUpstream({ url, token, body, contentType: "application/json" }); +} + +// 图生图:上游只认 /images/edits,且实测只接受两种入参—— +// 1) multipart/form-data,image 字段是文件(image=@a.jpg); +// 2) application/json,image 字段是 data:image/...;base64,... 的 data URL。 +// 这里走 multipart:参考图已经在本地手里,直接当文件上传,省掉 base64 的 1/3 体积膨胀, +// 也避开网关对超大 JSON 体的限制。响应格式与 generations 一致(data[0].url)。 +async function callImagesEdits({ url, token, model, prompt, image }) { + const ref = await downloadImage(image); + const form = new FormData(); + form.append("model", model); + form.append("prompt", prompt); + form.append("image", new Blob([ref.buffer], { type: ref.mime }), ref.filename); + form.append("n", "1"); + form.append("response_format", "url"); + // 不传 Content-Type:fetch 会带上含 boundary 的 multipart/form-data + return postUpstream({ url, token, body: form }); +} + // 只认 http(s) URL。b64_json 不再当 URL 存:它会把任务表撑爆,模型也读不了。 function extractUrls(data) { if (!data) return []; @@ -186,7 +309,7 @@ function hasInlineBase64(data) { } // ===== 自维护任务表(异步语义全靠这层模拟) ===== -// 上游智谱 images 接口是同步阻塞的,但对外要和 video_task 一样提供 +// 上游智谱/网关的 images 接口是同步阻塞的,但对外要和 video_task 一样提供 // create(立即返回 task_id)+ get(轮询结果)的异步契约: // create 登记 PROCESSING 后把同步调用丢到后台跑,get 从表里读最新状态。 // @@ -218,13 +341,21 @@ function pruneTasks() { // 后台跑同步上游调用,结果回写任务表(fire-and-forget,不 await) function runImageTask({ task, target, prompt, image }) { - callImagesGenerations({ - url: target.url, - token: target.token, - model: target.model, - prompt, - image, - }) + const upstream = image + ? callImagesEdits({ + url: resolveEndpoint(target.base, "edit"), + token: target.token, + model: target.model, + prompt, + image, + }) + : callImagesGenerations({ + url: resolveEndpoint(target.base, "generation"), + token: target.token, + model: target.model, + prompt, + }); + upstream .then((data) => { task.finishedAt = Date.now(); const urls = extractUrls(data); @@ -260,7 +391,8 @@ async function handleCreate({ args, headers }) { }; } - // image 是文生图/图生图开关:不传 = 文生图;传一个公网 URL = 修图。 + // image 是文生图/图生图开关:不传 = 文生图(/images/generations);传一个公网 URL = 修图 + // (/images/edits,服务会先把这张图拉下来再以 multipart 上传)。 // 只接受公网 http(s) URL;本地文件请先由调用方用 mint_public_link 换成公网链接。 if (args.image !== undefined && typeof args.image !== "string") { return {