Vue3 检索增强应用选型：轻量级 Vector 客户端与服务端 RAG 的架构权衡

Vue3 检索增强应用选型：轻量级 Vector 客户端与服务端 RAG 的架构权衡

检索增强应用常在两种方案之间取舍：在浏览器中运行向量模型和索引，或由服务端 Vector DB 提供检索并通过 Server-Sent Events（SSE）返回结果。

端侧方案可以减少服务端依赖，但索引体积、设备性能和首屏加载会限制适用范围。选型应回到内存占用、首屏耗时、离线需求和数据边界等可测指标。

1. 浏览器卡顿 300ms：WASM 向量索引加载带来的性能灾难

为了验证端侧 WASM 检索的可行性，搭建了一个包含 2000 条技术文档的测试 Demo。

在 M2 芯片的 Mac 上运行尚算流畅，但在中低端办公笔记本上打开页面时，Chrome 的主线程直接卡死 300 多毫秒。

[Performance Profile Snapshot]: - Main Thread Blocked: 342ms (Compacting WASM Memory & Building HNSW Graph) - Memory Heap Peak: 480MB (Loaded Vector Indices into JS ArrayBuffer) - Initial Load Duration: 4.8s (Fetching 45MB .wasm & Model Binaries)

卡顿的原因主要有三点：

1. 二进制文件体积巨大：模型文件加上 WASM 向量引擎的基础体积超过 40MB。即便开启 Gzip 压缩，在弱网环境下的加载延时也令人无法接受。
2. 内存压迫引发 Frequent GC：在 JavaScript 堆中维护高维向量数组，会导致 Chrome 频繁触发垃圾回收，导致页面滚动时出现肉眼可见的掉帧。
3. 向量更新与版本同步极其困难：一旦后端知识库有条目修改，端侧必须重新下载全量或增量向量索引，缓存失效逻辑极其繁琐。

这表明端侧 WASM 检索只适合纯离线、少数据量（小于 200 条）的极特殊场景。对于企业级 Vue3 知识库应用，服务端 RAG 架构依然是无可替代的主干选择。

2. 三种端侧与云端 RAG 检索链路的指标撕裂

为了明确技术选型的适用边界，对三种主流前端 AI 检索架构进行了实测对比：

从量化结果可以看出：全服务端 RAG (方案 C) 虽然增加了几十毫秒的网络 RTT 耗时，但在内存占用、加载体验和数据安全性上具备压倒性优势。而方案 B（混合架构）则是兼顾高频热门问题响应与工程亮点的折中解。

3. Mermaid 时序图：Vue3 响应式状态与流式 Chunk 分片编排

在 Vue3 中实现高性能 RAG 应用，核心在于将服务端的流式响应（Streamed Chunk）优雅地编排进 Composition API 的响应式状态中。

下图展示了从用户提问到 Markdown 流式渲染的全链路时序：

sequenceDiagram autonumber participant UI as Vue3 View (Component) participant Hook as useSmartRetrieval (Composition API) participant Cache as IndexedDB Local Cache participant API as Backend RAG Gateway (SSE) UI->>Hook: executeQuery("如何配置 Vue3 路由?") Hook->>Cache: 匹配本地 Prompt 结果 Hash alt 缓存命中 (Cache Hit) Cache-->>Hook: 返回历史 Markdown 响应 Hook-->>UI: 瞬间更新 reactive state (0ms) else 缓存未命中 (Cache Miss) Hook->>API: POST /api/v1/rag/stream (带 Bearer Token) activate API API-->>Hook: HTTP 200 OK (Transfer-Encoding: chunked) loop SSE 流式数据推送 API-->>Hook: event: chunk, data: {"text": "配置 Vue3..."} Hook->>Hook: 增量追加至 ShallowRef 状态 Hook-->>UI: 触发高效局部渲染 (Virtual DOM Update) end API-->>Hook: event: done deactivate API Hook->>Cache: 异步写入高频 Token 结果 end

通过将增量文本挂载到shallowRef而非深度响应式的ref上，可以大幅减少 Vue3 的依赖追踪开销，避免长时间流式打字效果导致的页面微小卡顿。

4. Vue3 Composition API + TypeScript：具备缓存与增量渲染的 RAG Hook

以下是生产环境可用的 Vue3useSmartRetrieval自定义 Hook 实现，集成了 Fetch EventSource 解析、ShallowRef 性能优化以及防抖缓存功能：

