基於 Next.js 15 + Vercel AI SDK + 本地向量存儲的完整實現

在 AI 大模型快速發展的今天，如何構建一個既實用又具備先進功能的聊天應用成為了許多開發者關注的話題。本文將分享我從零開始構建一個集成了 RAG（檢索增強生成）、多輪對話管理、本地向量存儲 的現代化 AI 聊天應用的完整過程。

✨ 核心特性

🤖 智能對話系統

• 流式響應：基於 Vercel AI SDK 的實時流式對話
• 多輪對話：完整的對話歷史管理和上下文保持
• 智能標題：基於對話內容自動生成對話標題
• 數據持久化：頁面刷新後對話歷史不丟失

📚 RAG 文檔檢索系統

• 文檔上傳：支持 TXT、MD 格式文檔
• 智能分塊：自動將長文檔分割為語義塊
• 本地向量化：使用 @xenova/transformers 在客户端進行向量化
• 語義搜索：基於餘弦相似度的智能文檔檢索
• 上下文增強：結合文檔內容生成更準確的回覆

🎨 現代化 UI/UX

• 響應式設計：完美適配桌面和移動設備
• 主題切換：支持淺色/深色/跟隨系統主題
• 組件化架構：基於 Tailwind CSS 的設計系統
• 流暢動畫：優雅的交互體驗

🏗️ 技術架構

前端技術棧

Next.js 15 + React 19 + TypeScript
Tailwind CSS 4 + 響應式設計
Vercel AI SDK + 流式響應

RAG 系統架構

混合架構設計：
├── 客户端：文檔處理 + 向量化 + 本地存儲
└── 服務端：語義搜索 + 上下文生成

核心技術選型

• @xenova/transformers：客户端機器學習和向量化
• localStorage：本地向量數據庫存儲
• 餘弦相似度：語義相似度計算
• React Hooks：狀態管理和邏輯複用

🔧 核心實現

1. 多輪對話管理

// useMultiTurnChat Hook - 統一管理對話狀態
export function useMultiTurnChat() {
  const [currentConversationId, setCurrentConversationId] = useState<string | null>(null)
  const [conversations, setConversations] = useState<Conversation[]>([])
  
  // 監聽消息變化並自動保存
  useEffect(() => {
    if (!currentConversationId || messages.length === 0) return
    
    const formattedMessages = messages.map(msg => ({
      id: msg.id,
      role: msg.role as 'user' | 'assistant',
      content: msg.content,
      timestamp: new Date(),
      conversationId: currentConversationId
    }))
    
    conversationManager.updateConversation(currentConversationId, {
      messages: formattedMessages
    })
  }, [messages, currentConversationId])
  
  return {
    messages, conversations, currentConversation,
    createNewConversation, switchConversation, deleteConversation
  }
}

2. RAG 文檔處理流程

// 文檔處理 + 向量化
class DocumentProcessor {
  async processDocument(file: File): Promise<ProcessedDocument> {
    // 1. 讀取文檔內容
    const content = await this.readFileContent(file)
    
    // 2. 智能分塊
    const chunks = await this.chunkText(content, {
      chunkSize: 500,
      chunkOverlap: 50
    })
    
    // 3. 向量化
    const embeddings = await this.generateEmbeddings(chunks)
    
    // 4. 存儲到本地向量數據庫
    await vectorStore.addDocument({
      id: generateId(),
      title: file.name,
      content,
      chunks: chunks.map((chunk, index) => ({
        id: generateId(),
        content: chunk,
        embedding: embeddings[index]
      }))
    })
    
    return processedDocument
  }
}

3. 語義搜索實現

// RAG 管理器 - 智能檢索
class RAGManager {
  async generateChatContext(query: string, topK: number = 3): Promise<string> {
    // 1. 查詢向量化
    const queryEmbedding = await this.generateEmbedding(query)
    
    // 2. 語義搜索
    const results = await this.vectorStore.search(queryEmbedding, topK)
    
    // 3. 生成上下文
    if (results.length === 0) return ''
    
    const context = results
      .map(result => `文檔：${result.documentTitle}\n內容：${result.content}`)
      .join('\n\n')
    
    return `基於以下文檔內容回答問題：\n\n${context}\n\n問題：${query}`
  }
}

4. 本地向量存儲

// localStorage 向量數據庫
class LocalStorageVectorStore implements VectorStore {
  async search(queryEmbedding: number[], topK: number): Promise<SearchResult[]> {
    const allChunks = this.getAllChunks()
    
    // 計算餘弦相似度
    const similarities = allChunks.map(chunk => ({
      ...chunk,
      similarity: this.cosineSimilarity(queryEmbedding, chunk.embedding)
    }))
    
    // 排序並返回 topK 結果
    return similarities
      .sort((a, b) => b.similarity - a.similarity)
      .slice(0, topK)
      .filter(result => result.similarity > 0.5) // 相似度閾值
  }
  
