ai-blog

LanguageModelV4StreamPart（流式通信协议）

vercel/ai 流式 LLM 通信协议的完整事件类型集合（21 种），V3 引入、V4 延续。定义了 Provider 在 doStream 中可以 emit 的所有事件，按 start/delta/end 三元组组织，内置展示语义（title 字段），tool-approval-request 有意不含对应 response（协议层单向请求，框架层闭环）。

定义

LanguageModelV4StreamPart 是 @ai-sdk/provider 包中的一个 TypeScript union type，定义了 LLM Provider 在流式响应时可以向框架层发送的 21 种事件类型。

它不只是一个数据类型，而是 vercel/ai 的流式 LLM 通信协议——类似 WebSocket 消息格式规范。

内部结构：三元组 + 单事件

21 种类型按模式分类：

start/delta/end 三元组（流式内容）：

  • text-start / text-delta / text-end
  • reasoning-start / reasoning-delta / reasoning-end
  • tool-input-start / tool-input-delta / tool-input-end

单事件（原子性）：

  • tool-result（工具执行完毕，全量到达）
  • tool-approval-request（Provider 请求用户审批）
  • tool-call、file、reasoning-file、source
  • stream-start、response-metadata、finish、raw、error

非对称设计：tool-result 没有三元组（工具输出是原子性 JSON，无需流式）。这是合理的非对称，不是设计缺陷。

tool-approval-request 的刻意非对称

协议里有 tool-approval-request（Provider 流出的审批请求），但没有 tool-approval-response（审批结果回传）。

这是设计决策，不是遗漏：

  • 审批结果不通过 stream 协议传回 Provider
  • 框架层收到请求后挂起，等待用户输入
  • 审批结果作为新的 prompt message 在下次 doGenerate/doStream 调用时传入

职责分离：Provider 协议层只管发出请求，框架层负责整个审批闭环。

tool-input-start 的协议内置展示语义

typescript
// tool-input-start 的关键可选字段
providerExecuted?: boolean  // Provider 服务端执行工具（MCP 场景）
dynamic?: boolean           // 工具名无法解析（DynamicToolCall 对应）
title?: string              // 工具的 UI 显示标题 ← 协议层内置展示语义

title 出现在协议层说明 vercel/ai 把工具的 UI 呈现当作 Provider 协议的一部分——Provider 在 stream 里可以直接指定工具的显示名称，UI 渲染层无需映射。

明显缺失的事件类型

tool-execution-update（mid-execution 进度通知）不存在。从 tool-input-end 到 tool-result 之间是黑盒，无进度反馈。长耗时工具（代码执行、文件搜索）无法向 UI 上报中间状态。pi-mono 的 tool_execution_update 事件填补了这个空缺，是编程助手场景的强需求。

与 StepResult.content 的关系

StepResult 的 content: ContentPart[] 是对流式事件的聚合和物化——流式事件是时序的、增量的，content 数组是整步完成后的静态快照。两者是同一份数据在不同时态的表示。