import { ref, shallowRef, readonly, onUnmounted } from 'vue'; export interface RAGSearchOptions { apiEndpoint: string; authToken?: string; enableLocalCache?: boolean; } export interface RetrievalChunk { text: string; sources?: Array<{ id: string; title: string }>; done: boolean; } export function useSmartRetrieval(options: RAGSearchOptions) { // 使用 shallowRef 避免深层响应式追踪，极大提升频繁字符串拼接时的渲染性能 const streamingContent = shallowRef<string>(''); const isLoading = ref<boolean>(false); const error = ref<string | null>(null); const sources = ref<Array<{ id: string; title: string }>>([]); let abortController: AbortController | null = null; const memoryCache = new Map<string, string>(); const executeQuery = async (query: string) => { const trimmedQuery = query.trim(); if (!trimmedQuery) return; // 1. 优先重置状态 streamingContent.value = ''; error.value = null; isLoading.value = true; sources.value = []; // 2. 检查内存缓存 if (options.enableLocalCache && memoryCache.has(trimmedQuery)) { streamingContent.value = memoryCache.get(trimmedQuery)!; isLoading.value = false; return; } // 3. 中断之前未完成的请求 if (abortController) { abortController.abort(); } abortController = new AbortController(); try { const response = await fetch(options.apiEndpoint, { method: 'POST', headers: { 'Content-Type': 'application/json', ...(options.authToken ? { Authorization: `Bearer ${options.authToken}` } : {}), }, body: JSON.stringify({ query: trimmedQuery, stream: true }), signal: abortController.signal, }); if (!response.ok || !response.body) { throw new Error(`HTTP 异常状态码: ${response.status} ${response.statusText}`); } const reader = response.body.getReader(); const decoder = new TextDecoder('utf-8'); let buffer = ''; // 4. 读取 SSE 流式数据 while (true) { const { value, done } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const lines = buffer.split('\n\n'); // 留出最后一个可能不完整的 chunk buffer = lines.pop() || ''; for (const line of lines) { const trimmedLine = line.trim(); if (!trimmedLine.startsWith('data:')) continue; const jsonStr = trimmedLine.replace(/^data:\s*/, ''); if (jsonStr === '[DONE]') { break; } try { const chunkData: RetrievalChunk = JSON.parse(jsonStr); // 手动触发 shallowRef 的响应式更新 streamingContent.value += chunkData.text; if (chunkData.sources && chunkData.sources.length > 0) { sources.value = chunkData.sources; } } catch (e) { console.warn('[RAG Hook] 跳过无法解析的数据帧:', jsonStr); } } } // 5. 成功完成，写入缓存 if (options.enableLocalCache) { memoryCache.set(trimmedQuery, streamingContent.value); } } catch (err: unknown) { if ((err as Error).name === 'AbortError') { console.log('[RAG Hook] 请求被主动取消'); } else { error.value = (err as Error).message || '网络请求故障，请稍后重试'; } } finally { isLoading.value = false; abortController = null; } }; const cancelStreaming = () => { if (abortController) { abortController.abort(); isLoading.value = false; } }; onUnmounted(() => { cancelStreaming(); }); return { streamingContent: readonly(streamingContent), isLoading: readonly(isLoading), error: readonly(error), sources: readonly(sources), executeQuery, cancelStreaming, }; }

在这段 TypeScript 代码中，采用shallowRef替代了常规ref来接收极高频的增量字符拼接。在 Chrome Performance 工具中对比发现，这一细节优化避免了 Vue3 内部对庞大长文本做深度 Proxy 包装的额外消耗，流式打字时的 CPU 占用降低了近 4无。

同时，加入了AbortController生命周期的绑定。当组件销毁或用户重新发起新查询时，自动中断上一次未完成的 SSE 管道，杜绝了废弃请求占用浏览器并发连接数的问题。

5. 选型收尾：百兆内存限制下的极致性价比选型

回到最初的争论，前端技术选型长期是对工程约束的博弈。

如果项目需要在移动端 WebView 或办公设备上限额 100MB 内存运行，一味追求“端侧全自主”只会带来糟心的用户体验。

通过这次重构实测，得出了非常明确的技术选型决策原则：

1. 放弃在浏览器端加载 > 10MB 的原生向量索引库。WASM 适合做单纯的数据转换和加密，不适合做高密度的向量图构建。
2. 前端聚焦于流式交互体验与局部缓存。使用 Composition API 的shallowRef配合 SSE 流式解析，把渲染卡顿控制在 16ms 帧预算以内。
3. 服务端收拢向量检索与权限隔离。把高维向量索引和文档切片留在后端处理，既保证了数据安全，也大幅减轻了客户端的负担。

不要为了选型而选型。最酷的技术方案，往往是那些能用最少的客户端资源、解决最核心业务问题的方案。