做AI应用这一年多被团队问得最多的一个点不是模型选型也不是提示词怎么写而是AI输出的内容到底怎么“流”到页面上还能不崩。某公司一个AI助手项目从第一版用Markdown做流式文本输出到后来演进成一套让模型直接生成界面描述结构、再由前端动态渲染成组件的生成式UI方案这条路我走了小一个季度。这篇文章就把整套实践的选型逻辑、增量协议设计、前端渲染管线和生产环境踩过的坑完整拆开讲。正在做AI应用的前端、全栈甚至后端同学可以直接拿到一套可落地的流式渲染参考方案。先说结论Markdown不是终点它只是AI内容落地的及格线。当你要给用户的不只是“读一段话”而是“看一张表”“填一个表单”“点一个按钮”的时候文本流就撑不住了。本文会重点覆盖从SSE流式传输、增量协议设计到LLM结构化输出约束、React端动态渲染再到降级与排查的完整链路。1. 为什么Markdown不够了AI流式渲染的演进起点1.1 第一版为什么选了Markdown流式输出任何方案的选择都要放在当时的约束条件下看。第一版AI助手的目标很简单让用户能像聊天一样看到AI逐字回答问题。这时候Markdown就是最优解原因有三个。第一LLM天生擅长输出Markdown。训练语料里大量存在这类格式模型不需要额外的格式约束就能稳定生成标题、列表、加粗、代码块。第二渲染成本极低。前端接到一段文本流累加字符串丢给Markdown解析器转成HTML几十行代码就能跑通。第三用户的认知成本为零。聊天窗口里的Markdown和我们在代码仓库里看到的README观感一致不突兀。第一版的实现方式是这样的后端把模型输出的增量文本通过SSE逐块推给前端前端维护一个完整的markdown字符串每次收到新块就重新解析、重新渲染。这个版本上线后纯文本问答场景体验其实挺好的用户能看到逐字蹦出来的效果也不觉得卡。但问题恰恰藏在“重新渲染”这个动作里。1.2 真正逼我们换方案的三个场景项目跑到第二个月产品侧的需求开始变化。不再是“回答一个问题”而是“完成一个任务”。三个场景直接暴露了Markdown流式渲染的天花板。第一个场景是数据表格。用户问“对比这三个月的销售数据”模型要输出一张可排序、可滚动、可导出的表格。Markdown的表格语法只能表达静态的文本网格无法承载排序、筛选、固定表头这些交互。就算前端把Markdown表格识别出来再手工转换成组件流式输出过程中表格结构不完整会导致解析错乱体验非常糟糕。第二个场景是图表。用户要求“画一个过去30天访问量的折线图”模型如果输出ASCII风格的折线图观感就是玩具。理想情况是模型直接生成图表配置前端灌进图表组件里渲染。而Markdown对这种结构化描述毫无表达能力。第三个场景是可交互表单。比如AI诊断完问题给用户一个“重启服务”的按钮或者让用户补充工单信息的表单。这类需求已经不是文本内容而是组件与事件。Markdown渲染器再强也做不出按钮的回调逻辑。这三个场景出现后我们意识到AI应用的前端渲染核心矛盾已经从“文本格式转换”变成了“结构化界面的动态生成与更新”。于是开始做生成式UI。2. 流式传输与增量协议先把数据管道打通2.1 传输层选型为什么SSE比WebSocket更省事生成式UI的第一步不是渲染是先把“流的通道”建好。流式方案里可选项无非SSE、WebSocket和HTTP轮询。我们的选择很直接服务端推送用SSE。单听概念可能有点绕其实可以这样理解SSE是一条服务端单向向浏览器推送文本消息的通道浏览器通过EventSource接口监听WebSocket则像一条双向隧道两边随时可以互发消息。AI对话有个天然特点消息方向以服务端往客户端为主用户只在发起阶段发送一次请求。这种单向数据流和SSE的模型完全匹配。SSE的好处还在于它建立在普通HTTP之上。内网网关、鉴权中间件、日志系统全都按HTTP那一套走不用额外引入WebSocket的协议升级和心跳保活机制。尤其在生产环境里WebSocket需要处理连接超时、重连、消息心跳任何一个环节出问题排查成本都不低。SSE自带的自动重连机制更是省心连接断了浏览器会主动重试。这里有一个实践细节虽然EventSource用起来简单但它只能发GET请求没法方便地携带POST body。我们的方案是改用fetch ReadableStream来消费SSE。后端照常返回text/event-stream前端用fetch发起POST再从响应体里读流。这样既能传参数又能拿到底层的流式数据灵活性高很多。const resp await fetch(/api/ai/stream, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ prompt: 对比这三个月的销售数据, sessionId: s-1024 }), }); const reader resp.body.getReader(); const decoder new TextDecoder(); let buffer ; while (true) { const { value, done } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); // SSE事件以空行分割这里只处理完整的事件 const events buffer.split(\n\n); buffer events.pop() ?? ; for (const event of events) { if (!event.startsWith(data:)) continue; const payload JSON.parse(event.slice(5).trim()); handlePayload(payload); } }2.2 增量协议v1delta文本流的实现与痛点数据通道建好后前后端约定一个极简协议。服务端每个SSE事件发一个JSON对象里面带一个delta字段存的是模型新生成的文本片段。前端维护一个累积的fullText每收到一块就拼接然后重新渲染Markdown。最初的渲染策略是“全量重渲染”也就是把完整的Markdown字符串反复交给解析器。实测下来文本短的时候没问题一旦回答超过1000个汉字每来一个块就全量解析一次页面明显掉帧。代码块场景更糟模型输出代码时还没闭合解析器会把后续的所有内容都当成代码文本处理用户会看到大段灰色背景反复跳变。这里要解释一个核心矛盾Markdown语法是上下文相关的一个未闭合的代码块会污染整个后续解析。而流式输出天然存在“中间态”很多语法在中间态是不完整、不正确的。如果每次对全量文本做解析就必须反复处理这种“脏中间态”。我们的折中方案是三项组合拳。第一渲染合并。不每收一个delta就渲染而是用一个队列把多个delta累积起来通过requestAnimationFrame合并成一次渲染操作把高频更新压到浏览器帧率以内。第二代码块延迟渲染。检测到未闭合的代码块标记时只显示一个“代码生成中”的占位等闭合标记到达后再一次性渲染整个代码块。第三滚动位置补偿。由于重新渲染会导致页面高度变化手动记录滚动容器的锚点元素位置渲染完成后把滚动偏移加回去。这套组合拳让Markdown流式体验达到了可用级别但根本矛盾还在Markdown渲染器输出的是一整段HTML前端无法对其中某个表格、某张图做局部更新。结构化的交互需求文本流永远满足不了。2.3 从“文本增量”到“结构增量”的关键转变流式渲染的进化节点是想通一个问题文本流式的单位是“字符增量”界面流式的单位应该是“操作增量”。什么意思呢文本流告诉前端“这段文字变多了”前端要做的是字符串拼接界面流应该告诉前端“在这个位置新增了一个组件”“给那个组件更新了属性”“在这个容器里插入了子节点”。前端拿到的是一个个明确的结构操作按顺序执行就能得到完整界面。这个思维的转变直接推动了增量协议v2的设计。协议不再是“模型说什么前端显示什么”而是“模型想让界面上发生什么变化前端就执行什么操作”。前端从被动的文本消费者变成了结构操作的解释器和执行器。3. 生成式UI让模型直接输出界面描述3.1 生成式UI的本质是UI Schema不是让模型画页面一听到“生成式UI”很多人的第一反应是让AI生成一份前端代码然后执行。这个方向既危险又笨重。危险在于让模型输出JavaScript并在页面执行等于引狼入室笨重在于代码生成的中间态太多流式渲染时非常容易产生半截语法。我们走的是另一条路让模型输出一棵描述型UI树也就是UI Schema。节点类型是预先定义好的白名单组件节点属性是组件的配置参数节点之间通过嵌套表达布局关系。渲染器拿到这棵树的描述动态映射成真实React组件。数据、样式、行为三者分离UI描述负责“长什么样”数据字段负责“显示什么”动作字段负责“点了之后干什么”。举一个最小示例模型想展示一条提示信息加一个操作按钮可以输出这样一个Schema{ type: Stack, props: { direction: vertical, gap: 12 }, children: [ { type: Alert, props: { kind: warning, text: 服务存在异常建议重启节点 } }, { type: Button, props: { text: 查看诊断报告, action: { name: openReport, payload: { reportId: r-1024 } } } } ] }这里action字段是事件出口。渲染器遇到带name的action会把它绑定到前端的事件分发器上。模型自己不需要知道点击按钮后具体执行什么——前端预先注册好动作处理器只管接收回调即可。这套隔离方案让生成式UI既灵活又不至于越权。3.2 增量指令流协议每条指令独立可应用如果让模型一次性输出完整的UI Schema JSON会产生两个问题第一长JSON生成时间长首屏等得急第二JSON在流式中途不完整前端没法解析等于没流。所以我们把UI Schema拆成了指令流。每条指令都是一个独立操作字段可以类比成数据库写入操作。核心指令集如下createNode声明一个组件实例分配唯一id指定type和初始props。appendChild把一个已有节点挂到某个父节点的children里。setProps更新某节点的属性。setData给某节点填充数据表格行、图表点位都走这里。removeNode删除节点。finish标记整棵UI树生成完毕前端可以收起“生成中”占位状态。流式表现大致长这样{op:createNode,id:card-1,type:Card,props:{title:本月数据}} {op:createNode,id:table-1,type:Table,props:{columns:[渠道,访问量]}} {op:appendChild,parentId:card-1,childId:table-1} {op:setData,id:table-1,data:[{channel:搜索,visits:12000}]} {op:finish,id:root}注意这里的字段名我在生产环境里会压缩成短键比如op直接保留id保留type缩成tprops缩成pparentId缩成pi。别小看这点优化LLM输出是按token计费的也更难让模型把长字段拼错。压缩后协议体积缩小约三成模型输出速度明显提升。可读性差一点没关系协议文档写清楚就行。这条协议设计里最关键的一点是每条指令都自包含、可独立应用。前端收到一条就执行一条不需要等待完整JSON。这样即使输出中途断掉已经渲染出来的部分依然有效系统可以随时降级。3.3 让LLM稳定输出合法指令的约束方法模型不可能天生知道你的UI协议必须约束。我们的做法分三层。第一层是系统提示词示例。在system prompt里给两到三个完整的指令流示例明确告诉模型“先创建节点再挂载子节点最后填充数据”的顺序。实测示例比抽象描述有效得多模型能模仿样例的结构。第二层是JSON Schema约束。如果你用的是支持结构化输出的模型服务可以直接在请求里附加JSON Schema声明每条指令的字段类型、必填项和枚举值。例如op字段只允许那六个值type字段只允许我们注册表里存在的组件名。模型在生成时会优先满足Schema约束出格式问题的概率大幅下降。第三层是前端兜底容错。不管前面做多好模型总有抽风的时候。后端要做一层格式校验发现解析失败就重试一次如果重试还是失败就把这部分内容降级为普通文本返回。前端也要做防御性解析每条指令单独try/catch单条失败不影响其他指令执行。约束的目标不是让模型百分百完美输出而是把错误率压到可接受范围并且让错误表现为“可降级”而不是“白屏”。这条心得后面做稳定性的时候还会再展开。4. 前端渲染实战从指令流到组件树4.1 用状态仓库管理UI树生成式UI的前端核心是一个可动态增删的UI树状态。我们用Zustand做状态管理结构很直观nodes是一个以节点id为key的Map存所有节点实例rootIds是根节点id列表。apply方法接收一批指令按顺序执行返回新的状态。interface UIState { nodes: Recordstring, UINode; rootIds: string[]; apply: (ops: UIOperation[]) void; } const useUIStore createUIState((set) ({ nodes: {}, rootIds: [], apply: (ops) set((state) { const nodes { ...state.nodes }; const rootIds [...state.rootIds]; for (const op of ops) { if (op.op createNode) { nodes[op.id] { ...op.node, children: [] }; if (op.node.isRoot) rootIds.push(op.id); } else if (op.op appendChild) { nodes[op.parentId]?.children.push(op.childId); } else if (op.op setProps) { nodes[op.id] { ...nodes[op.id], props: { ...nodes[op.id].props, ...op.props } }; } else if (op.op setData) { nodes[op.id] { ...nodes[op.id], data: op.data }; } } return { nodes, rootIds }; }), }));特别注意apply每次执行的都是纯状态更新不涉及任何组件实例操作。这意味着整个UI树的一举一动都可以记录成日志回放重演调Bug时犹如看录像。课件阶段我觉得这个设计可有可无上线后全靠这个日志定位了几次诡异问题。4.2 从UI树到React组件注册表与递归渲染状态里存的只是描述真正渲染成React元素需要两步注册表映射 递归渲染。注册表维护一个从组件type到React组件的映射。这是白名单机制的关键位置只允许注册过的组件类型被渲染其他一律渲染为一个透明Fallback绝不执行未知代码。const componentRegistry: Recordstring, React.ComponentTypeany { Card: CardComponent, Stack: StackComponent, Text: TextComponent, Table: DataTableComponent, Alert: AlertComponent, Button: ActionButtonComponent, };递归渲染器从根节点开始读取节点的type找到组件把props透传进去再递归渲染它的children。function RenderNode({ id }: { id: string }) { const node useUIStore((s) s.nodes[id]); if (!node) return NodeSkeleton /; const Component componentRegistry[node.type]; if (!Component) return UnknownNode node{node} /; const children (node.children ?? []).map((childId) ( RenderNode key{childId} id{childId} / )); return ( Component {...node.props} nodeData{node.data} {children} /Component ); }渲染器里有两个容易被忽略的细节。第一key必须用节点id。因为指令流可能动态调整节点顺序和父子关系用数组下标做key会让React复用错乱出现状态残留。第二子节点还没到达时父节点已经渲染的情况很常见。上面代码里node.children中某个childId在nodes里不存在时RenderNode会渲染一个骨架占位。等对应createNode指令到达骨架自动变成真实组件用户感知上是无缝的。4.3 React流式更新的性能优化流式渲染的性能关键不在React本身而在控制状态更新的频率和优先级。React 18的自动批处理能合并同一事件循环里的多次setState但SSE场景下数据是异步逐条到达的每个apply都可能触发独立渲染。我们的做法是积攒一批指令再一次性apply而不是来一条执行一条。接收线程把指令推进一个pending队列用微任务或定时器定期清空合并成一次更新。另一个更关键的优化是startTransition。UI树更新属于低优先级任务用户点击按钮、输入框打字属于高优先级交互。如果模型正在疯狂输出UI节点而这期间用户拖动滚动条或者点击了某个Tab不能让渲染卡住用户操作。用startTransition包裹UI树的setStateReact会在合适的时机中断低优先级渲染优先响应用户事件。长列表场景还要叠加虚拟滚动。一个表格可能有几百行数据一个树形组件可能挂几十个子节点。把这些全部真实渲染成DOM再快的React也扛不住。表格组件内部使用react-window做按需渲染只有可视区域的行才挂载DOM节点。流式生成期间表格数据从一行逐渐增至几百行每次update都由React的diff机制去处理新增行实测在数据量500行以内没有出现可感知卡顿。5. 生产环境的稳定性与降级策略5.1 乱序、超时与中断处理流式协议进了生产环境第一个遇到的隐性坑是乱序。理论上一根SSE连接顺序到达不会乱但模型服务端如果做了多路并发生成或者代理层做了缓冲重排指令就可能乱。比如appendChild先到而createNode还没到前端执行时找不到父节点或子节点。我们的对策是做一个挂起队列。所有操作先经过一层校验如果指令引用的节点id还不存在就先放进pending列表暂不执行。每成功创建一个节点就扫描pending列表里有哪些指令可以执行了。这个机制同样能解决“子节点未创建就挂载”的问题把乱序容错沉到协议执行前。超时也要分两类处理。首包超时指请求发出去很久第一条指令还没回来多半是模型服务异常或排队过久前端要给出“正在排队”的提示而不是一直转圈。完成超时指生成总时长超过阈值模型可能陷入死循环后端应该主动切断生成并发送一个finish指令兜底。前端的AbortController不仅能停掉HTTP请求还能触发清理UI树生成状态的逻辑。5.2 输入侧安全白名单与事件隔离生成式UI本质上是让模型操作你的页面结构安全边界必须划清楚。我们做了四个层面的隔离缺一不可。组件白名单只有注册表里存在的type才会被渲染非白名单一律渲染为Fallback组件。这从根上杜绝了“让模型创建任意组件”的越权风险。属性白名单组件接收的props逐一走Schema校验。比如某个组件的href字段只允许http和https协议事件字段只允许注册过的actionName。这里要特别小心有些组件库会透传onClick、dangerouslySetInnerHTML这类危险属性必须显式过滤掉。事件动作白名单模型只能声明action.name前端在实际执行时查询一个动作注册表里面是预先编写好的业务回调。回调之外的任何行为都不会被执行模型没有“执行任意JavaScript”的能力。文本转义所有模型生成的文本内容在进入组件前统一转义。宁可让特殊字符显示为转义码也不能让用户输入内容被当成HTML注入。这是最基本的底线。5.3 降级方案生成式UI失败时退回Markdown再完善的约束协议面对真实世界的模型重复度也要做好“万一失败了怎么办”的准备。我们的降级设计是双通道并存。后端在输出生成式UI指令流的同时把一份等价的Markdown文本也拼出来。正常时候走UI指令流渲染一旦前端检测到异常——比如指令解析连续报错、Schema校验失败率超过阈值、SSE连接多次中断后重试仍失败——就自动切换到Markdown通道把早已累积好的Markdown文本用传统方式渲染。这个设计的巧妙之处在于降级不是“白屏后重新请求”而是“已有内容换一种表现方式”。因为文本流始终在累积用户看到的结果不会断档只是从精美组件变成了朴素的Markdown排版。前端实现上用一个renderMode全局状态控制渲染分支。UI指令流把指令日志传给监控看板Markdown通道则渲染完整文本。两边的数据都从同一个SSE连接解析出来落地成本很低。这套降级机制多次在线上模型抽风时救了场用户几乎感知不到渲染模式切换只偶发觉得“版面变朴素了”——总比页面白屏好得多。6. 常见问题排查与避坑记录6.1 高频问题速查表把这段实践里碰到的典型问题整理成一张表方便直接对照排查。问题表现典型原因处理方式渲染内容一直不出现SSE首包超时模型排队过久前端增加首包超时提示后端提供排队状态事件指令JSON解析频繁报错模型输出非法格式降低temperature附加JSON Schema解析失败重试某个组件区域空白节点id在nodes里不存在检查appendChild是否早于createNode启用挂起队列表格数据越攒越卡全量行都挂载到DOM表格内部接入虚拟滚动未闭合代码块反复跳变Markdown中间态解析问题使用占位组件延迟渲染闭合后再完整渲染点击按钮无反应action.name未注册到动作表前端动作注册表按业务维度登记缺失时输出告警日志模型输出了未知组件type新组件未加入白名单注册表补齐组件Fallback组件给埋点信息降级后内容与UI模式不一致双通道文本未同步后端改成同一份输出源分别生成两个格式6.2 几条排查心法排查这类流式渲染问题最有效的不是盯页面而是盯「指令日志状态快照」。生产环境把每一条收到的指令都记录下来配合时间戳和状态哈希出问题时可以精确回放当时的UI树。我在定位一个表格列错乱问题时就是靠回放指令日志发现某次setData包含了一个错误的列定义字段模型把列头放在了数据行里。另一个容易被坑的点是网络字节流解析。SSE数据在传输层会被拆成任意大小的chunk绝对不能假定“一次read就是一条完整事件”。必须维护字符串buffer按空行切分事件再把剩余半截留在buffer里等下一次数据到达。我见过好几次线上偶发解析报错最后定位都是半包问题而不是模型乱输出。最后一条心得把模型当“不稳定的上游服务”对待。你做外部API调用时会设计超时重试、限流熔断、降级方案对LLM输出UI指令也应该用同样的工程心态。不要幻想模型每次输出都完美符合Schema而是要设计一套让“不完美”也能平稳落地的系统。写在最后的个人体会这个项目做下来最深的感受是Markdown和生成式UI不是二选一的对立关系它们是同一条演进路径上的不同站点。纯文本问答场景Markdown流式渲染永远是够用且简洁的选择但产品一旦往前走开始要求可点击、可填写、可筛选的界面时结构化的增量指令流就会成为必经之路。如果让我重新选择我会在一开始就把流式管道按“增量指令”来设计哪怕第一版只渲染Markdown文本也可以先把指令协议的空壳搭好后续切换成本会低很多。协议层是一切生成式UI的地基先想清楚这块再谈组件层和效果层。先做降级再追求花活这个顺序不要颠倒。最后再分享一个小技巧把UI指令流的日志输出到控制台用颜色区分不同操作类型开发调试时会非常愉悦。我在调试一个复杂卡片嵌套渲染时靠着彩色指令日志一眼看出了appendChild挂错父节点的问题省下至少半天排查时间。这个工具已经在团队里传开了。