关键认知
Streaming UI 的本质不是"让文字一个字一个字蹦出来",而是将 AI 的决策过程与 UI 的渲染过程在时间轴上对齐。Server Components 让组件在服务端流式渲染,AI SDK 让 LLM 的输出逐块到达——两者结合,用户看到的是"决策逐步具象化为界面",而不是"等待一个完整页面返回"。
一、传统 REST 方案在 AI 场景下的系统性瓶颈
在讨论流式方案之前,需要先理解为什么传统的 REST 接口模式在 AI 应用中越来越力不从心。这不是一个"体验优化"的小问题,而是架构层面的根本性错配。
1.1 全量等待模式的本质缺陷
REST 接口遵循经典的"请求-等待-响应"模型:客户端发出请求,服务端调用 LLM,等 LLM 生成完整响应后,一次性返回全部内容。这意味着用户在整个 LLM 推理期间——通常 3 秒到 15 秒甚至更长——面对的是空白页面或一个 loading spinner。
这不仅仅是"体验不好"的问题。传统 Web 应用中一个 API 的响应时间通常在 50-200ms,用户感知不到等待。但 AI 应用的延迟天然就在秒级,REST 模式把这个问题放大到了不可接受的程度。一个 10 秒的白屏等待,足以让大量用户直接关闭页面。
1.2 信息密度的时间错配
LLM 的输出具有明显的时间分布特征:前半段通常是推理过程、中间步骤或缓冲性文本(如"让我分析一下这个问题……"),后半段才是结构化的关键结果(如组件配置、数据结构、具体答案)。
REST 方式下,用户要么看到一个 spinner 等全部完成,要么前端就需要做"先显示文本再替换为组件"的 hack 处理。流式模式下可以做到:推理过程以轻量文本形式逐步展示(降低焦虑感),关键结构化数据到达时触发组件渲染(提供实际价值),两者的节奏完全不同。
1.3 中断、重试与成本问题
REST 请求一旦发出,如果中途用户想修改 Prompt 或放弃当前结果,只能取消整个请求。等 LLM 跑完的 token 全部浪费,但仍然计费。
网络波动场景下更严重:一个 10 秒的请求如果在第 8 秒断开,REST 方案下用户需要从头再来,之前 8 秒的计算和等待全部归零。流式方案天然支持部分保留:已经到达客户端的数据块不需要重传。
1.4 长输出场景下的内存与负载压力
当 LLM 输出非常长(比如生成一份完整报告或多个组件配置),REST 方案要求服务端在内存中缓存整个响应体,直到生成完毕才开始发送。高并发场景下,多个请求同时在服务端"持有"大型响应体,会显著增加内存占用。流式方案中,服务端可以边生成边转发,每个 chunk 发出后即可释放对应内存。
二、Streaming 的分层架构:数据流与渲染流
理解流式方案的关键,是将它拆分为两层来理解:数据流层负责将 LLM 的输出传输到客户端,渲染流层负责将到达的数据逐步转化为 UI。两者各自独立运作,又在关键节点上协同配合。
2.1 数据流层:AI SDK 的流式传输机制
streamText 的工作原理
streamText 是 Vercel AI SDK 提供的核心 API,封装了与 LLM 交互的流式通信。底层机制如下:LLM 的推理引擎(如 OpenAI、Anthropic 等)通过 Server-Sent Events(SSE)协议逐 token 返回结果,streamText 将这些 token 封装为一个 ReadableStream,通过 HTTP 的 Transfer-Encoding: chunked 方式传输到客户端。
基本调用方式:
// app/api/chat/route.ts
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: openai('gpt-4o'),
messages,
});
return result.toDataStreamResponse();
}
客户端通过 useChat hook 自动消费这个 stream:
'use client';
import { useChat } from 'ai/react';
export default function Chat() {
const { messages, input, handleInputChange, handleSubmit } = useChat();
return (
<div>
{messages.map(m => (
<div key={m.id}>
<strong>{m.role}:</strong> {m.content}
</div>
))}
<form onSubmit={handleSubmit}>
<input value={input} onChange={handleInputChange} />
</form>
</div>
);
}
Streaming Text vs Streaming Structured Data
这是生成式 UI 场景下最重要的区分。
Streaming Text 是 LLM 逐 token 输出自然语言文本,适合聊天、长文生成等场景。客户端拿到的是一个 token 流,前端通常直接追加渲染 Markdown。它的流式行为是线性的:每个 token 直接追加到已有文本末尾。
Streaming Structured Data 是 LLM 通过 Function Calling 或 Structured Output 逐步构建一个 JSON 对象。这是生成式 UI 的核心需求——AI 不是在"写文章",而是在"填写一张配置表"。两者的流式行为完全不同:文本流是线性的,结构化数据流是非线性的,JSON 的不同字段可能在不同时间点被填充。
用具体场景说明:用户说"帮我生成一个用户数据看板"。文本流输出的是"我建议使用看板组件,包含用户增长趋势图和活跃度指标卡……",结构化流输出的是:
{
"components": [
{
"type": "metric-card",
"title": "总用户数",
"value": "128,493"
},
{
"type": "line-chart",
"title": "用户增长趋势",
"data": [...]
}
]
}
后者可以直接驱动组件渲染,这就是结构化流的价值。
使用 streamObject 实现结构化流:
import { streamObject } from 'ai';
import { z } from 'zod';
const dashboardSchema = z.object({
components: z.array(
z.object({
type: z.enum(['metric-card', 'line-chart', 'bar-chart', 'table']),
title: z.string(),
data: z.any().optional(),
config: z.any().optional(),
})
),
});
export async function POST(req: Request) {
const { prompt } = await req.json();
const result = streamObject({
model: openai('gpt-4o'),
schema: dashboardSchema,
prompt: `根据用户需求生成数据看板配置:${prompt}`,
});
return result.toTextStreamResponse();
}
工具调用的流式化
当 AI 需要调用多个 Tool(比如先查数据库、再查天气、最后组装 UI)时,REST 方式需要等所有工具调用完成后才返回结果。流式模式下,每个 Tool 的调用决策、执行过程和返回结果都可以独立流入客户端。
用户看到的不再是"AI 在思考"的 spinner,而是:
- 第 1 秒:AI 决定查询用户数据 → 显示"正在查询用户数据……"
- 第 3 秒:用户数据返回 → 渲染出用户指标卡片
- 第 4 秒:AI 决定查询增长趋势 → 显示"正在分析增长趋势……"
- 第 7 秒:趋势数据返回 → 渲染出趋势图表
- 第 8 秒:AI 生成文字总结 → 渲染分析结论
这就是"AI 在逐步构建页面"的体验,远比一个 15 秒的 spinner 有价值。
Stream 协议详解
在实际工程中,理解底层传输协议有助于排查问题和做性能优化。
SSE(Server-Sent Events) 是 Vercel AI SDK 默认使用的协议。单向通信,基于 HTTP,浏览器原生支持 EventSource API。优势是简单、兼容性好、天然支持自动重连(通过 retry 字段)。在 AI 应用这种"服务端推、客户端收"的场景下非常合适。
WebSocket 是双向通信协议,适合需要客户端频繁向服务端发送数据的场景(如实时协作编辑、在线游戏)。但在 AI 应用中,客户端主要是接收数据,上行数据量很小(只是偶尔发一条消息),WebSocket 的双向能力属于过度设计,且增加了连接管理的复杂度。
HTTP Chunked Transfer 是 SSE 底层依赖的传输机制。每个 chunk 是一个完整的 HTTP 数据块,服务端可以逐块发送,客户端逐块接收。它不依赖特殊的 API(就是普通 HTTP),兼容性最好。
三者的选择建议:AI 应用优先用 SSE(简单、够用),需要双向实时通信时用 WebSocket,不要为了"看起来先进"而选择不需要的协议。
2.2 渲染流层:Server Components 的流式渲染机制
RSC 的流式工作原理
React Server Components(RSC)在服务端执行并渲染,产出的不是 HTML 字符串,而是一种特殊的 RSC Payload 格式——一种序列化的组件树描述。
这个 RSC Payload 可以流式传输:服务端不必等整棵组件树渲染完毕,而是逐步将已完成的组件序列化为 payload 并发送到客户端。客户端逐块接收并执行 hydration,将服务端产出的描述转化为真实的 DOM 节点。
一个简化的 RSC Payload 示例:
0:["$","div",null,{"className":"dashboard"}]
1:["$","h1",null,{"children":"用户数据看板"}]
2:["$","$Suspense",null,{"fallback":"$3","children":"$4"}]
3:["$","div",null,{"className":"skeleton","children":"加载中..."}]
4:["$","div",null,{"className":"metric-card","children":[...]}]
数字前缀表示 chunk 编号,每个 chunk 是一个自包含的组件描述。客户端在收到时就可以立即处理,不需要等全部到齐。
Suspense 边界的策略设计
<Suspense> 是控制流式渲染节奏的核心工具。被 <Suspense> 包裹的异步组件可以独立于父组件延迟到达,在等待期间客户端显示 fallback,数据到达后替换为真实内容。
不同的 Suspense 策略会产生完全不同的用户体验:
逐组件 Suspense:每个动态组件独立包裹 Suspense,各自有独立的加载和错误状态。适合组件间无依赖的场景。缺点是页面可能出现"此起彼伏"的骨架屏闪烁。
<Suspense fallback={<CardSkeleton />}>
<UserMetrics data={metricsPromise} />
</Suspense>
<Suspense fallback={<ChartSkeleton />}>
<GrowthChart data={chartPromise} />
</Suspense>
<Suspense fallback={<TableSkeleton />}>
<DataTable data={tablePromise} />
</Suspense>
分组 Suspense:相关组件共享一个 Suspense 边界,一起出现。适合需要保持视觉一致性的场景(如一个表单的所有字段必须同时出现)。
<Suspense fallback={<DashboardSkeleton />}>
<UserMetrics data={metricsPromise} />
<GrowthChart data={chartPromise} />
<DataTable data={tablePromise} />
</Suspense>
嵌套 Suspense:外层先展示骨架结构,内层逐步填充细节。这是生成式 UI 中最有价值的模式——页面的大框架快速出现,AI 生成的细节内容逐步填充进去。
<Suspense fallback={<DashboardSkeleton />}>
<DashboardLayout>
<Suspense fallback={<CardSkeleton />}>
<UserMetrics data={metricsPromise} />
</Suspense>
<Suspense fallback={<ChartSkeleton />}>
<GrowthChart data={chartPromise} />
</Suspense>
</DashboardLayout>
</Suspense>
在实际项目中,这三种策略往往混合使用。建议的原则是:视觉上强关联的组件放在同一个 Suspense 边界内,视觉上独立的组件各自包裹 Suspense。
2.3 两者结合:数据流 × 渲染流的时序对齐
核心机制:AI 输出流驱动 Server Component 渲染
AI 的输出流(ReadableStream)如何与 Server Component 的渲染流(RSC Payload)对接,是整个方案最关键的技术点。
基本模式如下:
- API Route 接收用户请求
- 调用
streamText或streamObject获取 AI 输出流 - 在 Server Component 中消费这个流
- 将流式数据作为 props 传递给子组件
<Suspense>控制每个区块的渲染时机
Vercel AI SDK 提供了 createStreamableUI 作为桥接工具。它创建一个"可流式更新的 UI 容器",初始渲染一个 fallback,随着 AI 输出逐步到达,调用 .update() 或 .append() 方法替换或追加 React 元素。客户端收到的是一个不断更新的 RSC Payload 流。
import { createStreamableUI } from 'ai/rsc';
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
export async function generateDashboard(prompt: string) {
const uiStream = createStreamableUI(<DashboardSkeleton />);
streamText({
model: openai('gpt-4o'),
prompt,
tools: {
queryDatabase: { /* tool definition */ },
fetchExternalAPI: { /* tool definition */ },
},
onChunk: async (chunk) => {
if (chunk.type === 'tool-result' && chunk.toolName === 'queryDatabase') {
uiStream.update(
<DashboardLayout>
<UserMetrics data={chunk.result} />
<ChartSkeleton />
</DashboardLayout>
);
}
if (chunk.type === 'tool-result' && chunk.toolName === 'fetchExternalAPI') {
uiStream.update(
<DashboardLayout>
<UserMetrics data={/* existing data */} />
<GrowthChart data={chunk.result} />
</DashboardLayout>
);
}
},
onFinish: () => {
uiStream.done();
},
});
return uiStream.value;
}
Promise 与 Suspense 的配合机制
createStreamableUI 返回的 .value 实际上是一个 Promise-like 对象,在流式过程中处于 pending 状态,流结束后 resolve 为最终的 React 元素。
当这个对象被放在 <Suspense> 边界内时,React 的行为是:pending 阶段显示 fallback,每次 .update() 调用触发客户端重新渲染最新内容,.done() 后 resolve 为最终版本。
这里有一个容易误解的点:这不是传统的 Promise resolve(一次性完成),而是通过特殊的流式协议实现的"多次推送"。传统的 Promise 从 pending 到 resolved 只有一次状态变化,但 createStreamableUI 的特殊之处在于它可以在 pending 阶段多次向客户端推送中间状态。理解这一点对于调试和优化至关重要。
完整时序
用一个具体的用户交互场景来串联整个流程。用户输入"帮我分析最近一周的用户增长数据":
0ms — 用户提交请求,客户端显示全页面骨架屏。
50ms — 服务端收到请求,创建 createStreamableUI,初始值为骨架屏组件。调用 streamText 开始 LLM 推理。
800ms — LLM 输出第一个 token:“根据”。此时 AI 还在推理阶段,内容不具备渲染价值,服务端暂不更新 UI stream。
2000ms — LLM 决定调用 queryDatabase 工具。服务端执行数据库查询(耗时 500ms),拿到用户数据后调用 uiStream.update(),将骨架屏的指标卡区域替换为真实的用户指标组件。客户端收到新的 RSC Payload chunk,hydrate 后更新 DOM——用户看到指标卡出现了。
3500ms — LLM 决定调用 fetchExternalAPI 获取行业对比数据。服务端发起外部 API 请求(耗时 1200ms),返回后更新 UI stream,趋势图表组件出现。
5200ms — LLM 开始输出文字总结:“从数据来看,本周用户增长率为 12.3%,较上周提升 2.1 个百分点……”。服务端以打字机节奏逐步推送文本到 UI stream,客户端逐字渲染。
8000ms — LLM 完成输出,服务端调用 uiStream.done()。客户端完成最终渲染,骨架屏全部消失,完整的数据分析页面呈现给用户。
整个过程中,用户的感知是:1 秒内看到骨架屏(反馈),3 秒看到第一个数据卡片(价值),5 秒看到图表(深化),8 秒看到完整报告(完成)。对比 REST 方案下 8 秒白屏后一次性呈现所有内容,体验提升是质变级别的。
三、实战:从简单到复杂的渐进式构建
3.1 基础版:AI 流式文本 + Markdown 渲染
这是最简单的 Streaming UI 场景:用户提问,AI 逐步输出带格式的文本回答。
服务端:
// app/api/chat/route.ts
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: openai('gpt-4o'),
messages,
system: '你是一个技术助手,请用 Markdown 格式回答。',
});
return result.toDataStreamResponse();
}
客户端:
'use client';
import { useChat } from 'ai/react';
import ReactMarkdown from 'react-markdown';
export default function Chat() {
const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();
return (
<div className="chat-container">
{messages.map(m => (
<div key={m.id} className={`message ${m.role}`}>
<ReactMarkdown>{m.content}</ReactMarkdown>
{isLoading && m.role === 'assistant' && m.id === messages[messages.length - 1].id && (
<span className="cursor-blink" />
)}
</div>
))}
<form onSubmit={handleSubmit}>
<input
value={input}
onChange={handleInputChange}
placeholder="输入你的问题..."
/>
<button type="submit">发送</button>
</form>
</div>
);
}
一个需要注意的边界情况:Markdown 渲染不完整状态的处理。比如 AI 还在输出一段代码块时,可能只到了 ```javascript\nconst a = 1 还没有闭合的 ````,此时react-markdown` 会将未闭合的代码块渲染为纯文本。解决方案是在渲染前做一个简单的预处理:检测未闭合的代码块标记并临时补全。
3.2 进阶版:AI 流式返回结构化配置 + 动态组件渲染
这个版本更接近真实的生成式 UI 场景:用户描述需求,AI 逐步输出组件配置 JSON,前端动态挂载不同类型的组件。
首先定义输出的 Schema:
import { z } from 'zod';
const componentSchema = z.object({
type: z.enum(['metric-card', 'line-chart', 'bar-chart', 'data-table', 'text-block']),
title: z.string(),
props: z.record(z.any()),
});
const dashboardSchema = z.object({
components: z.array(componentSchema),
layout: z.enum(['single-column', 'two-column', 'grid']).optional(),
});
服务端使用 streamObject:
// app/api/generate-dashboard/route.ts
import { streamObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { dashboardSchema } from '@/lib/schemas';
export async function POST(req: Request) {
const { prompt } = await req.json();
const result = streamObject({
model: openai('gpt-4o'),
schema: dashboardSchema,
prompt: `根据以下需求生成数据看板配置:${prompt}`,
});
return result.toTextStreamResponse();
}
客户端维护一个组件注册表,根据 AI 返回的 type 字段动态选择组件:
'use client';
import { useObject } from 'ai/react';
import { dashboardSchema } from '@/lib/schemas';
const componentRegistry: Record<string, React.ComponentType<any>> = {
'metric-card': MetricCard,
'line-chart': LineChart,
'bar-chart': BarChart,
'data-table': DataTable,
'text-block': TextBlock,
};
export default function DashboardGenerator() {
const { object, submit, isLoading } = useObject({
api: '/api/generate-dashboard',
schema: dashboardSchema,
});
return (
<div>
<button onClick={() => submit({ prompt: '用户增长数据看板' })}>
生成看板
</button>
<div className="dashboard">
{object?.components?.map((component, index) => {
const Component = componentRegistry[component?.type];
if (!Component) {
return <FallbackComponent key={index} type={component?.type} />;
}
return (
<Suspense key={index} fallback={<ComponentSkeleton type={component?.type} />}>
<Component title={component?.title} {...(component?.props ?? {})} />
</Suspense>
);
})}
</div>
</div>
);
}
三个重要的边界处理:
AI 返回了未知的 type:组件注册表中找不到对应组件时,显示一个 FallbackComponent,提示"不支持的组件类型",而不是白屏崩溃。
JSON 格式不合法:streamObject 内部配合 Zod schema 做校验。如果某个字段缺失或类型错误,Zod 会抛出校验错误。可以在 useObject 的 onError 回调中捕获并展示友好提示。
部分字段缺失:AI 可能先输出了 type 和 title,但 props 还没生成。此时组件应该使用默认 props 渲染,而不是等待。可以在组件内部做 props 的默认值合并。
3.3 完整版:多步 Tool Calling + 并行 UI 构建
这是最有说服力的示例,完整展示"AI 做决策 → 工具执行 → UI 构建"的全链路流式化。
场景:用户输入"对比我们和竞品的用户增长数据,生成分析报告"。AI 需要先查询内部数据库,再查询外部数据源,最后组装多个可视化组件。
定义工具:
const tools = {
queryUserGrowth: {
description: '查询内部用户增长数据',
parameters: z.object({
startDate: z.string(),
endDate: z.string(),
granularity: z.enum(['daily', 'weekly', 'monthly']),
}),
execute: async ({ startDate, endDate, granularity }) => {
// 查询数据库
return await db.query(`
SELECT date, new_users, active_users
FROM user_metrics
WHERE date BETWEEN ${startDate} AND ${endDate}
GROUP BY date
`);
},
},
queryCompetitorData: {
description: '查询竞品公开数据',
parameters: z.object({
competitor: z.string(),
metric: z.string(),
}),
execute: async ({ competitor, metric }) => {
// 调用外部 API
const response = await fetch(`https://api.competitor-data.com/${competitor}/${metric}`);
return response.json();
},
},
calculateGrowthRate: {
description: '计算增长率',
parameters: z.object({
current: z.number(),
previous: z.number(),
}),
execute: async ({ current, previous }) => {
return {
rate: ((current - previous) / previous * 100).toFixed(1),
trend: current > previous ? 'up' : 'down',
};
},
},
};
服务端处理多工具流式调用:
export async function generateAnalysisReport(prompt: string) {
const uiStream = createStreamableUI(<ReportSkeleton />);
const stepTracker = { currentStep: 0, totalSteps: 0 };
streamText({
model: openai('gpt-4o'),
prompt,
tools,
maxSteps: 5,
onStepFinish: async ({ toolCalls, toolResults }) => {
for (let i = 0; i < toolCalls.length; i++) {
const call = toolCalls[i];
const result = toolResults[i];
if (call.toolName === 'queryUserGrowth') {
uiStream.append(
<Section>
<SectionTitle>内部用户数据</SectionTitle>
<UserGrowthChart data={result} />
</Section>
);
}
if (call.toolName === 'queryCompetitorData') {
uiStream.append(
<Section>
<SectionTitle>竞品数据对比</SectionTitle>
<ComparisonChart ourData={/* ref */} competitorData={result} />
</Section>
);
}
if (call.toolName === 'calculateGrowthRate') {
uiStream.append(
<Section>
<SectionTitle>增长率分析</SectionTitle>
<GrowthRateCard rate={result.rate} trend={result.trend} />
</Section>
);
}
}
},
onFinish: async ({ text }) => {
uiStream.append(
<Section>
<SectionTitle>总结</SectionTitle>
<ReactMarkdown>{text}</ReactMarkdown>
</Section>
);
uiStream.done();
},
});
return uiStream.value;
}
客户端使用独立的 Suspense 边界管理每个区块:
export default function AnalysisPage() {
const [reportPromise] = useState(() => generateAnalysisReport('对比用户增长数据'));
return (
<div className="report-container">
<Suspense fallback={<ReportSkeleton />}>
<AnalysisReport promise={reportPromise} />
</Suspense>
</div>
);
}
function AnalysisReport({ promise }: { promise: Promise<ReactNode> }) {
const report = use(promise);
return <div>{report}</div>;
}
用户看到的体验:1 秒看到骨架屏 → 3 秒看到内部数据图表出现 → 6 秒看到竞品对比图出现 → 8 秒看到增长率指标卡 → 10 秒看到 AI 总结文字。整个报告在用户眼前逐步"搭建"完成。
四、用户体验深度优化
流式本身只解决了"内容能逐步到达"的问题,但要让用户真正感受到流畅和舒适,需要大量的 UX 设计细节。
4.1 骨架屏与渐进填充策略
AI 的第一个 token 到达前通常有 0.5-2 秒的推理延迟(TTFB),这段时间用户看到的是空白。骨架屏的作用是在这个窗口期提供视觉反馈。
骨架屏的设计原则:
- 形状与最终内容相似。如果最终是卡片,骨架也应该是卡片形状;如果最终是图表,骨架应该是一个带有坐标轴暗示的矩形。形状差异太大的骨架屏在替换时会产生明显的视觉跳变。
- 动画节奏舒缓。通常用 pulse(脉冲)或 shimmer(微光)效果,频率控制在 1.5-2 秒一个周期。太快会变成视觉噪音,太慢会让人以为系统卡死。
- 过渡平滑。骨架屏到真实内容的切换不能"闪一下",建议用 CSS transition 做 200-300ms 的 opacity 渐变。
进阶思路:根据 AI 的首段输出动态调整骨架屏。比如 AI 先输出了"我将为你生成一个包含图表和数据表格的报告",客户端解析这段文本后可以调整骨架屏的布局——显示一个图表形状的骨架和一个表格形状的骨架,让用户提前知道最终页面的结构。
4.2 流式中断与错误恢复
用户主动中断:提供"停止生成"按钮。技术实现上,调用 AbortController.abort() 中断 fetch 请求。
const { messages, input, handleInputChange, handleSubmit, stop, isLoading } = useChat();
// 停止按钮
{isLoading && (
<button onClick={stop}>停止生成</button>
)}
停止后已渲染的内容如何处理?建议保留当前状态。停止后已渲染的内容保持不变,用户可以在此基础上修改 Prompt 继续生成。这是最自然的体验,避免了"我停了但之前看到的东西也没了"的挫败感。
网络中断:SSE 断开后浏览器的 EventSource 会自动尝试重连(通过 retry 字段控制间隔)。但重连后如何恢复到断开点?Vercel AI SDK 内部维护了消息状态,重连后会从上一个完整的消息位置继续。如果 SDK 未自动处理,客户端可以在重连时将已有的 messages 数组传回服务端,让 LLM 从上下文中恢复。
LLM 超时或返回错误:流式过程中 LLM 可能因为上下文超长、内容过滤、服务过载等原因中断输出。需要在前端展示友好的错误信息,并保留已成功渲染的部分。
const { messages, error } = useChat();
if (error) {
return (
<div>
{/* 已渲染的消息保持不变 */}
{messages.map(m => <Message key={m.id} {...m} />)}
{/* 错误提示覆盖在底部 */}
<div className="error-banner">
生成中断:{error.message}
<button onClick={retry}>重试</button>
</div>
</div>
);
}
4.3 两种流式节奏的设计选择
打字机节奏(Typewriter):适用于文本内容。每个 token 到达后立即追加显示,配合光标闪烁动画。用户看到的是"AI 正在写"的过程感。
优化细节:token 的追加速度不宜过快(会导致文字跳帧,用户来不及阅读)也不宜过慢(会产生断续感),建议做节流处理,以 30-50ms 为间隔批量追加。光标用 CSS animation 实现闪烁的竖线,在最后一个 token 后面持续闪烁直到流结束。
.cursor-blink::after {
content: '│';
animation: blink 0.8s step-end infinite;
color: var(--accent);
}
@keyframes blink {
50% { opacity: 0; }
}
构建式节奏(Assembly):适用于结构化 UI。每个组件在数据准备好后独立出现,像搭积木一样逐步构建完整页面。
优化细节:组件出现时加一个入场动画(fade + slide up),增强"构建感"。相关组件(如一个图表和它的标题)应该通过同一个 Suspense 边界控制为一起出现,不要标题先出来再等 3 秒图表才出来。
.component-enter {
animation: fadeSlideUp 0.4s ease-out forwards;
}
@keyframes fadeSlideUp {
from {
opacity: 0;
transform: translateY(12px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
构建顺序的控制:AI 的输出顺序不一定是最优的视觉展示顺序。可以在客户端做缓冲——先收集足够数据再批量渲染一个区块,而不是零散地逐个显示。具体做法是维护一个 buffer 队列,当一个组件的完整 props 到齐后才加入渲染队列。
混合节奏:实际应用中,一个页面往往同时包含文本和结构化 UI。建议的设计是"文本区域用打字机节奏,组件区域用构建式节奏",两者通过不同的 Suspense 边界独立控制,互不干扰。
4.4 用户控制权与交互设计
停止生成:按钮在生成过程中始终可见,位置固定(如输入框旁边或浮动在右下角),样式醒目但不突兀。生成完成后按钮自动隐藏或变为"重新生成"。
重新生成:保留用户输入,清理上一次流式渲染的所有状态后重新发起请求。需要注意的是,不能只清 messages 不清 UI stream 状态,否则会出现上一次和这一次的 UI 混在一起的 bug。
编辑后继续:在 AI 生成的中间结果上修改,然后让 AI 基于修改后的内容继续生成。这需要将已渲染的 UI 状态反序列化为 AI 可理解的上下文,实现复杂度较高,但对于产品价值很大。
流式过程中的交互:AI 还在生成时,用户能否点击已经出现的组件进行交互?建议已渲染的组件应该立即可交互(如展开/折叠、切换标签页、hover 查看详情),而不是等全部生成完才允许操作。这要求组件的交互逻辑独立于流式状态。
4.5 性能感知优化
进度指示:虽然无法精确知道 LLM 的总输出长度,但可以用启发式方法提供粗略进度。比如根据已输出 token 数和模型的平均输出长度估算一个百分比,或者更简单地用"已生成 X 个组件 / 预计 Y 个组件"来表达。
内容预览:如果 AI 生成的是一个长页面,可以在流式过程中提供一个缩略的目录或"迷你地图",让用户知道当前生成到了哪个章节。
完成收束动画:所有组件都渲染完毕后,做一个轻微的整体收束动画——各组件轻微 settle 到最终位置,底部出现一条分割线或"生成完成"的标识。给用户一个明确的"完成感",而不是在某个不确定的时刻悄悄结束。
五、与 REST 方案的全面对比
5.1 技术维度
| 维度 | REST 接口 | Streaming + RSC |
|---|---|---|
| 首字节时间 (TTFB) | 高(等待完整响应,3-15s) | 低(首个 chunk 快速到达,0.5-2s) |
| 首屏渲染时间 | 高(接收完才开始渲染) | 低(边接收边渲染) |
| 用户感知延迟 | 强(白屏 + spinner) | 弱(内容逐步出现) |
| 结构化 UI 支持 | 响应后一次性渲染 | 边到达边渲染,组件逐步挂载 |
| 中断恢复 | 全部重来 | 保留已到达部分 |
| 服务端内存占用 | 高(缓存完整响应) | 低(边转发边释放) |
| 带宽利用 | 集中爆发(一次性大包) | 均匀分布(持续小包) |
5.2 工程维度
| 维度 | REST 接口 | Streaming + RSC |
|---|---|---|
| 实现复杂度 | 低(标准 CRUD 思维) | 中高(需理解 RSC + 流式协议) |
| 调试难度 | 低(完整请求/响应可捕获) | 高(流式数据需要特殊工具) |
| 测试复杂度 | 低(mock 一个完整响应即可) | 高(需模拟流式行为和时序) |
| 错误处理 | 简单(成功/失败二元) | 复杂(部分成功 + 中断 + 恢复) |
| 缓存策略 | 成熟(HTTP 缓存、CDN) | 复杂(流式内容难以缓存) |
| 浏览器兼容性 | 通用 | 需现代浏览器支持 |
5.3 适用场景
选 REST:短响应(< 1 秒)、简单查询、不需要实时反馈、对 SEO 有硬性要求、团队对 RSC 不熟悉且项目时间紧。
选 Streaming + RSC:长响应(> 3 秒)、生成式 UI、多步推理、需要实时反馈、需要展示 AI 决策过程、需要处理多工具调用的场景。
混合方案:同一个应用中,不同功能可以分别选择。核心 AI 交互用 Streaming,辅助功能(如用户设置、历史记录、认证接口)用 REST。不需要为了"统一技术栈"而强行把所有接口都改成流式。
六、边界、陷阱与生产注意事项
6.1 流式不是银弹
短响应场景下流式反而增加复杂度。如果 LLM 响应只需要 500ms,流式的 TTFB 优势不明显,但引入了 Suspense、streamableUI 等额外抽象层,增加了代码复杂度和维护成本。在做技术选型时,先评估你的 AI 应用的平均响应时间——如果大部分请求在 1 秒以内,REST 可能是更务实的选择。
团队学习成本也是现实问题。RSC + Streaming 的心智模型比传统 REST + useEffect 复杂很多。团队成员需要理解服务端组件 vs 客户端组件的边界、Suspense 的工作机制、流式协议的调试方法等。如果团队中大部分人没有 React 新架构的经验,贸然全盘采用可能导致大量难以排查的 bug。
6.2 SEO 与首屏性能
流式内容对搜索引擎不友好:爬虫可能在内容还未完整时就截取了页面,导致索引内容不完整。
解决方案是分场景处理:对需要 SEO 的页面(如公开的文章页、落地页)做 SSR fallback,在服务端等待完整响应后输出静态 HTML;对不需要 SEO 的应用内页面(如聊天界面、数据分析面板)直接用 Streaming。
6.3 Token 成本的用户感知
流式让用户看到了 AI 的"思考过程"。如果 AI 在中间出现了明显的修正(如先输出了一个方案,然后又否定并重新选择),用户可能会对结果质量产生怀疑。这在 REST 方案下不会发生,因为用户只看到最终结果。
解决方案有两个方向:一是在 Prompt 层面约束 AI 的输出风格,减少犹豫和修正(如"直接输出最终方案,不要展示推理过程");二是在 UI 层面过滤掉中间状态,客户端只渲染最终的、稳定的组件配置,中间的"草稿"用轻量的动画过渡跳过。
6.4 安全与内容过滤
流式内容在到达客户端之前难以做完整的安全审查,因为内容还在生成中。特别是结构化数据场景,AI 可能在第 10 个组件中才输出恶意内容。
建议的策略是多层防御:服务端逐 chunk 做基本的安全检查(关键词过滤、Schema 校验),客户端做最终渲染前的完整性校验。对于高敏感场景,可以在流式结束后用一次完整的内容审查,如果发现问题则替换已渲染的 UI 为安全提示。
6.5 监控与可观测性
流式场景下的监控比 REST 更复杂。需要追踪每个 stream 的完整生命周期。建议的埋点指标:
- TTFB(首 chunk 延迟):从请求发出到第一个 chunk 到达的时间,反映 LLM 的推理启动速度。
- Stream 完成率:成功完成的 stream 占总请求的比例。低于 95% 说明有系统性问题需要排查。
- 中断率:因为网络、超时等原因中断的 stream 比例。
- 用户中断率:用户主动点击"停止"的比例。这个指标间接反映了生成内容的质量——如果大量用户选择中途停止,说明 AI 的输出不符合预期。
- 端到端延迟:从请求到完整渲染的时间。这是最终的用户体验指标。
6.6 多设备与弱网适配
弱网环境下,流式的小 chunk 可能会频繁超时或丢失。需要在客户端做 chunk 缓冲和重连机制。具体做法是设置一个 buffer,在网络恢复后批量刷新已积累的 chunk,而不是逐个渲染过时的数据。
移动端的特殊考虑:SSE 连接在移动端可能因为网络切换(WiFi ↔ 蜂窝)而中断,需要更积极的重连策略。建议将 SSE 的 retry 间隔从默认的 3 秒缩短到 1 秒,并在重连成功后发送一个 ping 确认连接状态。另外,移动端浏览器在页面进入后台时可能会暂停 SSE 连接,需要在页面恢复前台时主动检查并重建连接。
6.7 SSR 与 Streaming 的关系
一个常见的混淆:SSR(服务端渲染)和 Streaming 是两个独立的概念,但经常被混为一谈。
- SSR 是在服务端把组件渲染为 HTML,发送给客户端,客户端 hydrate 后变成可交互的 SPA。一次性的。
- Streaming 是数据的传输方式,可以用于 SSR(RSC Payload 流式传输),也可以用于纯数据流(SSE)。
- RSC 的流式渲染结合了两者:服务端流式地发送 RSC Payload,客户端流式地 hydrate 组件。
理解这个区别有助于做正确的架构决策。如果你只需要流式接收 AI 数据但不需要 RSC(比如客户端已经有完整的 SPA),直接用 SSE + useChat 就够了,不需要引入 RSC 的复杂度。
七、总结
回到开篇的关键认知:Streaming UI 的本质是将 AI 的决策过程与 UI 的渲染过程在时间轴上对齐。
技术层面,数据流(AI SDK 的 streamText / streamObject)和渲染流(Server Components 的 Suspense 边界)是两层独立的机制,通过 createStreamableUI 等工具桥接。理解这两层各自的工作原理和协作方式,是正确实现 Streaming UI 的前提。
工程层面,从 REST 到 Streaming 不是简单的 API 替换。错误处理变复杂了,调试变困难了,测试变棘手了。但换来的是质变级的用户体验提升:用户从"等待一个完整页面"变成了"观看一个页面逐步构建"。
实践层面,不是所有场景都需要流式。评估你的 AI 应用的响应时间分布、目标用户群体、团队技术储备,然后做出务实的选择。对于生成式 UI、多工具调用、长文本生成等场景,Streaming + RSC 是当前最优解;对于简单的问答和查询,REST 仍然够用。
最后一句话:不要把 Streaming 当作一个炫酷的前端特效,把它当作 AI 应用的基础设施来设计和投入。
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/2501_90821979/article/details/163474194



