案例基于火山方舟大模型的智能物品识别Web应用，React+TypeScript+Vite+Arco Design技术栈，支持实时识别与分类。
2025 年 Q1，我们基于客户提供的本地项目资料（Trae/package.json），构建了一套智能物品识别 Web 应用——核心能力是调用火山方舟大模型，对用户上传的物品图片做实时识别与分类。这个项目的价值不在于「用了大模型」，而在于把大模型的能力封装成了一款普通用户打开浏览器就能用的生产级工具——这中间的工程距离，远比跑通一个 API Demo 要长。
传统做法是「前端 → 后端代理 → 大模型 API」：用户上传图片先到后端服务器，后端转发给火山方舟，拿到结果再返回前端。这套链路在安全审计和权限控制上有优势，但会引入额外的网络跳转——用户从点击上传到看到识别结果，延迟通常要到 1.5–2.5 秒。
这个项目的需求场景是「即时识别」——用户期望拍完照 1 秒内看到结果。所以我们的架构决策是前端直连火山方舟 SDK：图片在前端做压缩和 base64 编码后，直接通过 HTTPS 发送到火山方舟推理端点，绕过中间服务层。代价是把 API Key 暴露在前端（通过环境变量注入 + CSP 限制请求域名做基本防护），收益是端到端延迟压到了 600–900ms。
如果你在做一个「后台管理系统里的批量识别」而非「C 端即时交互」，那还是走后端代理更安全。
坑一：大图片上传导致浏览器冻结。用户拿手机拍了张 12MB 的 4000×3000 原图直接上传，前端在主线程做 Canvas 压缩时，页面卡死了 3 秒。原因是默认的 Canvas 缩放 + toBlob 操作没有做 Web Worker 卸载。修复方案：把图片压缩逻辑移到 Web Worker 里，压缩到 800×600、JPEG quality 0.7，输出控制在 150KB 以内。修复后主线程冻结时间从 3 秒降到几乎不可感知。
坑二：模型返回格式不稳定。火山方舟的 vision 模型在 prompt 里要求返回 JSON，但大约 8% 的请求返回了带 Markdown 包裹或多余换行的「非标准 JSON」——```json\n{...}\n```。前端 JSON.parse 直接抛异常。解决方案不是反复调 prompt（prompt engineering 永远做不到 100%），而是在前端解析层加一个「宽松解析器」：先 strip Markdown 代码块标记，再 strip 首尾空白，用 try-catch 兜底——解析失败时把原始文本原样展示，不作为系统错误抛出。这个方案上线后识别可用率从 92% 提升到 99.4%。
坑三：Zustand 状态管理在多分类场景下的竞态。用户快速切换识别图片时（比如连续拍了 3 张），3 个异步请求几乎同时发出。由于网络延迟不同，第 3 张的响应可能比第 1 张先回来，导致最终展示的是第 1 张的旧结果。修复方法是在 Zustand store 里为每次识别请求分配一个 requestId，写入结果前比对 requestId——只有当前最新请求的结果才被接受，旧请求的响应直接丢弃。
前端：React 18 · TypeScript · Vite · Arco Design · Zustand · 火山方舟 SDK
为什么不选更多：项目定位是轻量级 Web 工具，刻意不引入后端层（减少运维成本）。状态管理选 Zustand 而非 Redux——这个项目的状态树简单（识别结果 + 历史记录 + 加载态），不需要 Redux 的 boilerplate。UI 框架选 Arco Design 而非 Ant Design——Arco 的按需加载和 Tree Shaking 做得更好，包体积比 Ant Design 方案少约 60KB。
]]>