企业官网建设流程全解析

@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 Provider（@ai-sdk/openai）的 CHANGELOG 为骨架，系统梳理该包从早期 Chat Completions 支持到当前4.0.65的能力演进路线，覆盖 Responses API 深度集成、GPT 系列模型 ID、图像生成/编辑、语音与转录、Batch 批量、程序化工具调用与 Realtime 语音等核心能力。读完本文，你将掌握该 Provider 当前具备的完整能力矩阵、历次破坏性变更的迁移要点，以及如何在 AI SDK 中正确使用这些模型工厂方法与 Provider 选项。

一、包定位与安装

@ai-sdk/openai是 AI SDK（The AI Toolkit for TypeScript，源自 Next.js 团队）官方维护的 OpenAI Provider，提供语言模型（Chat Completions / Responses / Completion）、Embedding、图像生成与编辑、语音合成、转录、实时语音（Realtime）、文件与 Batch 等一整套模型工厂与工具集。按照 README 的说明，安装与最小使用方式如下：

npm i @ai-sdk/openai

import { 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-only（"type": "module"）、sideEffects: false，仅依赖@ai-sdk/provider与@ai-sdk/provider-utils两个核心包；prepack脚本会将官方文档 03-openai.mdx 复制进包内docs/目录，方便离线查阅。

二、模型工厂：Provider 的能力入口

从 openai-provider.ts 的源码可以看出，OpenAIProvider实现了ProviderV4规范，以工厂方法的形式暴露全部能力：

以 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.33（experimental_startTextBatch）起步，到4.0.65补齐「batch cancellation and listing」形成闭环。关键节点：

• 4.0.61支持 batch 中按请求指定模型（per-request models）与异步工具调用；
• 4.0.54为 batch 加入工具调用支持（tool calling support to batch）；
• 4.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模型 ID；
• 4.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 Calling）

4.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 calls）；4.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 transcription）；
• 4.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类型统一更名为*SpeechTranslationModel（4.0.34）。

四、4.0.0 破坏性变更与迁移要点

4.0.0（AI SDK v7 预发布）是自 v3 以来最大的一次破坏性升级，迁移时需关注：

1. 全面 ESM-only：所有包移除 CommonJS 导出（ef992f8），require()用户必须切换到import语法；
2. openai.tools.customTool()移除冗余的name参数（61753c3）：工具名改为直接取tools对象键。迁移示例——迁移前：

   tools: { write_sql: openai.tools.customTool({ name: 'write_sql', description: '...', }), }

   迁移后：

   tools: { write_sql: openai.tools.customTool({ description: '...', }), }

3. createToolNameMapping()不再接受resolveProviderToolName：Provider 工具名改为基于tools键的静态映射，不再支持运行时动态解析；
4. 顶层reasoning参数（3887c70）：generateText/streamText支持统一的推理参数规范；
5. Provider References 抽象（c29a26f、34bd95d）：支持按 Provider 上传文件与 Skills，uploadFile/uploadSkill可直接传 Provider 实例（e311194）；
6. Node.js 最低版本提升到 22（7fc6bd6），官方支持 22 / 24 / 26；
7. 新增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中的StreamingToolCallTracker（f807e45）。

五、Responses API：从工具矩阵到推理与元数据

Responses API 是@ai-sdk/openai近几个大版本投入最深的方向，CHANGELOG 记录了清晰的演进脉络。

5.1 Provider 内置工具（openai.tools）

对应实现全部位于 tool/ 目录：

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: '24h'（gpt-5.1 系列）、store: false时自动附加reasoning.encrypted_contentinclude（edc5548）；
• 4.0.0默认在开启推理强度时使用 detailed reasoning summaries（1772a63）；4.0.11为 GPT-5.6 加入推理与提示缓存控制；4.0.59/4.0.60支持gpt-4o-transcribe-diarize（分块 + 说话人元数据）与 GPT-6 推理配置更新；
• 多轮对话层面修复了 reasoning item 的往返问题（5e18272：无itemId时以encrypted_content兜底；a71d345：store: 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 的细节演进

• Embedding：3.0.0中textEmbeddingModel泛型移除，统一为embeddingModel()（8d9e8ad）；4.0.48为 OpenAI 与 Azure OpenAI 的 Embedding 请求增加基于 UTF-8 字节预算的保守切分（结合聚合 token 上限与输入条数上限双重约束）；
• Chat Completions：3.0.0起默认启用严格 JSON（strict json，73d9883），gpt-5.x 系列在reasoningEffort: 'none'时允许 temperature/topP/logProbs（5648ec0）；4.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 API（0877683）、OPENAI_BASE_URL环境变量（9a51b92）、fileIdPrefixes配置（097b452，Azure 侧支持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