这篇不先堆名词。我们把《我用前端经验做了次 AI 项目，最先失效的是旧方法》拆成几级台阶，看完至少知道下一步该学什么、该练什么。

摘要

前端做 AI 应用，最大的坑不是模型不会用，而是 Demo 阶段根本不会暴露的工程化问题。权限、日志、可观测性这三道坎，跨过去才能从"能跑"变成"能用"。

目录

• 真实案例
• AI 应用交互模式：前端能做什么，不能做什么
• 流式输出：从 Demo 到生产的关键差异
• 代码解释
• 排查过程：权限、日志、可观测性问题定位
• 失败原因：业务错误、配置错误、环境错误的区分
• 适用边界
• 多模态体验：前端的新战场
• 作品集方向：前端转 AI 应该展示什么
• 总结：先补什么，暂时放什么

真实案例

去年我带过一个前端同事做企业知识库问答系统。Demo 阶段很顺利：用户提问，RAG 检索文档片段，流式输出回答。前端同学用 React + Vercel AI SDK 搭了个界面，模型选的是通义千问，本地部署的 Embedding 模型，整个链路跑起来响应不到两秒。

但上线第一周就出问题。

第一个是权限问题。有员工用这个系统查到了其他部门的薪资制度文档——系统没做任何鉴权，只凭用户身份透传了所有检索结果。第二个是日志缺失。某次用户反馈"回答质量很差"，我们查不到是检索阶段丢了片段，还是模型阶段理解偏了，只能盲猜。第三个是可观测性。大促期间系统响应从 2 秒涨到 15 秒，但监控面板上只有"请求成功"和"请求失败"两个指标，中间环节耗时完全未知。

这三个问题，任何一个单独看都不难解决，但 Demo 阶段根本不会有人去处理它们。前端同学通常擅长的是交互细节和渲染性能，而 AI 应用真正卡住的，是这些"看不见"的工程化问题。

AI 应用交互模式：前端能做什么，不能做什么

做 AI 应用，前端的能力边界需要重新定义。

传统前端关注的是：页面渲染、状态管理、API 调用、用户体验优化。这些能力在 AI 应用里依然重要，但不是核心竞争力。AI 应用的核心是：如何把模型的输出转化为用户可理解、可操作的信息，以及如何在模型不确定时给用户反馈。

我见过很多前端转 AI 的同学，第一反应是"我去学 LangChain"。但 LangChain 解决的是后端工程问题，前端真正需要掌握的是：

• 流式输出处理：模型输出是逐 token 生成的，前端需要实时渲染并处理中间状态
• 多模态展示：答案可能包含图片、表格、代码块，渲染逻辑比传统表单复杂
• 交互反馈：用户可能中途打断、追问、纠正，需要管理对话状态和上下文

以流式输出为例，传统 API 调用是"请求-等待-响应"的同步模式，而 AI 应用是 SSE（Server-Sent Events）的流式模式。前端需要处理不确定的数据到达时间、部分响应的渲染、以及用户中断后的状态清理。

流式输出：从 Demo 到生产的关键差异

流式输出在 Demo 阶段和在生产环境，体验差异巨大。

Demo 阶段，你用一个简单的 fetch 请求加上 ReadableStream 就能跑通。但生产环境需要考虑：网络抖动时的重试、长连接的超时处理、以及流式数据在 React 组件中的状态管理。

// 生产环境的流式请求封装
async function streamQuery(messages, options = {}) {
  const { signal, onToken, onComplete, onError } = options;

  try {
    const response = await fetch('/api/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ messages }),
      signal, // 支持用户中断
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    if (!response.body) throw new Error('No response body');

    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    let buffer = '';

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      buffer += decoder.decode(value, { stream: true });
      const lines = buffer.split('\n');
      buffer = lines.pop() || ''; // 保留不完整的行

      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = line.slice(6);
          if (data === '[DONE]') {
            onComplete?.();
            break;
          }
          try {
            const parsed = JSON.parse(data);
            onToken?.(parsed.token);
          } catch (e) {
            // 解析失败时记录但不中断流
            console.warn('Stream parse error:', e);
          }
        }
      }
    }
  } catch (error) {
    if (error.name !== 'AbortError') {
      onError?.(error);
    }
  }
}

代码解释

这段关键代码的 code walkthrough 如下，帮你理解实现原理。

输入参数：messages 是对话历史数组，options 包含四个回调：signal（用于中断请求）、onToken（逐 token 回调）、onComplete（完成回调）、onError（错误回调）。

核心逻辑分三段：

第一段是请求建立。用 fetch 发 POST 请求，传入 signal 让调用方可以随时中断。这里没有设置超时，生产环境建议加上 AbortSignal.timeout()。

第二段是流式读取。response.body.getReader() 拿到读取器后，用 TextDecoder 把二进制流解码成字符串。关键细节在缓冲处理：SSE 数据可能按任意大小分片到达，所以用 buffer 累积数据，按 \n 分割后，把最后一行（可能不完整）留到下一轮继续拼接。这是很多 Demo 代码会忽略的地方。

第三段是数据解析。每行以 data: 开头的是有效数据，遇到 [DONE] 表示流结束。中间用 try-catch 包裹 JSON.parse，解析失败只打日志不中断，保证用户体验的连续性。

输出和异常处理：成功时通过 onToken 逐 token 回调，完成后调用 onComplete。异常分两类：网络错误或解析错误走 onError，但 AbortError（用户主动中断）不报错，静默处理。

排查过程：权限、日志、可观测性问题定位

回到之前的案例，三个问题逐一排查：

