簡(jiǎn)介面向全棧開(kāi)發(fā)者這份資源是一套基于Spring Boot 3與LangChain4j的AI應(yīng)用平臺(tái)源碼能幫助快速搭建具備智能代碼生成、智能體編排、工作流管理與工具調(diào)用能力的完整系統(tǒng)。前端使用Vue 3構(gòu)建交互界面后端提供可視化編輯、一鍵部署、應(yīng)用管理和智能路由等核心能力并整合多級(jí)存儲(chǔ)與Nginx通過(guò)ARMS、Prometheus與Grafana實(shí)現(xiàn)應(yīng)用監(jiān)控也兼容Cursor Vibe Coding開(kāi)發(fā)模式。壓縮包內(nèi)共216個(gè)文件以143個(gè)Java文件為主要組成部分承載后端業(yè)務(wù)邏輯與集成配置21個(gè)TypeScript文件和19個(gè)Vue文件對(duì)應(yīng)前端頁(yè)面與交互邏輯其余包括JSON配置、SQL初始化腳本、YAML部署文件以及說(shuō)明文檔等輔助材料。整體壓縮包大小約1.14MB結(jié)構(gòu)清晰便于按需閱讀。截至目前已有250人瀏覽學(xué)習(xí)適合想要深入實(shí)踐LangChain4j、LangGraph4j工作流以及AI應(yīng)用工程化的開(kāi)發(fā)者參考學(xué)習(xí)。1. 這個(gè)“AI應(yīng)用平臺(tái)”到底在解決什么問(wèn)題如果你所在團(tuán)隊(duì)已經(jīng)試過(guò)把大模型接進(jìn)業(yè)務(wù)系統(tǒng)大概率會(huì)遇到這三件事第一模型只會(huì)“聊天”讓它去查數(shù)據(jù)庫(kù)、改工單、調(diào)接口就得寫(xiě)一堆膠水代碼第二一段固定的提示詞應(yīng)付不了多步任務(wù)業(yè)務(wù)要求“先查庫(kù)存再算報(bào)價(jià)最后生成合同”每一步都有嚴(yán)格順序第三做出來(lái)的東西只活在開(kāi)發(fā)者的 IDEA 里業(yè)務(wù)方想要在頁(yè)面上自己拖一拖、改一改、點(diǎn)一下就能上線(xiàn)。這個(gè)標(biāo)題把這件事說(shuō)全了——基于 SpringBoot3 LangChain4j Vue3 搭一個(gè) AI 應(yīng)用平臺(tái)用 AI 智能體和 ToolCalling 讓模型有手有腳用 LangGraph4j 工作流把不可控的對(duì)話(huà)變成可控的流程再用 Vue3 做一套可視化編輯、應(yīng)用管理和一鍵部署的殼子。它適合兩類(lèi)人一類(lèi)是 Java 后端為主、想在公司內(nèi)部落地 AI 功能但不想引一堆 Python 微服務(wù)的團(tuán)隊(duì)另一類(lèi)是正在做 AI 應(yīng)用低代碼平臺(tái)、需要參考一條端到端技術(shù)路徑的開(kāi)發(fā)者。這篇筆記按后端底座、智能體、工作流、前端落地和常見(jiàn)坑的順序展開(kāi)照著能做出一版可演示、可評(píng)審、可繼續(xù)投入的骨架。2. 后端底座SpringBoot3 LangChain4j 的模型接入與多路召回2.1 為什么選 SpringBoot3 LangChain4j而不是自己封裝 HTTP 客戶(hù)端很多 Java 團(tuán)隊(duì)接到 AI 需求后的第一反應(yīng)是直接調(diào)模型廠(chǎng)商的 HTTP 接口寫(xiě)一個(gè) RestTemplate 封裝再自己管理上下文和歷史消息。短期看沒(méi)毛病一旦要支持多模型切換、流式輸出、多輪記憶、工具調(diào)用這套手寫(xiě)代碼會(huì)迅速膨脹成沒(méi)人敢動(dòng)的“黑匣子”。LangChain4j 在 Java 生態(tài)里的定位相當(dāng)于把 LangChain 那套抽象用 Java 重寫(xiě)了一遍但它更收斂核心就幾個(gè)概念——ChatLanguageModel 管模型對(duì)話(huà)EmbeddingModel 管向量化AiService 管聲明式接口Tool 管工具調(diào)用Memory 管對(duì)話(huà)歷史。對(duì) SpringBoot3 團(tuán)隊(duì)來(lái)說(shuō)集成成本比引入 Python 服務(wù)低得多而且可以跟現(xiàn)有的 Spring 容器、配置體系、事務(wù)、監(jiān)控直接融合。SpringBoot3 本身的價(jià)值在 AI 場(chǎng)景里會(huì)被放大一是原生支持虛擬線(xiàn)程處理 SSE 流式響應(yīng)和工具并行調(diào)用時(shí)線(xiàn)程開(kāi)銷(xiāo)明顯下降二是 SpringBoot3 的配置綁定和自動(dòng)裝配讓 LangChain4j 的模型參數(shù)可以全部放進(jìn) application.yml換模型時(shí)不需要改 Java 代碼三是 SpringBoot3 對(duì) GraalVM 的支持雖然還不是萬(wàn)能靈藥但做平臺(tái)類(lèi)項(xiàng)目時(shí)預(yù)留了后續(xù)優(yōu)化啟動(dòng)內(nèi)存的余地。這一層選型的核心訴求不是“誰(shuí)的生態(tài)更熱鬧”而是“這個(gè)團(tuán)隊(duì)能不能低成本把 AI 能力接進(jìn)現(xiàn)有的 Java 服務(wù)里”。2.2 模型接入層用 OpenAI 兼容協(xié)議適配多模型平臺(tái)類(lèi)應(yīng)用最忌諱把模型廠(chǎng)商寫(xiě)死在代碼里。常見(jiàn)的做法是底層統(tǒng)一走 OpenAI 兼容的 Chat 接口協(xié)議上層通過(guò)配置決定連哪家服務(wù)。這樣無(wú)論是公有云模型、私有化部署的模型還是開(kāi)源模型網(wǎng)關(guān)只要對(duì)方暴露了兼容接口就能一根配置切過(guò)去。LangChain4j 內(nèi)置的 OpenAiChatModel 支持自定義 baseUrl官方模型和兼容協(xié)議模型都可以?huà)斓酵粋€(gè)入口下。spring: application: name: ai-platform langchain4j: open-ai: base-url: ${LLM_BASE_URL:https://your-llm-gateway.example.com/v1} api-key: ${LLM_API_KEY:} chat-model: model-name: ${LLM_MODEL_NAME:qwen2.5-72b-instruct} temperature: 0.7 timeout: 60s max-tokens: 4096 log-requests: false這段配置的關(guān)鍵在于base-url和model-name都做成了環(huán)境變量占位。平臺(tái)內(nèi)部測(cè)試用一套模型生產(chǎn)切另一套前端的工作流定義、智能體配置完全不用改。log-requests在聯(lián)調(diào)階段建議開(kāi)成 true能看到實(shí)際發(fā)給模型的 payload排查“模型為什么沒(méi)按預(yù)期調(diào)用工具”時(shí)這是第一手證據(jù)上線(xiàn)前一定關(guān)掉否則每次對(duì)話(huà)的完整內(nèi)容都會(huì)落日志時(shí)間長(zhǎng)了下游日志系統(tǒng)先扛不住。然后是聲明式接口。LangChain4j 的 AiService 用注解定義服務(wù)方法框架在運(yùn)行時(shí)生成實(shí)現(xiàn)類(lèi)AiService public interface ChatAssistant { String chat(MemoryId String memoryId, UserMessage String userMessage); Streaming FluxString streamChat(MemoryId String memoryId, UserMessage String userMessage); }這個(gè)接口直接被 Spring 代理方法上的UserMessage表示哪個(gè)人傳參數(shù)拼進(jìn)用戶(hù)消息MemoryId表示按業(yè)務(wù)維度隔離對(duì)話(huà)歷史——比如一個(gè)表單一個(gè)記憶一個(gè)工單一個(gè)記憶而不是全局共享上下文。Streaming返回 Reactor 的 Flux配合 SpringBoot3 的 WebFlux 或 MVC 異步支持把流式 token 通過(guò) SSE 推給前端。需要注意AiService 的實(shí)現(xiàn)機(jī)制對(duì)“自定義上下文拼接”不夠靈活。常見(jiàn)做法是平臺(tái)的應(yīng)用配置里允許用戶(hù)填系統(tǒng)提示詞這部分不適合寫(xiě)死在注解上而是用 ChatMemory 和 MessageWindow 在會(huì)話(huà)維度動(dòng)態(tài)構(gòu)造。2.3 多路召回向量檢索 關(guān)鍵詞檢索 融合排序熱詞里那個(gè)“l(fā)angchain4j 多路召回”本質(zhì)是 RAG 里提升召回質(zhì)量的關(guān)鍵手段。單靠向量檢索遇到專(zhuān)有名詞、型號(hào)、工單編號(hào)這類(lèi)沒(méi)有語(yǔ)義但字符高度精確的查詢(xún)效果會(huì)很差單靠關(guān)鍵詞檢索又接不住“幫我把最近一周未結(jié)算的訂單按金額排個(gè)序”這種口語(yǔ)化表達(dá)。平臺(tái)里我給知識(shí)庫(kù)場(chǎng)景設(shè)計(jì)的召回鏈路是一路走向量相似度一路走關(guān)鍵詞 BM25兩邊分別取 topK再做歸一化融合。Component public class HybridRetriever { private final EmbeddingStoreTextSegment embeddingStore; private final EmbeddingModel embeddingModel; private final KeywordSearchService keywordSearchService; public ListScoredDocument retrieve(String query, int topK) { // 第一路向量召回 var queryEmbedding embeddingModel.embed(query).content(); var vectorResults embeddingStore.search(queryEmbedding, topK 5) .stream() .map(hit - new ScoredDocument(hit.scoredText().text(), hit.score(), vector)) .toList(); // 第二路關(guān)鍵詞召回走 BM25 或者數(shù)據(jù)庫(kù)全文索引 ListScoredDocument keywordResults keywordSearchService.search(query, topK 5); // 第三路融合用 RRF 公式而非直接加權(quán) return fuse(vectorResults, keywordResults, topK); } }融合邏輯先刷一出分?jǐn)?shù)歸一化再用倒數(shù)排名融合RRFprivate List fuse(List vectorDocs, List keywordDocs, int topK) { MapString, Double scoreMap new HashMap(); addWithRrf(scoreMap, vectorDocs, 60); addWithRrf(scoreMap, keywordDocs, 60); return scoreMap.entrySet().stream() .sorted(Map.Entry.String, DoublecomparingByValue().reversed()) .limit(topK) .map(e - new ScoredDocument(e.getKey(), e.getValue(), fused)) .toList(); }private void addWithRrf(MapString, Double map, List docs, int k) { for (int rank 0; rank docs.size(); rank) { ScoredDocument doc docs.get(rank); map.merge(doc.content(), 1.0 / (k rank 1), Double::sum); } }參數(shù)說(shuō)明里最值得調(diào)的是兩個(gè)值向量召回和關(guān)鍵詞召回的數(shù)量、RRF 的常數(shù) k。常見(jiàn)做法是多召回一部分比如 topK5讓融合階段有得選k 一般取 60 左右調(diào)小會(huì)讓高排名文檔權(quán)重更突出調(diào)大則更平均。實(shí)際跑下來(lái)經(jīng)驗(yàn)是向量召回 top 50 里如果沒(méi)有答案融合也救不回來(lái)問(wèn)題通常出在文檔切分粒度或 Embedding 模型本身。 ### 2.4 代碼生成器場(chǎng)景模型輸出到工程落地之間還有一道閘 標(biāo)題里專(zhuān)門(mén)點(diǎn)出智能代碼生成這是 AI 應(yīng)用平臺(tái)最接地氣的一個(gè)能力。實(shí)現(xiàn)上不是扔一個(gè)“給我生成 UserController”的提示詞就完事而是把代碼生成拆成三步需求理解、工程結(jié)構(gòu)約束、代碼后處理。工程結(jié)構(gòu)約束是最容易被忽略的——直接讓模型自由輸出生成的代碼大概率跟項(xiàng)目現(xiàn)有框架不一致。 常見(jiàn)做法是把項(xiàng)目的技術(shù)棧約束、目錄規(guī)范、接口風(fēng)格寫(xiě)成 system prompt 的一部分再把代碼生成的產(chǎn)物限定為填充式代碼塊。例如生成一個(gè) SpringBoot 的 Service 實(shí)現(xiàn)時(shí)平臺(tái)先注入項(xiàng)目模板模型只需要補(bǔ)全方法體。生成之后的工作站不住腳代碼格式化、編譯校驗(yàn)、導(dǎo)入補(bǔ)全這三步必須自動(dòng)化否則用戶(hù)拿到一坨縮進(jìn)混亂、缺 import 文件根本沒(méi)法看。這部分后續(xù)會(huì)展開(kāi)談但在后端底座這里要明確一條邊界——LangChain4j 負(fù)責(zé)和模型打交道代碼生成的工程部分必須由平臺(tái)自己的服務(wù)接管。 ## 3. 讓模型有手有腳ToolCalling 與 AI 智能體的實(shí)現(xiàn)細(xì)節(jié) ### 3.1 ToolCalling 到底是什么為什么智能體離不開(kāi)它 讓模型直接生成“查數(shù)據(jù)庫(kù)、發(fā)郵件、創(chuàng)建工單”這些操作是不現(xiàn)實(shí)的模型本質(zhì)上是概率生成文本它不知道自己能不能執(zhí)行、有沒(méi)有權(quán)限、操作結(jié)果是什么。ToolCalling 解決的是這個(gè)“能力邊界”問(wèn)題模型在對(duì)話(huà)中輸出一個(gè)結(jié)構(gòu)化請(qǐng)求比如“調(diào)用 searchContract 工具參數(shù) keyword采購(gòu)合同”應(yīng)用層負(fù)責(zé)真正執(zhí)行再把執(zhí)行結(jié)果作為新的上下文繼續(xù)讓模型推理。智能體之所以叫“智能體”就是因?yàn)樗邆涓兄盏接脩?hù)輸入、決策決定調(diào)哪個(gè)工具、行動(dòng)執(zhí)行工具、觀察讀取執(zhí)行結(jié)果的循環(huán)。 ### 3.2 用 LangChain4j 注冊(cè)一個(gè)工具參數(shù)描述決定成敗 LangChain4j 的 Tool 注解會(huì)把方法暴露給模型方法名、參數(shù)名、參數(shù)描述會(huì)拼到模型的工具定義里。這部分是對(duì)模型效果影響最大、也是最容易敷衍的地方。 java Component public class ContractTool { private final ContractRepository contractRepository; Tool(根據(jù)合同編號(hào)或關(guān)鍵字搜索合同返回合同名稱(chēng)、金額、簽訂日期和當(dāng)前狀態(tài)) public ListContractSearchResult searchContract( ToolParameter(搜索關(guān)鍵字可以是合同名稱(chēng)片段或完整合同編號(hào)) String keyword, ToolParameter(value 是否只查有效合同默認(rèn) true) boolean activeOnly) { return contractRepository.search(keyword, activeOnly); } Tool(查詢(xún)指定合同金額是否已超過(guò)預(yù)算上限) public BudgetCheckResult checkBudget( ToolParameter(合同編號(hào)) String contractNo, ToolParameter(預(yù)算金額單位元) double budgetAmount) { // 參數(shù)進(jìn) LLM 時(shí)是字符串必須做類(lèi)型校驗(yàn)和范圍校驗(yàn) if (budgetAmount 0 || budgetAmount 1_000_000_000) { throw new IllegalArgumentException(預(yù)算金額超出合理范圍); } return contractRepository.checkBudget(contractNo, budgetAmount); } }兩個(gè)細(xì)節(jié)值得說(shuō)。第一Tool 的工具描述要寫(xiě)清楚“這個(gè)工具能做什么、返回什么”模型依賴(lài)這段描述決定何時(shí)調(diào)用描述寫(xiě)得太短模型容易在其他工具上誤選寫(xiě)得太長(zhǎng)又占用上下文。第二參數(shù)描述必須包含“取值范圍、單位、主鍵格式”等信息——你寫(xiě)“預(yù)算金額單位元”模型就知道把用戶(hù)嘴里的“五百萬(wàn)”轉(zhuǎn)成 5000000 而不是 500 萬(wàn)次調(diào)用。這個(gè)環(huán)節(jié)做不好后面所有容錯(cuò)邏輯都是在給提示詞背鍋。3.3 工具執(zhí)行的循環(huán)控制超時(shí)、并發(fā)、死循環(huán)模型輸出工具調(diào)用請(qǐng)求后應(yīng)用層要執(zhí)行工具并回填結(jié)果。LangChain4j 在 AiServices 內(nèi)建了工具執(zhí)行循環(huán)但我一般會(huì)自己控制這個(gè)循環(huán)因?yàn)槠脚_(tái)需要統(tǒng)一記錄每一次工具調(diào)用的入?yún)?、出參、耗時(shí)和錯(cuò)誤。public ChatResponse runAgentLoop(String userMessage, ListObject tools) { ChatRequest request ChatRequest.builder() .messages(List.of(UserMessage.from(userMessage))) .toolSpecs(Specs.from(tools)) .build(); ToolContext toolContext new ToolContext(); for (int step 0; step 5; step) { ChatResponse response model.chat(request); AiMessage aiMessage response.aiMessage(); if (!aiMessage.hasToolExecutionRequests()) { return response; // 模型不再請(qǐng)求工具正常結(jié)束 } ListToolExecutionRequest requests aiMessage.toolExecutionRequests(); ListToolExecutionResultMessage results new ArrayList(); for (ToolExecutionRequest req : requests) { try (var ignored TimeLimiter.timeout(30, SECONDS)) { String result executeTool(req, tools, toolContext); results.add(new ToolExecutionResultMessage(req, result)); } catch (Exception e) { // 工具失敗必須回填給模型而不是中斷整個(gè)循環(huán) results.add(new ToolExecutionResultMessage(req, 工具執(zhí)行失敗: e.getMessage())); } } request appendResults(request, aiMessage, results); } throw new AgentLoopExceededException(工具調(diào)用超過(guò)5輪已終止); }這個(gè)循環(huán)里三個(gè)參數(shù)按場(chǎng)景調(diào)循環(huán)上限建議 3~5超過(guò)就是業(yè)務(wù)設(shè)計(jì)有問(wèn)題而不是模型能力問(wèn)題單工具超時(shí) 30 秒已經(jīng)偏寬松一般查詢(xún)類(lèi)接口 5 秒就該返回工具失敗信息回填給模型是非常反直覺(jué)但極重要的點(diǎn)——模型看到“工具執(zhí)行失敗合同編號(hào)不存在”會(huì)自己修正參數(shù)再試一次而不是生硬地報(bào)錯(cuò)給用戶(hù)。這里有個(gè)口語(yǔ)經(jīng)驗(yàn)寧可讓模型多問(wèn)一輪也別讓它亂猜答案。3.4 生產(chǎn)環(huán)境給工具加三道鎖工具一旦面向業(yè)務(wù)方開(kāi)放就不能只考慮“能不能跑通”。第一道鎖是冪等控制尤其是寫(xiě)操作工具——?jiǎng)?chuàng)建訂單、發(fā)送通知這類(lèi)工具要支持冪等鍵否則模型在一次循環(huán)里重復(fù)調(diào)用兩次業(yè)務(wù)數(shù)據(jù)就臟了。第二道鎖是范圍校驗(yàn)工具里的參數(shù)不能用默認(rèn)值糊弄數(shù)字范圍、枚舉值、超長(zhǎng)文本都要在 Java 側(cè)做校驗(yàn)不能把校驗(yàn)壓力留給模型。第三道鎖是審計(jì)日志每次工具調(diào)用的入?yún)ⅰ⒊鰠?、耗時(shí)、由哪次會(huì)話(huà)觸發(fā)都要落庫(kù)或者打到獨(dú)立的日志通道里——這不是為了排查問(wèn)題是為了出問(wèn)題時(shí)能向業(yè)務(wù)方交代。4. LangGraph4j 工作流從“自由對(duì)話(huà)”到“可控流程”4.1 為什么有了智能體還需要工作流智能體自由發(fā)揮適合“幫我寫(xiě)一段代碼”這類(lèi)開(kāi)放任務(wù)但業(yè)務(wù)場(chǎng)景里更多是“先查余額再走審批最后發(fā)通知”這種固定流程。自由決策意味著同樣的輸入每次可能走不同的路徑這在 ToB 場(chǎng)景里是災(zāi)難。LangGraph4j 把工作流建模成一張狀態(tài)圖StateGraph節(jié)點(diǎn)是處理單元邊是流轉(zhuǎn)規(guī)則條件邊根據(jù)當(dāng)前狀態(tài)決定下一步走哪個(gè)分支。這樣既保留了 AI 節(jié)點(diǎn)的靈活性又把整體流程定義成了業(yè)務(wù)方可預(yù)期、可審計(jì)的確定性結(jié)構(gòu)。平臺(tái)里 LangGraph4j 的角色很明確作為后端執(zhí)行引擎承接前端可視化畫(huà)布生成的 JSON 工作流定義編譯后執(zhí)行并實(shí)時(shí)上報(bào)節(jié)點(diǎn)狀態(tài)。它和 Reactor 的契合度也不錯(cuò)——每個(gè)節(jié)點(diǎn)返回的狀態(tài)變更天然適合用不可變對(duì)象傳遞。4.2 定義狀態(tài)和節(jié)點(diǎn)最小可跑的 LangGraph4j 流程StateGraphAgentState workflow new StateGraph(AgentState::new); workflow.addNode(planner, new PlannerNode()); workflow.addNode(coder, new CodeGenNode()); workflow.addNode(reviewer, new ReviewNode()); workflow.addNode(finish, new FinishNode()); workflow.setEntryPoint(planner); workflow.addEdge(planner, coder); workflow.addEdge(coder, reviewer); workflow.addConditionalEdge(reviewer, state - state.isApproved() ? finish : coder, Set.of(finish, coder)); CompiledGraphAgentState app workflow.compile();這段代碼里的核心概念就四個(gè)狀態(tài)AgentState、節(jié)點(diǎn)Node、普通邊addEdge和條件邊addConditionalEdge。AgentState 是這個(gè)流程的“黑板上寫(xiě)的東西”——用戶(hù)需求、生成的代碼、評(píng)審意見(jiàn)、循環(huán)次數(shù)都在這個(gè)狀態(tài)對(duì)象里傳遞。常見(jiàn)坑是新手把狀態(tài)設(shè)計(jì)成可變對(duì)象一邊跑一邊改并發(fā)場(chǎng)景下一改就串號(hào)。public class AgentState { private final String userRequirement; private final String generatedCode; private final String reviewComment; private final boolean approved; private final int iterationCount; public AgentState copyWith(String newCode, String newComment, boolean newApproved) { return new AgentState(userRequirement, newCode, newComment, newApproved, iterationCount 1); } }節(jié)點(diǎn)實(shí)現(xiàn)只需要接收當(dāng)前狀態(tài)、返回新?tīng)顟B(tài)。例如 CodeGenNode 拿到 userRequirement 后調(diào)用模型生成代碼生成結(jié)果放進(jìn) copyWith 返回的新?tīng)顟B(tài)里。iterationCount是防止“代碼永遠(yuǎn)評(píng)審不通過(guò)”的保險(xiǎn)絲——ReviewNode 里如果發(fā)現(xiàn) iterationCount 超過(guò) 3直接強(qiáng)制 approved 為 true留一個(gè)明確的人工介入標(biāo)記。4.3 條件邊背后的“意圖識(shí)別”怎么做條件邊是工作流真正復(fù)雜的部分。它會(huì)根據(jù)當(dāng)前狀態(tài)判斷下一步走向這里最常見(jiàn)的設(shè)計(jì)是兩類(lèi)一類(lèi)是規(guī)則判定比如“評(píng)審結(jié)果是否通過(guò)”“金額是否超過(guò)閾值”代碼寫(xiě)死可解釋性強(qiáng)另一類(lèi)是需要模型裁決的比如讓模型判斷“用戶(hù)這個(gè)問(wèn)題是否需要查知識(shí)庫(kù)”這時(shí)候條件邊內(nèi)部就內(nèi)嵌了一次模型調(diào)用。這里的實(shí)現(xiàn)細(xì)節(jié)是模型打分結(jié)果要映射成離散的邊名不要直接用自由文本。常見(jiàn)做法是給模型一個(gè)枚舉讓它輸出一個(gè) JSON 字段String rawVerdict model.generate( 根據(jù)用戶(hù)問(wèn)題判斷是否需要檢索知識(shí)庫(kù)只返回 JSON: {\needSearch\: true/false}); boolean needSearch JsonPath.read(rawVerdict, $.needSearch); return needSearch ? search_kb : direct_answer;4.4 工作流如何被前端可視化編輯JSON 就是橋梁LangGraph4j 的圖定義本質(zhì)上是一張有向圖而前端可視化畫(huà)布編輯的也正是這張圖。平臺(tái)里把工作流定義統(tǒng)一成一個(gè) JSON 結(jié)構(gòu)節(jié)點(diǎn)列表、邊列表、每個(gè)節(jié)點(diǎn)的類(lèi)型和參數(shù)。前端拖拽生成這個(gè) JSON后端解析后動(dòng)態(tài)構(gòu)建 LangGraph4j 實(shí)例。節(jié)點(diǎn)類(lèi)型做三層收斂普通 LLM 節(jié)點(diǎn)填提示詞和模型參數(shù)、工具節(jié)點(diǎn)綁定已注冊(cè)的 Tool、邏輯節(jié)點(diǎn)條件判斷/循環(huán)/聚合。這就帶來(lái)一個(gè)版本問(wèn)題工作流 JSON 結(jié)構(gòu)會(huì)演化必須加 schemaVersion 字段后端做版本遷移。否則線(xiàn)上跑著 20 個(gè)應(yīng)用改了字段格式老的直接編譯失敗。這塊在避坑章節(jié)再展開(kāi)。5. 避坑從本地 Demo 到可用平臺(tái)最容易翻車(chē)的 5 個(gè)問(wèn)題5.1 模型根本不支持 ToolCalling但代碼沒(méi)做降級(jí)現(xiàn)象功能調(diào)試時(shí)工具調(diào)用一直不觸發(fā)或者模型回答里出現(xiàn)一大段 JSON 工具請(qǐng)求文本而不是結(jié)構(gòu)化請(qǐng)求。 原因接入的模型網(wǎng)關(guān)不支持該協(xié)議或者模型名配置到了不帶工具能力的小參數(shù)版本上。 解決在模型接入層做一個(gè)能力探測(cè)請(qǐng)求啟動(dòng)時(shí)用一條固定消息發(fā)起一次 tool call如果返回里沒(méi)有結(jié)構(gòu)化 request就把該模型標(biāo)記為“不支持工具”平臺(tái)側(cè)在智能體配置頁(yè)直接禁用或提示換模型。這比運(yùn)行時(shí)反復(fù)重試靠譜得多。5.2 工作流狀態(tài)對(duì)象設(shè)計(jì)成可變 Map并發(fā)時(shí)狀態(tài)互相覆蓋現(xiàn)象兩個(gè)用戶(hù)同時(shí)觸發(fā)同一個(gè)工作流A 用戶(hù)的評(píng)審意見(jiàn)出現(xiàn)在 B 用戶(hù)的生成代碼里。 原因狀態(tài)類(lèi)里用了共享的 HashMap 存放中間數(shù)據(jù)沒(méi)有做不可變拷貝。 解決強(qiáng)制使用不可變對(duì)象每次節(jié)點(diǎn)返回新?tīng)顟B(tài)實(shí)例如果有大對(duì)象需要傳遞在節(jié)點(diǎn)側(cè)只傳引用 ID具體內(nèi)容存外部存儲(chǔ)避免整個(gè)對(duì)象在每一步都被復(fù)制一次導(dǎo)致內(nèi)存膨脹。5.3 SSE 流式響應(yīng)老是斷流或者首字遲遲不出現(xiàn)象前端 EventSource 收到幾個(gè)字就斷開(kāi)重連后更亂。 原因中間代理層默認(rèn)緩沖了響應(yīng)模型輸出攢到一定量才刷給瀏覽器另外代理超時(shí)時(shí)間太短模型思考時(shí)間長(zhǎng)一點(diǎn)就掐斷了。 解決服務(wù)端設(shè)置Cache-Control: no-cache和X-Accel-Buffering: no響應(yīng)頭從架構(gòu)上繞開(kāi)緩沖同時(shí)定期發(fā)一個(gè)注釋行或空格作為心跳防止空閑超時(shí)斷開(kāi)。5.4 多路召回的結(jié)果反而比單路更差現(xiàn)象做了向量關(guān)鍵詞融合之后檢索質(zhì)量明顯下降最相關(guān)的文檔排在了第五第六位。 原因兩路分?jǐn)?shù)沒(méi)做歸一化就線(xiàn)性加權(quán)向量相似度分?jǐn)?shù)總體偏高把關(guān)鍵詞那路的優(yōu)勢(shì)項(xiàng)全壓下去了。 解決放棄線(xiàn)性加權(quán)改成 RRF 倒數(shù)排名融合關(guān)鍵詞召回和向量召回各自保證 top 范圍里有真相關(guān)文檔再靠 RRF 將其抬上來(lái)。5.5 LangGraph4j 版本 API 變動(dòng)導(dǎo)致升級(jí)翻車(chē)現(xiàn)象升級(jí)小版本后addEdge 方法簽名變了編譯直接報(bào)錯(cuò)。 原因LangGraph4j 還在快速演進(jìn)API 穩(wěn)定性遠(yuǎn)不如 SpringBoot。如果你搜資料跟著老版本示例寫(xiě)半年后很可能跑不起來(lái)。 解決鎖定版本并記錄遷移步驟升級(jí)后先用固定的測(cè)試工作流批量回歸把工作流定義 JSON 和引擎解耦無(wú)論引擎怎么改業(yè)務(wù)方畫(huà)布里的 JSON 不變只需要適配層改解析代碼。6. Vue3 可視化編輯與一鍵部署最小實(shí)現(xiàn)與驗(yàn)收技巧可視化編輯的本質(zhì)是把工作流 JSON 變成看得見(jiàn)的節(jié)點(diǎn)和連線(xiàn)。Vue3 做這件事的核心優(yōu)勢(shì)是 Composition API 配合 reactive/ref 管理畫(huà)布狀態(tài)比 Vue2 時(shí)期用 data 和大對(duì)象操作清晰得多。最小實(shí)現(xiàn)只需要三塊一個(gè)節(jié)點(diǎn)面板可拖出不同類(lèi)型的節(jié)點(diǎn)、一個(gè)畫(huà)布放置和連線(xiàn)、一個(gè)屬性面板編輯選中節(jié)點(diǎn)的參數(shù)const nodes: RefFlowNode[] ref([]) const edges: RefFlowEdge[] ref([]) function addNode(type: string, position: { x: number; y: number }) { nodes.value.push({ id: crypto.randomUUID(), type, // llm | tool | condition position, config: initConfigByType(type), }) } function toWorkflowJson(): WorkflowDefinition { return { schemaVersion: 1, nodes: nodes.value, edges: edges.value, } } function loadWorkflow(json: WorkflowDefinition) { nodes.value reactive(json.nodes) edges.value reactive(json.edges) }這里要提醒一句不要讓畫(huà)布組件直接持有業(yè)務(wù)數(shù)據(jù)。nodes 里存的是“圖的結(jié)構(gòu)”具體的提示詞、模型參數(shù)、工具名都放在每個(gè)節(jié)點(diǎn)的 config 里。一鍵部署的做法是把 toWorkflowJson() 的產(chǎn)物交給后端接口后端將其持久化并構(gòu)建 LangGraph4j 實(shí)例運(yùn)行時(shí)的模型 API Key、知識(shí)庫(kù)連接串全部通過(guò)環(huán)境變量注入工作流 JSON 里不出現(xiàn)任何敏感信息。驗(yàn)收時(shí)我會(huì)固定用 20 個(gè)典型場(chǎng)景跑一遍離線(xiàn)回放對(duì)比每個(gè)節(jié)點(diǎn)的入?yún)⒊鰠⑹欠穹项A(yù)期再放開(kāi)給業(yè)務(wù)方試用。這是我踩出來(lái)的習(xí)慣——以前總覺(jué)得線(xiàn)上能跑就是好后來(lái)一次升級(jí)把評(píng)審節(jié)點(diǎn)跑丟了只能連夜回滾。從那以后每次改工作流引擎我都先過(guò)一遍回放再上線(xiàn)。希望這套路徑和這些坑能幫你少走一段彎路。本文還有配套的精品資源點(diǎn)擊獲取