1. 知析智能AI助手系統(tǒng)從需求到可運行骨架知析智能AI助手系統(tǒng)是一套面向文檔處理、知識檢索、內(nèi)容生成和任務(wù)執(zhí)行場景的全棧 AI 應(yīng)用前端用 Vue 3 Element Plus后端用 Spring Boot Spring AI核心能力是 RAG 檢索增強問答。它適合想復(fù)刻同類 AI 助手的全棧開發(fā)者尤其是已經(jīng)會寫 CRUD、但沒完整跑通過「上傳文檔 → 切片 → 向量化 → 檢索 → 大模型回答」這條鏈路的人。我先把整體鏈路說清楚避免你寫到一半發(fā)現(xiàn)方向錯了。系統(tǒng)分四層前端層負(fù)責(zé)頁面展示、SSE 流式接收、任務(wù)狀態(tài)渲染接口層提供 REST API 和 SSE 流式接口業(yè)務(wù)層包含對話服務(wù)、知識庫服務(wù)、文檔服務(wù)、網(wǎng)頁服務(wù)、內(nèi)容生成服務(wù)、工具服務(wù)、MCP 服務(wù)、智能體調(diào)度服務(wù)AI 能力層用 Spring AI 承載 RAG 檢索增強、Prompt 模板、ChatMemory、Advisor、Tool Calling、ReAct Agent。數(shù)據(jù)層用 MySQL 存業(yè)務(wù)數(shù)據(jù)Redis 做緩存PGvector 存向量本地文件存儲或 MinIO 存原始文檔。數(shù)據(jù)庫表設(shè)計上用戶、會話、消息、知識庫、知識庫文檔、文檔切片、網(wǎng)頁資源、AI 任務(wù)、智能體計劃、工具調(diào)用日志、MCP 調(diào)用日志、導(dǎo)出記錄這些表要提前建好。接口統(tǒng)一返回格式是{ code: 200, message: success, data: {} }這個格式看著簡單但后面所有 Controller 都靠它統(tǒng)一前端 Axios 攔截器也靠它判斷成功失敗所以一開始就定死別中途改。前端頁面清單是 8 個核心頁面登錄頁、首頁/工作臺、智能對話頁、知識庫管理頁、文檔處理頁、網(wǎng)頁分析頁、智能體任務(wù)頁、系統(tǒng)管理頁。其中智能對話頁是三欄布局左側(cè)會話列表中間聊天區(qū)域右側(cè)參數(shù)配置面板。右側(cè)面板包含模型選擇DeepSeek、通義千問、本地 Ollama、是否啟用知識庫開關(guān)、是否啟用工具調(diào)用開關(guān)、是否啟用智能體模式開關(guān)、輸出風(fēng)格下拉框、最大輸出長度、保存配置按鈕。這些參數(shù)不是擺設(shè)后面接后端時它們會直接映射到請求體字段。用戶使用流程有三條主線。文檔摘要流程上傳文檔 → 系統(tǒng)解析文本 → 用戶選擇「摘要生成」→ 大模型生成摘要 → 用戶預(yù)覽并導(dǎo)出。知識庫問答流程新建知識庫 → 上傳多個文檔 → 系統(tǒng)切片與向量化 → 進(jìn)入問答頁面 → 系統(tǒng)檢索相關(guān)片段 → 大模型生成答案。智能體執(zhí)行流程輸入任務(wù)目標(biāo) → 系統(tǒng)生成計劃 → 調(diào)用搜索/抓取/下載/PDF 工具 → 匯總結(jié)果 → 展示最終報告。這三條流程里知識庫問答是 RAG 的核心也是本文重點。文檔摘要和智能體執(zhí)行可以后面再補但 RAG 鏈路必須先跑通否則整個系統(tǒng)沒有靈魂。技術(shù)棧版本上JDK 建議 21Maven 也用 21 對應(yīng)版本。前端用npm create vitelatest zhixi-ai-frontend選 vue JavaScript。后端 Spring Boot 項目建好后先跑一次package和run確認(rèn)能啟動再往下寫。依賴包引入 hutool、knife4jknife4j 的配置后面在 IDEA 里改。配置文件在resources下默認(rèn)是 properties我們改成 ymlspring: application: name: zhixi-ai server: port: 8123 servlet: context-path: /api springdoc: swagger-ui: path: /swagger-ui.html tags-sorter: alpha operations-sorter: alpha api-docs: path: /v3/api-docs group-configs: - group: default paths-to-match: /** packages-to-scan: org.zhuhe.zhixiai.controller knife4j: enable: true setting: language: zh_cn注意packages-to-scan這一行它指定掃描哪些包的接口寫錯了 doc.html 就打不開。冒號之后要連著空格YAML 對縮進(jìn)和空格敏感。寫完寫一個測試接口訪問api/doc.html確認(rèn)能打開。到這里項目骨架和配置就齊了。下一步是接入大模型這是整個系統(tǒng)能不能跑起來的關(guān)鍵。2. TaoToken 統(tǒng)一接入一個 Key 打通多模型調(diào)用大模型接入這塊很多人卡在「每個平臺一個 Key、一套 SDK、一套計費」的碎片化問題上。知析系統(tǒng)要支持 DeepSeek、通義千問、本地 Ollama 多種模型切換如果每個都單獨接代碼里會散落一堆 if-else。我的做法是用 TaoToken 做統(tǒng)一接入層一個 Key、一個 Base URL通過改 Model ID 切換模型。TaoToken 的官網(wǎng)是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。它提供 OpenAI 兼容的接口格式所以 Spring AI 的 OpenAI starter、LangChain4j 的 OpenAI 模塊都能直接對接不需要為每個模型寫適配器。先說清楚它解決什么問題。知析系統(tǒng)的對話服務(wù)需要調(diào)用大模型RAG 問答需要調(diào)用大模型內(nèi)容生成需要調(diào)用大模型智能體的 think 步驟也需要調(diào)用大模型。如果每個場景都硬編碼某個廠商的 SDK后面換模型就要改多處代碼。用 TaoToken 之后所有調(diào)用都走同一個 Base URL模型差異只體現(xiàn)在 Model ID 上切換成本從「改代碼」降到「改配置」。接入前需要準(zhǔn)備三樣?xùn)|西Base URL、API Key、Model ID。Base URL 填https://taotoken.net/apiAPI Key 在控制臺創(chuàng)建Model ID 根據(jù)你要用的模型填比如gpt-4o-mini、claude-3-5-sonnet這類。這三件套在后面的 Spring AI 配置、Cline MCP 配置、Codex auth.json 里都會反復(fù)出現(xiàn)格式要記牢。Spring AI 里配置 OpenAI 兼容端點application-local.yml這樣寫spring: ai: openai: base-url: https://taotoken.net/api api-key: sk-你的TaoToken密鑰 chat: options: model: gpt-4o-mini temperature: 0.7這里base-url不要帶/v1后綴Spring AI 的 OpenAI starter 會自己拼路徑。api-key建議放在application-local.yml里并且把application-local.yml加入.gitignore避免密鑰上傳到倉庫。application.yml里通過spring.profiles.active: local激活本地配置。如果你用 LangChain4j配置方式類似OpenAiChatModel model OpenAiChatModel.builder() .baseUrl(https://taotoken.net/api) .apiKey(sk-你的TaoToken密鑰) .modelName(gpt-4o-mini) .build(); String answer model.chat(你好); System.out.println(answer);注意 LangChain4j 的baseUrl有時需要帶/v1具體看版本。如果報 404先檢查路徑拼接。我實測下來Spring AI 的 starter 對路徑處理更省心建議后端統(tǒng)一用 Spring AI。如果你用 Cline 或 Claude Code 這類編碼工具配置也是同一套三件套。Cline 的 MCP 配置里填 Base URL、API Key、Model IDClaude Code 的 settings 里同樣填這三項。Codex 的auth.json里也是這三個字段。格式統(tǒng)一的好處是你在一個地方配通了換個工具只是復(fù)制粘貼。TaoToken 的 Coding Plan 適合長期編碼和 Agent 場景模型對話入口適合驗證模型是否通API Keys 頁面用來創(chuàng)建和管理密鑰接入文檔里有各語言的示例代碼。這幾個入口后面 CTA 會分別給出。配置寫完后先別急著寫業(yè)務(wù)代碼用最小請求驗證一下通道是否通。這是下一步。3. 可復(fù)制配置Spring AI RAG 向量庫落地這一節(jié)給出可直接復(fù)制的配置片段包括 Spring AI 的 OpenAI 兼容配置、RAG 向量庫配置、ChatMemory 配置。路徑和原文一致你照著填就能跑。先看完整的application-local.ymlspring: ai: openai: base-url: https://taotoken.net/api api-key: sk-你的TaoToken密鑰 chat: options: model: gpt-4o-mini temperature: 0.7 embedding: options: model: text-embedding-3-small datasource: url: jdbc:mysql://localhost:3306/zhixi_ai?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 你的數(shù)據(jù)庫密碼 driver-class-name: com.mysql.cj.jdbc.Driver data: redis: host: localhost port: 6379application.yml里激活 local profilespring: application: name: zhixi-ai profiles: active: local server: port: 8123 servlet: context-path: /apiRAG 向量庫配置類用 Spring AI 內(nèi)置的 SimpleVectorStore 做內(nèi)存向量庫適合開發(fā)和演示package org.zhuhe.zhixiai.ai.Rag; import jakarta.annotation.Resource; import org.springframework.ai.document.Document; import org.springframework.ai.embedding.EmbeddingModel; import org.springframework.ai.vectorstore.SimpleVectorStore; import org.springframework.ai.vectorstore.VectorStore; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import java.util.List; Configuration public class OfficeVectorStoreConfig { Resource private OfficeDocumentLoader officeDocumentLoader; Bean VectorStore officeVectorStore(EmbeddingModel embeddingModel) { SimpleVectorStore simpleVectorStore SimpleVectorStore.builder(embeddingModel).build(); ListDocument documentList officeDocumentLoader.loadMarkdowns(); simpleVectorStore.add(documentList); return simpleVectorStore; } }Markdown 文檔加載器負(fù)責(zé)批量讀取、分割、存儲 markdown 文件并寫入 meta 信息package org.zhuhe.zhixiai.ai.Rag; import lombok.extern.slf4j.Slf4j; import org.springframework.ai.document.Document; import org.springframework.ai.reader.markdown.MarkdownDocumentReader; import org.springframework.ai.reader.markdown.config.MarkdownDocumentReaderConfig; import org.springframework.core.io.Resource; import org.springframework.core.io.support.ResourcePatternResolver; import org.springframework.stereotype.Component; import java.io.IOException; import java.util.ArrayList; import java.util.List; Component Slf4j public class OfficeDocumentLoader { private final ResourcePatternResolver resourcePatternResolver; public OfficeDocumentLoader(ResourcePatternResolver resourcePatternResolver) { this.resourcePatternResolver resourcePatternResolver; } public ListDocument loadMarkdowns() { ListDocument allDocuments new ArrayList(); try { Resource[] resources resourcePatternResolver.getResources(classpath:document/*.md); for (Resource resource : resources) { String filename resource.getFilename(); String status filename.substring(filename.length() - 8, filename.length() - 4); MarkdownDocumentReaderConfig config MarkdownDocumentReaderConfig.builder() .withHorizontalRuleCreateDocument(true) .withIncludeCodeBlock(false) .withIncludeBlockquote(false) .withAdditionalMetadata(filename, filename) .withAdditionalMetadata(status, status) .build(); MarkdownDocumentReader reader new MarkdownDocumentReader(resource, config); allDocuments.addAll(reader.get()); } } catch (IOException e) { log.error(Markdown 文檔加載失敗, e); } return allDocuments; } }ChatMemory 用 JDBC 實現(xiàn)先引入依賴dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-autoconfigure-model-chat-memory-repository-jdbc/artifactId version2.0.0-M4/version /dependency然后注入OfficeChatClient再寫一個ChatMemory配置就完成了。ChatMemory 的作用是讓多輪對話記住上下文RAG 問答時把檢索到的片段和對話歷史一起拼進(jìn) prompt。RAG 問答的核心方法public String chatWithRag(String message, String chatId) { ChatResponse chatResponse chatClient.prompt() .user(message) .advisors(advisor - advisor.param(ChatMemory.CONVERSATION_ID, chatId)) .advisors(QuestionAnswerAdvisor.builder(officeVectorStore).build()) .call() .chatResponse(); return chatResponse.getResult().getOutput().getText(); }這里引入了兩個 AdvisorQuestionAnswerAdvisor負(fù)責(zé)檢索增強VectorStoreChatMemoryAdvisor負(fù)責(zé)對話記憶。多個 Advisor 是責(zé)任鏈模式按順序執(zhí)行。如果你要用 PGvector 替代 SimpleVectorStore先在阿里云開通 PGSQL創(chuàng)建管理員賬號和數(shù)據(jù)庫安裝向量存儲插件然后在項目里配置數(shù)據(jù)庫連接。Spring AI 的文檔里寫得很清楚照著配就行。配置寫完后下一步是驗證請求是否真的通了。4. 驗證請求從 curl 到流式對話的成功結(jié)果配置寫完不代表通了必須用最小請求驗證。我習(xí)慣分三步先 curl 驗證 TaoToken 通道再驗證 Spring AI 調(diào)用最后驗證 RAG 問答。第一步curl 驗證 TaoToken 通道curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密鑰 \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [ {role: system, content: You are a helpful assistant.}, {role: user, content: 你是誰} ], stream: false }如果返回 200 并且 body 里有choices字段說明通道通了。如果返回 401檢查 Key 是否正確如果返回 404檢查路徑是否多了或少了/v1。第二步Spring AI 調(diào)用驗證。寫一個CommandLineRunner項目啟動后自動執(zhí)行Component public class SpringAIApi implements CommandLineRunner { Resource private ChatModel chatModel; Override public void run(String... args) throws Exception { AssistantMessage output chatModel.call(new Prompt(你好我是知析助手)) .getResult() .getOutput(); System.out.println(output.getText()); } }啟動項目控制臺打印出模型回復(fù)說明 Spring AI 配置正確。如果報NoApiKeyException檢查application-local.yml里的api-key是否被正確加載如果報連接超時檢查base-url是否寫成了https://taotoken.net/api而不是帶/v1的地址。第三步RAG 問答驗證。在classpath:document/下放幾個 markdown 文件格式要統(tǒng)一否則預(yù)處理不好處理。啟動項目后調(diào)用chatWithRag方法傳入問題和 chatId觀察返回內(nèi)容是否引用了文檔里的信息。如果返回的是通用回答而不是文檔內(nèi)容說明檢索沒生效檢查QuestionAnswerAdvisor是否被正確注入以及向量庫是否成功 add 了文檔。流式對話驗證用 SSE。前端用 EventSource 接收后端用SseEmitter推送。驗證時先發(fā)一個簡單問題觀察前端是否逐字顯示。如果一次性顯示全部內(nèi)容說明流式?jīng)]生效檢查后端是否用了stream()而不是call()。成功的結(jié)果是這樣的curl 返回 200 和 choicesSpring AI 控制臺打印模型回復(fù)RAG 問答返回文檔相關(guān)內(nèi)容SSE 流式逐字顯示。四個都通過說明鏈路完整。驗證過程中常見的報錯和排查方法下一節(jié)集中說。5. 常見報錯排查401、local proxy failed、reading choices、OAuth這一節(jié)對照真實報錯給出排查路徑。這些錯誤我在接入過程中都踩過按順序排查基本能解決。401 Unauthorized。最常見的原因是 API Key 錯誤或過期。先檢查application-local.yml里的api-key是否和 TaoToken 控制臺里的一致注意不要有多余空格。如果 Key 正確檢查base-url是否寫對https://taotoken.net/api不要寫成https://taotoken.net/api/v1Spring AI 的 OpenAI starter 會自己拼/v1/chat/completions。如果還報 401去 TaoToken 控制臺確認(rèn) Key 是否被禁用或額度是否用完。local proxy failed。這個報錯通常出現(xiàn)在網(wǎng)絡(luò)層不是代碼問題。檢查本機是否能正常訪問https://taotoken.net/api用 curl 直接測。如果 curl 也失敗檢查 DNS 和網(wǎng)絡(luò)連接。注意不要配置任何非官方的網(wǎng)絡(luò)工具直接用系統(tǒng)默認(rèn)網(wǎng)絡(luò)即可。如果公司網(wǎng)絡(luò)有限制換一個網(wǎng)絡(luò)環(huán)境再試。reading choices 報錯。這個錯誤通常出現(xiàn)在解析響應(yīng)時原因是返回的 JSON 結(jié)構(gòu)不符合預(yù)期。先看完整響應(yīng)體確認(rèn)是否有choices字段。如果沒有可能是模型名寫錯了比如把gpt-4o-mini寫成了gpt-4o-min。也可能是請求體格式不對檢查messages是否是數(shù)組role和content是否都有。還有一種情況是流式和非流式混用stream: true時返回的是 SSE 格式不能用普通 JSON 解析。OAuth 相關(guān)報錯。如果你用 Claude Code 或 Codex 這類工具可能會遇到 OAuth 報錯。這類工具通常需要配置auth.json或 settings 文件里面填 Base URL、API Key、Model ID 三件套。檢查auth.json里的字段名是否正確比如base_url和baseUrl在不同工具里寫法不同。如果工具提示 OAuth 失敗先確認(rèn)是否誤用了需要 OAuth 的官方端點改用 TaoToken 的 API 端點即可。Cline MCP 配置報錯。Cline 的 MCP 配置里需要填三件套Base URL 填https://taotoken.net/apiAPI Key 填 TaoToken 密鑰Model ID 填你要用的模型。如果 MCP 服務(wù)啟動失敗檢查 JSON 格式是否合法逗號和引號是否配對。如果提示模型不存在檢查 Model ID 是否拼寫正確。Codex auth.json 報錯。Codex 的auth.json里同樣填三件套。如果報invalid api key檢查 Key 是否有多余字符。如果報model not found檢查 Model ID。如果報網(wǎng)絡(luò)錯誤檢查 Base URL 是否可達(dá)。向量庫相關(guān)報錯。如果 RAG 問答返回空結(jié)果檢查classpath:document/下是否有 markdown 文件文件名格式是否統(tǒng)一。如果報EmbeddingModel注入失敗檢查spring.ai.openai.embedding.options.model是否配置。如果報向量維度不匹配檢查 embedding 模型和向量庫是否匹配。SSE 流式報錯。如果前端收不到流式內(nèi)容檢查后端是否用了SseEmitter并且設(shè)置了正確的Content-Type: text/event-stream。如果連接很快斷開檢查超時時間設(shè)置。如果內(nèi)容一次性返回檢查是否誤用了call()而不是stream()。排查的核心思路是先確認(rèn)通道通不通curl再確認(rèn)配置對不對yml最后確認(rèn)代碼邏輯對不對Advisor、VectorStore、ChatMemory。三步走下來大部分問題都能定位。6. 繼續(xù)深入Coding Plan 與接入文檔RAG 鏈路跑通后知析系統(tǒng)還有幾塊可以繼續(xù)深入。文檔處理頁要支持 PDF、DOCX、TXT 上傳和解析網(wǎng)頁分析頁要支持 URL 抓取和正文提取智能體任務(wù)頁要實現(xiàn) ReAct Agent 的 think-act 循環(huán)工具調(diào)用要支持 WebSearchTool、WebCrawlerTool、PdfExportTool、FileTool。這些能力都建立在大模型調(diào)用之上而大模型調(diào)用統(tǒng)一走 TaoToken 通道。如果你要長期做編碼和 Agent 場景TaoToken 的 Coding Plan 值得看一下入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它適合需要穩(wěn)定調(diào)用、多模型切換、按量計費的開發(fā)場景。如果你在接入過程中遇到 Key 或通道問題去 API Keys 頁面管理密鑰https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。各語言的接入示例在接入文檔里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先驗證模型是否通用模型對話入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite ?？刂婆_在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。最后說一個我踩過的坑RAG 的檢索效果不好很多時候不是模型問題而是文檔切片和 meta 信息沒做好。切片太大檢索不精準(zhǔn)切片太小上下文不完整。meta 信息要標(biāo)注來源、狀態(tài)、時間檢索時可以用 metadata 過濾。文檔格式要統(tǒng)一否則 MarkdownDocumentReader 解析出來的結(jié)構(gòu)不一致后續(xù)處理很麻煩。這些細(xì)節(jié)比換模型更能提升效果。