用途:让大语言模型按给定 schema 返回类型安全的 JSON 结构化结果,用于脚本、服务端接口、CLI 或前端渐进式表单等场景。
主要能力:在 chat() 传入 outputSchema 时,返回 Promise<推断类型> 而非流式块;加 stream: true 则得到增量 JSON 加终端已校验对象。useChat({ outputSchema }) 提供 partial(流式逐字段填充)与 final(完成时快照)。支持 Zod、ArkType、Valibot schema,含嵌套对象与数组。每次成功完成的结构化运行会向 assistant 消息添加类型化的 StructuredOutputPart,保留多轮历史。
使用方式:以 openaiText('gpt-5.2') 等适配器调用 chat,messages 加 outputSchema;流式时用 for await 读取,遇到 CUSTOM 块且 name 为 structured-output.complete 时取 chunk.value.object。前端在服务端用 toServerSentEventsResponse(stream) 返回 SSE,客户端用 useChat({ connection: fetchServerSentEvents(...), outputSchema }) 读取 partial/final。UI 端点必须传 stream: true。
适配器:部分适配器支持原生组合模式(schema 与 tools 同次调用),其余走回退路径,先跑智能体循环再单独做结构化输出。消费端代码在各提供者间一致。
限制:useChat 的 outputSchema 仅用于客户端类型推断,流式服务端路径不执行 Standard Schema 校验,必要时需在消费端自行校验;部分适配器不支持 schema 与 tools 同时流式。本技能依赖 ai-core 与 ai-core/chat-experience,应先阅读。