TomEval头像

从阻塞到流式:Vercel AI SDK + React Server Components 实现生成式 UI 的架构原理、工程实践与深度优化

关键认知

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)对接,是整个方案最关键的技术点。

基本模式如下:

  1. API Route 接收用户请求
  2. 调用 streamText 或 streamObject 获取 AI 输出流
  3. 在 Server Component 中消费这个流
  4. 将流式数据作为 props 传递给子组件
  5. <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

文章来源转载

评论

评论列表

微信小程序
QQ小程序

关于作者

点赞数:0
关注数:0
粉丝:0
文章:0
关注标签:0
加入于:--