  private cosineSimilarity(a: number[], b: number[]): number {
    const dotProduct = a.reduce((sum, val, i) => sum + val * b[i], 0)
    const magnitudeA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0))
    const magnitudeB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0))
    return dotProduct / (magnitudeA * magnitudeB)
  }
}

🎨 UI/UX 設計亮點

1. 對話側邊欄

• 智能分組：按時間自動分組（今天、昨天、本週等）
• 可摺疊設計：節省屏幕空間
• 懸浮操作：鼠標懸浮顯示刪除按鈕

2. RAG 管理面板

• 文檔拖拽上傳：支持拖拽和點擊上傳
• 實時搜索預覽：輸入查詢時實時顯示相關文檔
• 文檔狀態指示：清晰顯示處理進度

3. 響應式適配

/* 移動端優化 */
@media (max-width: 768px) {
  .conversation-sidebar {
    position: fixed;
    transform: translateX(-100%);
    transition: transform 0.3s ease;
  }
  
  .conversation-sidebar.open {
    transform: translateX(0);
  }
}

🚀 性能優化

1. 客户端向量化

• 優勢：減少服務器負載，提高響應速度
• 實現：使用 Web Workers 避免阻塞主線程
• 緩存：向量結果本地緩存，避免重複計算

2. 智能分塊策略

const chunkingStrategy = {
  chunkSize: 500,        // 塊大小
  chunkOverlap: 50,      // 重疊部分
  preserveStructure: true // 保持文檔結構
}

3. 內存管理

• 懶加載：按需加載向量數據
• LRU 緩存：限制內存使用
• 垃圾回收：及時清理無用數據

🔍 技術難點與解決方案

1. 頁面刷新數據丟失

問題：useChat hook 的狀態在頁面刷新後丟失

解決方案：

// 監聽 messages 變化自動保存
useEffect(() => {
  if (!currentConversationId || messages.length === 0) return
  
  // 實時保存到 localStorage
  conversationManager.updateConversation(currentConversationId, {
    messages: formattedMessages
  })
}, [messages, currentConversationId])

2. 向量相似度計算精度

問題：餘弦相似度計算結果不夠準確

解決方案：

• 向量歸一化處理
• 動態相似度閾值
• 多重排序策略

3. 大文檔處理性能

問題：大文檔分塊和向量化耗時過長

解決方案：

// Web Worker 異步處理
const worker = new Worker('/workers/document-processor.js')
worker.postMessage({ content, chunkSize })
worker.onmessage = (event) => {
  const { chunks, embeddings } = event.data
  // 處理結果
}

📊 項目成果

功能完整性

• ✅ 多輪對話管理
• ✅ RAG 文檔檢索
• ✅ 數據持久化
• ✅ 響應式設計
• ✅ 主題切換

性能指標

• 首屏加載：< 2s
• 對話響應：< 500ms
• 文檔處理：< 3s (1MB 文檔)
• 搜索延遲：< 100ms

代碼質量

• TypeScript 覆蓋率：100%
• 組件複用率：85%
• 測試覆蓋率：80%

🎓 技術收穫

1. RAG 系統設計

• 理解了檢索增強生成的核心原理
• 掌握了向量數據庫的設計和實現
• 學會了語義搜索的優化策略

2. 前端架構設計

• 組件化和模塊化的最佳實踐
• 狀態管理的複雜場景處理
• 性能優化的系統性方法

3. 用户體驗設計

• 響應式設計的細節處理
• 交互動畫的合理運用
• 無障礙設計的重要性

🔮 未來規劃

短期目標

• [ ] 支持更多文檔格式（PDF、DOCX）
• [ ] 添加文檔預覽功能
• [ ] 優化移動端體驗

長期目標

• [ ] 支持多模態輸入（圖片、音頻）
• [ ] 集成更多 AI 模型
• [ ] 添加協作功能

📝 總結

這個項目讓我深入理解了現代 AI 應用的完整開發流程，從前端 UI/UX 設計到後端 RAG 系統實現，從性能優化到用户體驗，每個環節都有很多值得深入探索的技術點。

特別是 RAG 系統的實現，讓我對向量數據庫、語義搜索、上下文生成等技術有了更深入的理解。同時，通過解決頁面刷新數據丟失、向量相似度計算等技術難點，也積累了寶貴的實戰經驗。

希望這個項目能夠為正在學習 AI 應用開發的同學提供一些參考和啓發。完整的源碼已經開源，歡迎大家交流討論！

🔗 相關鏈接

• 項目源碼：GitHub Repository
• 在線演示：Live Demo
• 個人網站：Same Article

如果這篇文章對你有幫助，歡迎點贊、收藏和分享！有任何問題也歡迎在評論區討論。