1. 項目前言從“AI聊天”到“AI會按圖索驥”做 RAG 的朋友應該都有同感純向量檢索的方案搞個知識庫 Demo 很容易但一上生產就露餡。用戶問“宮保雞丁和魚香肉絲有什么區別”向量檢索返回的是兩篇高度相似的菜譜片段LLM 對著拼湊出來的上下文要么答非所問要么直接編造步驟。這個問題的根子在于傳統 RAG 把知識庫當成了一袋子文檔碎片丟失了實體之間的關系。而烹飪這個場景恰恰是關系密集型知識的典型代表——食材、菜品、技法、菜系、口味之間有著清晰的層級和關聯。比如“魚香肉絲”依賴“魚香汁”“魚香汁”又依賴“泡椒”“泡椒”屬于“川菜調料”。這種知識結構用文檔切片去表達天然就是錯的。所以我做了這個基于圖 RAG的烹飪問答系統核心思路很簡單用Neo4j把菜譜領域知識建模成圖用Milvus做食材描述和自由文本的向量召回再用LLM做意圖識別和答案組織。三個組件各司其職把“知識圖譜的結構化推理能力”和“向量檢索的語義泛化能力”結合起來實測下來回答質量和可解釋性都遠超純向量方案。這篇文章會把整個項目的完整工程實踐寫下來從架構設計到環境搭建從數據建模到混合檢索再到 LLM 的編排和常見問題排查全部是實操向的內容。適合正在做 RAG 應用、或者想了解圖數據庫和向量數據庫如何協同工作的朋友尤其是遇到“純向量檢索答非所問”、“知識庫關系密集”這類問題的場景這篇文章應該能給你一個具體可落地的參考方案。2. 整體架構設計為什么是 Neo4j Milvus LLM 三件套2.1 解構需求烹飪問答到底難在哪先花點篇幅聊聊這個項目的需求拆解因為架構選擇的依據全部來自業務場景本身。烹飪問答系統表面上的需求是“用戶問菜譜系統答菜譜”但實際用戶的問題類型差別很大。我整理了一下大概能分成四類第一類是事實查詢型比如“魚香肉絲需要哪些食材”這類問題答案相對固定關鍵詞匹配就能定位。第二類是關系推理型比如“川菜里有哪些菜用了花生”這就需要在菜系、菜品、食材之間做多跳關聯查詢。第三類是泛化語義型比如“我想吃點清爽的葷菜”這沒有明確實體必須靠語義理解來匹配食材屬性和菜品標簽。第四類是約束排除型比如“有沒有不用油炸的雞胸肉做法”這類問題帶有排除條件需要把“不包含某技法”作為硬約束。如果只用向量檢索第一類和第三類還能對付第二類基本無能為力第四類效果也很差。如果只用圖譜查詢第三類直接沒法處理因為用戶輸入里根本沒有實體可以匹配。所以混合架構不是炫技而是業務需求逼出來的。2.2 組件選型三個數據庫為什么是它們先說 Neo4j。圖數據庫領域 Neo4j 是事實標準Cypher 查詢語言表達能力很強社區版就能滿足項目需要。選擇圖數據庫的核心原因是烹飪知識天然是圖結構菜品節點連接食材節點技法節點連接菜品節點菜系節點歸類菜品節點。用圖來存查詢“回鍋肉用了什么豆瓣醬”、“哪些菜用到郫縣豆瓣”就是一個簡單的路徑查詢不用做多表 JOIN。再說 Milvus。向量數據庫里 Milvus 是開源方案里最成熟的之一支持多種索引類型社區活躍而且有 Attu 這個可視化工具調試起來方便。它負責的是“語義模糊匹配”這部分——用戶說“清爽”系統要能召回“涼拌”、“清蒸”、“低油”相關的菜品。最后是 LLM。這里 LLM 扮演的是編排者的角色不是知識來源。它接收用戶的自然語言問題判斷應該走圖譜查詢、向量召回還是兩者并行然后把結果組織成自然語言答案。我用的是 OpenAI 兼容接口的模型具體模型名不影響架構只要支持函數調用或工具調用就行。注意這個架構里 LLM 和知識庫的分工要非常清楚——LLM 負責理解和表達知識庫負責事實。如果把 LLM 既當編排器又當知識源那就不需要圖數據庫和向量數據庫了但那樣做出來的系統幻覺問題會很嚴重。2.3 系統流程一次問答背后的數據流轉整個系統的工作流程可以拆成六個步驟我在這里先給個總體預覽后續章節會逐個展開第一步用戶輸入問題LLM 先做一輪意圖識別和實體抽取。第二步系統根據抽取結果決定檢索策略有明確實體就走圖譜查詢分支有模糊描述就走向量召回分支兩者都有就并行執行。第三步圖譜查詢結果經過后處理轉成 LLM 能理解的文本片段。第四步Milvus 召回結果與圖譜結果做融合排序過濾掉低相關度的片段。第五步所有候選上下文拼裝成 Prompt交給 LLM 生成答案。第六步答案經過格式化和引用標注展示給用戶。這個流程的巧妙之處在于檢索階段是規則的、可解釋的生成階段是靈活的、自然的。規則的歸規則語義的歸語義各管一段互不干擾出現問題也好排查。3. 環境搭建Neo4j 和 Milvus 的安裝避坑指南3.1 Neo4j 安裝與配置Windows 和 Docker 兩條路這個項目里 Neo4j 是知識圖譜的存儲引擎安裝方式取決于你的開發環境。我自己用的是 Docker 方式但不少朋友在 Windows 上折騰過原生安裝這里兩條路都說一下。如果本機已經裝了 Docker推薦直接用容器跑干凈且好卸載。一條命令就能起一個帶數據卷的 Neo4j 實例docker run -d \ --name neo4j-cooking \ -p 7474:7474 -p 7687:7687 \ -e NEO4J_AUTHneo4j/yourpassword \ -v $PWD/neo4j-data:/data \ neo4j:5.20-community這里端口說明一下7474 是瀏覽器端的 Neo4j Browser 訪問端口7687 是 Bolt 協議端口Python 驅動連的是 7687。數據卷一定要掛載否則容器刪了數據就全沒了這個坑我踩過一次重新導入圖譜的滋味不好受。Windows 上不依賴 Docker 的話可以去 Neo4j 官網下載 Desktop 版或社區版 zip 包。Desktop 版帶圖形界面新建數據庫很方便適合新手。zip 社區版要自己配環境變量把NEO4J_HOME指到解壓目錄然后進 bin 目錄執行neo4j console前臺啟動首次啟動會自動初始化。配置方面有兩個點值得特別注意第一如果要用 Python 或 Java 驅動遠程連接記得修改neo4j.conf里的監聽地址。默認只監聽 localhost需要改成server.default_listen_address0.0.0.0才能被容器外的程序訪問。第二社區版最多打開一個數據庫Enterprise 版才支持多庫。做實驗的話 Community 版完全夠用不用糾結企業版的功能差異。3.2 Milvus 安裝非 Docker 部署和 etcd 依賴處理Milvus 的安裝是大多數人的痛點因為官方主推 Docker Compose 方式對純本機開發環境不太友好。我推薦兩個方案方案一Docker Compose 單機版這是官方推薦的快速開始方式。下載milvus.yaml和docker-compose.yml執行docker compose up -d即可。它會同時啟動三個容器etcd元數據存儲、MinIO對象存儲和 Milvus 主服務。注意這里etcd 是 Milvus 的元數據存儲不是可選項很多人以為只裝 Milvus 一個容器就行結果啟動后報錯找不到 etcd其實是因為 Compose 文件里沒有把 trio 一起拉起來。方案二Windows 非 Docker 安裝。Milvus 官方其實不提供 Windows 原生二進制包非要在 Windows 裸機跑只能靠 WSL2。在 WSL2 里裝 Ubuntu 子系統然后在子系統內按照 Linux 方式安裝。這個過程有點折騰我的建議是開發階段直接用 Docker 方案最省心生產環境一般也是 K8s 或物理機部署Windows 原生安裝意義不大。裝好之后強烈建議再裝一個Attu這是 Milvus 的圖形化管理工具。Attu 是獨立容器連接到 Milvus 的 19530 端口即可docker run -d \ -p 8000:3000 \ -e MILVUS_URLhost.docker.internal:19530 \ zilliz/attu:latest打開http://localhost:8000就能在瀏覽器里查看 collection、向量檢索結果。調試階段有沒有可視化工具效率完全是兩回事。版本兼容性提示Attu 對 Milvus 版本有一點挑剔。我用的是 Milvus 2.4.x Attu 2.4.x 的組合如果你用的是 Milvus 2.3 或 2.5盡量選擇相同大版本的 Attu避免出現“能連接但看不到數據”這種詭異問題。3.3 Python 依賴 langchain4j-milvus 的替代方案熱詞里出現了langchain4j-milvus這里多說一句。langchain4j 是 Java 生態的 LangChain 移植版如果你用 Java 寫服務它確實提供了 Milvus 的集成包。但大多數做算法原型的人用的是 Python對應的是pymilvus這個官方 Python SDK。我的項目里用的是 Python 技術棧核心依賴如下# 向量數據庫相關 pip install pymilvus2.4.9 # 圖數據庫相關 pip install neo4j5.20.0 # LLM 調用相關 pip install openai1.35.0 # 數據處理相關 pip install pandas numpy版本號是我實測過的組合不做強制要求但建議大版本不要差太多。pymilvus2.4.x 連接 2.4 的 Milvus 服務端沒問題如果裝了最新 2.5 的 SDK 去連 2.3 的服務端可能出現 proto 協議不兼容的報錯遇到就降版本。4. 數據建模把烹飪知識變成圖結構4.1 實體和關系的設計菜品、食材、技法、菜系圖譜建模是整個項目里最核心的環節建模的好壞直接決定后續查詢能做什么、不能做什么。我先列出這個項目用的實體類型和關系類型再解釋為什么這樣設計。節點類型標簽一共六類Dish菜品核心實體如“宮保雞丁”、“麻婆豆腐”Ingredient食材如“雞胸肉”、“花生米”Technique技法如“炒”、“炸”、“蒸”、“涼拌”Cuisine菜系如“川菜”、“粵菜”、“魯菜”Flavor口味如“麻辣”、“酸甜”、“清淡”Seasoning調料如“郫縣豆瓣醬”、“生抽”、“料酒”關系類型一共八類(Dish)-[:HAS_INGREDIENT {amount: 200g, optional: false}]-(Ingredient)(Dish)-[:USES_TECHNIQUE]-(Technique)(Dish)-[:BELONGS_TO]-(Cuisine)(Dish)-[:HAS_FLAVOR]-(Flavor)(Dish)-[:USES_SEASONING]-(Seasoning)(Ingredient)-[:IS_A]-(IngredientCategory)如“雞胸肉”屬于“禽肉類”(Seasoning)-[:COMPOSES]-(Seasoning)如“魚香汁”由“泡椒、糖、醋”組成(Dish)-[:SIMILAR_TO]-(Dish)菜品相似關系用于推薦這里有兩個設計上的細節值得展開講。第一個是關于食材的量化和可選性。我在HAS_INGREDIENT關系上掛了屬性amount和optional因為用戶經常問“宮保雞丁要不要放糖”“哪些食材可以不放”。如果不把屬性放在關系上而是放在食材節點上語義就是錯的——同一個食材在不同菜品里的用量不同“花生米”在宮保雞丁里是主料在別的菜里可能是 garnish。第二個是關于技法的層級化。技法節點之間我設計了SUB_TECHNIQUE_OF關系例如“干煸”是“炒”的子技法“清蒸”是“蒸”的子技法。這樣用戶問“不用炒的雞肉做法”圖譜查詢可以做子技法排除不至于把“干煸雞”這類菜也算進去。4.2 Cypher 批量導入從結構化數據到圖譜建模設計好之后面臨的問題就是數據怎么進 Neo4j。菜譜數據以結構化表格形式存在CSV 或 JSON導入方式我推薦用 Cypher 的LOAD CSV語句或者批量 MERGE。以菜品和食材的關系為例CSV 數據格式如下dish_name,ingredient_name,amount,optional,cuisine,technique 宮保雞丁,雞胸肉,200g,false,川菜,炒 宮保雞丁,花生米,50g,false,川菜,炒 宮保雞丁,干辣椒,10g,false,川菜,炒 魚香肉絲,豬里脊,200g,false,川菜,炒導入時先創建節點再創建關系分兩步走// 第一步導入菜品節點和食材節點MERGE 去重 LOAD CSV WITH HEADERS FROM file:///dishes.csv AS row MERGE (d:Dish {name: row.dish_name}) MERGE (i:Ingredient {name: row.ingredient_name}) MERGE (c:Cuisine {name: row.cuisine}) MERGE (t:Technique {name: row.technique}); // 第二步創建關系 LOAD CSV WITH HEADERS FROM file:///dishes.csv AS row MATCH (d:Dish {name: row.dish_name}) MATCH (i:Ingredient {name: row.ingredient_name}) MERGE (d)-[:HAS_INGREDIENT {amount: row.amount, optional: row.optional}]-(i);這里必須提醒一個常見問題file:///指向的是 Neo4j 服務器所在機器的import目錄不是你的本地目錄。Docker 方式部署時要把 CSV 文件掛載到容器的/var/lib/neo4j/import下否則LOAD CSV會報文件不存在。另外導入時一定要用MERGE而不是CREATE。我第一版用的是CREATE跑完發現一個菜品出現了十幾條重復節點查詢結果全是笛卡爾積排查了半天才找到原因——CSV 里有重復行CREATE不會去重。4.3 圖譜數據的質量保障實體對齊和去重圖譜數據質量這塊容易被忽略但決定系統上限的恰恰就是它。我遇到的主要有三類問題第一類是同名異義。“土豆”和“馬鈴薯”指同一個東西但在導入時會被當成兩個節點。解決辦法是在導入前做實體歸一化維護一個同義詞映射表統一實體名稱。第二類是關系冗余。同一道菜在多個數據源里都有合并時要判斷是不是同一個菜品我的做法是用“菜品名 菜系”做聯合唯一鍵。第三類是屬性缺失。很多菜譜不標注食材用量和是否可選這類數據直接放棄或打上默認值否則圖譜查詢會返回不完整的答案。經驗之談圖譜數據寧缺毋濫。用戶問“宮保雞丁需要什么食材”如果圖譜里只有 60% 的關系是完整的返回的結果還不如純向量檢索。我在初期測試時用了一大批不完整的菜譜數據結果圖查詢經常“查不到”后來加了數據校驗流程只導入關系完整的菜譜條目準確率才上來。5. Milvus 向量檢索食材描述的語義化召回5.1 Collection 設計與 Embedding 模型選擇Neo4j 負責精確匹配和多跳關系查詢但用戶提問中經常沒有明確的實體詞比如“清爽”、“下飯”、“低脂高蛋白”這些描述需要語義理解。我選擇把這些“描述性屬性”抽取出來做成向量。具體做法是為每個菜品生成一條描述性文檔內容包含它的口味標簽、主要技法、適用場景、食材營養屬性的自然語言描述然后把這整段文本 embedding 成向量存入 Milvus。創建 Collection 的核心代碼如下from pymilvus import ( connections, CollectionSchema, FieldSchema, DataType, Collection ) connections.connect(aliasdefault, hostlocalhost, port19530) fields [ FieldSchema(namedish_id, dtypeDataType.INT64, is_primaryTrue, auto_idFalse), FieldSchema(namedish_name, dtypeDataType.VARCHAR, max_length128), FieldSchema(namedescription, dtypeDataType.VARCHAR, max_length4096), FieldSchema(nameembedding, dtypeDataType.FLOAT_VECTOR, dim1024) ] schema CollectionSchema(fields, descriptionDish semantic descriptions) collection Collection(dish_semantic, schema) # 創建 IVF_FLAT 索引nlist 根據數據量調整 index_params { index_type: IVF_FLAT, metric_type: IP, params: {nlist: 128} } collection.create_index(embedding, index_params)Embedding 模型我選的是BAAI/bge-large-zh-v1.5這是一個中文語義向量模型1024 維在中文語義匹配任務上表現穩定。如果你資源有限可以用bge-base-zh或text2vec-large-chinese維度會不同一般是 768 維代碼里對應改dim即可。提示metric_type用了內積IP而不是余弦COSINE。bge 系列模型官方建議在 embedding 向量做歸一化之后用內積計算效果等價于余弦相似度但速度更快。如果你沒有對向量做歸一化還是用COSINE更穩妥否則相似度分數語義會有偏差。5.2 數據同步從 Neo4j 到 Milvus 的管道數據進入 Milvus 之前需要做一步轉換從圖結構生成文本描述。這個過程本質上是一個 Cypher 查詢 文本拼接 向量化 寫入的管道。核心邏輯如下def generate_description(dish_name: str, ingredients: list, techniques: list, flavors: list) - str: desc f{dish_name}是一道{flavors}風味菜肴。 if techniques: desc f主要烹飪技法包括{、.join(techniques)}。 if ingredients: desc f主要食材包括{、.join(ingredients)}。 # 追加更多屬性和標簽文本... return desc這一步生成的文本質量直接影響 embedding 的效果。如果只是把食材和技法名平鋪拼起來語義召回效果會很差。我的建議是加入一些模板化的描述比如“這道菜口味偏麻辣適合下飯”、“食材以雞肉為主屬于高蛋白低脂肪選項”讓文本更接近自然語言的語義空間。生成文本后逐條調用 embedding 接口得到向量寫入 Milvus。這里有個工程優化點批量 embedding 比逐條調用快得多一次傳 32 條文本吞吐量能提高好幾倍。寫入 Milvus 也建議用批量 insert。5.3 Attu 驗證召回效果同一個語義不同表述Milvus 寫數據之后我的習慣是用 Attu 里的查詢功能先做一輪驗證確認向量召回效果符合預期。在 Attu 的查詢界面里可以手動輸入一段描述文本選擇 collection點擊查詢就能看到按照相似度倒序返回的結果列表。我的一個測試示例是輸入“酸甜口味的豬肉菜”期望返回的結果應該包含“糖醋里脊”、“菠蘿咕咾肉”、“鍋包肉”等。第一次測試我得到的結果里混進了一堆“酸辣湯”和“酸菜魚”原因是相似度閾值太低而“酸甜”和“酸辣”在向量空間里距離并不遠。這個現象說明單靠向量檢索做菜譜匹配容易受表達方式干擾用戶說“酸甜”得到的可能更多是“辣”向量的鄰居。這也從側面驗證了混合架構的必要性。調整方式有兩個方向一個方向是優化描述文本的生成模板把“酸甜”這類 key flavor 詞在文本中前置并重復強調另一個方向是在檢索后處理階段加入關鍵詞過濾用戶沒提辣就把帶“辣”標簽的菜品過濾掉。第二個方向涉及混合排序后面細說。6. LLM 編排層意圖識別、函數調用與答案生成6.1 用提示詞把檢索策略“教”給 LLMLLM 在這個系統里是“大腦”的角色但它不是知識庫的替代品。我通過 system prompt 告訴 LLM你的任務是理解用戶問題然后調用提供的工具函數來獲取事實信息最后基于返回內容組織答案。核心的 system prompt 簡化版如下你是一個烹飪助手。你必須通過調用工具獲取事實信息不能根據自己的知識編造菜譜步驟。 可用的工具 1. query_graph: 查詢知識圖譜參數是 cypher 語句適用于有明確實體或關系的問題。 2. search_semantic: 語義搜索菜品描述參數是自然語言描述文本適用于模糊語義匹配。 3. get_dish_detail: 根據菜品名獲取完整菜譜信息。 流程要求 - 首先判斷問題類型決定調用哪個工具可以并行調用多個工具。 - 收到工具返回結果后基于結果組織回答。 - 如果結果為空明確告訴用戶“知識庫中暫未找到相關信息”。這里的關鍵是讓 LLM 學會工具調用function calling。如果模型不支持原生 function calling也可以用 ReAct 模式的提示詞模擬讓模型輸出 JSON 格式的工具調用指令代碼解析后執行再返回結果。但原生 function calling 的穩定性和格式規范性要好得多能用原生的就別自己造輪子。6.2 工具層實現Cypher 查詢和 Milvus 召回的封裝說了這么多看看工具層具體怎么實現。所有工具函數的簽名都統一成一個 JSON Schema方便 LLM 按格式調用。query_graph工具的實現會做一層 Cypher 語句的白名單控制。LLM 生成的 Cypher 語句不能直接透傳給 Neo4j 執行必須做校驗——至少檢查是否只包含MATCH和RETURN禁止DELETE、MERGE、CREATE等寫操作。這個安全措施一定要有因為 LLM 生成的語句不可控生產環境更要嚴格限制。def query_graph(cypher: str) - list: # 安全校驗禁止寫操作和危險語句 forbidden [DELETE, MERGE, CREATE, SET , REMOVE, DROP] upper cypher.upper() for kw in forbidden: if kw in upper: raise ValueError(fForbidden keyword: {kw}) with driver.session() as session: result session.run(cypher) return [record.data() for record in result]search_semantic工具實現時我對返回結果做了字段裁剪只保留 dish_name、dish_id 和相似度得分避免大段文本塞進 Prompt 導致 token 超限。def search_semantic(query_text: str, top_k: int 5) - list: query_vector embed_model.encode(query_text) collection.load() results collection.search( data[query_vector], anns_fieldembedding, param{metric_type: IP, params: {nprobe: 16}}, limittop_k, output_fields[dish_name] ) return [ {dish_name: hit.entity.get(dish_name), score: hit.score} for hit in results[0] ]6.3 多工具并行圖譜分支和向量分支的結果融合實際項目里LLM 經常會同時調用多個工具。比如用戶問“有沒有不用油炸的雞胸肉菜譜”這個問題既有實體“雞胸肉”又有約束“不用油炸”還有屬性“菜譜推薦”。我讓 LLM 同時調用query_graph和search_semantic。圖譜查詢負責精確匹配雞胸肉相關的菜品并排除油炸技法向量召回負責找語義上接近的菜品。兩份結果需要融合融合策略我用的是加權分數合并圖譜命中基礎分 1.0匹配“不用油炸”條件的不加分命中油炸的在排序時直接過濾向量命中直接用相似度分數融合分 圖譜命中分數 × 0.7 向量命中分數 × 0.3融合后的列表按分數降序取 Top-N 作為上下文片段再返回給 LLM 組織答案。這個權重比例是我調了多輪才確定的圖譜結果可信度更高所以權重更大。6.4 Prompt 拼接策略控制上下文長度和信息密度上下文拼接到 Prompt 里有一個很現實的問題——token 超限。一個菜品的信息如果全部展開包含食材、步驟、技法、口味、調料很容易超過 2000 token。而一次問答往往同時返回 5 個菜品全塞進去根本不夠用。我的做法是分層次摘要。圖譜查詢結果先轉成簡潔的結構化文本菜品宮保雞丁 所屬菜系川菜 主要食材雞胸肉、花生米、干辣椒、花椒 技法炒 口味麻辣、微甜這種格式信息密度高token 消耗小LLM 理解起來也不費力。詳細的食材用量和步驟只在用戶明確要求時才去調get_dish_detail工具補充。實操心得LLM 生成的答案質量很大程度取決于上下文的結構化程度。投喂大段 JSON 原始記錄讓 LLM “自己找重點”效果遠不如我們先把重點提煉成簡短條目。這個提煉過程應該是代碼做的而不是 LLM 做的。7. 工程實現從單個 Demo 到可復用的服務7.1 項目目錄結構整個項目我用 FastAPI 封裝了一層 HTTP 服務目錄結構如下cooking-rag-graph/ ├── app/ │ ├── main.py # FastAPI 入口 │ ├── agents/ │ │ ├── orchestrator.py # LLM 編排邏輯 │ │ └── prompts.py # 提示詞模板 │ ├── tools/ │ │ ├── neo4j_tool.py # 圖譜查詢工具 │ │ ├── milvus_tool.py # 向量召回工具 │ │ └── recipe_tool.py # 菜譜詳情工具 │ ├── models/ │ │ └── schema.py # API 請求/響應模型 │ └── services/ │ ├── graph_service.py │ └── vector_service.py ├── data/ │ ├── dishes.csv │ └── descriptions.json ├── scripts/ │ ├── import_graph.py │ ├── sync_milvus.py │ └── test_query.py ├── requirements.txt └── .env這個結構把工具層、服務層和編排層分開了后續如果要加新的數據源或者換成其他 LLM改動的范圍可以控制得很小。7.2 函數調用循環LLM 與工具之間的完整交互核心的編排循環代碼如下這是一個簡化但完整的 function calling 流程def handle_question(user_question: str) - str: messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_question} ] # 第一輪調用LLM 決定調用哪些工具 response llm.chat_completion( messagesmessages, toolsTOOL_SCHEMAS, tool_choiceauto ) # 如果 LLM 沒有調用工具直接返回生成結果 if not response.tool_calls: return response.content # 執行工具函數收集結果 tool_results [] for tool_call in response.tool_calls: tool_name tool_call.function.name arguments json.loads(tool_call.function.arguments) result execute_tool(tool_name, arguments) tool_results.append({ tool_call_id: tool_call.id, role: tool, content: json.dumps(result, ensure_asciiFalse) }) # 第二輪調用把工具結果回傳給 LLM 生成答案 messages.append(response) messages.extend(tool_results) final_response llm.chat_completion(messagesmessages) return final_response.content這里有個細節值得注意messages.append(response)這一步很關鍵。OpenAI 兼容接口要求工具調用完成后原始 assistant 消息包含 tool_calls 字段必須追加回對話歷史中然后再追加 tool 角色的結果消息。如果順序錯了或漏了 assistant 消息接口會報 400 錯誤。有朋友會遇到開頭熱詞里提到的error: llm request failed: provider rejected the request schema or tool payload這個報錯的常見原因之一就是 tool schema 格式不符合 provider 要求。比如有些 provider 要求parameters必須是一個合法的 JSON Schema 對象如果你傳成了{type: object}之外的格式或者某些字段類型不兼容就會觸發這個錯誤。排查方法是把tools參數單獨打印出來格式化檢查逐個字段對照官方文檔。7.3 常見 LLM 請求錯誤超時和拒絕實操中 LLM 調用最常見的兩個報錯我直接給出排查經驗。第一個是llm request timed out. the model did not produce a response before the model這類超時問題。原因一般有兩個推理模型在 function calling 場景下思考時間過長或者是網絡鏈路慢。解決辦法調大超時時間比如從 30s 調到 120s如果業務允許用流式輸出配合 SSE 給前端做 loading還有一種情況是模型本身在循環調用工具停不下來這時需要限制最大工具調用輪數我一般設置為 2 輪。第二個是provider rejected the request schema or tool payload這類 schema 拒絕問題。大多數是因為提示詞和 tool schema 信息量太大加上上下文過長超過了 provider 的單次請求限制。解決辦法精簡 system prompt減少工具描述的冗余文本必要時壓縮候選上下文后再調用 LLM。7.4 FastAPI 接口封裝服務層我用 FastAPI 暴露了一個簡單接口app.post(/api/ask) async def ask(request: AskRequest): try: answer orchestrator.handle_question(request.question) return {answer: answer, status: success} except Exception as e: return {answer: str(e), status: error}這個接口本身非常簡單但要注意線程安全的問題。Neo4j 的driver對象是線程安全的可以全局共享Milvus 的connections也是線程安全的。但如果你的代碼里用了全局的 embedding 模型實例要確認它是否線程安全不安全的模型實例需要用線程鎖包起來。8. 圖 RAG 的查詢優化從 Cypher 到混合檢索的細節8.1 典型圖查詢模式多跳關聯和條件排除圖查詢是這套系統最有優勢的地方舉幾個實際場景的 Cypher 示例都是測試過程中反復用到的模式。場景一多跳關系查詢。用戶問“川菜里有哪些菜用了花生”需要從 Cuisine 走到 Dish再走到 Ingredient兩跳查詢MATCH (c:Cuisine {name: 川菜})-[:BELONGS_TO]-(d:Dish) MATCH (d)-[:HAS_INGREDIENT]-(i:Ingredient {name: 花生}) RETURN d.name AS dish_name場景二條件排除。用戶問“不用油炸的雞肉菜譜”需要先找用雞肉的菜品再排除用油炸技法的MATCH (d:Dish)-[:HAS_INGREDIENT]-(i:Ingredient {name: 雞胸肉}) WHERE NOT EXISTS { MATCH (d)-[:USES_TECHNIQUE]-(t:Technique {name: 炸}) } RETURN d.name AS dish_name LIMIT 10場景三圖譜中的相似推薦。用戶問“有沒有類似麻婆豆腐的菜”利用SIMILAR_TO關系一步就能找到推薦菜品MATCH (d:Dish {name: 麻婆豆腐})-[:SIMILAR_TO]-(recommend) RETURN recommend.name AS dish_name這三個場景充分說明了圖查詢的價值——結構化約束和關系推理能力這是純向量檢索做不到的。8.2 混合檢索的排序策略圖譜分數和向量分數的權重混合檢索不是簡單地把兩個結果列表拼接起來。我在項目里實現了一個比較簡單的融合排序函數邏輯如下def fuse_results(graph_results: list, vector_results: list, top_k5): score_map {} # 圖譜結果存在即給 1.0 基礎分 for item in graph_results: name item[dish_name] score_map[name] score_map.get(name, 0) 1.0 # 向量結果相似度分數乘以權重 for item in vector_results: name item[dish_name] score_map[name] score_map.get(name, 0) item[score] * 0.3 # 按分數降序排列取 Top-K ranked sorted(score_map.items(), keylambda x: x[1], reverseTrue) return [name for name, score in ranked[:top_k]]這個融合邏輯雖然簡單但實際效果很不錯。它保證了兩件事圖譜命中的菜品永遠排在有語義相似度但無圖譜關系的菜品前面向量召回可以作為圖譜召回的有效補充捕獲那些圖譜沒有顯式建模的語義近似關系。權重參數 0.3 怎么定的我做了幾輪評測讓三個朋友分別打分對比不同權重下回答結果的滿意度。0.5 以上向量權重時圖譜的硬約束會被稀釋0.2 以下時向量召回的寬松語義匹配基本不起作用。0.3 是一個經驗值業務數據不同可能需要微調。8.3 圖譜回答的可解釋性設計圖 RAG 相比傳統 RAG 的一個巨大優勢就是可解釋性。圖譜查詢的結果可以精確追溯到“哪個菜品、哪個食材、哪個關系”每個答案都能畫出一條或者多條路徑。我在 API 返回結果里加了一個evidence字段記錄答案對應的圖譜查詢路徑或向量召回依據{ answer: 宮保雞丁是川菜中一道經典菜品主要食材包括雞胸肉、花生米、干辣椒等。, evidence: { graph_path: 宮保雞丁 -[BELONGS_TO]- 川菜, graph_path: 宮保雞丁 -[HAS_INGREDIENT]- 雞胸肉 } }這個設計的實際價值在于用戶或者開發者懷疑答案有誤時可以直接檢查圖譜路徑是否合理。傳統 RAG 的“黑盒召回 LLM 生成”模式下根本沒法定位錯誤是來自于檢索還是生成。而圖 RAG 中圖譜路徑是精確的、可審計的。9. 常見問題與排查技巧實錄9.1 Neo4j 常見坑連接、導入和權限我整理了一份速查表直接列出問題和對應的解決方向問題現象可能原因解決方向Python 連接 Neo4j 報錯未修改監聽地址修改neo4j.conf中server.default_listen_address0.0.0.0LOAD CSV 找不到文件文件不在服務器 import 目錄Docker 掛載 CSV 到/var/lib/neo4j/importMERGE 后節點重復唯一約束未創建為 Dish.name、Ingredient.name 等字段創建唯一約束Cypher 執行超時圖數據量過大缺少索引為常用查詢字段創建索引瀏覽器訪問 7474 無法打開Docker 端口映射錯誤檢查映射容器內 Neo4j 默認監聽 7474 和 7687這里要特別強調唯一約束的創建。導入大量數據前一定要先建約束CREATE CONSTRAINT dish_name_unique IF NOT EXISTS FOR (d:Dish) REQUIRE d.name IS UNIQUE; CREATE CONSTRAINT ingredient_name_unique IF NOT EXISTS FOR (i:Ingredient) REQUIRE i.name IS UNIQUE;不建約束的話即使用了 MERGE并發導入時也可能產生重復節點。我在一次大批量導入時因為漏了約束結果圖譜里出現了上千個重復菜品節點。9.2 Milvus 常見坑版本匹配和索引異常Milvus 的坑大多是版本相關的。舉幾個我實際遇到的問題第一個是Attu 連接不上本地 Milvus。最常見原因是 Attu 容器里的localhost指向的是容器自己不是宿主機。要用host.docker.internal或者宿主機的局域網 IP 來連接。Docker Desktop 下host.docker.internal是直接可用的。第二個是搜索時報索引不匹配。我在創建 Collection 時用了IVF_FLAT但搜索時nprobe參數沒有傳或者傳的params格式不對報index not found或者nprobe must be greater than 0。解決辦法搜索前需要collection.load()把數據加載到內存并且search_params里要帶params: {nprobe: 16}。第三個是刪除 collection 后重新創建報錯。如果有同名 collection 處于加載狀態刪除后馬上重建可能會遇到元數據殘留問題。解決辦法先collection.release()再drop等幾秒再重建。9.3 LLM 編排的常見坑工具調用循環和上下文超限LLM 編排這塊的問題更隱蔽因為錯誤往往是邏輯錯誤而不是系統錯誤。工具調用死循環LLM 反復調用同一個工具每次都返回同樣的結果就是不結束。解決辦法在編排層加最大工具調用輪數我設置 2 輪超過后強制終止用已有上下文生成答案。上下文超限工具結果和對話歷史太長超出了模型的最大上下文長度。解決辦法工具返回結果盡量精簡保留對話歷史時只保留最近兩輪如果用的是長上下文模型可以放寬一些。答案中使用幻覺信息LLM 在調用工具拿到結果后仍然會在回答中加入工具結果之外的知識。比如圖譜查詢返回三道菜LLM 卻在回答中補充了第四道菜的步驟。解決辦法prompt 中明確要求“只能使用工具返回的信息組織答案”同時讓 LLM 在回答末尾標注信息來源圖譜/向量降低用戶對幻覺信息的信任度。9.4 完整版的“避坑清單”最后把實踐中總結的清單完整列出來Neo4j 導入前必建唯一約束Milvus 搜索等待 Collection load 完成collection.load()是異步的需要輪詢或加延時LLM 工具調用要對 Cypher 做只讀校驗禁止執行寫操作所有工具返回結果都要做 token 裁剪不要讓生成長文本直接進 Prompt向量召回 top_k 不宜過大一般 5-10 條足夠圖譜結果和向量結果的時間戳最好都記錄下來方便后續效果分析和權重調優Embedding 模型要和查詢文本匹配中文問題用中文模型中英混合效果會差數據量和索引參數要匹配。小數據量直接FLAT索引即可IVF_FLAT的nlist一般設為4*sqrt(N)左右10. 實踐復盤這套方案適合什么場景項目做完之后我對這套“圖 RAG”方案的適用邊界有了更清晰的認識。它最適合的場景是知識本身具有強結構、實體關系密集、且查詢中包含明確關系約束的領域。烹飪是典型例子電商導購商品-類目-屬性、醫療問答癥狀-疾病-藥物、企業知識庫項目-人員-文檔也都是適合的方向。這些場景的共同特點是用戶問的問題中有大量“條件約束”和“關系推理”純向量檢索無法精確滿足。但如果你的知識庫是松散的文檔集合比如一堆技術博客、新聞資訊、會議紀要實體關系非常弱用戶的問題也以開放型檢索為主那么圖 RAG 的優勢發揮不出來反而增加了圖譜構建和維護的成本。這種情況下傳統的向量 RAG 加上 rerank 可能更合適。從工程成本來看圖 RAG 的引入確實增加了很多工作量。圖譜建模需要領域知識數據導入需要清洗和實體對齊混合檢索需要調權重的經驗。但帶來的回報是回答準確率提升、幻覺率下降、可解釋性增強。對一個面向生產環境的知識問答系統來說這些回報是值得的。我在實際測試中有一個很深的體會圖 RAG 的查詢鏈路里最需要的不是復雜的算法而是清晰的職責劃分。Neo4j 管事實精確匹配、Milvus 管語義模糊匹配、LLM 管理解與表達三者不越界系統自然就穩定。如果哪天出現了回答質量下降先檢查是哪個環節出了問題而不是一上來就調模型參數。最后說一個后續可以擴展的方向目前圖譜數據是離線構建的后續可以做一個半自動的知識更新管道從新增菜譜文檔中抽取實體和關系經過人審后寫入 Neo4j。另外混合排序的權重目前是靜態的可以嘗試根據用戶反饋做動態調整。這些都是在現有架構上的增量優化骨架不用變。如果你正在做一個 RAG 項目并且被“答非所問”和“結果不可控”困擾不妨試試這個組合。圖數據庫加向量數據庫的混合檢索方案值得踩一遍坑。