如何用 AI SDK 的 Batch API 提交异步批处理并跟踪结果状态【免费下载链接】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 的 Batch API 允许你把多个请求作为一个批次提交给 provider由 provider 在后台异步处理你这边只需定期查询状态、取回终态结果。适用前提Node.js 22 与 pnpm依据 Node.js 快速入门的要求以及ai包。需要注意 Batch 支持目前是实验性能力官方文档明确提示 API 可能在补丁版本中变化升级时留意变更。准备环境按照 AI SDK 的 Node.js 快速入门初始化一个项目mkdir my-batch-app cd my-batch-app pnpm init安装依赖pnpm add ai zod dotenv pnpm add -D types/node tsx typescript其中ai是 AI SDK 主包五个 Batch 生命周期函数都从这里导出tsx用于直接运行 TypeScript 文件。创建项目根目录下的.env文件并写入你的密钥。走 AI Gateway全局默认 provider时环境变量是AI_GATEWAY_API_KEYAI SDK 用它与 Vercel AI Gateway 鉴权AI_GATEWAY_API_KEYxxxxxxxxx把xxxxxxxxx替换为你的实际 API 密钥。如果你想直连某个 provider如 Anthropic则安装对应的 provider 包例如pnpm add ai-sdk/anthropic并按该 provider 的 provider 文档完成凭证配置。选择支持批处理的 provider批处理要求 provider 实现了 batch 接口支持情况按 provider 和模型区分。官方文档列出的第一方支持如下ProviderProvider 值支持的请求类型对应原生 APIAnthropicanthropictextMessage Batches APIGooglegoogletext, imageGemini Batch APIOpenAIopenaitextBatch APIxAIxaitext, imageBatch APIAI Gateway全局默认textBatch processing各 provider 支持的模型、限制和原生批处理行为以其 provider 文档为准。有一个细节要注意OpenAI 和 xAI 的批处理支持是通过 Responses API 提供的而不是openai.chat()/xai.chat()。提交批次startBatchAI SDK 提供五个带experimental_前缀的函数均从ai导出experimental_startBatch提交批次返回初始状态和可序列化的批次引用experimental_getBatchStatus查询最新状态与请求计数experimental_getBatchResults异步迭代每个请求的终态结果experimental_cancelBatch请求取消批次experimental_listBatches分页列出批次及最新状态。下面的主路径使用全局默认 provider未配置全局 provider 时即 AI Gateway依赖前面的AI_GATEWAY_API_KEY把提交、轮询、取结果串成一个完整脚本。把它保存为index.ts用pnpm tsx index.ts运行import { experimental_getBatchResults as getBatchResults, experimental_getBatchStatus as getBatchStatus, experimental_startBatch as startBatch, } from ai; import { setTimeout } from node:timers/promises; import dotenv/config; const batch await startBatch({ requests: [ { id: capital-france, type: text, model: gpt-4.1-nano, prompt: What is the capital of France?, }, { id: capital-germany, type: text, model: gpt-4.1-nano, prompt: What is the capital of Germany?, }, ], }); console.log(batch.id, batch.status); let status batch.status; let error batch.error; while (status pending) { await setTimeout(10_000); const latestStatus await getBatchStatus({ batch }); status latestStatus.status; error latestStatus.error; } if (status failed) { throw new Error(error?.message ?? The batch failed.); } for await (const item of getBatchResults({ batch })) { if (item.status succeeded) { console.log(item.id, item.text); } else { console.error(item.id, item.status, item.error); } }requests中的每个请求必须指定type: text、一个模型 ID以及文本prompt或messages数组。请求 ID 必须非空且在批次内唯一——它是输入请求与结果之间的关联键。结果不保证按输入顺序到达所以应用侧应通过item.id而不是数组下标来把结果映射回业务数据。provider 支持的模型允许时不同请求可以使用不同的模型 ID。每个请求还可以带常规文本生成设置如instructions、maxOutputTokens、temperature、topP、topK、presencePenalty、frequencyPenalty、stopSequences、seed、reasoning。provider 专属配置可以放在批次的providerOptions上也可以放在单个请求的providerOptions上两个层级支持的配置项可能不同startBatch返回结果中的warnings属性会提示不受支持的配置。直连 provider 时把 provider 实例显式传入之后查询状态和取结果也要传同一个 provider。以 Anthropic 为例示例来自官方指南模型claude-haiku-4-5import { anthropic } from ai-sdk/anthropic; import { experimental_startBatch as startBatch } from ai; const provider anthropic; const batch await startBatch({ provider, requests: [ { id: capital-france, type: text, model: claude-haiku-4-5, prompt: What is the capital of France?, }, ], });startBatch返回的批次引用是可序列化的含id、provider、初始status等字段。如果批次会由另一个进程或在稍后时间完成在进程退出前先把它持久化取回批次时传入相同的 providerSDK 会用它确保批次不会经由不兼容的 provider 读取。跟踪批次状态getBatchStatus上面的轮询循环依赖getBatchStatus返回的归一化状态取值只有三种pendingprovider 仍在处理completed批次到达终态可以取结果failed批次无法完成error属性可能包含详情。状态响应还可能包含requestCountsprovider 已知的 total、pending、completed、failed 请求数、createdAt、expiresAt、rawStatus和 provider 元数据。当状态为failed时把error?.message抛出来是文档给出的处理方式。如果不适合持续轮询可以改用 webhook给startBatch传webhookUrl批次到达终态时 provider 会通知该地址。webhook 的支持与载荷是 provider 特定的不支持 webhook 的 provider 会返回一个 unsupported 警告并继续处理不会报错中断。取回结果getBatchResults批次完成后getBatchResults返回一个异步可迭代对象每个 item 对应一个输入请求的终态。成功item.status succeeded的文本 item 包含text拼接后的文本内容结果中没有文本部分时可能是空字符串content按顺序归一化的内容部分text、reasoning、files、sources、tool calls、tool results 等视 provider 支持情况finishReason和可选的rawFinishReasonusage与可选的response元数据可选的providerMetadata。失败、取消、过期的 item 只包含id和终态状态失败 item 附带error取消和过期 item 也可能附带。单个请求失败不代表整个批次全部失败需要逐个 item 独立处理。两点行为限制要清楚批次取结果不会运行 AI SDK 的 tool loop也不会调用客户端定义的execute函数provider 定义的工具有可能在 provider 端执行。结果内容和 provider 元数据应视为不可信的模型输出不要不加筛选地打进日志其中可能包含敏感数据。图片请求是可选分支仅 Google 和 xAI 支持见上面的 provider 表。图片请求使用与generateImage相同的prompt、n、size、aspectRatio、seed、providerOptions等设置例如import { google } from ai-sdk/google; import { experimental_startBatch as startBatch } from ai; const batch await startBatch({ provider: google, requests: [ { id: red-panda, type: image, model: gemini-2.5-flash-image, prompt: A red panda reading beside a cabin window, aspectRatio: 16:9, }, ], });成功的图片 item 带images数组GeneratedFile值混合结果中用type属性区分for await (const item of getBatchResults({ provider: google, batch })) { if (item.type image item.status succeeded) { console.log(item.images); } }注意 provider 的 batch 端点可能只支持上述选项的子集不支持的选项会产生警告或错误。客户端工具同样是可选能力。批次中的客户端定义工具只有定义、没有执行execute函数永远不会被调用AI SDK 也不会代你提交工具结果或发起后续生成。把同一套工具传给getBatchResults用于校验和归一化返回的 tool callimport { anthropic } from ai-sdk/anthropic; import { experimental_getBatchResults as getBatchResults, experimental_startBatch as startBatch, tool, } from ai; import { z } from zod; const tools { get_weather: tool({ description: Get the current weather for a location., inputSchema: z.object({ location: z.string() }), execute: async ({ location }) { // This function is not called by batch processing. return { location, temperature: 21, condition: sunny }; }, }), }; const batch await startBatch({ provider: anthropic, requests: [ { id: weather-san-francisco, type: text, model: claude-haiku-4-5, prompt: Call get_weather for San Francisco, California., tools, toolChoice: { type: tool, toolName: get_weather }, }, ], }); for await (const item of getBatchResults({ provider: anthropic, batch, tools })) { if (item.status succeeded) { console.log(item.id, item.content); } }同名工具在多个请求中使用时定义必须一致。provider 定义的工具如 web search、code execution在 provider 的 batch API 支持时可在 provider 端执行其 tool call 和结果会以归一化的content部分返回。可选操作取消批次与列出批次取消与列批是可选的 provider 能力。用未实现对应能力的 provider 调用这两个函数会抛出UnsupportedFunctionalityError所以下面示例中的provider都指实现了相应能力的 batch provider。请求取消const result await cancelBatch({ provider, batch }); console.log(result.providerMetadata);调用成功只表示 provider 接受了取消请求不保证取消已完成也不保证所有 pending 请求都会被取消。请求取消后仍应再用getBatchStatus查询最新状态确认。列出批次使用游标分页nextCursor不透明且与 provider 相关原样存储或传递即可let cursor: string | undefined; do { const page await listBatches({ provider, limit: 20, cursor, }); for (const batch of page.batches) { console.log(batch.id, batch.status); } cursor page.nextCursor; } while (cursor ! null);每个列表项都是带最新归一化状态的可序列化批次引用可以直接传给getBatchStatus、getBatchResults或cancelBatch。请求控制参数与已知限制所有五个生命周期函数都接受providerOptions、headers、timeout、abortSignalgetBatchStatus、getBatchResults、listBatches额外接受maxRetriesmaxRetries只作用于状态查询、结果取回和列表请求默认 2设为 0 禁用重试它不会重试批次创建或取消操作abortSignal取消当前这次 API 请求timeout限制当前 HTTP 操作。这些参数只影响你与 provider 之间的通信不会改变 provider 侧的处理期限也不会取消已提交的批次。参考文档与示例批处理指南content/docs/03-ai-sdk-core/42-batch.mdxAPI 参考experimental_startBatch、experimental_getBatchStatus、experimental_getBatchResults、experimental_cancelBatch可运行示例Anthropic 文本批次完整流程、AI Gateway 示例、Google 取消与列批示例【免费下载链接】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），仅供参考 如何用 AI SDK 的 Batch API 提交异步批处理并跟踪结果状态
如何用 AI SDK 的 Batch API 提交异步批处理并跟踪结果状态【免费下载链接】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 的 Batch API 允许你把多个请求作为一个批次提交给 provider由 provider 在后台异步处理你这边只需定期查询状态、取回终态结果。适用前提Node.js 22 与 pnpm依据 Node.js 快速入门的要求以及ai包。需要注意 Batch 支持目前是实验性能力官方文档明确提示 API 可能在补丁版本中变化升级时留意变更。准备环境按照 AI SDK 的 Node.js 快速入门初始化一个项目mkdir my-batch-app cd my-batch-app pnpm init安装依赖pnpm add ai zod dotenv pnpm add -D types/node tsx typescript其中ai是 AI SDK 主包五个 Batch 生命周期函数都从这里导出tsx用于直接运行 TypeScript 文件。创建项目根目录下的.env文件并写入你的密钥。走 AI Gateway全局默认 provider时环境变量是AI_GATEWAY_API_KEYAI SDK 用它与 Vercel AI Gateway 鉴权AI_GATEWAY_API_KEYxxxxxxxxx把xxxxxxxxx替换为你的实际 API 密钥。如果你想直连某个 provider如 Anthropic则安装对应的 provider 包例如pnpm add ai-sdk/anthropic并按该 provider 的 provider 文档完成凭证配置。选择支持批处理的 provider批处理要求 provider 实现了 batch 接口支持情况按 provider 和模型区分。官方文档列出的第一方支持如下ProviderProvider 值支持的请求类型对应原生 APIAnthropicanthropictextMessage Batches APIGooglegoogletext, imageGemini Batch APIOpenAIopenaitextBatch APIxAIxaitext, imageBatch APIAI Gateway全局默认textBatch processing各 provider 支持的模型、限制和原生批处理行为以其 provider 文档为准。有一个细节要注意OpenAI 和 xAI 的批处理支持是通过 Responses API 提供的而不是openai.chat()/xai.chat()。提交批次startBatchAI SDK 提供五个带experimental_前缀的函数均从ai导出experimental_startBatch提交批次返回初始状态和可序列化的批次引用experimental_getBatchStatus查询最新状态与请求计数experimental_getBatchResults异步迭代每个请求的终态结果experimental_cancelBatch请求取消批次experimental_listBatches分页列出批次及最新状态。下面的主路径使用全局默认 provider未配置全局 provider 时即 AI Gateway依赖前面的AI_GATEWAY_API_KEY把提交、轮询、取结果串成一个完整脚本。把它保存为index.ts用pnpm tsx index.ts运行import { experimental_getBatchResults as getBatchResults, experimental_getBatchStatus as getBatchStatus, experimental_startBatch as startBatch, } from ai; import { setTimeout } from node:timers/promises; import dotenv/config; const batch await startBatch({ requests: [ { id: capital-france, type: text, model: gpt-4.1-nano, prompt: What is the capital of France?, }, { id: capital-germany, type: text, model: gpt-4.1-nano, prompt: What is the capital of Germany?, }, ], }); console.log(batch.id, batch.status); let status batch.status; let error batch.error; while (status pending) { await setTimeout(10_000); const latestStatus await getBatchStatus({ batch }); status latestStatus.status; error latestStatus.error; } if (status failed) { throw new Error(error?.message ?? The batch failed.); } for await (const item of getBatchResults({ batch })) { if (item.status succeeded) { console.log(item.id, item.text); } else { console.error(item.id, item.status, item.error); } }requests中的每个请求必须指定type: text、一个模型 ID以及文本prompt或messages数组。请求 ID 必须非空且在批次内唯一——它是输入请求与结果之间的关联键。结果不保证按输入顺序到达所以应用侧应通过item.id而不是数组下标来把结果映射回业务数据。provider 支持的模型允许时不同请求可以使用不同的模型 ID。每个请求还可以带常规文本生成设置如instructions、maxOutputTokens、temperature、topP、topK、presencePenalty、frequencyPenalty、stopSequences、seed、reasoning。provider 专属配置可以放在批次的providerOptions上也可以放在单个请求的providerOptions上两个层级支持的配置项可能不同startBatch返回结果中的warnings属性会提示不受支持的配置。直连 provider 时把 provider 实例显式传入之后查询状态和取结果也要传同一个 provider。以 Anthropic 为例示例来自官方指南模型claude-haiku-4-5import { anthropic } from ai-sdk/anthropic; import { experimental_startBatch as startBatch } from ai; const provider anthropic; const batch await startBatch({ provider, requests: [ { id: capital-france, type: text, model: claude-haiku-4-5, prompt: What is the capital of France?, }, ], });startBatch返回的批次引用是可序列化的含id、provider、初始status等字段。如果批次会由另一个进程或在稍后时间完成在进程退出前先把它持久化取回批次时传入相同的 providerSDK 会用它确保批次不会经由不兼容的 provider 读取。跟踪批次状态getBatchStatus上面的轮询循环依赖getBatchStatus返回的归一化状态取值只有三种pendingprovider 仍在处理completed批次到达终态可以取结果failed批次无法完成error属性可能包含详情。状态响应还可能包含requestCountsprovider 已知的 total、pending、completed、failed 请求数、createdAt、expiresAt、rawStatus和 provider 元数据。当状态为failed时把error?.message抛出来是文档给出的处理方式。如果不适合持续轮询可以改用 webhook给startBatch传webhookUrl批次到达终态时 provider 会通知该地址。webhook 的支持与载荷是 provider 特定的不支持 webhook 的 provider 会返回一个 unsupported 警告并继续处理不会报错中断。取回结果getBatchResults批次完成后getBatchResults返回一个异步可迭代对象每个 item 对应一个输入请求的终态。成功item.status succeeded的文本 item 包含text拼接后的文本内容结果中没有文本部分时可能是空字符串content按顺序归一化的内容部分text、reasoning、files、sources、tool calls、tool results 等视 provider 支持情况finishReason和可选的rawFinishReasonusage与可选的response元数据可选的providerMetadata。失败、取消、过期的 item 只包含id和终态状态失败 item 附带error取消和过期 item 也可能附带。单个请求失败不代表整个批次全部失败需要逐个 item 独立处理。两点行为限制要清楚批次取结果不会运行 AI SDK 的 tool loop也不会调用客户端定义的execute函数provider 定义的工具有可能在 provider 端执行。结果内容和 provider 元数据应视为不可信的模型输出不要不加筛选地打进日志其中可能包含敏感数据。图片请求是可选分支仅 Google 和 xAI 支持见上面的 provider 表。图片请求使用与generateImage相同的prompt、n、size、aspectRatio、seed、providerOptions等设置例如import { google } from ai-sdk/google; import { experimental_startBatch as startBatch } from ai; const batch await startBatch({ provider: google, requests: [ { id: red-panda, type: image, model: gemini-2.5-flash-image, prompt: A red panda reading beside a cabin window, aspectRatio: 16:9, }, ], });成功的图片 item 带images数组GeneratedFile值混合结果中用type属性区分for await (const item of getBatchResults({ provider: google, batch })) { if (item.type image item.status succeeded) { console.log(item.images); } }注意 provider 的 batch 端点可能只支持上述选项的子集不支持的选项会产生警告或错误。客户端工具同样是可选能力。批次中的客户端定义工具只有定义、没有执行execute函数永远不会被调用AI SDK 也不会代你提交工具结果或发起后续生成。把同一套工具传给getBatchResults用于校验和归一化返回的 tool callimport { anthropic } from ai-sdk/anthropic; import { experimental_getBatchResults as getBatchResults, experimental_startBatch as startBatch, tool, } from ai; import { z } from zod; const tools { get_weather: tool({ description: Get the current weather for a location., inputSchema: z.object({ location: z.string() }), execute: async ({ location }) { // This function is not called by batch processing. return { location, temperature: 21, condition: sunny }; }, }), }; const batch await startBatch({ provider: anthropic, requests: [ { id: weather-san-francisco, type: text, model: claude-haiku-4-5, prompt: Call get_weather for San Francisco, California., tools, toolChoice: { type: tool, toolName: get_weather }, }, ], }); for await (const item of getBatchResults({ provider: anthropic, batch, tools })) { if (item.status succeeded) { console.log(item.id, item.content); } }同名工具在多个请求中使用时定义必须一致。provider 定义的工具如 web search、code execution在 provider 的 batch API 支持时可在 provider 端执行其 tool call 和结果会以归一化的content部分返回。可选操作取消批次与列出批次取消与列批是可选的 provider 能力。用未实现对应能力的 provider 调用这两个函数会抛出UnsupportedFunctionalityError所以下面示例中的provider都指实现了相应能力的 batch provider。请求取消const result await cancelBatch({ provider, batch }); console.log(result.providerMetadata);调用成功只表示 provider 接受了取消请求不保证取消已完成也不保证所有 pending 请求都会被取消。请求取消后仍应再用getBatchStatus查询最新状态确认。列出批次使用游标分页nextCursor不透明且与 provider 相关原样存储或传递即可let cursor: string | undefined; do { const page await listBatches({ provider, limit: 20, cursor, }); for (const batch of page.batches) { console.log(batch.id, batch.status); } cursor page.nextCursor; } while (cursor ! null);每个列表项都是带最新归一化状态的可序列化批次引用可以直接传给getBatchStatus、getBatchResults或cancelBatch。请求控制参数与已知限制所有五个生命周期函数都接受providerOptions、headers、timeout、abortSignalgetBatchStatus、getBatchResults、listBatches额外接受maxRetriesmaxRetries只作用于状态查询、结果取回和列表请求默认 2设为 0 禁用重试它不会重试批次创建或取消操作abortSignal取消当前这次 API 请求timeout限制当前 HTTP 操作。这些参数只影响你与 provider 之间的通信不会改变 provider 侧的处理期限也不会取消已提交的批次。参考文档与示例批处理指南content/docs/03-ai-sdk-core/42-batch.mdxAPI 参考experimental_startBatch、experimental_getBatchStatus、experimental_getBatchResults、experimental_cancelBatch可运行示例Anthropic 文本批次完整流程、AI Gateway 示例、Google 取消与列批示例【免费下载链接】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），仅供参考