Cherry Studio 支持 OpenAI gpt-image-2依赖升级、响应格式兼容与补丁移植实践【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本文基于 CherryHQ/cherry-studio 仓库中的 changeset 记录.changeset/gpt-image-2-response-format.md完整剖析该项目为支持 OpenAIgpt-image-2模型所做的一整套技术工作AI SDK 依赖版本升级、ai-sdk/openai补丁移植、图片响应格式base64/URL兼容、以及工具工厂类型约束的放宽。读完本文你将理解一个多模型桌面客户端在接入新图像模型时为何需要同时协调 provider SDK 版本、补丁机制、类型系统和模型注册数据并掌握可在当前仓库中逐项验证的实现细节。一、变更背景一个 changeset 背后的完整工程.changeset/gpt-image-2-response-format.md是一份面向cherrystudio/ai-core与cherrystudio/ai-sdk-provider两个包的 patch 级变更记录其核心目标只有一句话让 Cherry Studio 能通过 Vercel AI SDK 正常调用 OpenAI 的gpt-image-2图像生成模型。但这条支持背后并不只是往模型列表里加一个 ID而是牵涉四类互相关联的改动升级ai-sdk/openai至^3.0.53并同步刷新整个ai-sdk/*一阶包族用pnpm.overrides固定ai-sdk/provider-utils版本解决类型声明产物declaration emit的 TS2742 可移植性错误对ai-sdk/openai3.0.53打补丁把gpt-image-2注册进modelMaxImagesPerCall与defaultResponseFormatPrefixes避免向 OpenAI 发送被拒绝的response_format参数放宽ToolFactoryPatch.tools的类型约束兼容 AI SDK 收紧ToolINPUT, OUTPUT泛型后不再坍缩为ToolSet联合类型的新工具如webSearch/webSearchPreview。下面逐项结合仓库源码展开。二、gpt-image-2 在 Cherry Studio 中的模型定义Cherry Studio 通过 provider-registry 包维护各提供商的模型目录。gpt-image-2被定义为 OpenAI 提供商下的图像生成模型见 packages/provider-registry/src/creators/openai.tsfamily: gpt-image与gpt-image-1同属一个图像模型家族capabilities包含image-recognition、image-generation、file-input即支持图片识别图像编辑、图像生成和文件输入三种能力inputModalities: [text, image]outputModalities: [image]输入接受文本与图片输出为图片。其图像生成参数在模型目录数据中也有完整声明见 packages/provider-registry/data/models.json参数类型可选值 / 默认值backgroundenumauto、opaquenumImagesrange默认1范围1–10qualityenumauto、low、medium、highsizeenum默认1024x1024可选auto、1024x1024、1536x1024、1024x1536这些声明会驱动渲染进程的绘画painting模型选择器渲染参数控件。同时gpt-image-2已在 packages/provider-registry/data/provider-models.json 中映射为openai/gpt-image-2并配套了模型图标见 packages/ui/src/components/icons/models/gpt-image-2/meta.ts。三、依赖升级策略整族刷新与单点固定3.1 一阶ai-sdk/*包族同步升级changeset 明确列出了刷新清单anthropic^3.0.71、azure^3.0.54、amazon-bedrock^4.0.96、cerebras^2.0.45、cohere^3.0.30、gateway^3.0.104、google^3.0.64、google-vertex^4.0.112、groq^3.0.35、huggingface^1.0.43、mistral^3.0.30、perplexity^3.0.29、togetherai^2.0.45、xai^3.0.83其中 OpenAI 相关核心是ai-sdk/openai ^3.0.53。从当前仓库的 package.json 可以看到这一策略的演进结果ai-sdk/openai已升至^3.0.109ai-sdk/google固定在3.0.113ai-sdk/openai-compatible保持在2.0.72changeset 特别注明keepai-sdk/openai-compatibleon its currently-patched version因为它自带独立补丁不随大流升级。也就是说每次引入新模型能力时AI SDK 全家桶必须以同步版本基线整体升级避免各 provider 实现之间的类型与协议错位。3.2 固定 provider-utils 规避 TS2742changeset 记录通过pnpm.overrides把ai-sdk/provider-utils固定到4.0.23使整棵ai-sdk/*依赖树解析出唯一的 provider-utils 副本从而规避coreExtensions声明产物中的 TS2742 可移植性错误TS2742 通常由声明文件中的类型不可被外部引用导致常见原因正是同一类型的多个副本彼此不兼容。当前仓库 package.json 中该依赖已进一步演进为^4.0.48但用 overrides 统一 provider-utils 版本这一工程手段始终保留。四、关键补丁为什么 gpt-image-2 会被 400 拒绝changeset 记录了一个典型的AI SDK 落后于新模型问题未打补丁的 provider 会把response_format: b64_json发送给gpt-image-2而 OpenAI 以400 Unknown parameter: response_format拒绝该请求。修复方式是给ai-sdk/openai3.0.53打补丁将gpt-image-2加入两处白名单modelMaxImagesPerCall控制单次调用允许生成的图片数量上限defaultResponseFormatPrefixes控制哪些模型默认使用response_format前缀——将gpt-image-2排除在外请求体就不会再携带被拒绝的参数。changeset 明确说明这是对 vercel/ai#14680 / #14682 的回移植backport 到release-v6.0并建议一旦ai-sdk/openai3.0.54发布即可移除该补丁。仓库当前的补丁文件 patches/ai-sdk__openai3.0.109.patch 已随依赖升级演进到 3.0.109 版本可以看到同一条补丁线路上叠加的后续修正其中与图片模型直接相关的部分包括图片响应 schema 放宽openaiImageResponseSchema将b64_json由必填z.string()改为.nullish()并新增url: z.string().nullish()因为gpt-image-2的响应可能返回 URL 而非 base64图片解析逻辑OpenAIImageModel.doGenerate/doGenerateV2从response.data.map((item) item.b64_json)改为flatMap分支处理——优先取b64_json字符串否则取url字符串两者皆无则跳过。这正对应 changeset 中响应格式兼容的主题gpt-image-2时代AI SDK 的图片结果解析必须同时支持 base64 与 URL 两种载体。五、响应格式兼容的测试验证packages/aiCore中用ai-sdk/openai的真实 provider 编写了兼容性测试packages/aiCore/src/core/providers/tests/openaiImageModel.test.ts通过 mock fetch 依次验证URL 响应data: [{ url: https://cdn.example.com/generated.png }]→ 结果为该 URLbase64 响应data: [{ b64_json: aGVsbG8 }]→ 原样返回 base64混合响应且 base64 优先同一项同时含url与b64_json时取 base64纯 URL 项取 URL大型 base64 编辑响应约 2.95MB 的 base64 字符串经generateImage编辑路径往返后长度不变关闭重试时的失败语义504 响应不触发重试直接抛错。这些用例直接固化了 changeset 所描述响应格式兼容的行为契约是补丁正确性的自动化保障。六、ToolFactoryPatch 类型放宽适配收紧的 Tool 泛型changeset 记录的最后一类改动是类型层面将ToolFactoryPatch.tools从ToolSet放宽为Recordstring, any。原因在类型定义注释中有完整说明见 packages/aiCore/src/core/providers/types/toolFactory.tsai-sdk/openai3.0.53收紧的ToolINPUT, OUTPUT泛型例如webSearch/webSearchPreview不再能坍缩到ToolSet的Toolany,any | Toolany,never | Toolnever,any | Toolnever,never联合类型导致satisfies ProviderExtensionConfig...校验失败。而运行时params.tools只是浅拷贝形状完全等价因此放宽类型没有运行时风险。该类型在插件执行路径中真实生效内置的providerToolPluginpackages/aiCore/src/core/plugins/built-in/providerToolPlugin.ts调用工具工厂拿到 patch 后执行params.tools { ...params.tools, ...patch.tools }完成浅拷贝合并providerOptions则通过专用合并函数处理。类型放宽只影响编译期约束不影响这段运行逻辑。七、推理强度reasoning effort泄漏防护changeset 还提到一处容易被忽略的连带影响ai-sdk/anthropic3.0.71引入了新的xhigheffort 档位因此需要收窄getAnthropicReasoningParams的返回类型防止xhigh泄漏进AgentSessionContext.effort。这对应 Cherry Studio 的provider 无关推理词汇表设计共享层的 src/shared/ai/reasoning.ts 定义了统一的 effort 档位及其预算比例low: 0.05、medium: 0.5、high: 0.8、xhigh: 0.9、max: 1、ultra: 1会话上下文只接受这一受控词汇表。如果 Anthropic 的新档位未经收敛就进入上下文会导致跨 provider 的推理预算计算出现未知档位。收窄返回类型本质上是在AI SDK 新增枚举值与应用层受控词汇表之间建立边界防止底层升级悄悄破坏上层协议。八、实践启示与验证路径从这份 changeset 中可以提炼出接入新模型的标准操作流程模型注册在 provider-registry 的 creator 与数据文件中登记模型 ID、能力、输入输出模态与生成参数packages/provider-registry/src/creators/openai.tsSDK 基线升级整族刷新ai-sdk/*用pnpm.overrides固定共享工具包版本补丁移植当上游 SDK 落后于新模型协议时用补丁文件承载临时兼容本仓库所有补丁集中在 patches 目录并记录上游修复版本号以便后续移除类型适配SDK 类型收紧导致应用层声明失败时在明确运行时语义的前提下放宽类型约束测试固化用真实 provider mock fetch 写兼容性用例把响应格式等行为契约固定下来。读者可以在当前仓库中逐项核验上述内容changeset 原文见 .changeset/gpt-image-2-response-format.md补丁实现见 patches/ai-sdk__openai3.0.109.patch模型注册数据见 packages/provider-registry/data/models.json 与 packages/provider-registry/data/provider-models.json测试用例见 packages/aiCore/src/core/providers/tests/openaiImageModel.test.ts。这份变更不仅是新增一个模型的记录更是一个多 LLM 客户端在模型生态快速演进中维护兼容性基线的完整样本。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cherry Studio 支持 OpenAI gpt-image-2：依赖升级、响应格式兼容与补丁移植实践
Cherry Studio 支持 OpenAI gpt-image-2依赖升级、响应格式兼容与补丁移植实践【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本文基于 CherryHQ/cherry-studio 仓库中的 changeset 记录.changeset/gpt-image-2-response-format.md完整剖析该项目为支持 OpenAIgpt-image-2模型所做的一整套技术工作AI SDK 依赖版本升级、ai-sdk/openai补丁移植、图片响应格式base64/URL兼容、以及工具工厂类型约束的放宽。读完本文你将理解一个多模型桌面客户端在接入新图像模型时为何需要同时协调 provider SDK 版本、补丁机制、类型系统和模型注册数据并掌握可在当前仓库中逐项验证的实现细节。一、变更背景一个 changeset 背后的完整工程.changeset/gpt-image-2-response-format.md是一份面向cherrystudio/ai-core与cherrystudio/ai-sdk-provider两个包的 patch 级变更记录其核心目标只有一句话让 Cherry Studio 能通过 Vercel AI SDK 正常调用 OpenAI 的gpt-image-2图像生成模型。但这条支持背后并不只是往模型列表里加一个 ID而是牵涉四类互相关联的改动升级ai-sdk/openai至^3.0.53并同步刷新整个ai-sdk/*一阶包族用pnpm.overrides固定ai-sdk/provider-utils版本解决类型声明产物declaration emit的 TS2742 可移植性错误对ai-sdk/openai3.0.53打补丁把gpt-image-2注册进modelMaxImagesPerCall与defaultResponseFormatPrefixes避免向 OpenAI 发送被拒绝的response_format参数放宽ToolFactoryPatch.tools的类型约束兼容 AI SDK 收紧ToolINPUT, OUTPUT泛型后不再坍缩为ToolSet联合类型的新工具如webSearch/webSearchPreview。下面逐项结合仓库源码展开。二、gpt-image-2 在 Cherry Studio 中的模型定义Cherry Studio 通过 provider-registry 包维护各提供商的模型目录。gpt-image-2被定义为 OpenAI 提供商下的图像生成模型见 packages/provider-registry/src/creators/openai.tsfamily: gpt-image与gpt-image-1同属一个图像模型家族capabilities包含image-recognition、image-generation、file-input即支持图片识别图像编辑、图像生成和文件输入三种能力inputModalities: [text, image]outputModalities: [image]输入接受文本与图片输出为图片。其图像生成参数在模型目录数据中也有完整声明见 packages/provider-registry/data/models.json参数类型可选值 / 默认值backgroundenumauto、opaquenumImagesrange默认1范围1–10qualityenumauto、low、medium、highsizeenum默认1024x1024可选auto、1024x1024、1536x1024、1024x1536这些声明会驱动渲染进程的绘画painting模型选择器渲染参数控件。同时gpt-image-2已在 packages/provider-registry/data/provider-models.json 中映射为openai/gpt-image-2并配套了模型图标见 packages/ui/src/components/icons/models/gpt-image-2/meta.ts。三、依赖升级策略整族刷新与单点固定3.1 一阶ai-sdk/*包族同步升级changeset 明确列出了刷新清单anthropic^3.0.71、azure^3.0.54、amazon-bedrock^4.0.96、cerebras^2.0.45、cohere^3.0.30、gateway^3.0.104、google^3.0.64、google-vertex^4.0.112、groq^3.0.35、huggingface^1.0.43、mistral^3.0.30、perplexity^3.0.29、togetherai^2.0.45、xai^3.0.83其中 OpenAI 相关核心是ai-sdk/openai ^3.0.53。从当前仓库的 package.json 可以看到这一策略的演进结果ai-sdk/openai已升至^3.0.109ai-sdk/google固定在3.0.113ai-sdk/openai-compatible保持在2.0.72changeset 特别注明keepai-sdk/openai-compatibleon its currently-patched version因为它自带独立补丁不随大流升级。也就是说每次引入新模型能力时AI SDK 全家桶必须以同步版本基线整体升级避免各 provider 实现之间的类型与协议错位。3.2 固定 provider-utils 规避 TS2742changeset 记录通过pnpm.overrides把ai-sdk/provider-utils固定到4.0.23使整棵ai-sdk/*依赖树解析出唯一的 provider-utils 副本从而规避coreExtensions声明产物中的 TS2742 可移植性错误TS2742 通常由声明文件中的类型不可被外部引用导致常见原因正是同一类型的多个副本彼此不兼容。当前仓库 package.json 中该依赖已进一步演进为^4.0.48但用 overrides 统一 provider-utils 版本这一工程手段始终保留。四、关键补丁为什么 gpt-image-2 会被 400 拒绝changeset 记录了一个典型的AI SDK 落后于新模型问题未打补丁的 provider 会把response_format: b64_json发送给gpt-image-2而 OpenAI 以400 Unknown parameter: response_format拒绝该请求。修复方式是给ai-sdk/openai3.0.53打补丁将gpt-image-2加入两处白名单modelMaxImagesPerCall控制单次调用允许生成的图片数量上限defaultResponseFormatPrefixes控制哪些模型默认使用response_format前缀——将gpt-image-2排除在外请求体就不会再携带被拒绝的参数。changeset 明确说明这是对 vercel/ai#14680 / #14682 的回移植backport 到release-v6.0并建议一旦ai-sdk/openai3.0.54发布即可移除该补丁。仓库当前的补丁文件 patches/ai-sdk__openai3.0.109.patch 已随依赖升级演进到 3.0.109 版本可以看到同一条补丁线路上叠加的后续修正其中与图片模型直接相关的部分包括图片响应 schema 放宽openaiImageResponseSchema将b64_json由必填z.string()改为.nullish()并新增url: z.string().nullish()因为gpt-image-2的响应可能返回 URL 而非 base64图片解析逻辑OpenAIImageModel.doGenerate/doGenerateV2从response.data.map((item) item.b64_json)改为flatMap分支处理——优先取b64_json字符串否则取url字符串两者皆无则跳过。这正对应 changeset 中响应格式兼容的主题gpt-image-2时代AI SDK 的图片结果解析必须同时支持 base64 与 URL 两种载体。五、响应格式兼容的测试验证packages/aiCore中用ai-sdk/openai的真实 provider 编写了兼容性测试packages/aiCore/src/core/providers/tests/openaiImageModel.test.ts通过 mock fetch 依次验证URL 响应data: [{ url: https://cdn.example.com/generated.png }]→ 结果为该 URLbase64 响应data: [{ b64_json: aGVsbG8 }]→ 原样返回 base64混合响应且 base64 优先同一项同时含url与b64_json时取 base64纯 URL 项取 URL大型 base64 编辑响应约 2.95MB 的 base64 字符串经generateImage编辑路径往返后长度不变关闭重试时的失败语义504 响应不触发重试直接抛错。这些用例直接固化了 changeset 所描述响应格式兼容的行为契约是补丁正确性的自动化保障。六、ToolFactoryPatch 类型放宽适配收紧的 Tool 泛型changeset 记录的最后一类改动是类型层面将ToolFactoryPatch.tools从ToolSet放宽为Recordstring, any。原因在类型定义注释中有完整说明见 packages/aiCore/src/core/providers/types/toolFactory.tsai-sdk/openai3.0.53收紧的ToolINPUT, OUTPUT泛型例如webSearch/webSearchPreview不再能坍缩到ToolSet的Toolany,any | Toolany,never | Toolnever,any | Toolnever,never联合类型导致satisfies ProviderExtensionConfig...校验失败。而运行时params.tools只是浅拷贝形状完全等价因此放宽类型没有运行时风险。该类型在插件执行路径中真实生效内置的providerToolPluginpackages/aiCore/src/core/plugins/built-in/providerToolPlugin.ts调用工具工厂拿到 patch 后执行params.tools { ...params.tools, ...patch.tools }完成浅拷贝合并providerOptions则通过专用合并函数处理。类型放宽只影响编译期约束不影响这段运行逻辑。七、推理强度reasoning effort泄漏防护changeset 还提到一处容易被忽略的连带影响ai-sdk/anthropic3.0.71引入了新的xhigheffort 档位因此需要收窄getAnthropicReasoningParams的返回类型防止xhigh泄漏进AgentSessionContext.effort。这对应 Cherry Studio 的provider 无关推理词汇表设计共享层的 src/shared/ai/reasoning.ts 定义了统一的 effort 档位及其预算比例low: 0.05、medium: 0.5、high: 0.8、xhigh: 0.9、max: 1、ultra: 1会话上下文只接受这一受控词汇表。如果 Anthropic 的新档位未经收敛就进入上下文会导致跨 provider 的推理预算计算出现未知档位。收窄返回类型本质上是在AI SDK 新增枚举值与应用层受控词汇表之间建立边界防止底层升级悄悄破坏上层协议。八、实践启示与验证路径从这份 changeset 中可以提炼出接入新模型的标准操作流程模型注册在 provider-registry 的 creator 与数据文件中登记模型 ID、能力、输入输出模态与生成参数packages/provider-registry/src/creators/openai.tsSDK 基线升级整族刷新ai-sdk/*用pnpm.overrides固定共享工具包版本补丁移植当上游 SDK 落后于新模型协议时用补丁文件承载临时兼容本仓库所有补丁集中在 patches 目录并记录上游修复版本号以便后续移除类型适配SDK 类型收紧导致应用层声明失败时在明确运行时语义的前提下放宽类型约束测试固化用真实 provider mock fetch 写兼容性用例把响应格式等行为契约固定下来。读者可以在当前仓库中逐项核验上述内容changeset 原文见 .changeset/gpt-image-2-response-format.md补丁实现见 patches/ai-sdk__openai3.0.109.patch模型注册数据见 packages/provider-registry/data/models.json 与 packages/provider-registry/data/provider-models.json测试用例见 packages/aiCore/src/core/providers/tests/openaiImageModel.test.ts。这份变更不仅是新增一个模型的记录更是一个多 LLM 客户端在模型生态快速演进中维护兼容性基线的完整样本。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
