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