From bdc2de7128b9fbbf347f750ecdf4a7d052750b88 Mon Sep 17 00:00:00 2001 From: kicer Date: Sun, 25 Oct 2026 09:13:32 +0800 Subject: [PATCH] =?UTF-8?q?image=5Ftask=20=E5=8E=BB=E6=8E=89=E6=99=BA?= =?UTF-8?q?=E8=B0=B1=E4=B8=93=E7=94=A8=E9=80=9A=E9=81=93=EF=BC=8C=E7=BB=9F?= =?UTF-8?q?=E4=B8=80=E6=8C=89=20OpenAI=20=E5=85=BC=E5=AE=B9=E5=8D=8F?= =?UTF-8?q?=E8=AE=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 三个 header 全部必填:Authorization / X-Image-Task-Base-Url / X-Image-Task-Model - 删除 zhipu 别名、bigmodel.cn 主机判断与默认模型;地址必须是完整 http(s) URL, 已给到 /images/generations 就直接用,否则自动补全 - 请求体统一为 { model, prompt, n: 1, response_format: "url" },传图时追加 images - 任务摘要不再输出 provider;图生图不再按通道拒绝,能否编辑交给上游 - 同步 image_task README / package.json 描述 / 根 README 与 mcp/README 的示例 --- README.md | 2 +- mcp/README.md | 4 +- mcp/image_task/README.md | 109 +++++++------------------------ mcp/image_task/package.json | 2 +- mcp/image_task/src/mcp-server.js | 108 ++++++++++-------------------- 5 files changed, 62 insertions(+), 163 deletions(-) diff --git a/README.md b/README.md index 06f4a4a..7e80cfb 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: "zhipu" # 或任意 OpenAI 兼容网关地址 + # X-Image-Task-Base-Url: "https://open.bigmodel.cn/api/paas/v4" # 任意 OpenAI 兼容的 /images/generations 上游 # X-Image-Task-Model: "CogView-4" # mode: skill # - name: video_task diff --git a/mcp/README.md b/mcp/README.md index c32e43e..368ee2c 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -47,8 +47,8 @@ mcp_servers: `image_task` / `video_task` 的 token **不由服务端保存**——每个请求从 `Authorization` header 读取 (agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。`video_task` 用智谱 token; -`image_task` 用对应上游(智谱或 OpenAI 兼容网关)的 token,上游地址与模型分别由 -`X-Image-Task-Base-Url` / `X-Image-Task-Model` 指定。所以这两个服务不用配任何密钥。 +`image_task` 走任意 OpenAI 兼容的 `/images/generations`,上游地址与模型分别由 +`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 d46bd0a..93950e4 100644 --- a/mcp/image_task/README.md +++ b/mcp/image_task/README.md @@ -3,12 +3,9 @@ 一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片生成 / 编辑服务。 对外只有一个工具 `image_task`,用 `op` 区分动作(`create` / `get`),异步任务契约与 `video_task` 一致。 -上游支持两种协议,由 `X-Image-Task-Base-Url` 选择: - -| 通道 | 上游 | 请求体 | -|---|---|---| -| 智谱原生 | `https://open.bigmodel.cn/api/paas/v4/images/generations` | `{ model, prompt }` | -| OpenAI 兼容 | 任意实现 `/images/generations` 的网关(如 `https://wb.ai.foresh.com/v1`) | `{ model, prompt, n: 1, response_format: "url", images? }` | +上游必须是 OpenAI 兼容的 `/images/generations` 端点(智谱 `https://open.bigmodel.cn/api/paas/v4` +与各类网关走同一套协议)。`X-Image-Task-Base-Url` / `X-Image-Task-Model` / `Authorization` +三个 header 都必填,服务不存密钥、也不预设厂商或默认模型。 - 协议:MCP **Streamable HTTP**(单端点 `/mcp`,支持 SSE 流) - 端口:容器内 `3000`(**不映射宿主机**,只在 `agent-mcp-net` 内被 agent 访问) @@ -43,7 +40,7 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r "url": "http://localhost:8082/mcp", "headers": { "Authorization": "Bearer ", - "X-Image-Task-Base-Url": "zhipu", + "X-Image-Task-Base-Url": "https://open.bigmodel.cn/api/paas/v4", "X-Image-Task-Model": "CogView-4" } } @@ -84,7 +81,7 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r 本地图片先用 `mint_public_link` 换成公网 URL,再传给 `image`。 > 尺寸、质量、模型、上游地址都**不是**工具参数:它们属于部署策略,由调用方在 header 里固定, -> 避免 AI 乱填尺寸档位或模型名白烧额度。智谱原生通道也不接受尺寸,直接走上游默认值。 +> 避免 AI 乱填尺寸档位或模型名白烧额度。尺寸/质量直接走上游默认值。 ### 返回 @@ -93,7 +90,7 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r ```jsonc { "content": [ - { "type": "text", "text": "Model: CogView-4\nProvider: zhipu\nMode: text-to-image\ntask_id: \ntask_status: PROCESSING\n\nImage generation is running in background. Call this tool again with op=\"get\" and task_id=\"\" to fetch the result." } + { "type": "text", "text": "Model: CogView-4\nMode: text-to-image\ntask_id: \ntask_status: PROCESSING\n\nImage generation is running in background. Call this tool again with op=\"get\" and task_id=\"\" to fetch the result." } ] } ``` @@ -106,7 +103,7 @@ docker exec mcp_image_task node -e "fetch('http://localhost:3000/health').then(r ```jsonc { "content": [ - { "type": "text", "text": "task_id: \nmodel: CogView-4\nprovider: zhipu\nelapsed: 12s\ntask_status: SUCCESS\nImage URL: https://..." } + { "type": "text", "text": "task_id: \nmodel: CogView-4\nelapsed: 12s\ntask_status: SUCCESS\nImage URL: https://..." } ] } ``` @@ -122,70 +119,37 @@ URL 由上游签名下发,**带有效期**(通常 24h),需要长期保 | Header | 必填 | 说明 | |---|---|---| | `Authorization` | ✅ | `Bearer `,原样作为上游 Bearer token | -| `X-Image-Task-Base-Url` | ❌ | 别名或完整 URL;缺省 `zhipu` | -| `X-Image-Task-Model` | 见下 | 模型名原样透传 | +| `X-Image-Task-Base-Url` | ✅ | 上游 base URL(完整 `http(s)` 地址);已给到 `/images/generations` 就直接用,否则自动补上 | +| `X-Image-Task-Model` | ✅ | 模型名原样透传 | -### Base-Url 别名 - -| 值 | 实际地址 | 协议 | -|---|---|---| -| `zhipu`(默认) | `https://open.bigmodel.cn/api/paas/v4` | 智谱原生 | - -其余值必须是完整的 `http(s)` URL: - -```yaml -X-Image-Task-Base-Url: "https://wb.ai.foresh.com/v1" -``` - -- 已经给到 `/images/generations` 全路径就直接用,否则自动补 `/images/generations`。 -- 解析后的 host 是 `bigmodel.cn`(含子域)→ 智谱原生请求体;其余 host → OpenAI 兼容请求体。 -- 因此把网关地址填进来即可,不需要额外指定“用哪家协议”。 - -### 模型 - -| 场景 | `X-Image-Task-Model` | -|---|---| -| Base-Url = `zhipu` | 可省略,缺省 `CogView-3-Flash` | -| 其他 Base-Url | **必填**(不会把 CogView 误发到网关) | - -模型只由 header 决定,AI 看不到也填不了。换模型 = 改 header 后重启 core。 +地址与模型只由 header 决定,AI 看不到也填不了;换模型 = 改 header 后重启 core。 ### 图生图 -`image` 只对 OpenAI 兼容通道生效: +传了 `image` 时,请求体带 `images: [url]`(数组形式)。是否支持由上游模型决定——不支持时 +上游会回 4xx,`op=get` 里以 `task_status: FAIL` 呈现。 -| Base-Url | 传 `image` | -|---|---| -| `zhipu` | 直接返回错误:智谱不支持图生图(只做文生图) | -| 网关 URL | 上游请求体带 `images: [url]` | +### 请求体 -### 请求体差异 - -| 字段 | 智谱原生 | OpenAI 兼容 | -|---|---|---| -| `model` / `prompt` | ✅ | ✅ | -| `n` | ❌ | 固定 `1` | -| `response_format` | ❌ | 固定 `"url"` | -| `size` / `quality` | ❌ | ❌(交给上游默认值) | -| `images` | ❌ | 传图时带,数组形式 `[url]` | +固定 `{ model, prompt, n: 1, response_format: "url" }`,传图时追加 `images: [url]`。 +`size` / `quality` 一律不传,交给上游默认值。 --- ## 配置示例 -### 智谱直连(默认) +智谱与网关走同一套协议,只换地址与模型: ```yaml - name: image_task url: "http://mcp_image_task:3000/mcp" headers: - Authorization: "Bearer <智谱 KEY>" + Authorization: "Bearer " + X-Image-Task-Base-Url: "https://open.bigmodel.cn/api/paas/v4" X-Image-Task-Model: "CogView-4" mode: skill ``` -### OpenAI 兼容网关(文生图) - ```yaml - name: image_task url: "http://mcp_image_task:3000/mcp" @@ -196,20 +160,6 @@ X-Image-Task-Base-Url: "https://wb.ai.foresh.com/v1" mode: skill ``` -### OpenAI 兼容网关(图生图 / 修图) - -```yaml - - name: image_task - url: "http://mcp_image_task:3000/mcp" - headers: - Authorization: "Bearer <网关 KEY>" - X-Image-Task-Base-Url: "https://wb.ai.foresh.com/v1" - X-Image-Task-Model: "cn:hunyuan-image-alpha" - mode: skill -``` - -同一个网关换模型只改 `X-Image-Task-Model`;换供应商只改 `X-Image-Task-Base-Url`。 - --- ## 错误响应 @@ -217,9 +167,8 @@ X-Image-Task-Base-Url: "https://wb.ai.foresh.com/v1" | 场景 | HTTP 状态 | 表现 | |---|---|---| | 缺 `Authorization` | `200`(MCP 工具返回) | `isError: true`,提示补 header | -| `X-Image-Task-Base-Url` 非法 | `200`(MCP 工具返回) | `isError: true`,列出可用别名 | -| 非 zhipu 通道缺 `X-Image-Task-Model` | `200`(MCP 工具返回) | `isError: true`,提示补 header | -| zhipu 通道传了 `image` | `200`(MCP 工具返回) | `isError: true`,提示智谱不支持图生图,改用 OpenAI 兼容端点 | +| 缺 `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 | | `op=create` 缺 prompt / `op=get` 缺 task_id | `200`(MCP 工具返回) | `isError: true`,参数提示 | | `op=get` 查不到任务 | `200`(MCP 工具返回) | `isError: true`,提示 unknown task_id | @@ -264,11 +213,12 @@ curl -s -X POST http://localhost:8082/mcp \ -H "Mcp-Session-Id: $SESSION" \ -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}' -# 3. 文生图(智谱通道;换成网关时补 X-Image-Task-Base-Url / X-Image-Task-Model) +# 3. 文生图(三个 header 都必填) curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer $TOKEN" \ + -H "X-Image-Task-Base-Url: https://open.bigmodel.cn/api/paas/v4" \ -H "X-Image-Task-Model: CogView-4" \ -H "Mcp-Session-Id: $SESSION" \ -d '{ @@ -284,7 +234,7 @@ curl -s -X POST http://localhost:8082/mcp \ } }' -# 4. 图生图(OpenAI 兼容通道) +# 4. 图生图 curl -s -X POST http://localhost:8082/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ @@ -356,15 +306,6 @@ image_task/ - **`image` 单一开关**:不传 = 文生图,传一个公网 URL = 图生图;`image` 是单个字符串,只接受公网 `http(s)` URL - **URL 提取**:只接受 `data[].url` 形式的 http(s) URL;上游若回 `b64_json` 则记 `FAIL` 并给出明确错误 -### 默认模型 - -```js -// src/mcp-server.js -const DEFAULT_MODEL = "CogView-3-Flash"; // 仅 Base-Url=zhipu 时生效 -``` - -修改后 `docker compose up -d --build mcp_image_task` 即可生效。 - --- ## 常见问题 @@ -378,8 +319,8 @@ A: 不需要重建 session,但 core 的 `mcp_servers[].headers` 是启动时 **Q: 为什么只支持一张参考图?** A: 当前上游契约只稳定支持单张;`image` 因此是单个 URL 字符串。 -**Q: 图生图为什么在 zhipu 通道报错?** -A: 智谱原生接口不支持图生图。把 `X-Image-Task-Base-Url` 指向支持 `images` 字段的 OpenAI 兼容网关即可。 +**Q: 图生图报错?** +A: 是否支持取决于上游模型;不支持时上游回 4xx,在 `op=get` 里以 `task_status: FAIL` 呈现。换一个支持 `images` 字段的模型即可。 **Q: 本地图片怎么传?** A: 先调用 agent 内置的 `mint_public_link` 工具,把会话目录里的文件换成短期公网 URL,再传给 `image`。本服务不接受文件上传或 base64,上游服务器也无法访问你的本地路径。 diff --git a/mcp/image_task/package.json b/mcp/image_task/package.json index 81c24c1..41eceaf 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 Zhipu BigModel CogView or 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/generations endpoint (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 e674ba0..37fafb3 100644 --- a/mcp/image_task/src/mcp-server.js +++ b/mcp/image_task/src/mcp-server.js @@ -6,15 +6,9 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js"; import { z } from "zod"; -// 上游地址既支持完整 URL,也支持别名。zhipu 走智谱原生协议(body 只有 -// model/prompt);其余地址一律按 OpenAI 兼容的 /images/generations 协议 -// (body 加 n / response_format=url)。别名目前只保留 zhipu。 -const BASE_URL_ALIASES = { - zhipu: "https://open.bigmodel.cn/api/paas/v4", -}; -// 只有智谱需要走原生请求体,其余主机一律按 OpenAI 兼容处理。 -const ZHIPU_HOST_SUFFIX = "bigmodel.cn"; -const DEFAULT_MODEL = "CogView-3-Flash"; +// 上游必须是 OpenAI 兼容的 /images/generations 端点:Base-Url / 模型 / 凭据全部由调用方 +// 随每个请求用 header 带入(X-Image-Task-Base-Url / X-Image-Task-Model / Authorization), +// 服务自己不存、也不预设任何厂商。 // 上游同步调用耗时上限(出图几十秒量级,留足余量)。 // 超时后任务记为 FAIL,避免上游挂而不回时永远卡在 PROCESSING。 @@ -84,45 +78,32 @@ function pickModel(headers) { return pickHeaderString(headers, "x-image-task-model"); } -// 解析 Base-Url:别名优先,否则必须是 http(s) URL。 -// 返回 { provider, url }:url 是最终 POST 的完整地址。 +// 解析 Base-Url:必须是完整 http(s) URL。已经给到 /images/generations 就直接用, +// 否则补在 base 后面。 function resolveEndpoint(rawBase) { - const raw = String(rawBase || "zhipu").trim().replace(/\/+$/, ""); - const alias = BASE_URL_ALIASES[raw.toLowerCase()]; - const base = alias || raw; - - let host; - try { - if (!/^https?:\/\//i.test(base)) throw new Error("not http(s)"); - host = new URL(base).hostname.toLowerCase(); - } catch { + const base = String(rawBase || "").trim().replace(/\/+$/, ""); + if (!base) { throw new Error( - `Invalid X-Image-Task-Base-Url "${raw}": use an alias (${Object.keys(BASE_URL_ALIASES).join(", ")}) ` + - "or a full http(s) URL." + "Missing X-Image-Task-Base-Url: pass the upstream base URL (e.g. https:///v1)." ); } - - // 已经给到 /images/generations 就直接用;否则补在 base 后面。 - const url = /\/images\/generations$/i.test(base) + if (!/^https?:\/\//i.test(base)) { + throw new Error( + `Invalid X-Image-Task-Base-Url "${base}": must be a full http(s) URL.` + ); + } + return /\/images\/generations$/i.test(base) ? base : base + "/images/generations"; - const provider = - host === ZHIPU_HOST_SUFFIX || host.endsWith("." + ZHIPU_HOST_SUFFIX) - ? "zhipu" - : "openai"; - return { provider, url }; } -// 模型只由 header 决定,AI 看不到也填不了。 -// zhipu 通道有默认模型;其他通道必须显式给 —— 否则会把 CogView 发到网关, -// 换来的只是一个含义不明的 400。 -function resolveModel(headers, provider) { +// 模型只由 header 决定,AI 看不到也填不了。不猜缺省值:猜错只会换来含义不明的 400。 +function resolveModel(headers) { const model = pickModel(headers); - if (model) return model; - if (provider === "zhipu") return DEFAULT_MODEL; - throw new Error( - "X-Image-Task-Model is required when X-Image-Task-Base-Url is not the zhipu alias." - ); + if (!model) { + throw new Error("Missing X-Image-Task-Model: pass the upstream model name."); + } + return model; } // 一次解析出本次请求的上游、凭据、模型。 @@ -132,22 +113,21 @@ function resolveTarget(headers) { if (!token) { throw new Error('Missing Authorization: use "Authorization: Bearer ".'); } - const { provider, url } = resolveEndpoint(pickBaseUrl(headers)); - return { provider, url, token, model: resolveModel(headers, provider) }; + return { + url: resolveEndpoint(pickBaseUrl(headers)), + token, + model: resolveModel(headers), + }; } -async function callImagesGenerations({ provider, url, token, model, prompt, image }) { - // 智谱原生只认 model/prompt;OpenAI 兼容通道固定单图,并要求返回 URL - // (b64_json 几十 MB,既塞不进任务表也没法给模型看)。尺寸/质量一律不传, - // 交给上游默认值 —— 各家(尤其 CogView)对尺寸的限制并不一致。 +async function callImagesGenerations({ url, token, model, prompt, image }) { + // 统一按 OpenAI 兼容协议:单图 + response_format=url(b64_json 几十 MB,既塞不进 + // 任务表也没法给模型看)。尺寸/质量一律不传,交给上游默认值。 // 传了 image 就是图生图;上游字段是数组,所以这里包一层。 - const body = - provider === "zhipu" - ? { model, prompt } - : Object.assign( - { model, prompt, n: 1, response_format: "url" }, - image ? { images: [image] } : null - ); + const body = Object.assign( + { model, prompt, n: 1, response_format: "url" }, + image ? { images: [image] } : null + ); let resp; try { resp = await fetch(url, { @@ -175,9 +155,8 @@ async function callImagesGenerations({ provider, url, token, model, prompt, imag data = { raw: text }; } if (!resp.ok) { - const label = provider === "zhipu" ? "Zhipu" : "OpenAI-compatible"; const err = new Error( - `${label} API error: ${resp.status} ${resp.statusText} - ${text}` + `Upstream API error: ${resp.status} ${resp.statusText} - ${text}` ); err.status = resp.status; err.detail = data; @@ -240,7 +219,6 @@ function pruneTasks() { // 后台跑同步上游调用,结果回写任务表(fire-and-forget,不 await) function runImageTask({ task, target, prompt, image }) { callImagesGenerations({ - provider: target.provider, url: target.url, token: target.token, model: target.model, @@ -318,26 +296,10 @@ async function handleCreate({ args, headers }) { }; } - // 智谱原生接口不支持图生图;带 image 的请求只能走 OpenAI 兼容端点。 - if (image && target.provider === "zhipu") { - return { - isError: true, - content: [ - { - type: "text", - text: - 'Image editing is not supported by the configured model. ' + - 'Remove "image" for text-to-image.', - }, - ], - }; - } - pruneTasks(); const taskId = randomUUID(); const task = { status: "PROCESSING", - provider: target.provider, model: target.model, prompt, createdAt: Date.now(), @@ -350,7 +312,6 @@ async function handleCreate({ args, headers }) { const mode = image ? "edit" : "text-to-image"; const summary = `Model: ${target.model}\n` + - `Provider: ${target.provider}\n` + `Mode: ${mode}\n` + `task_id: ${taskId}\n` + `task_status: PROCESSING\n` + @@ -411,7 +372,6 @@ async function handleGet({ args }) { text: `task_id: ${taskId}\n` + `model: ${task.model}\n` + - `provider: ${task.provider}\n` + `elapsed: ${elapsed}s\n` + `task_status: PROCESSING\n` + `\n` + @@ -429,7 +389,6 @@ async function handleGet({ args }) { type: "text", text: `task_id: ${taskId}\n` + - `provider: ${task.provider}\n` + `elapsed: ${elapsedSeconds(task)}s\n` + `task_status: FAIL\n` + `error: ${task.error}`, @@ -447,7 +406,6 @@ async function handleGet({ args }) { const summary = `task_id: ${taskId}\n` + `model: ${task.model}\n` + - `provider: ${task.provider}\n` + `elapsed: ${elapsedSeconds(task)}s\n` + `task_status: SUCCESS\n` + `${lines}`;