1. 知析智能AI助手系統(tǒng)從需求到可運(yùn)行骨架知析智能AI助手系統(tǒng)是一套面向文檔處理、知識(shí)檢索、內(nèi)容生成和任務(wù)執(zhí)行場(chǎng)景的全棧 AI 應(yīng)用前端用 Vue 3 Element Plus后端用 Spring Boot Spring AI核心能力是 RAG 檢索增強(qiáng)問答。它適合想復(fù)刻同類 AI 助手的全棧開發(fā)者尤其是已經(jīng)會(huì)寫 CRUD、但沒完整跑通過「上傳文檔 → 切片 → 向量化 → 檢索 → 大模型回答」這條鏈路的人。我先把整體鏈路說清楚避免你寫到一半發(fā)現(xiàn)方向錯(cuò)了。系統(tǒng)分四層前端層負(fù)責(zé)頁(yè)面展示、SSE 流式接收、任務(wù)狀態(tài)渲染接口層提供 REST API 和 SSE 流式接口業(yè)務(wù)層包含對(duì)話服務(wù)、知識(shí)庫(kù)服務(wù)、文檔服務(wù)、網(wǎng)頁(yè)服務(wù)、內(nèi)容生成服務(wù)、工具服務(wù)、MCP 服務(wù)、智能體調(diào)度服務(wù)AI 能力層用 Spring AI 承載 RAG 檢索增強(qiáng)、Prompt 模板、ChatMemory、Advisor、Tool Calling、ReAct Agent。數(shù)據(jù)層用 MySQL 存業(yè)務(wù)數(shù)據(jù)Redis 做緩存PGvector 存向量本地文件存儲(chǔ)或 MinIO 存原始文檔。數(shù)據(jù)庫(kù)表設(shè)計(jì)上用戶、會(huì)話、消息、知識(shí)庫(kù)、知識(shí)庫(kù)文檔、文檔切片、網(wǎng)頁(yè)資源、AI 任務(wù)、智能體計(jì)劃、工具調(diào)用日志、MCP 調(diào)用日志、導(dǎo)出記錄這些表要提前建好。接口統(tǒng)一返回格式是{ code: 200, message: success, data: {} }這個(gè)格式看著簡(jiǎn)單但后面所有 Controller 都靠它統(tǒng)一前端 Axios 攔截器也靠它判斷成功失敗所以一開始就定死別中途改。前端頁(yè)面清單是 8 個(gè)核心頁(yè)面登錄頁(yè)、首頁(yè)/工作臺(tái)、智能對(duì)話頁(yè)、知識(shí)庫(kù)管理頁(yè)、文檔處理頁(yè)、網(wǎng)頁(yè)分析頁(yè)、智能體任務(wù)頁(yè)、系統(tǒng)管理頁(yè)。其中智能對(duì)話頁(yè)是三欄布局左側(cè)會(huì)話列表中間聊天區(qū)域右側(cè)參數(shù)配置面板。右側(cè)面板包含模型選擇DeepSeek、通義千問、本地 Ollama、是否啟用知識(shí)庫(kù)開關(guān)、是否啟用工具調(diào)用開關(guān)、是否啟用智能體模式開關(guān)、輸出風(fēng)格下拉框、最大輸出長(zhǎng)度、保存配置按鈕。這些參數(shù)不是擺設(shè)后面接后端時(shí)它們會(huì)直接映射到請(qǐng)求體字段。用戶使用流程有三條主線。文檔摘要流程上傳文檔 → 系統(tǒng)解析文本 → 用戶選擇「摘要生成」→ 大模型生成摘要 → 用戶預(yù)覽并導(dǎo)出。知識(shí)庫(kù)問答流程新建知識(shí)庫(kù) → 上傳多個(gè)文檔 → 系統(tǒng)切片與向量化 → 進(jìn)入問答頁(yè)面 → 系統(tǒng)檢索相關(guān)片段 → 大模型生成答案。智能體執(zhí)行流程輸入任務(wù)目標(biāo) → 系統(tǒng)生成計(jì)劃 → 調(diào)用搜索/抓取/下載/PDF 工具 → 匯總結(jié)果 → 展示最終報(bào)告。這三條流程里知識(shí)庫(kù)問答是 RAG 的核心也是本文重點(diǎn)。文檔摘要和智能體執(zhí)行可以后面再補(bǔ)但 RAG 鏈路必須先跑通否則整個(gè)系統(tǒng)沒有靈魂。技術(shù)棧版本上JDK 建議 21Maven 也用 21 對(duì)應(yīng)版本。前端用npm create vitelatest zhixi-ai-frontend選 vue JavaScript。后端 Spring Boot 項(xiàng)目建好后先跑一次package和run確認(rèn)能啟動(dòng)再往下寫。依賴包引入 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這一行它指定掃描哪些包的接口寫錯(cuò)了 doc.html 就打不開。冒號(hào)之后要連著空格YAML 對(duì)縮進(jìn)和空格敏感。寫完寫一個(gè)測(cè)試接口訪問api/doc.html確認(rèn)能打開。到這里項(xiàng)目骨架和配置就齊了。下一步是接入大模型這是整個(gè)系統(tǒng)能不能跑起來的關(guān)鍵。2. TaoToken 統(tǒng)一接入一個(gè) Key 打通多模型調(diào)用大模型接入這塊很多人卡在「每個(gè)平臺(tái)一個(gè) Key、一套 SDK、一套計(jì)費(fèi)」的碎片化問題上。知析系統(tǒng)要支持 DeepSeek、通義千問、本地 Ollama 多種模型切換如果每個(gè)都單獨(dú)接代碼里會(huì)散落一堆 if-else。我的做法是用 TaoToken 做統(tǒng)一接入層一個(gè) Key、一個(gè) 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 模塊都能直接對(duì)接不需要為每個(gè)模型寫適配器。先說清楚它解決什么問題。知析系統(tǒng)的對(duì)話服務(wù)需要調(diào)用大模型RAG 問答需要調(diào)用大模型內(nèi)容生成需要調(diào)用大模型智能體的 think 步驟也需要調(diào)用大模型。如果每個(gè)場(chǎng)景都硬編碼某個(gè)廠商的 SDK后面換模型就要改多處代碼。用 TaoToken 之后所有調(diào)用都走同一個(gè) Base URL模型差異只體現(xiàn)在 Model ID 上切換成本從「改代碼」降到「改配置」。接入前需要準(zhǔn)備三樣?xùn)|西Base URL、API Key、Model ID。Base URL 填https://taotoken.net/apiAPI Key 在控制臺(tái)創(chuàng)建Model ID 根據(jù)你要用的模型填比如gpt-4o-mini、claude-3-5-sonnet這類。這三件套在后面的 Spring AI 配置、Cline MCP 配置、Codex auth.json 里都會(huì)反復(fù)出現(xiàn)格式要記牢。Spring AI 里配置 OpenAI 兼容端點(diǎn)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 會(huì)自己拼路徑。api-key建議放在application-local.yml里并且把a(bǔ)pplication-local.yml加入.gitignore避免密鑰上傳到倉(cāng)庫(kù)。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有時(shí)需要帶/v1具體看版本。如果報(bào) 404先檢查路徑拼接。我實(shí)測(cè)下來Spring AI 的 starter 對(duì)路徑處理更省心建議后端統(tǒng)一用 Spring AI。如果你用 Cline 或 Claude Code 這類編碼工具配置也是同一套三件套。Cline 的 MCP 配置里填 Base URL、API Key、Model IDClaude Code 的 settings 里同樣填這三項(xiàng)。Codex 的auth.json里也是這三個(gè)字段。格式統(tǒng)一的好處是你在一個(gè)地方配通了換個(gè)工具只是復(fù)制粘貼。TaoToken 的 Coding Plan 適合長(zhǎng)期編碼和 Agent 場(chǎng)景模型對(duì)話入口適合驗(yàn)證模型是否通API Keys 頁(yè)面用來創(chuàng)建和管理密鑰接入文檔里有各語(yǔ)言的示例代碼。這幾個(gè)入口后面 CTA 會(huì)分別給出。配置寫完后先別急著寫業(yè)務(wù)代碼用最小請(qǐng)求驗(yàn)證一下通道是否通。這是下一步。3. 可復(fù)制配置Spring AI RAG 向量庫(kù)落地這一節(jié)給出可直接復(fù)制的配置片段包括 Spring AI 的 OpenAI 兼容配置、RAG 向量庫(kù)配置、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ù)庫(kù)密碼 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 向量庫(kù)配置類用 Spring AI 內(nèi)置的 SimpleVectorStore 做內(nèi)存向量庫(kù)適合開發(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é)批量讀取、分割、存儲(chǔ) 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 實(shí)現(xiàn)先引入依賴dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-autoconfigure-model-chat-memory-repository-jdbc/artifactId version2.0.0-M4/version /dependency然后注入OfficeChatClient再寫一個(gè)ChatMemory配置就完成了。ChatMemory 的作用是讓多輪對(duì)話記住上下文RAG 問答時(shí)把檢索到的片段和對(duì)話歷史一起拼進(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(); }這里引入了兩個(gè) AdvisorQuestionAnswerAdvisor負(fù)責(zé)檢索增強(qiáng)VectorStoreChatMemoryAdvisor負(fù)責(zé)對(duì)話記憶。多個(gè) Advisor 是責(zé)任鏈模式按順序執(zhí)行。如果你要用 PGvector 替代 SimpleVectorStore先在阿里云開通 PGSQL創(chuàng)建管理員賬號(hào)和數(shù)據(jù)庫(kù)安裝向量存儲(chǔ)插件然后在項(xiàng)目里配置數(shù)據(jù)庫(kù)連接。Spring AI 的文檔里寫得很清楚照著配就行。配置寫完后下一步是驗(yàn)證請(qǐng)求是否真的通了。4. 驗(yàn)證請(qǐng)求從 curl 到流式對(duì)話的成功結(jié)果配置寫完不代表通了必須用最小請(qǐng)求驗(yàn)證。我習(xí)慣分三步先 curl 驗(yàn)證 TaoToken 通道再驗(yàn)證 Spring AI 調(diào)用最后驗(yàn)證 RAG 問答。第一步curl 驗(yàn)證 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: 你是誰(shuí)} ], stream: false }如果返回 200 并且 body 里有choices字段說明通道通了。如果返回 401檢查 Key 是否正確如果返回 404檢查路徑是否多了或少了/v1。第二步Spring AI 調(diào)用驗(yàn)證。寫一個(gè)CommandLineRunner項(xiàng)目啟動(dòng)后自動(dòng)執(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()); } }啟動(dòng)項(xiàng)目控制臺(tái)打印出模型回復(fù)說明 Spring AI 配置正確。如果報(bào)NoApiKeyException檢查application-local.yml里的api-key是否被正確加載如果報(bào)連接超時(shí)檢查base-url是否寫成了https://taotoken.net/api而不是帶/v1的地址。第三步RAG 問答驗(yàn)證。在classpath:document/下放幾個(gè) markdown 文件格式要統(tǒng)一否則預(yù)處理不好處理。啟動(dòng)項(xiàng)目后調(diào)用chatWithRag方法傳入問題和 chatId觀察返回內(nèi)容是否引用了文檔里的信息。如果返回的是通用回答而不是文檔內(nèi)容說明檢索沒生效檢查QuestionAnswerAdvisor是否被正確注入以及向量庫(kù)是否成功 add 了文檔。流式對(duì)話驗(yàn)證用 SSE。前端用 EventSource 接收后端用SseEmitter推送。驗(yàn)證時(shí)先發(fā)一個(gè)簡(jiǎn)單問題觀察前端是否逐字顯示。如果一次性顯示全部?jī)?nèi)容說明流式?jīng)]生效檢查后端是否用了stream()而不是call()。成功的結(jié)果是這樣的curl 返回 200 和 choicesSpring AI 控制臺(tái)打印模型回復(fù)RAG 問答返回文檔相關(guān)內(nèi)容SSE 流式逐字顯示。四個(gè)都通過說明鏈路完整。驗(yàn)證過程中常見的報(bào)錯(cuò)和排查方法下一節(jié)集中說。5. 常見報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth這一節(jié)對(duì)照真實(shí)報(bào)錯(cuò)給出排查路徑。這些錯(cuò)誤我在接入過程中都踩過按順序排查基本能解決。401 Unauthorized。最常見的原因是 API Key 錯(cuò)誤或過期。先檢查application-local.yml里的api-key是否和 TaoToken 控制臺(tái)里的一致注意不要有多余空格。如果 Key 正確檢查base-url是否寫對(duì)https://taotoken.net/api不要寫成https://taotoken.net/api/v1Spring AI 的 OpenAI starter 會(huì)自己拼/v1/chat/completions。如果還報(bào) 401去 TaoToken 控制臺(tái)確認(rèn) Key 是否被禁用或額度是否用完。local proxy failed。這個(gè)報(bào)錯(cuò)通常出現(xiàn)在網(wǎng)絡(luò)層不是代碼問題。檢查本機(jī)是否能正常訪問https://taotoken.net/api用 curl 直接測(cè)。如果 curl 也失敗檢查 DNS 和網(wǎng)絡(luò)連接。注意不要配置任何非官方的網(wǎng)絡(luò)工具直接用系統(tǒng)默認(rèn)網(wǎng)絡(luò)即可。如果公司網(wǎng)絡(luò)有限制換一個(gè)網(wǎng)絡(luò)環(huán)境再試。reading choices 報(bào)錯(cuò)。這個(gè)錯(cuò)誤通常出現(xiàn)在解析響應(yīng)時(shí)原因是返回的 JSON 結(jié)構(gòu)不符合預(yù)期。先看完整響應(yīng)體確認(rèn)是否有choices字段。如果沒有可能是模型名寫錯(cuò)了比如把gpt-4o-mini寫成了gpt-4o-min。也可能是請(qǐng)求體格式不對(duì)檢查messages是否是數(shù)組role和content是否都有。還有一種情況是流式和非流式混用stream: true時(shí)返回的是 SSE 格式不能用普通 JSON 解析。OAuth 相關(guān)報(bào)錯(cuò)。如果你用 Claude Code 或 Codex 這類工具可能會(huì)遇到 OAuth 報(bào)錯(cuò)。這類工具通常需要配置auth.json或 settings 文件里面填 Base URL、API Key、Model ID 三件套。檢查auth.json里的字段名是否正確比如base_url和baseUrl在不同工具里寫法不同。如果工具提示 OAuth 失敗先確認(rèn)是否誤用了需要 OAuth 的官方端點(diǎn)改用 TaoToken 的 API 端點(diǎn)即可。Cline MCP 配置報(bào)錯(cuò)。Cline 的 MCP 配置里需要填三件套Base URL 填https://taotoken.net/apiAPI Key 填 TaoToken 密鑰Model ID 填你要用的模型。如果 MCP 服務(wù)啟動(dòng)失敗檢查 JSON 格式是否合法逗號(hào)和引號(hào)是否配對(duì)。如果提示模型不存在檢查 Model ID 是否拼寫正確。Codex auth.json 報(bào)錯(cuò)。Codex 的auth.json里同樣填三件套。如果報(bào)invalid api key檢查 Key 是否有多余字符。如果報(bào)model not found檢查 Model ID。如果報(bào)網(wǎng)絡(luò)錯(cuò)誤檢查 Base URL 是否可達(dá)。向量庫(kù)相關(guān)報(bào)錯(cuò)。如果 RAG 問答返回空結(jié)果檢查classpath:document/下是否有 markdown 文件文件名格式是否統(tǒng)一。如果報(bào)EmbeddingModel注入失敗檢查spring.ai.openai.embedding.options.model是否配置。如果報(bào)向量維度不匹配檢查 embedding 模型和向量庫(kù)是否匹配。SSE 流式報(bào)錯(cuò)。如果前端收不到流式內(nèi)容檢查后端是否用了SseEmitter并且設(shè)置了正確的Content-Type: text/event-stream。如果連接很快斷開檢查超時(shí)時(shí)間設(shè)置。如果內(nèi)容一次性返回檢查是否誤用了call()而不是stream()。排查的核心思路是先確認(rèn)通道通不通curl再確認(rèn)配置對(duì)不對(duì)yml最后確認(rèn)代碼邏輯對(duì)不對(duì)Advisor、VectorStore、ChatMemory。三步走下來大部分問題都能定位。6. 繼續(xù)深入Coding Plan 與接入文檔RAG 鏈路跑通后知析系統(tǒng)還有幾塊可以繼續(xù)深入。文檔處理頁(yè)要支持 PDF、DOCX、TXT 上傳和解析網(wǎng)頁(yè)分析頁(yè)要支持 URL 抓取和正文提取智能體任務(wù)頁(yè)要實(shí)現(xiàn) ReAct Agent 的 think-act 循環(huán)工具調(diào)用要支持 WebSearchTool、WebCrawlerTool、PdfExportTool、FileTool。這些能力都建立在大模型調(diào)用之上而大模型調(diào)用統(tǒng)一走 TaoToken 通道。如果你要長(zhǎng)期做編碼和 Agent 場(chǎng)景TaoToken 的 Coding Plan 值得看一下入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它適合需要穩(wěn)定調(diào)用、多模型切換、按量計(jì)費(fèi)的開發(fā)場(chǎng)景。如果你在接入過程中遇到 Key 或通道問題去 API Keys 頁(yè)面管理密鑰https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。各語(yǔ)言的接入示例在接入文檔里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先驗(yàn)證模型是否通用模型對(duì)話入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite ?？刂婆_(tái)在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。最后說一個(gè)我踩過的坑RAG 的檢索效果不好很多時(shí)候不是模型問題而是文檔切片和 meta 信息沒做好。切片太大檢索不精準(zhǔn)切片太小上下文不完整。meta 信息要標(biāo)注來源、狀態(tài)、時(shí)間檢索時(shí)可以用 metadata 過濾。文檔格式要統(tǒng)一否則 MarkdownDocumentReader 解析出來的結(jié)構(gòu)不一致后續(xù)處理很麻煩。這些細(xì)節(jié)比換模型更能提升效果。