簡(jiǎn)介基于知識(shí)圖譜和生成式AI的智能食譜推薦系統(tǒng)畢業(yè)設(shè)計(jì)源碼面向計(jì)算機(jī)相關(guān)專業(yè)正在準(zhǔn)備畢設(shè)的學(xué)生及需要項(xiàng)目實(shí)戰(zhàn)練習(xí)的學(xué)習(xí)者。項(xiàng)目以知識(shí)圖譜組織食譜數(shù)據(jù)結(jié)合生成式AI提供智能推薦難度適中適合作為課程設(shè)計(jì)或期末大作業(yè)。壓縮包共42個(gè)文件約681KB其中以19個(gè)tsx、9個(gè)less等前端類型文件為主輔以3個(gè)ts、2個(gè)json配置文件以及main.py、yaml等后端與部署相關(guān)文件結(jié)構(gòu)清晰便于快速定位前端頁(yè)面、組件、布局與后端入口。項(xiàng)目經(jīng)導(dǎo)師指導(dǎo)并通過(guò)評(píng)審得分98分源碼全部本地編譯可運(yùn)行經(jīng)過(guò)嚴(yán)格調(diào)試。目前已有404人學(xué)習(xí)下載適合需要參考完整項(xiàng)目結(jié)構(gòu)、理解知識(shí)圖譜與AI推薦結(jié)合方式或希望直接獲取可運(yùn)行源碼進(jìn)行二次開(kāi)發(fā)的讀者。1. 這個(gè)基于知識(shí)圖譜和生成式AI的智能食譜推薦系統(tǒng)解決的是什么問(wèn)題在各種推薦系統(tǒng)里最容易翻車的場(chǎng)景是用戶說(shuō)“今晚想吃得清淡點(diǎn)蛋白質(zhì)高一點(diǎn)但不能碰花生最好十五分鐘能端上桌”。協(xié)同過(guò)濾在沒(méi)有用戶行為數(shù)據(jù)時(shí)直接失效純標(biāo)簽匹配又答不了這種組合約束。這個(gè)基于知識(shí)圖譜和生成式AI的智能食譜推薦系統(tǒng)就是沖這類需求來(lái)的畢業(yè)設(shè)計(jì)源碼先用圖數(shù)據(jù)庫(kù)把食材、菜譜、營(yíng)養(yǎng)標(biāo)簽、場(chǎng)景之間的關(guān)聯(lián)結(jié)構(gòu)化再把圖查詢召回的結(jié)果交給大模型生成帶理由的推薦文案。項(xiàng)目主干分成 Python 后端、React 前端和知識(shí)圖譜數(shù)據(jù)層源碼本地編譯可運(yùn)行適合計(jì)算機(jī)相關(guān)專業(yè)做畢設(shè)、課程設(shè)計(jì)或期末大作業(yè)有 Web 基礎(chǔ)就能改。2. 知識(shí)圖譜層四類節(jié)點(diǎn)和五條關(guān)系如何把推薦約束變成圖查詢2.1 推薦為什么需要一個(gè)圖結(jié)構(gòu)從冷啟動(dòng)和組合約束說(shuō)起先說(shuō)結(jié)論傳統(tǒng)推薦在這個(gè)場(chǎng)景下的短板不在算法本身而在數(shù)據(jù)表達(dá)。協(xié)同過(guò)濾依賴“用戶—物品”交互記錄新用戶進(jìn)來(lái)沒(méi)有任何行為推薦結(jié)果只能靠全局熱門這就是冷啟動(dòng)問(wèn)題。關(guān)鍵詞標(biāo)簽匹配稍微好一點(diǎn)但它是平面結(jié)構(gòu)回答不了“低卡但要有雞胸肉、還要適合減脂期”這種帶多約束的查詢——標(biāo)簽系統(tǒng)里這些條件只能靠 AND 硬拼拼出來(lái)的結(jié)果往往既不準(zhǔn)也不可解釋。知識(shí)圖譜把“菜譜包含哪些食材”“菜譜打了什么營(yíng)養(yǎng)標(biāo)簽”“菜譜適合什么場(chǎng)景”“哪些食材互相沖突”這些關(guān)系變成圖上的路徑。查詢條件變成一次圖遍歷比如“從雞胸肉食材節(jié)點(diǎn)出發(fā)走到所有菜譜節(jié)點(diǎn)再過(guò)濾掉含花生的路徑”這就是天然的可解釋推薦。后面接大模型時(shí)圖譜已經(jīng)給出了結(jié)構(gòu)化候選集大模型只負(fù)責(zé)潤(rùn)色文案、補(bǔ)充理由而不是憑空生成菜譜這樣既避免了 AI 幻覺(jué)也保住了推薦結(jié)果可控。2.2 節(jié)點(diǎn)與關(guān)系設(shè)計(jì)四類實(shí)體和五條關(guān)系照著建就行這個(gè)系統(tǒng)里我按使用頻率把圖譜設(shè)計(jì)成四類節(jié)點(diǎn)Recipe即菜譜節(jié)點(diǎn)記錄菜名、熱量、烹飪時(shí)間、難度Ingredient食材節(jié)點(diǎn)記錄名稱、分類比如肉類、蔬菜、豆制品NutrientTag營(yíng)養(yǎng)標(biāo)簽節(jié)點(diǎn)比如低卡、高蛋白、少油Scene場(chǎng)景節(jié)點(diǎn)比如減脂期、學(xué)生餐、節(jié)日聚餐。關(guān)系也固定成五條Recipe 指向 Ingredient 的 CONTAINS表示菜譜包含某食材Recipe 指向 NutrientTag 的 HAS_TAG表示菜譜具備某營(yíng)養(yǎng)屬性Recipe 指向 Scene 的 SUIT_FOR表示適合某場(chǎng)景Ingredient 指向自身的 IS_A表示上下級(jí)分類比如“雞胸肉 IS_A 禽肉”Ingredient 之間用 CONFLICT_WITH 表示禁忌沖突比如“花生 CONFLICT_WITH 對(duì)堅(jiān)果過(guò)敏人群”。對(duì)應(yīng)建庫(kù)時(shí)先給節(jié)點(diǎn)字段建唯一約束避免導(dǎo)入重復(fù)數(shù)據(jù)。這里給出初始化結(jié)構(gòu)的 Cypher 語(yǔ)句// 為兩類核心節(jié)點(diǎn)建立唯一約束防止重復(fù)導(dǎo)入 CREATE CONSTRAINT recipe_id IF NOT EXISTS FOR (r:Recipe) REQUIRE r.id IS UNIQUE; CREATE CONSTRAINT ingredient_id IF NOT EXISTS FOR (i:Ingredient) REQUIRE i.id IS UNIQUE; // 建立索引按名稱查食材時(shí)避免全圖掃描 CREATE INDEX ingredient_name IF NOT EXISTS FOR (i:Ingredient) ON (i.name);邏輯說(shuō)明第一段給菜譜和食材的 id 字段建唯一約束這是后續(xù)用 MERGE 做冪等寫入的前提重復(fù)執(zhí)行導(dǎo)入腳本不會(huì)產(chǎn)生雙份數(shù)據(jù)。第二段給食材名稱建索引推薦接口里大量查詢以食材名稱為入口沒(méi)有索引時(shí)節(jié)點(diǎn)多了會(huì)明顯變慢。參數(shù)說(shuō)明約束名 recipe_id、ingredient_id 是自定義的可改成你習(xí)慣的命名REQUIRE 語(yǔ)法要求當(dāng)前圖數(shù)據(jù)庫(kù)版本支持如果用的是老版本需要把約束語(yǔ)法換成 CREATE CONSTRAINT ON (r:Recipe) ASSERT r.id IS UNIQUE 這種舊寫法。2.3 召回查詢一個(gè) Cypher 同時(shí)過(guò)濾熱量、食材與場(chǎng)景圖模型立住以后核心召回邏輯就變成一條 Cypher 查詢。后端拿到用戶輸入“雞胸肉 低卡 減脂期”后把約束翻譯成圖遍歷召回符合條件的菜譜并按熱量升序返回// 召回含雞胸肉、帶低卡標(biāo)簽、適合減脂期的菜譜 MATCH (r:Recipe)-[:CONTAINS]-(i:Ingredient {name: 雞胸肉}) WITH r MATCH (r)-[:HAS_TAG]-(t:NutrientTag {name: 低卡}) MATCH (r)-[:SUIT_FOR]-(s:Scene {name: 減脂期}) RETURN r.name AS recipe_name, r.calories AS calories, r.cook_time AS cook_time ORDER BY r.calories ASC LIMIT 10邏輯說(shuō)明第一段先鎖定包含雞胸肉的菜譜這一步把候選集收窄WITH r 把當(dāng)前結(jié)果傳遞到下一段避免后續(xù) MATCH 產(chǎn)生笛卡爾積膨脹。后面兩段分別校驗(yàn)“低卡”標(biāo)簽和“減脂期”場(chǎng)景三個(gè)條件全部滿足的菜譜才進(jìn)入返回結(jié)果。參數(shù)說(shuō)明name 的值是中文時(shí)注意保證 Neo4j 數(shù)據(jù)庫(kù)存儲(chǔ)編碼為 UTF-8否則匹配不上LIMIT 10 控制召回?cái)?shù)量實(shí)際項(xiàng)目里我建議調(diào)到 20給后面規(guī)則過(guò)濾和 LLM 排序留一些余量。ORDER BY r.calories ASC 是簡(jiǎn)單的熱量升序如果你想優(yōu)先推薦口味更重的菜可以改成按評(píng)分字段降序。2.4 數(shù)據(jù)初始化從 CSV 到圖數(shù)據(jù)庫(kù)的常規(guī)導(dǎo)入路徑這個(gè)項(xiàng)目里的菜譜和食材數(shù)據(jù)量不大常見(jiàn)做法是用 CSV 存放在后端某個(gè) data 目錄里首次啟動(dòng)時(shí)一次性導(dǎo)入。導(dǎo)入腳本長(zhǎng)這樣// 從 CSV 導(dǎo)入食材節(jié)點(diǎn)MERGE 保證重復(fù)執(zhí)行不產(chǎn)生重復(fù)節(jié)點(diǎn) LOAD CSV WITH HEADERS FROM file:///ingredients.csv AS row MERGE (i:Ingredient {id: row.id}) SET i.name row.name, i.category row.category;邏輯說(shuō)明LOAD CSV WITH HEADERS 會(huì)把 CSV 第一行當(dāng)字段名row.id、row.name 對(duì)應(yīng)每一列。MERGE 會(huì)先按 id 查找節(jié)點(diǎn)存在則只更新屬性不存在才創(chuàng)建配合前面建的唯一約束這個(gè)腳本可以反復(fù)執(zhí)行。參數(shù)說(shuō)明file:///ingredients.csv 是相對(duì)路徑文件必須放在圖數(shù)據(jù)庫(kù)安裝目錄的 import 文件夾下否則會(huì)報(bào)找不到文件的錯(cuò)誤。導(dǎo)入中文 CSV 時(shí)我犯過(guò)一個(gè)低級(jí)錯(cuò)誤用 Excel 另存的 CSV 默認(rèn)是 ANSI 編碼進(jìn)圖數(shù)據(jù)庫(kù)后中文全變亂碼解決方法是把文件另存為 UTF-8 編碼或者用 Python 腳本先做一次編碼轉(zhuǎn)換再導(dǎo)入。3. Python 后端main.py 里的混合推薦主鏈路從路由到模型調(diào)用3.1 從入口看整體流程FastAPI 風(fēng)格的路由與中間件打開(kāi) main.py從目錄結(jié)構(gòu)和路由寫法能看出這個(gè)工程用的是 FastAPI 風(fēng)格。整個(gè)后端流程是前端把用戶需求 POST 到 /recommend 接口服務(wù)端先連接圖數(shù)據(jù)庫(kù)做召回再做規(guī)則過(guò)濾最后調(diào)用大模型生成推薦文案。下面這段代碼是這個(gè)工程里最核心的應(yīng)用初始化部分from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from pydantic import BaseModel app FastAPI(titlerecipe-recommender) # 前后端分離開(kāi)發(fā)時(shí)必須配 CORS否則瀏覽器會(huì)攔截請(qǐng)求 app.add_middleware( CORSMiddleware, allow_origins[http://localhost:8000], allow_methods[*], allow_headers[*], ) class RecommendRequest(BaseModel): ingredients: list[str] # 用戶手頭有的食材 max_calories: int 600 # 熱量上限默認(rèn) 600 千卡 tags: list[str] [低卡] # 營(yíng)養(yǎng)標(biāo)簽可多選 scene: str 減脂期 # 場(chǎng)景 avoid_food: list[str] [] # 禁忌食材邏輯說(shuō)明CORSMiddleware 加在應(yīng)用實(shí)例上用于解決前端頁(yè)面在 localhost 不同端口調(diào)用接口時(shí)的跨域攔截問(wèn)題。RecommendRequest 是一個(gè) Pydantic 模型FastAPI 會(huì)自動(dòng)校驗(yàn)請(qǐng)求體結(jié)構(gòu)前端漏傳字段時(shí)用默認(rèn)值兜底避免接口直接報(bào) 422 錯(cuò)誤。參數(shù)說(shuō)明allow_origins 里的地址要寫成前端實(shí)際跑起來(lái)的地址比如前端用 8000 端口這里就放 http://localhost:8000。max_calories、tags、scene 的默認(rèn)值是我按“減脂推薦”這個(gè)典型場(chǎng)景設(shè)置的實(shí)際使用中前端會(huì)顯式傳值覆蓋。avoid_food 是禁忌食材列表對(duì)應(yīng)圖譜里的 CONFLICT_WITH 關(guān)系下面過(guò)濾階段會(huì)用到。3.2 圖召回、規(guī)則過(guò)濾、大模型解讀三段式推薦邏輯推薦主鏈路我習(xí)慣拆成三個(gè)函數(shù)每個(gè)函數(shù)只干一件事出了問(wèn)題也好排查。第一段 graph_recall 負(fù)責(zé)把請(qǐng)求參數(shù)拼成 Cypher 查詢執(zhí)行并返回候選菜譜第二段 rule_filter 負(fù)責(zé)把候選里含禁忌食材的菜譜剔除掉順帶做去重第三段 llm_interpret 把結(jié)構(gòu)化候選交給大模型生成帶理由的推薦文案。def recommend(req: RecommendRequest): # 第一步按請(qǐng)求參數(shù)查知識(shí)圖譜召回候選菜譜 candidates graph_recall(req) # 第二步剔除含禁忌食材的菜譜并做基礎(chǔ)去重 filtered rule_filter(candidates, req.avoid_food) # 第三步調(diào)用大模型把結(jié)構(gòu)化候選轉(zhuǎn)成推薦文案 result llm_interpret(filtered, req) return {items: result}邏輯說(shuō)明候選人少時(shí)rule_filter 里直接用 Python 集合操作判斷菜譜包含的食材是否和 avoid_food 有交集即可不需要再查圖。llm_interpret 放在最后一步是因?yàn)榇竽Ｐ驼{(diào)用耗時(shí)且可能失敗先盡量把候選集縮到最小再調(diào)用能顯著降低超時(shí)概率和調(diào)用成本。參數(shù)說(shuō)明graph_recall 內(nèi)部把 req.ingredients 里的食材名稱用參數(shù)化查詢拼進(jìn) Cypher避免字符串拼接注入風(fēng)險(xiǎn)。rule_filter 注意保留原始順序因?yàn)閳D查詢結(jié)果已經(jīng)是按熱量排好序的過(guò)濾后如果重新排序會(huì)丟失這一層優(yōu)先級(jí)。3.3 大模型調(diào)用封裝temperature、timeout 和降級(jí)策略大模型在這個(gè)系統(tǒng)里的定位不是生成菜譜而是把圖譜召回結(jié)果“翻譯”成用戶能直接看的推薦理由。所以 prompt 里要明確告訴模型只能基于給定菜譜列表回答不要自己編新菜。下面這段是這類調(diào)用比較穩(wěn)的封裝方式import requests def call_llm(prompt: str) - str: resp requests.post( LLM_ENDPOINT, headers{Authorization: fBearer {LLM_API_KEY}}, json{ model: LLM_MODEL, messages: [{role: user, content: prompt}], temperature: 0.3, max_tokens: 800, }, timeout20, ) resp.raise_for_status() return resp.json()[choices][0][message][content] def llm_interpret(candidates, req): if not candidates: return {message: 沒(méi)有找到匹配的菜譜, items: []} try: prompt build_prompt(candidates, req) content call_llm(prompt) return parse_llm_reply(content) except Exception: # 大模型掛了也不讓接口掛降級(jí)返回結(jié)構(gòu)化候選 return {items: candidates[:3], source: graph_fallback}邏輯說(shuō)明call_llm 把 prompt 和參數(shù)包成 POST 請(qǐng)求拿到響應(yīng)后只取 choices 里的文本內(nèi)容。llm_interpret 里 try 包裹整個(gè)調(diào)用過(guò)程任何異常都走降級(jí)分支直接返回圖譜候選保證接口始終有響應(yīng)不會(huì)因?yàn)橥獠糠?wù)不穩(wěn)定而整體不可用。參數(shù)說(shuō)明temperature 設(shè)為 0.3是為了讓模型在“基于事實(shí)改寫”時(shí)少發(fā)散數(shù)值越高越容易發(fā)揮但越容易偏離候選菜譜。max_tokens 限制回復(fù)長(zhǎng)度按 800 夠輸出三四條帶理由的推薦了。timeout 設(shè) 20 秒是這個(gè)場(chǎng)景的臨界值低于 10 秒在模型服務(wù)忙時(shí)基本必超時(shí)高于 30 秒會(huì)讓前端等到失去耐心。3.4 配置管理密鑰、數(shù)據(jù)庫(kù)連接串不要寫進(jìn)倉(cāng)庫(kù)這個(gè)項(xiàng)目運(yùn)行時(shí)需要兩類敏感配置大模型 API 密鑰和圖數(shù)據(jù)庫(kù)連接信息。常見(jiàn)做法是單獨(dú)建一個(gè) config.py從環(huán)境變量讀取而不是把真實(shí)密鑰硬編碼進(jìn) main.py。我見(jiàn)過(guò)太多臨時(shí)畢設(shè)項(xiàng)目把密鑰寫死在代碼里最后打包發(fā)布時(shí)跟著源碼一起泄露。import os LLM_ENDPOINT os.getenv(LLM_ENDPOINT, ) LLM_API_KEY os.getenv(LLM_API_KEY, ) LLM_MODEL os.getenv(LLM_MODEL, default-model) NEO4J_URI os.getenv(NEO4J_URI, bolt://localhost:7687) NEO4J_USER os.getenv(NEO4J_USER, neo4j) NEO4J_PASSWORD os.getenv(NEO4J_PASSWORD, )邏輯說(shuō)明每個(gè)變量用 os.getenv 讀取帶默認(rèn)值的適合本地開(kāi)發(fā)比如數(shù)據(jù)庫(kù)地址默認(rèn)連本機(jī)不帶默認(rèn)值的強(qiáng)制要求環(huán)境變量存在缺失時(shí)啟動(dòng)階段就應(yīng)該拋錯(cuò)提醒。這個(gè)文件本身建議寫進(jìn) .gitignore。參數(shù)說(shuō)明NEO4J_URI 默認(rèn) bolt://localhost:7687這是圖數(shù)據(jù)庫(kù)的 Bolt 協(xié)議端口注意不要和瀏覽器訪問(wèn)用的 7474 端口混淆Python 驅(qū)動(dòng)用的是前者。LLM_MODEL 里的默認(rèn)值按你實(shí)際接的模型服務(wù)商文檔填不同廠商的模型標(biāo)識(shí)符差異很大。4. React 前端food-react-master 的工程結(jié)構(gòu)、啟動(dòng)與聯(lián)調(diào)4.1 前端頁(yè)面與組件職責(zé)從 pages 到 common 的目錄分工前端部分是一個(gè)標(biāo)準(zhǔn)的 umi 工程目錄結(jié)構(gòu)里 src 下面分了 pages、components、assets、layouts、common 幾類。pages 是頁(yè)面級(jí)路由組件components 放在頁(yè)面里復(fù)用的業(yè)務(wù)組件layouts 是整體布局common 主要放請(qǐng)求封裝、常量定義這類跨頁(yè)面共享的邏輯。按這個(gè)工程實(shí)際頁(yè)面來(lái)對(duì)我判斷至少有四類頁(yè)面首頁(yè)展示推薦入口和菜品卡片流推薦結(jié)果頁(yè)展示后端返回的菜譜列表和推薦理由知識(shí)圖譜可視化頁(yè)用關(guān)系圖組件展示食材和菜譜的關(guān)聯(lián)結(jié)構(gòu)AI 對(duì)話頁(yè)用戶輸入需求后端返回生成式文案。組件層面會(huì)拆出菜譜卡片、食材標(biāo)簽選擇器、搜索框、加載狀態(tài)這幾個(gè)高頻復(fù)用件。4.2 pnpm 安裝與啟動(dòng)一次跑通的命令序列項(xiàng)目里帶 pnpm-lock.yaml說(shuō)明依賴管理用的是 pnpm不是 npm。新機(jī)器上第一次跑命令順序和版本匹配是兩個(gè)最容易踩坑的點(diǎn)。按下面順序來(lái)通常能直接跑通# 進(jìn)入前端工程目錄 cd food-react-master # 安裝依賴使用 lock 文件鎖定版本 pnpm install # 啟動(dòng)開(kāi)發(fā)服務(wù)器 pnpm start邏輯說(shuō)明pnpm install 嚴(yán)格按 pnpm-lock.yaml 解析依賴版本同一個(gè) lock 文件在不同機(jī)器上裝出來(lái)的依賴樹(shù)是一致的這是保證“本地編譯可運(yùn)行”的關(guān)鍵。pnpm start 會(huì)讀取 .umirc.ts 里的配置默認(rèn)起一個(gè)開(kāi)發(fā)服務(wù)器并監(jiān)聽(tīng)代理轉(zhuǎn)發(fā)規(guī)則。參數(shù)說(shuō)明如果本機(jī)沒(méi)裝 pnpm先通過(guò)系統(tǒng)包管理器或 Node 自帶的 corepack 啟用啟動(dòng)前檢查 Node 版本和工程開(kāi)發(fā)時(shí)用的版本差異過(guò)大時(shí)pnpm install 可能會(huì)因?yàn)槟承┰蕾嚲幾g失敗而報(bào)錯(cuò)。另外注意不要直接刪掉 pnpm-lock.yaml 改成 npm install這會(huì)把依賴樹(shù)整個(gè)打散容易觸發(fā)版本不兼容。4.3 請(qǐng)求封裝與跨域代理前端怎么和后端連通前后端分離開(kāi)發(fā)時(shí)最省事的連通方式不是在后端配 CORS而是在前端開(kāi)發(fā)服務(wù)器里配代理。.umirc.ts 里通常有一段 proxy 配置把前端發(fā)出的 /api 請(qǐng)求轉(zhuǎn)發(fā)到后端地址export default { npmClient: pnpm, proxy: { /api: { target: http://127.0.0.1:8000, changeOrigin: true, }, }, };邏輯說(shuō)明開(kāi)發(fā)服務(wù)器收到路徑以 /api 開(kāi)頭的請(qǐng)求時(shí)會(huì)轉(zhuǎn)發(fā)到 target 指定的 8000 端口。這樣瀏覽器里頁(yè)面請(qǐng)求的同源地址實(shí)際上被開(kāi)發(fā)服務(wù)器代理到了后端天然繞開(kāi)跨域限制。參數(shù)說(shuō)明target 要寫后端實(shí)際監(jiān)聽(tīng)地址如果后端跑在別的機(jī)器上就改成對(duì)應(yīng) IPchangeOrigin 設(shè)為 true 后后端收到請(qǐng)求時(shí)的 Host 頭會(huì)是 target 地址否則某些框架會(huì)因 Host 校驗(yàn)拒絕請(qǐng)求。上線時(shí)這段代理配置不再生效需要由部署端 Web 服務(wù)器統(tǒng)一做反向代理。請(qǐng)求調(diào)用的封裝通常放在 common 目錄統(tǒng)一走 umi 自帶的 request 方法import { request } from umi; // 把后端 /recommend 接口封裝成可復(fù)用函數(shù) export async function fetchRecommend(params: RecommendParams) { return request(/api/recommend, { method: POST, data: params, }); }邏輯說(shuō)明umi 的 request 自動(dòng)帶上 JSON 序列化和 Content-Type 頭頁(yè)面組件里只需要調(diào) fetchRecommend 拿到 Promise。返回體結(jié)構(gòu)要和后端保持一致推薦接口的返回是 { items: [...] }頁(yè)面拿到 items 后渲染成菜譜卡片列表。參數(shù)說(shuō)明params 是調(diào)用方傳入的對(duì)象對(duì)應(yīng)后端 RecommendRequest 的字段名建議和 Python 側(cè)的字段保持完全一致比如 ingredients、max_calories否則后端解析會(huì)得到空值或報(bào) 422。4.4 知識(shí)圖譜可視化與 AI 對(duì)話頁(yè)的數(shù)據(jù)流圖譜可視化頁(yè)不是重點(diǎn)功能但做好了答辯效果會(huì)好看不少。數(shù)據(jù)通常來(lái)自后端一個(gè)只讀接口返回圖譜的節(jié)點(diǎn)和關(guān)系數(shù)組前端用關(guān)系圖組件渲染。數(shù)據(jù)流是頁(yè)面加載時(shí) GET /graph 拿到 { nodes: [...], links: [...] }傳給圖表組件生成力導(dǎo)向圖。注意數(shù)據(jù)量知識(shí)圖譜節(jié)點(diǎn)幾百個(gè)時(shí)問(wèn)題不大幾千個(gè)時(shí)瀏覽器會(huì)明顯卡頓此時(shí)后端要做節(jié)點(diǎn)數(shù)截?cái)?。AI 對(duì)話頁(yè)的數(shù)據(jù)流稍有不同用戶輸入一句話前端 POST 到 /recommend 或單獨(dú)的 /chat 接口后端查圖拿到候選后交給大模型返回的文案帶流式效果。如果沒(méi)有實(shí)現(xiàn)流式輸出可以退而求其次把大模型響應(yīng)整個(gè)拿回來(lái)后一次性渲染交互略笨但功能完整。5. 避坑記錄安裝、圖數(shù)據(jù)與接口聯(lián)調(diào)的 5 個(gè)典型翻車點(diǎn)5.1 依賴安裝與版本類現(xiàn)象前端目錄執(zhí)行 pnpm install中途報(bào)錯(cuò) panic或者裝完以后 pnpm start 直接白屏控制臺(tái)一堆模塊找不到。原因大多數(shù)情況是本機(jī) Node 版本和工程開(kāi)發(fā)時(shí)期的主版本不一致。pnpm-lock.yaml 里鎖了部分依賴的安裝包版本但 Node 運(yùn)行時(shí)的原生模塊需要重新編譯版本差異大就編譯失敗。解決先看 package.json 里的 engines 字段或 README 里是否標(biāo)注了兼容 Node 版本沒(méi)有標(biāo)注就查看 lock 文件首部的 lockfileVersion 判斷年代把本機(jī) Node 切到該時(shí)代的主流版本區(qū)間。切換版本用 nvm 這類版本管理工具最省事裝好以后重新跑 pnpm install不要在原報(bào)錯(cuò)目錄上反復(fù)重試。5.2 數(shù)據(jù)庫(kù)連接類現(xiàn)象后端啟動(dòng)時(shí)報(bào)連接失敗提示 localhost 對(duì)應(yīng)端口沒(méi)有服務(wù)監(jiān)聽(tīng)或認(rèn)證失敗無(wú)法連接數(shù)據(jù)庫(kù)。原因兩個(gè)端口容易搞混——圖數(shù)據(jù)庫(kù)的瀏覽器界面走 HTTP 端口 7474Python 驅(qū)動(dòng)連的是 Bolt 端口 7687。后端配置里寫的是 bolt 端口但有人用瀏覽器先打開(kāi)了 7474 確認(rèn)服務(wù)在跑后端卻還是連不上另一種情況是數(shù)據(jù)庫(kù)服務(wù)壓根沒(méi)啟動(dòng)或密碼和 Neo4j 安裝時(shí)設(shè)置的不一致。解決先用瀏覽器訪問(wèn) 7474 端口確認(rèn)數(shù)據(jù)庫(kù)面板能打開(kāi)再用命令行或 Python 腳本測(cè)試 7687 端口通不通。認(rèn)證錯(cuò)誤時(shí)到數(shù)據(jù)庫(kù)配置文件里臨時(shí)改回初始密碼或者通過(guò)命令行工具執(zhí)行重置密碼語(yǔ)句。最保險(xiǎn)的做法是把 NEO4J_PASSWORD 配置通過(guò)環(huán)境變量傳入別寫死在 config.py 里。5.3 食材名稱匹配不上現(xiàn)象接口返回空列表但明明圖數(shù)據(jù)庫(kù)里有這道菜直接在圖查詢工具里執(zhí)行同樣的 Cypher 卻查得到。原因中文名稱匹配不上基本都是編碼或字段值不一致。最常見(jiàn)的是導(dǎo)入 CSV 時(shí)編碼不是 UTF-8圖數(shù)據(jù)庫(kù)里存的是亂碼其次是查詢參數(shù)里帶空格比如“雞胸肉 ”和“雞胸肉”不匹配還有一種情況是導(dǎo)入時(shí)某個(gè)食材把“雞胸肉”寫成了“雞小胸”名稱字段不統(tǒng)一。解決把導(dǎo)入用的 CSV 全部轉(zhuǎn)成 UTF-8 編碼再導(dǎo)入在查詢前對(duì)請(qǐng)求參數(shù)做 strip 去空格名稱統(tǒng)一問(wèn)題先在項(xiàng)目里建一個(gè)食材別名映射表把“雞小胸”“雞里脊”這類近似食材映射到標(biāo)準(zhǔn)名再進(jìn)圖查詢。5.4 大模型接口超時(shí)導(dǎo)致推薦失敗現(xiàn)象前端點(diǎn)推薦按鈕后轉(zhuǎn)圈幾十秒最后接口報(bào)錯(cuò)頁(yè)面彈網(wǎng)絡(luò)錯(cuò)誤后端日志顯示 requests.post 一直卡住直到拋異常。原因大模型服務(wù)響應(yīng)慢是常態(tài)尤其在調(diào)用高峰時(shí)段。沒(méi)設(shè) timeout 時(shí)requests 庫(kù)默認(rèn)會(huì)一直等到底層 TCP 超時(shí)用戶體驗(yàn)就是白等。更隱蔽的問(wèn)題是重試機(jī)制缺失一次偶發(fā)超時(shí)就直接讓整個(gè)推薦鏈路失敗而圖召回階段的結(jié)果本來(lái)是可用的。解決調(diào)用層統(tǒng)一加 timeout并且把重試邏輯做成兩層——第一層針對(duì)連接錯(cuò)誤快速重試一次第二層在最終失敗時(shí)走降級(jí)直接返回圖譜候選集。這樣即使大模型完全不可用推薦功能也只是少了文案不會(huì)整體崩潰。5.5 跨域與請(qǐng)求路徑不一致現(xiàn)象前端頁(yè)面能打開(kāi)但所有推薦請(qǐng)求都報(bào) CORS error 或 404。CORS error 說(shuō)明請(qǐng)求發(fā)出去了但響應(yīng)被瀏覽器攔截404 說(shuō)明請(qǐng)求路徑和后端路由對(duì)不上。原因CORS error 通常是后端中間件沒(méi)配或 allow_origins 沒(méi)包含前端地址404 大部分是代理配置里前端發(fā) /api/recommend后端路由卻定義在 /recommend代理沒(méi)有做路徑重寫。解決路徑不一致時(shí)在代理配置里加一層路徑重寫把 /api 前綴剝掉再轉(zhuǎn)發(fā)或者在 FastAPI 側(cè)把路由統(tǒng)一加 /api 前綴。兩種做法選一種但前后端要約定一致不要出現(xiàn)前端發(fā) /api/recommend、后端只接受 /recommend 的割裂狀態(tài)。6. 驗(yàn)證推薦質(zhì)量用一份需求清單把系統(tǒng)調(diào)到能答辯的狀態(tài)系統(tǒng)跑通只是第一步推薦質(zhì)量才是答辯時(shí)被追問(wèn)的重點(diǎn)。我習(xí)慣在項(xiàng)目里維護(hù)一份“需求清單”包含 5 類典型用戶需求低卡減脂、高蛋白增肌、少油清淡、不吃某類食材、節(jié)日聚餐。每輪改完推薦邏輯后不用人工去頁(yè)面點(diǎn)直接用 curl 把清單里的需求逐條打進(jìn)接口看返回結(jié)果是否符合硬約束curl -X POST http://127.0.0.1:8000/recommend \ -H Content-Type: application/json \ -d {ingredients:[雞胸肉],max_calories:600,tags:[低卡],scene:減脂期,avoid_food:[花生]}判斷返回結(jié)果時(shí)我只看三件事硬約束有沒(méi)有違反比如含花生卻被推薦排序是否符合用戶預(yù)期低卡需求下熱量低的排前面生成的推薦理由是不是從候選菜譜事實(shí)出發(fā)有沒(méi)有出現(xiàn)模型憑空編造的菜名。三條都滿足這一輪調(diào)優(yōu)就算過(guò)了。這類“清單自測(cè)”適合開(kāi)發(fā)期反復(fù)執(zhí)行比頁(yè)面點(diǎn)點(diǎn)點(diǎn)快得多。真正答辯前再補(bǔ)一次鏈路走查啟動(dòng)后端確認(rèn)圖數(shù)據(jù)庫(kù)服務(wù)在跑再啟動(dòng)前端從頁(yè)面完成一次完整推薦。后端日志里重點(diǎn)看兩個(gè)指標(biāo)Cypher 查詢執(zhí)行時(shí)間是否在百毫秒級(jí)大模型調(diào)用是否穩(wěn)定。太慢就檢查圖譜數(shù)據(jù)量是否過(guò)大或查詢是否沒(méi)有走索引。這套代碼本身已經(jīng)把三種關(guān)鍵技術(shù)串起來(lái)了知識(shí)圖譜保證推薦可解釋可約束生成式 AI 保證推薦文案像真人寫的前后端分離方便各部分單獨(dú)調(diào)試。如果你想在畢設(shè)里加點(diǎn)差異化改進(jìn)我建議優(yōu)先做一層緩存把相同查詢參數(shù)的推薦結(jié)果緩存幾分鐘圖查詢和大模型調(diào)用都省了系統(tǒng)響應(yīng)速度會(huì)有一個(gè)明顯提升——這個(gè)改動(dòng)要?jiǎng)拥牡胤讲欢嗪蠖送扑]函數(shù)外面包一層緩存邏輯就行。這項(xiàng)目我先后跑過(guò)兩遍第一遍就是沒(méi)注意 Node 版本卡在前端白屏上大半天第二遍老老實(shí)實(shí)按清單先檢查環(huán)境再啟動(dòng)半小時(shí)就跑通了全部鏈路。從那以后我每次拿到新源碼都強(qiáng)制先看一眼 lock 文件、再確認(rèn)數(shù)據(jù)庫(kù)服務(wù)狀態(tài)才動(dòng)手執(zhí)行任何安裝命令。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取