权限问题定位：用户反馈能访问不该看的文档后，我们在检索层加了权限过滤。排查时发现，Embedding 模型返回的相似度分数没有结合用户权限做二次过滤。验证方法是：用不同身份的用户查询同一问题，对比返回的文档片段是否一致。排除结果是：检索逻辑本身没问题，是权限过滤层缺失。

日志缺失定位：用户反馈回答质量差，我们加了结构化日志。排查时发现，问题出在检索阶段——相似度阈值设置过低（0.3），导致无关文档也被召回。验证方法是：对比召回文档与问题的相关性。排除结果是：模型本身没问题，是检索参数配置错误。

可观测性定位：响应时间从 2 秒涨到 15 秒，我们加了分环节耗时追踪。排查时发现，瓶颈在 Embedding 模型的批量推理，单请求排队等待时间过长。验证方法是：对比高峰期和低峰期的 Embedding 请求耗时。排除结果是：模型推理本身没问题，是资源分配和队列管理问题。

这三个问题的共同点是：Demo 阶段不会暴露，只有真实用户、真实数据、真实并发才会出现。前端同学通常缺乏这类问题的排查经验，需要补齐工程化思维。

失败原因：业务错误、配置错误、环境错误的区分

AI 应用上线失败，原因通常分为三类：

业务错误：模型输出不符合预期。比如检索结果不相关、回答逻辑错误、多轮对话状态丢失。这类问题需要调整 Prompt、优化检索策略、改进对话管理逻辑。

配置错误：参数设置不合理。比如相似度阈值、温度参数、最大 token 数等。这类问题需要 A/B 测试、数据分析、逐步调优。

环境错误：基础设施问题。比如模型服务超时、网络抖动、权限配置错误、资源不足。这类问题需要监控告警、容错机制、弹性扩容。

很多前端同学会把这三类问题混为一谈。比如模型响应慢，第一反应是"模型不行"，可能是环境错误（资源不足）或配置错误（超时时间设置过短）。区分这三类错误，是 AI 应用工程化的基础能力。

适用边界

这套方案有明确的适用边界，照搬会踩坑。

适用场景：

• 企业内部知识库问答、客服助手等 RAG 类应用
• 对话式 AI 产品，需要流式输出和多轮交互
• 前端团队主导的 AI 功能模块

限制条件：

• 本文聚焦前端侧的工程化问题，不涉及模型选型、训练、微调
• 流式代码示例基于 SSE 协议，不适用于 WebSocket 或 gRPC streaming
• 权限、日志、可观测性的方案需要配合后端基础设施，前端只能做接入层

取舍建议：

• 如果项目只是内部小范围试用，可以先不上完整的可观测性，用基础日志替代
• 如果并发量低（<100 QPS），Embedding 模型可以直接同步调用，不需要队列管理
• 多模态渲染组件可以按需开发，不要一次性做完所有类型

什么时候不应照搬：

• 高安全要求的场景（金融、医疗），权限模型需要独立设计，不能只靠检索层过滤
• 实时性要求极高的场景（<500ms 响应），流式输出的缓冲逻辑可能引入额外延迟
• 模型输出格式不可控的场景，多模态渲染组件需要更强的容错设计

多模态体验：前端的新战场

AI 应用的多模态输出，给前端带来新的渲染挑战。

传统前端处理的是结构化数据：文本、图片、视频，渲染逻辑相对固定。AI 应用需要处理的是：模型可能输出 Markdown、代码块、表格、图表，甚至内嵌 HTML。这些内容的渲染需要更灵活的组件设计。

比如，一个知识库问答系统可能需要：

• 普通文本：直接渲染
• 代码块：语法高亮 + 复制按钮
• 表格：响应式布局 + 排序筛选
• 图片：懒加载 + 缩放预览
• 数学公式：LaTeX 渲染

这些能力在传统前端项目里可能用不上，但在 AI 应用里是标配。前端同学需要提前准备这些组件，而不是等项目开发时临时找方案。

作品集方向：前端转 AI 应该展示什么

很多前端同学想做 AI 应用项目，但不知道简历上放什么。我的建议是：不要只放"能跑通的 Demo"，要放"解决了生产问题的方案"。

具体可以展示：
1. 流式输出的完整实现：包括中断、重试、状态管理
2. 多模态渲染组件：代码块、表格、图片的优雅处理
3. 错误处理和降级策略：模型超时、网络抖动、解析失败的处理
4. 性能优化案例：首屏渲染、流式渲染、缓存策略

一个能展示"从 Demo 到生产"思维的项目，比十个跑通的 Demo 更有价值。

总结：先补什么，暂时放什么

前端转 AI 应用，学习路线需要取舍：

先补的：

• 流式数据处理：SSE、WebSocket、流式响应处理
• 多模态渲染：Markdown、代码、表格、图片的组件设计
• 基础工程化：日志、监控、错误处理的基本实践

暂时放下的：

• 复杂的 Agent 编排：LangGraph、多 Agent 协作等，等项目需要时再学
• 模型微调：除非你的项目明确需要，否则先会用就行
• 底层算法原理：了解基本原理即可，不用深入推导

Demo 能跑和能上线之间，隔着权限、日志、可观测性这三道坎。前端同学的优势是交互体验和渲染能力，补齐工程化思维后，在 AI 应用方向会有很强的竞争力。

资料展示

下面是我整理的AI大模型学习资料和工具包预览，适合收藏后按主题逐步学习。

如果你想看完整资料目录，可以在评论区留言「资料」；也欢迎告诉我你更关注AI大模型里的哪类内容。