@ai-sdk/openai 版本演进全解析：从 Responses API 到 Batch 与程序化工具调用的能力版图

ai-sdk/openai 版本演进全解析从 Responses API 到 Batch 与程序化工具调用的能力版图【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai本篇技术指南以 AI SDK 官方 OpenAI Providerai-sdk/openai的 CHANGELOG 为骨架系统梳理该包从早期 Chat Completions 支持到当前4.0.65的能力演进路线覆盖 Responses API 深度集成、GPT 系列模型 ID、图像生成/编辑、语音与转录、Batch 批量、程序化工具调用与 Realtime 语音等核心能力。读完本文你将掌握该 Provider 当前具备的完整能力矩阵、历次破坏性变更的迁移要点以及如何在 AI SDK 中正确使用这些模型工厂方法与 Provider 选项。一、包定位与安装ai-sdk/openai是 AI SDKThe AI Toolkit for TypeScript源自 Next.js 团队官方维护的 OpenAI Provider提供语言模型Chat Completions / Responses / Completion、Embedding、图像生成与编辑、语音合成、转录、实时语音Realtime、文件与 Batch 等一整套模型工厂与工具集。按照 README 的说明安装与最小使用方式如下npm i ai-sdk/openaiimport { openai } from ai-sdk/openai; import { generateText } from ai; const { text } await generateText({ model: openai(gpt-5-mini), prompt: Write a vegetarian lasagna recipe for 4 people., });从 package.json 可以看到当前版本为4.0.65包采用 ESM-onlytype: module、sideEffects: false仅依赖ai-sdk/provider与ai-sdk/provider-utils两个核心包prepack脚本会将官方文档 03-openai.mdx 复制进包内docs/目录方便离线查阅。二、模型工厂Provider 的能力入口从 openai-provider.ts 的源码可以看出OpenAIProvider实现了ProviderV4规范以工厂方法的形式暴露全部能力工厂方法能力对应实现openai(modelId)/languageModel()/responses()Responses API 文本生成openai-responses-language-model.tschat(modelId)Chat Completions 文本生成openai-chat-language-model.tscompletion(modelId)传统 Completion APIopenai-completion-language-model.tsembedding(modelId)/embeddingModel()文本 Embeddingopenai-embedding-model.tsimage(modelId)图像生成与编辑openai-image-model.tsspeech(modelId)语音合成openai-speech-model.tstranscription(modelId)语音转录openai-transcription-model.tstranslation(modelId)流式语音翻译如gpt-realtime-translateopenai-speech-translation-model.tsexperimental_realtime()实时语音对话WebSocketopenai-realtime-model.tsfiles/skills/batch文件、技能、批量处理openai-files.ts、openai-skills.ts、openai-batch.tstoolsProvider 内置工具web_search、file_search 等openai-tools.ts以 CHANGELOG 记录的 2.0.15 版本为例模型配置被整合进getResponsesModelConfig()2.0.7 起为 gpt-5 系列加入flex与priority处理模式2.0.8 起支持verbosity参数与minimal推理强度。这些能力最终都汇聚到上述工厂方法中。三、4.x 最新版本线Batch、图像与程序化工具调用当前4.0.x系列截至4.0.65的演进重点集中在批量处理、图像生成、程序化工具调用与流式鲁棒性四个方面。3.1 Batch 批量 API 的完整落地批量能力从4.0.33experimental_startTextBatch起步到4.0.65补齐「batch cancellation and listing」形成闭环。关键节点4.0.61支持 batch 中按请求指定模型per-request models与异步工具调用4.0.54为 batch 加入工具调用支持tool calling support to batch4.0.57在 batch 启动结果上暴露providerMetadata.provider.inputFileId/inputFileExpiresAt并支持inputFileExpiresAfter上传过期选项4.0.47为experimental_startTextBatch增加webhookUrl通过 batchcallbackUrl契约实现完成回调通知Anthropic 与 OpenAI 直接 Provider 在不支持时返回 unsupported 警告4.0.48对齐了各 Provider 间的 batch 结果解析、请求计数与生命周期行为。3.2 图像生成与编辑GPT Image 系列4.0.63新增GPT Image 2.5 Flare / Sunburst模型 ID4.0.62为上述模型增加xhigh与max两档图像质量支持覆盖图像生成、图像编辑与 Responses API 图像生成工具三条路径4.0.58支持 Responses 图像生成的完整文档化选项与ultrafast 服务层级更早的 v3 时代3.0.0已引入gpt-image-1.5、gpt-image-1-mini、gpt-5-pro等模型并实现图像编辑image editing、图像生成结果的预览preview image generation results与generateImage的 usage token 暴露。图像生成的响应元数据在providerMetadata中持续扩充3.0.0 中「include more image generation response metadata」并修复了revised_prompt偶发null导致的报错3.0.0-beta.45。3.3 程序化工具调用Programmatic Tool Calling4.0.20是这一能力的里程碑为 OpenAI Responses API 加入程序化工具调用包含托管程序工具hosted program tools、函数调用者控制function caller controls、结构化输出 Schema 与多步续接支持。配套的openai.tools.customTool()是声明自定义工具的唯一入口对应实现位于 programmatic-tool-calling.ts 与 custom.ts。4.0.63进一步修复了被拒绝的程序化工具调用reject denied programmatic tool calls4.0.64修复了空 Chat Completions choices 时返回统一 AI SDK 错误的行为4.0.25修复doStream在response.in_progress事件上提前解析、从而显著改善网关/代理场景 TTFB 的问题。3.4 Realtime 语音与流式转录4.0.0引入Experimental_RealtimeModelV4规范与openai.experimental_realtime()支持服务端/浏览器双端运行、.getToken()临时令牌、experimental_useRealtimeReact Hook 与inputAudioTranscription会话配置4.0.7起为转录模型如gpt-realtime-whisper提供流式转录experimental streaming transcription4.0.12将 WebSocket 连接层收敛为ai-sdk/provider-utils的connectToWebSocket并修复了 realtime 握手同时携带 subprotocol key 与Authorization头导致被 OpenAI 拒绝的问题4.0.13修复转录认证头的大小写匹配问题4.0.22新增流式语音翻译模型openai.translation(gpt-realtime-translate)并将*TranslationModel类型统一更名为*SpeechTranslationModel4.0.34。四、4.0.0 破坏性变更与迁移要点4.0.0AI SDK v7 预发布是自 v3 以来最大的一次破坏性升级迁移时需关注全面 ESM-only所有包移除 CommonJS 导出ef992f8require()用户必须切换到import语法openai.tools.customTool()移除冗余的name参数61753c3工具名改为直接取tools对象键。迁移示例——迁移前tools: { write_sql: openai.tools.customTool({ name: write_sql, description: ..., }), }迁移后tools: { write_sql: openai.tools.customTool({ description: ..., }), }createToolNameMapping()不再接受resolveProviderToolNameProvider 工具名改为基于tools键的静态映射不再支持运行时动态解析顶层reasoning参数3887c70generateText/streamText支持统一的推理参数规范Provider References 抽象c29a26f、34bd95d支持按 Provider 上传文件与 SkillsuploadFile/uploadSkill可直接传 Provider 实例e311194Node.js 最低版本提升到 227fc6bd6官方支持 22 / 24 / 26新增allowedToolsProvider 选项29e6ac6、gpt-5.3-chat-latest/gpt-5.4/gpt-5.5系列模型 ID以及为所有模型提供WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE的工作流序列化支持b3976a2。此外4.0.0还包含一个安全修复45b3d76/ac306ed流式工具调用不再以「可解析的部分 JSON」作为完成判据而是统一在 streamflush()阶段终结避免在参数未传完时提前执行工具。该逻辑被抽取为ai-sdk/provider-utils中的StreamingToolCallTrackerf807e45。五、Responses API从工具矩阵到推理与元数据Responses API 是ai-sdk/openai近几个大版本投入最深的方向CHANGELOG 记录了清晰的演进脉络。5.1 Provider 内置工具openai.tools对应实现全部位于 tool/ 目录工具引入/完善节点说明web_search2.0.26 引入持续迭代支持sources、action.queries转发4.0.0、外部网络访问参数external_web_access、域名黑名单过滤4.0.23file_search2.0.10/2.0.32 重做支持额外设置3.0.0、file_citation 注解、file_id 保留code_interpreter2.0.10/2.0.29输入代码以tool-input-start/delta/end块流式输出支持注解image_generation2.0.31Provider 执行式图像生成工具apply_patch3.0.0支持部分 diff 流式输出、工具 ID 保留shell/local_shell3.0.0OpenAI 官方 shell 工具与本地 shell 工具支持多轮容器执行mcp3.0.0Provider MCP 工具含审批approval流程tool_search4.0.0新增工具搜索工具支持延迟工具分发与namespace字段往返94eba1bcomputer4.0.15客户端执行式计算机工具支持批量动作与截图输出4.0.43修复了allowedTools选项的映射逻辑之前每条白名单条目都被序列化为{ type: function, name }而 OpenAI 以type识别内置工具导致白名单声明 web search、图像生成、MCP 等工具时抛Tool choice name not found in tools parameter现在条目从声明工具推导含 MCP server 标签与自定义工具名无法白名单的工具tool search、延迟工具、带命名空间的工具会带警告丢弃若白名单因此为空则直接抛错而非静默放行。5.2 推理Reasoning能力2.0.5起加入推理模型配置348fd10将未知模型默认按推理模型处理88574c1又把检测方式从黑名单改为白名单 override 选项3.0.0支持xhigh推理强度5bf101a、promptCacheRetention: 24hgpt-5.1 系列、store: false时自动附加reasoning.encrypted_contentincludeedc55484.0.0默认在开启推理强度时使用 detailed reasoning summaries1772a634.0.11为 GPT-5.6 加入推理与提示缓存控制4.0.59/4.0.60支持gpt-4o-transcribe-diarize分块 说话人元数据与 GPT-6 推理配置更新多轮对话层面修复了 reasoning item 的往返问题5e18272无itemId时以encrypted_content兜底a71d345store: false时丢弃无加密内容的 reasoning parts。5.3 Provider 元数据与流式协议3.0.8修复code_interpreter注解并导出OpenaiResponsesTextProviderMetadata等类型3.0.19在消息/推理层级导出OpenaiResponsesProviderMetadata、AzureResponsesProviderMetadata等3.0.34支持 Responses 消息项的phase字段commentary/final_answer如 gpt-5.3-codex 返回自动在后续请求中保留4.0.16对 200 状态但缺output数组的畸形响应抛出可读的APICallError不再出现output is not iterable的晦涩崩溃4.0.48将流中段 Provider 错误事件统一规范为公开的StreamProviderError保留 Provider 自有的 type/code/status/retry/raw payload 元数据4.0.25修复response.in_progress分块建模后流可提前可用的问题详见 3.3 节。六、Embedding、Chat 与 Completion 的细节演进Embedding3.0.0中textEmbeddingModel泛型移除统一为embeddingModel()8d9e8ad4.0.48为 OpenAI 与 Azure OpenAI 的 Embedding 请求增加基于 UTF-8 字节预算的保守切分结合聚合 token 上限与输入条数上限双重约束Chat Completions3.0.0起默认启用严格 JSONstrict json73d9883gpt-5.x 系列在reasoningEffort: none时允许 temperature/topP/logProbs5648ec04.0.8将内联图片以 data URL 形式发送而非裸 base64流式工具调用4.0.30修复非零、非连续、复用或缺失索引的流式工具调用4.0.9修复部分可解析 JSON 提前终结的问题3.0.36允许 Azure AI Foundry 省略流式 tool_calls delta 的type字段按function处理。七、版本时间线与升级建议3.x 系列AI SDK 6以 Responses API 为主战场引入 gpt-5 系列推理模型、图像/语音/转录 v3 规范、MCP 工具与审批、Conversations API0877683、OPENAI_BASE_URL环境变量9a51b92、fileIdPrefixes配置097b452Azure 侧支持assistant-前缀文件 ID等4.x 系列AI SDK 7 预发布ESM-only 化、顶层 reasoning、Provider References、Batch、程序化工具调用、GPT Image 2.5 / GPT-6 等新模型接入以及对流式协议与错误语义的系统性打磨。对于正在升级的用户建议按本文第四节逐项核对破坏性变更对于新接入用户直接采用当前4.0.65并优先使用 Responses 工厂方法openai(modelId)/responses()以获取最新能力推理、工具搜索、程序化工具调用、图像生成工具等历史模型 ID 与各能力的类型自动补全可参考 chat、responses、image、speech、transcription 等处的模型 ID 类型定义包内还自带test:node/test:edge双端 Vitest 测试vitest.node.config.js、vitest.edge.config.js与 openai-provider.test.ts 等测试用例可作为 API 行为的事实参照。更细的逐版本记录可随时查阅 CHANGELOG 全文。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考