現(xiàn)汽修RAG問(wèn)答與工單閉環(huán)實(shí)踐)
1. 項(xiàng)目全景為什么汽修問(wèn)答需要 RAG 工單閉環(huán)做汽修信息化也有幾年了我接觸過(guò)的不少維修廠(chǎng)和連鎖門(mén)店都有一個(gè)很尷尬的現(xiàn)狀老師傅的經(jīng)驗(yàn)全在腦子里新人查故障手冊(cè)翻半天客服接電話(huà)被問(wèn)得啞口無(wú)言售后工單又是另一個(gè)系統(tǒng)里的死數(shù)據(jù)修完就存檔下次遇到類(lèi)似問(wèn)題還得從頭摸索。這套項(xiàng)目就是奔著解決這個(gè)痛點(diǎn)去的——用 FastAPI 搭后端服務(wù)用 Milvus 存向量知識(shí)用 RAG 讓大模型基于真實(shí)維修資料問(wèn)答同時(shí)把每一次問(wèn)答自動(dòng)關(guān)聯(lián)到工單流程里形成“提問(wèn)—解決—沉淀”的閉環(huán)。這個(gè)項(xiàng)目適合誰(shuí)參考首先是負(fù)責(zé)汽修門(mén)店數(shù)字化系統(tǒng)的后端工程師其次是研究 RAG 落地但找不到具體場(chǎng)景的技術(shù)同學(xué)還有想在生產(chǎn)環(huán)境用 Milvus 但對(duì)部署選型比較猶豫的人。我會(huì)把從環(huán)境搭建到接口聯(lián)調(diào)、再到工單流轉(zhuǎn)的完整路徑都寫(xiě)清楚包括實(shí)際踩過(guò)的坑。很多人一提到智能問(wèn)答就想到微調(diào)大模型這是最常見(jiàn)的誤區(qū)。汽修領(lǐng)域的故障現(xiàn)象、維修步驟、配件參數(shù)更新得很快微調(diào)一次成本高不說(shuō)知識(shí)還會(huì)過(guò)期。RAG 的思路更聰明——把維修手冊(cè)、技術(shù)通報(bào)、歷史工單切塊向量化存進(jìn) Milvus提問(wèn)時(shí)先檢索出最相關(guān)的知識(shí)片段再把這些片段作為上下文丟給大模型生成答案。這樣知識(shí)更新只需要重新灌庫(kù)模型本身不用動(dòng)。加上工單閉環(huán)之后系統(tǒng)就不再是“一次性問(wèn)答機(jī)器人”而是能持續(xù)從真實(shí)維修記錄里學(xué)到新東西的知識(shí)引擎。工單閉環(huán)是這個(gè)項(xiàng)目的靈魂。傳統(tǒng)問(wèn)答機(jī)器人答完就結(jié)束用戶(hù)問(wèn)完還得自己對(duì)著答案去干活干完了也沒(méi)有反饋。我設(shè)計(jì)的閉環(huán)是問(wèn)答結(jié)果不僅要返回自然語(yǔ)言答復(fù)還會(huì)拆解出建議的維修項(xiàng)目、工時(shí)、配件然后自動(dòng)生成一張草稿工單維修技師實(shí)際完成維修后工單狀態(tài)變更為“已完成”并回寫(xiě)結(jié)論系統(tǒng)定期把已完成的工單再向量化回 Milvus下次遇到相似故障就能檢索到真實(shí)維修案例。這套邏輯讓知識(shí)庫(kù)自己“生長(zhǎng)”越用越準(zhǔn)。2. 技術(shù)選型與架構(gòu)拆解2.1 FastAPI 作為服務(wù)層異步和自動(dòng)文檔是最大紅利后端框架我選 FastAPI 沒(méi)有太多猶豫。首先是異步支持RAG 鏈路里有大量 IO 操作——調(diào)向量庫(kù)查詢(xún)、調(diào)大模型接口、讀寫(xiě)數(shù)據(jù)庫(kù)用 async/await 能把并發(fā)吞吐?lián)纹饋?lái)比如汽修門(mén)店高峰期同時(shí)十幾個(gè)工位在查故障同步框架很容易把線(xiàn)程池打滿(mǎn)。其次是 FastAPI 自帶 OpenAPI 文檔前端、安卓、小程序都能直接看接口契約省掉了手動(dòng)維護(hù)文檔的時(shí)間。還有 Pydantic 做參數(shù)校驗(yàn)工單數(shù)據(jù)結(jié)構(gòu)復(fù)雜時(shí)嵌套模型定義得清清楚楚遠(yuǎn)比 Flask 手動(dòng)校驗(yàn)來(lái)得穩(wěn)妥。在這個(gè)項(xiàng)目里FastAPI 不只是做 HTTP 層它還承擔(dān)了流程編排的職責(zé)。一個(gè)典型的問(wèn)答請(qǐng)求進(jìn)來(lái)先經(jīng)過(guò)POST /api/rag/query然后服務(wù)內(nèi)部依次執(zhí)行查詢(xún) Milvus、拼裝 prompt、調(diào)用 LLM、解析結(jié)構(gòu)化結(jié)果、寫(xiě)工單草稿。每一步都是獨(dú)立的 service 函數(shù)用 FastAPI 的依賴(lài)注入把它們串起來(lái)。這樣寫(xiě)的好處是方便測(cè)試也方便以后替換組件——比如換 embedding 模型或者加一個(gè)多路召回都只是在 service 內(nèi)部改。2.2 Milvus 向量數(shù)據(jù)庫(kù)選型與版本坑選 Milvus 而不是其他向量庫(kù)核心原因是它支持集合collection級(jí)別的動(dòng)態(tài) Schema這對(duì)汽修知識(shí)庫(kù)很重要。維修手冊(cè)和工單的字段差異很大有的需要存故障碼有的需要存車(chē)型用固定 Schema 的庫(kù)會(huì)很痛苦。Milvus 從 2.x 開(kāi)始支持 JSON 字段和動(dòng)態(tài)字段我可以把各種元數(shù)據(jù)一股腦塞進(jìn)去查詢(xún)時(shí)再用 filter 精確過(guò)濾比純向量檢索加后置過(guò)濾要高效得多。但這玩意兒的版本是個(gè)深坑。我最早用的是 Milvus 2.2.x后來(lái)為了用新特性升級(jí)到 2.4.x結(jié)果發(fā)現(xiàn) Attu 客戶(hù)端版本不一樣連接方式全變了。Attu 是一個(gè) Milvus 的可視化管理工具如果你只裝了 Milvus 服務(wù)端而沒(méi)裝 Attu可視化調(diào)試會(huì)非常痛苦。這里強(qiáng)調(diào)一下版本對(duì)應(yīng)關(guān)系A(chǔ)ttu 2.3.0 及以前基本兼容 Milvus 2.2/2.3Milvus 2.4 的 WebUI 其實(shí)是內(nèi)置的不再?gòu)?qiáng)烈依賴(lài) Attu但很多人還是習(xí)慣用 Attu 看數(shù)據(jù)。我是裝了 Milvus 2.4.1然后直接用內(nèi)置 WebUI默認(rèn)端口 9091再用 Attu 2.4.x 連接流暢度還行。如果你剛上手建議就裝 Milvus 2.4.x 版本然后 Access 方式別搞錯(cuò)否則你會(huì)一頭扎進(jìn)“ETCD 報(bào)錯(cuò)”里出不來(lái)。2.3 RAG 流程整體編排從 query 到 answer 的完整鏈路RAG 不是簡(jiǎn)單的“向量檢索 大模型生成”細(xì)拆有以下幾步query 預(yù)處理對(duì)用戶(hù)輸入做去噪、同義詞擴(kuò)展比如“車(chē)子啟動(dòng)不了”擴(kuò)展為“無(wú)法啟動(dòng)”、“打不著火”這些規(guī)則可以先用正則和詞典做不要一開(kāi)始就上模型。embedding 落入向量庫(kù)用同一個(gè) embedding 模型把 query 編碼成向量這一步必須保證 encode 模型和入庫(kù)時(shí)一致否則向量空間錯(cuò)位檢索結(jié)果一塌糊涂。向量召回 元數(shù)據(jù)過(guò)濾先按車(chē)型、系統(tǒng)發(fā)動(dòng)機(jī)/變速箱/電氣過(guò)濾再在子集里算相似度召回 top-k。重排如果召回結(jié)果多了可以用簡(jiǎn)單的 RRF倒數(shù)排名融合加上關(guān)鍵詞 overlap 調(diào)權(quán)比直接依賴(lài)向量距離更穩(wěn)。prompt 組裝把召回片段拼成上下文加上系統(tǒng)提示詞要求模型只依據(jù)上下文回答不要瞎編。結(jié)構(gòu)化抽取讓模型輸出建議的維修項(xiàng)目、工時(shí)、配件存到工單草稿里。我用 langchain 還是直接手寫(xiě)坦率講這個(gè)場(chǎng)景我建議手寫(xiě) pipeline。LangChain 的抽象層確實(shí)方便但版本升級(jí)太頻繁出了問(wèn)題很難排查。RAG 核心鏈路其實(shí)不復(fù)雜自己用 Python 寫(xiě)也就 100 多行。后面我會(huì)把關(guān)鍵代碼貼出來(lái)。3. 環(huán)境準(zhǔn)備與 Milvus 本地部署非 Docker 實(shí)測(cè)3.1 Windows / Linux 下 Milvus 安裝細(xì)節(jié)Milvus 官方推薦用 Docker Compose 部署但是很多公司內(nèi)網(wǎng)或者個(gè)人開(kāi)發(fā)機(jī)沒(méi)有 Docker 環(huán)境尤其 Windows 下要裝 Docker Desktop 一堆麻煩事。我實(shí)際測(cè)試過(guò)Milvus 2.4.x 也提供了不帶 Docker 的安裝方式這里給出幾個(gè)路線(xiàn)。路線(xiàn)一Windows 下用 Docker Desktop 跑。雖然用到了 Docker但只要你裝好 Docker Desktopdocker-compose.yml一拉就能跑起來(lái)。這里有個(gè)坑Windows 下 Milvus 默認(rèn)掛載卷的路徑如果包含中文或空格容器會(huì)起不來(lái)所以最好把目錄設(shè)置成純英文。路線(xiàn)二直接上 Linux 裸機(jī)裝。以 Ubuntu 22.04 為例不依賴(lài) Docker 的安裝步驟大概是這樣先裝 etcd再裝 MinIO然后再裝 Milvus standalone單機(jī)版。Milvus standalone 雖然內(nèi)部依賴(lài) etcd 和 MinIO但它有自己的啟動(dòng)腳本只要配置里指向 etcd 和 MinIO 的端點(diǎn)就行。我用的版本組合是etcd 3.5.9、MinIO RELEASE.2023-03-20T00-00-00Z、Milvus 2.4.1。順序很重要先啟動(dòng) etcd再 MinIO最后啟動(dòng) Milvus。Windows 純本機(jī)非 Docker 安裝我沒(méi)走通官方對(duì) Windows 原生支持不足建議如果不想用 Docker 就裝 WSL2 跑 Ubuntu然后在 WSL 里按照 Linux 方式裝。我測(cè)試下來(lái)這套組合最穩(wěn)定。3.2 Attu 客戶(hù)端連接不同 Milvus 版本的問(wèn)題很多人第一次用 Attu 都懵因?yàn)?Attu 和 Milvus 的版本沒(méi)有嚴(yán)格一一對(duì)應(yīng)。Attu 的 GitHub 倉(cāng)庫(kù)說(shuō)支持 2.x 大版本但實(shí)際連接時(shí)如果 Milvus 版本太新接口路徑變了Attu 會(huì)顯示一堆空數(shù)據(jù)或者直接報(bào)錯(cuò)。比如用 Attu 2.3.8 連 Milvus 2.4.1集群信息能顯示但查詢(xún)數(shù)據(jù)時(shí)可能拿不到向量字段的標(biāo)量值。我的經(jīng)驗(yàn)是Milvus 2.4.x 盡量用 Attu v2.4.0 以上版本Milvus 2.2/2.3 則用 Attu 2.3.x。還有一個(gè)更省心的方法——Milvus 2.4 自帶的 WebUI啟動(dòng)后瀏覽器訪(fǎng)問(wèn)http://localhost:9091/webui能看集合、做搜索、看日志。我后來(lái)基本都在 WebUI 里排查數(shù)據(jù)Attu 只是偶爾用來(lái)做數(shù)據(jù)管理。3.3 etcd 與存儲(chǔ)配置要點(diǎn)Milvus 的元數(shù)據(jù)、分片信息、索引狀態(tài)都存在 etcd 里etcd 掛了 Milvus 就廢了。我有一個(gè)血淚教訓(xùn)之前搭建時(shí) etcd 用的默認(rèn)端口 2379結(jié)果跟本地另一個(gè)服務(wù)沖突Milvus 啟動(dòng)過(guò)程一直在 etcd 連接重試日志大量刷etcdserver: request timed out。排查了半天才找到元兇。建議部署時(shí)把 etcd 的listen-client-urls和listen-peer-urls分開(kāi)客戶(hù)端地址用本機(jī) IP而不要用0.0.0.0這樣安全也好排障。MinIO 的 bucket 名稱(chēng)可以自己定義但 Milvus 啟動(dòng)時(shí)會(huì)自動(dòng)建 bucket如果你之前手動(dòng)建過(guò)同名 bucket 且權(quán)限不對(duì)初始化會(huì)失敗所以最省事的做法是讓 Milvus 自動(dòng)創(chuàng)建。另外Milvus 的配置文件milvus.yaml里有一個(gè)common.threadCount參數(shù)默認(rèn)是 CPU 核數(shù)。如果機(jī)器 CPU 核不多又同時(shí)跑 embedding 模型容易導(dǎo)致環(huán)境卡死。我調(diào)到 8效果穩(wěn)定。4. 后端核心實(shí)現(xiàn)FastAPI 接口與 RAG 鏈路4.1 數(shù)據(jù)切分與向量化汽修數(shù)據(jù)源五花八門(mén)PDF 維修手冊(cè)、Excel 零件表、歷史工單文本。我統(tǒng)一先轉(zhuǎn)成純文本再做結(jié)構(gòu)化切分。直接按固定字符切是最蠢的會(huì)把一句話(huà)砍成兩半。我用的策略是分層切分先按一級(jí)目錄比如“發(fā)動(dòng)機(jī)系統(tǒng)”“變速箱系統(tǒng)”分成大塊再按最小語(yǔ)義單元——段落和列表項(xiàng)——切成 chunk每個(gè) chunk 控制在 500 到 800 個(gè) tokenchunk 之間保留 50 個(gè) token 的 overlap。這里有一個(gè)小技巧對(duì)于維修手冊(cè)把“故障碼 可能原因 排查步驟”作為一個(gè)整體切因?yàn)檫@三者是一個(gè)完整檢索單元拆開(kāi)了檢索噪音很大。對(duì)于歷史工單我字段里用fault_desc、solution、parts_used分別存向量化時(shí)只對(duì)fault_desc solution做 embeddingparts 作為過(guò)濾條件。embedding 模型我選擇了bge-large-zh-v1.5中文場(chǎng)景效果不錯(cuò)維度是 1024。Milvus 建立 collection 時(shí)向量字段類(lèi)型設(shè)為 FLOAT_VECTORdim 1024。如果用 OpenAI 的 embeddingAPI 有調(diào)用費(fèi)用內(nèi)網(wǎng)部署不方便。bge 模型在本地用sentence-transformers加載速度也挺快。切分和向量化代碼大概長(zhǎng)這樣from sentence_transformers import SentenceTransformer from pymilvus import Collection, FieldSchema, CollectionSchema, DataType, connections model SentenceTransformer(BAAI/bge-large-zh-v1.5) def embed_texts(texts): return model.encode(texts, normalize_embeddingsTrue) fields [ FieldSchema(nameid, dtypeDataType.INT64, is_primaryTrue, auto_idFalse), FieldSchema(nametext, dtypeDataType.VARCHAR, max_length65535), FieldSchema(namecar_model, dtypeDataType.VARCHAR, max_length128), FieldSchema(namesystem_tag, dtypeDataType.VARCHAR, max_length64), FieldSchema(namevector, dtypeDataType.FLOAT_VECTOR, dim1024), FieldSchema(namemetadata, dtypeDataType.JSON), ] schema CollectionSchema(fields, descriptioncar repair knowledge) col Collection(namecar_repair, schemaschema)4.2 檢索邏輯dense vector search 的踩坑檢索最簡(jiǎn)單的方式就是col.search()傳 query 向量取 top_k。但如果直接全庫(kù)搜索會(huì)把完全不同的故障問(wèn)混進(jìn)來(lái)。比如用戶(hù)問(wèn)“怠速不穩(wěn)”你召回的是“怠速馬達(dá)更換”這算相關(guān)但如果召回的是“空調(diào)不制冷”那就是噪音。所以要先 filter 再 search用expr參數(shù)把車(chē)型、系統(tǒng)限定住。踩過(guò)最大的坑是metric_type的選擇。Milvus 支持IP內(nèi)積、L2歐氏距離、COSINE。我用 bge 模型的時(shí)候normalize_embeddingsTrue之后用 IP 和 COSINE 等價(jià)但別用 L2。具體看模型說(shuō)明bge 官方建議用 COSINE。若 embedding 沒(méi)歸一化IP 的分?jǐn)?shù)范圍不穩(wěn)定檢索前幾名容易錯(cuò)。還有一個(gè)容易被忽略的是search_params里的ef參數(shù)針對(duì) HNSW 索引。索引類(lèi)型我用HNSW時(shí)ef 越大召回越準(zhǔn)但越慢。在線(xiàn)問(wèn)答場(chǎng)景我設(shè)ef128這能兼顧精度與速度。另一個(gè)參數(shù)nprobe是 IVF 索引的如果老版本用了 IVF 別搞混。檢索代碼加上過(guò)濾條件后query_embedding embed_texts([query])[0].tolist() search_params {metric_type: COSINE, params: {ef: 128}} expr system_tag in [發(fā)動(dòng)機(jī), 電氣] result col.search(data[query_embedding], anns_fieldvector, paramsearch_params, limit5, exprexpr, output_fields[text, car_model])注意expr里字符串要用單引號(hào)包著字段名不能用反引號(hào)。我剛開(kāi)始用習(xí)慣了 SQL 的語(yǔ)法寫(xiě)著寫(xiě)著就報(bào)語(yǔ)法錯(cuò)誤。Milvus 的 expr 語(yǔ)法基本兼容過(guò)濾表達(dá)式的子集但 JSON 字段訪(fǎng)問(wèn)要用metadata[part_no]這種用法具體官方文檔要看一眼。4.3 生成與工單創(chuàng)建聯(lián)動(dòng)召回得到 top-5 片段后就要組裝 prompt。我用了兩個(gè)模型一個(gè)是本地部署的 Qwen2.5-14B通過(guò) vLLM 部署另一個(gè)是 OpenAI 兼容接口?？紤]到大模型輸出的穩(wěn)定性我把 prompt 寫(xiě)得非常死板你是汽修專(zhuān)家。只依據(jù)以下資料回答問(wèn)題不要編造。 資料 1. [片段1] 2. [片段2] ... 問(wèn)題{user_query} 請(qǐng)輸出 JSON字段包括 - answer: 自然語(yǔ)言回答 - likely_causes: 可能原因數(shù)組 - suggestions: 建議操作列表 - parts: 建議配件列表每個(gè)包含名稱(chēng)和數(shù)量 - estimated_hours: 預(yù)計(jì)工時(shí)數(shù)字 如果資料信息不足answer 里明確說(shuō)“資料中未找到請(qǐng)人工核實(shí)”。為什么要讓模型輸出 JSON因?yàn)槲倚枰苯影焉山Y(jié)果映射到工單草稿。FastAPI 的響應(yīng)模型天然支持 Pydantic大模型輸出 JSON 后我用json.loads解析再存為工單對(duì)象的字段。如果允許模型自由發(fā)揮那工單數(shù)據(jù)就是一堆垃圾。在 FastAPI 里創(chuàng)建工單的接口和問(wèn)答接口分開(kāi)更清晰app.post(/api/rag/query) async def rag_query(req: QueryRequest): contexts search_milvus(req) messages build_prompt(contexts, req.query) llm_resp await call_llm(messages) parsed parse_json(llm_resp) draft_id await create_work_order_from_parsed(req, parsed) return {answer: parsed[answer], draft_work_order_id: draft_id}這一步關(guān)聯(lián)了問(wèn)答和工單問(wèn)答結(jié)果不只是給用戶(hù)看的同時(shí)已經(jīng)是半結(jié)構(gòu)化工單。前端可以顯示“已生成草稿工單工單編號(hào) WO-20250521-001”用戶(hù)確認(rèn)后即可進(jìn)入維修流程。5. 工單閉環(huán)從智能問(wèn)答到執(zhí)行反饋5.1 工單數(shù)據(jù)結(jié)構(gòu)設(shè)計(jì)工單表我用 PostgreSQL 存儲(chǔ)但核心業(yè)務(wù)邏輯在 FastAPI 中處理下面是關(guān)鍵的字段設(shè)計(jì)字段名類(lèi)型說(shuō)明work_order_idvarchar工單號(hào)格式 WO-YYYYMMDD-NNNquery_texttext原始問(wèn)題answer_texttext大模型生成的答案car_modelvarchar車(chē)型vinvarchar車(chē)架號(hào)fault_codevarchar故障碼可為空l(shuí)ikely_causesjsonb可能原因數(shù)組suggestionsjsonb建議操作列表partsjsonb配件列表名稱(chēng)、數(shù)量estimated_hoursnumeric預(yù)計(jì)工時(shí)statusvarchar狀態(tài)DRAFT/IN_PROGRESS/DONE/CLOSEDactual_solutiontext修理工實(shí)際處理方法閉環(huán)關(guān)鍵actual_partsjsonb實(shí)際使用配件created_attimestamp創(chuàng)建時(shí)間closed_attimestamp關(guān)閉時(shí)間設(shè)計(jì)時(shí)我特別加了actual_solution和actual_parts。這是跟普通問(wèn)答系統(tǒng)最大的不同問(wèn)答結(jié)束后系統(tǒng)并沒(méi)有完事它等著維修技師干完活把結(jié)果填回來(lái)。有了這兩列才能持續(xù)更新知識(shí)庫(kù)。5.2 問(wèn)答結(jié)果如何映射為工單在create_work_order_from_parsed里面我把解析后的 JSON 映射到上面的表。這里有一個(gè)細(xì)節(jié)如果用戶(hù)問(wèn)的是“這個(gè)故障代碼 P0300 是什么意思”生成結(jié)果里可能沒(méi)有具體配件estimated_hours 可能是 null。沒(méi)關(guān)系工單草稿允許空值維修技師在確認(rèn)草稿時(shí)可以補(bǔ)充。但是如果用戶(hù)問(wèn)的是“換機(jī)油”系統(tǒng)應(yīng)該能自動(dòng)預(yù)測(cè)工時(shí)和機(jī)油濾芯配件這就要靠 prompt 引導(dǎo)。我在 prompt 里增加了規(guī)則“如果問(wèn)題明顯是維修請(qǐng)求必須輸出 parts、estimated_hours如果只是知識(shí)詢(xún)問(wèn)parts 可以為空數(shù)組”。這樣能減少垃圾工單的產(chǎn)生。另外工單創(chuàng)建前我會(huì)調(diào)用一個(gè)簡(jiǎn)單的去重函數(shù)根據(jù)car_model query_text 時(shí)間范圍最近1小時(shí)判斷有沒(méi)有重復(fù)工單防止用戶(hù)一直點(diǎn)同一個(gè)按鈕刷出來(lái)一堆草稿。5.3 閉環(huán)反饋與知識(shí)庫(kù)更新閉環(huán)的落地點(diǎn)在于每天凌晨跑一個(gè)批處理腳本把最近 24 小時(shí)狀態(tài)為CLOSED且actual_solution非空的工單再次切分向量化后寫(xiě)入 Milvus。寫(xiě)入的時(shí)候用text 故障描述 query_text 實(shí)際解決 actual_solution再附上實(shí)際的配件、車(chē)型等信息。這樣知識(shí)庫(kù)里會(huì)不斷加入真實(shí)維修案例而不是只有官方手冊(cè)內(nèi)容。同時(shí)我會(huì)更新舊數(shù)據(jù)的knowledge_source字段讓它區(qū)分是官方手冊(cè)還是歷史工單。檢索時(shí)可以把來(lái)源權(quán)重調(diào)高一點(diǎn)比如官方手冊(cè)的metadata[source]為manual工單的為work_order在重排階段對(duì)work_order的命中做一個(gè)小激勵(lì)因?yàn)檎鎸?shí)維修案例往往更有參考價(jià)值。這一套閉環(huán)跑起來(lái)后系統(tǒng)越用越懂你們門(mén)店的常見(jiàn)問(wèn)題。舉個(gè)例子某品牌車(chē)在店里經(jīng)常出現(xiàn)某個(gè)通病官方手冊(cè)沒(méi)寫(xiě)但第一個(gè)維修師傅手工填了實(shí)際解決過(guò)程之后第二個(gè)師傅再問(wèn)就能檢索到。這就是閉環(huán)的意義。6. 常見(jiàn)問(wèn)題與排查實(shí)錄6.1 Milvus 連接失敗與 etcd 問(wèn)題最典型的現(xiàn)象是 FastAPI 啟動(dòng)時(shí)connections.connect(aliasdefault, hostlocalhost, port19530)報(bào)連接超時(shí)。先別急著查 Milvus 本身先看 etcd 是否正常。排查步驟檢查 etcd 進(jìn)程ps aux | grep etcd。如果沒(méi)有啟動(dòng)/path/to/etcd --data-dir/data/etcd --listen-client-urlshttp://0.0.0.0:2379 --advertise-client-urlshttp://0.0.0.0:2379。檢查 Milvus 日志/var/log/milvus/server.log。如果看到grpc: addrConn.createTransport failed大概率是 Milvus 配置里的 etcd 地址寫(xiě)錯(cuò)了。驗(yàn)證 etcd 連通性curl http://localhost:2379/health返回{health:true}才正常。我遇到最扯的一次是 etcd 啟動(dòng)成功了但防火墻把 2379 端口擋住了Milvus 進(jìn)程在另外一臺(tái)機(jī)器上連不上。所以如果你把 etcd 和 Milvus 分開(kāi)部署請(qǐng)確保端口是通的。6.2 Attu 版本不兼容如果打開(kāi) Attu 后發(fā)現(xiàn)集合列表為空但數(shù)據(jù)明明在里面或者執(zhí)行查詢(xún)時(shí)報(bào)milvus collection not found十有八九是 Attu 的 proto 版本比 Milvus 老。你可以在 Attu 頁(yè)面右上角的設(shè)置里看連接的 Milvus 版本或者看 Attu 的 Release Notes。解決辦法很簡(jiǎn)單升級(jí) Attu 到與 Milvus 匹配的版本。我整理了一張對(duì)照表按這個(gè)來(lái)基本不會(huì)錯(cuò)Milvus 版本Attu 推薦版本備注2.2.x2.2.x老項(xiàng)目常用2.3.x2.3.x較穩(wěn)定2.4.x2.4.x 或內(nèi)置 WebUI內(nèi)置 WebUI 更舒服另外注意Milvus 2.4 開(kāi)始Attu 連接時(shí)默認(rèn)端口 19530我曾經(jīng)在 web UI 之間切換過(guò)結(jié)果同一個(gè)瀏覽器 session 混了導(dǎo)致數(shù)據(jù)看不到清理緩存或換個(gè)無(wú)痕窗口就好了。6.3 RAG 效果不理想如何調(diào)優(yōu)很多剛?cè)腴T(mén)的朋友調(diào) RAG搜索沒(méi)結(jié)果就覺(jué)得是 embedding 模型問(wèn)題其實(shí)大概率是切分方式和過(guò)濾條件的問(wèn)題。比如汽修故障碼 P0300缺火如果按系統(tǒng)切分成“發(fā)動(dòng)機(jī)系統(tǒng)”一個(gè)大塊再 embed 的時(shí)候整塊太長(zhǎng)信息被稀釋了。我的調(diào)優(yōu)順序建議先看召回片段是否相關(guān)。直接在 Milvus WebUI 里手動(dòng)查 query 的 top10。如果前 5 個(gè)都不相關(guān)那就是切分粒度或 embedding 問(wèn)題。如果相關(guān)的排在第 5 位之后那就是重排問(wèn)題。檢查 filter 條件是否太嚴(yán)。比如用戶(hù)沒(méi)填車(chē)型你默認(rèn)過(guò)濾car_model 那必然什么都查不到。應(yīng)該是“有車(chē)型就過(guò)濾沒(méi)有則跳過(guò)”。調(diào)整 overlap。chunk 之間的 overlap 對(duì)跨句語(yǔ)義有影響我測(cè)下來(lái) 50-100 token 的 overlap 對(duì)維修手冊(cè)比較合適。調(diào)整ef參數(shù)。在線(xiàn)服務(wù)里 ef 可以設(shè)為 64 提升速度但離線(xiàn)評(píng)估時(shí)用 256。如果你用 IVF 索引nprobe 通常設(shè)為 8-16數(shù)值太低召回很差。評(píng)估方面我建了一個(gè) 200 條真實(shí)問(wèn)題的評(píng)測(cè)集每條文成兩部分是否命中相關(guān)維修手冊(cè)、大模型答案是否讓修理工滿(mǎn)意。計(jì)算基本指標(biāo)如 hit5、MRR再加上人工打分。僅僅看向量相似度是不靠譜的因?yàn)樵?xún)問(wèn)題目表述和文檔差很遠(yuǎn)相似度數(shù)值不能完全代表語(yǔ)義相關(guān)性。6.4 FastAPI 并發(fā)與超時(shí)優(yōu)化RAG 鏈路里最慢的是調(diào)用大模型我用 Qwen2.5-14B 單卡部署單次生成平均 2-3 秒。如果用戶(hù)在 FastAPI 接口等太久前端會(huì)報(bào)超時(shí)。我這里做了兩個(gè)優(yōu)化第一用asynciohttpx.AsyncClient異步調(diào)用 LLM不要用同步 requests。同步會(huì)阻塞事件循環(huán)并發(fā)一高全部卡死。改成異步之后能支撐 20 個(gè)并發(fā)請(qǐng)求同時(shí)問(wèn)答。第二給 LLM 請(qǐng)求設(shè)置 timeout。我用 openai 的 async client 時(shí)timeout60秒但實(shí)際大部分請(qǐng)求 10 秒內(nèi)能完成。超時(shí)后做降級(jí)不回工單只返回一個(gè)固定提示“系統(tǒng)繁忙請(qǐng)稍后再試”。這個(gè)兜底非常重要不然大模型偶爾卡死了接口就一直掛著數(shù)據(jù)庫(kù)連接也會(huì)被耗盡。還有緩存。同一個(gè)問(wèn)題一周內(nèi)被問(wèn)超過(guò) 3 次完全可以走 Redis 緩存。我實(shí)現(xiàn)了一個(gè)簡(jiǎn)單邏輯把 query 語(yǔ)義 hash 到rag:cache:{md5}TTL 7 天命中了直接返回答案和之前的工單號(hào)。這樣可以顯著降低大模型壓力也提升用戶(hù)感知速度。7. 項(xiàng)目后續(xù)擴(kuò)展與個(gè)人經(jīng)驗(yàn)總結(jié)這套系統(tǒng)已經(jīng)在我們合作的一家連鎖維修廠(chǎng)跑了三個(gè)月從最初的知識(shí)庫(kù)只有 200 份手冊(cè)、一天幾十次問(wèn)答到現(xiàn)在沉淀了 5000 多條真實(shí)工單檢索準(zhǔn)確率大概提升了 15%。但這里有一個(gè)需要特別注意的問(wèn)題工單回寫(xiě)知識(shí)庫(kù)一定要做質(zhì)量過(guò)濾。有些技師隨便寫(xiě)的解決方法可能并不正確直接灌進(jìn)知識(shí)庫(kù)會(huì)污染數(shù)據(jù)源。我的建議是只在知識(shí)庫(kù)里寫(xiě)入狀態(tài)為“已閉環(huán)”且經(jīng)過(guò)主管審核的工單或者至少將工單數(shù)據(jù)權(quán)重調(diào)低避免帶偏后續(xù)檢索結(jié)果。另一個(gè)未來(lái)可以繼續(xù)擴(kuò)展的方向是視覺(jué)能力。很多汽修故障是需要看照片的比如底盤(pán)漏油、電瓶腐蝕只靠文本 RAG 有上限。目前我考慮再用 CLIP/ViT 把維修圖片也向量化存到 Milvus 的同一個(gè) collection 里然后做多模態(tài)搜索。FastAPI 這邊只要增加一個(gè)圖片上傳接口前端拍照就能查問(wèn)題。雖然這個(gè)還沒(méi)完全落地但架構(gòu)上已經(jīng)預(yù)留了向量字段和 metadata 的冗余空間。最后再分享一個(gè)運(yùn)維里的小技巧Milvus 數(shù)據(jù)備份不要只靠 etcd 快照。保險(xiǎn)的做法是定期用milvus_backup這個(gè)官方工具把 collection 數(shù)據(jù)導(dǎo)出到本地磁盤(pán)或者 OSS因?yàn)?etcd 只是元數(shù)據(jù)真正向量數(shù)據(jù)在 MinIO兩者都要備份。曾經(jīng)有一次我不小心刪了 MinIO 里的一個(gè) bucket結(jié)果整個(gè)集合全毀了恢復(fù)只能從備份中拉數(shù)據(jù)?，F(xiàn)在腳本每天晚上自動(dòng)備份算是花錢(qián)買(mǎi)教訓(xùn)。這套項(xiàng)目如果完全重做一遍我仍然會(huì)堅(jiān)持 FastAPI Milvus RAG 這個(gè)組合。FastAPI 的工程效率和類(lèi)型安全對(duì)業(yè)務(wù)快速迭代太友好了Milvus 雖然部署有些小坑但生產(chǎn)可用的特性和成熟度在開(kāi)源向量庫(kù)里是第一梯隊(duì)RAG 則讓 AI 能力真正貼合業(yè)務(wù)。希望這篇實(shí)操記錄能幫少走幾條彎路。 FastAPI+Milvus實(shí)現(xiàn)汽修RAG問(wèn)答與工單閉環(huán)實(shí)踐
1. 項(xiàng)目全景為什么汽修問(wèn)答需要 RAG 工單閉環(huán)做汽修信息化也有幾年了我接觸過(guò)的不少維修廠(chǎng)和連鎖門(mén)店都有一個(gè)很尷尬的現(xiàn)狀老師傅的經(jīng)驗(yàn)全在腦子里新人查故障手冊(cè)翻半天客服接電話(huà)被問(wèn)得啞口無(wú)言售后工單又是另一個(gè)系統(tǒng)里的死數(shù)據(jù)修完就存檔下次遇到類(lèi)似問(wèn)題還得從頭摸索。這套項(xiàng)目就是奔著解決這個(gè)痛點(diǎn)去的——用 FastAPI 搭后端服務(wù)用 Milvus 存向量知識(shí)用 RAG 讓大模型基于真實(shí)維修資料問(wèn)答同時(shí)把每一次問(wèn)答自動(dòng)關(guān)聯(lián)到工單流程里形成“提問(wèn)—解決—沉淀”的閉環(huán)。這個(gè)項(xiàng)目適合誰(shuí)參考首先是負(fù)責(zé)汽修門(mén)店數(shù)字化系統(tǒng)的后端工程師其次是研究 RAG 落地但找不到具體場(chǎng)景的技術(shù)同學(xué)還有想在生產(chǎn)環(huán)境用 Milvus 但對(duì)部署選型比較猶豫的人。我會(huì)把從環(huán)境搭建到接口聯(lián)調(diào)、再到工單流轉(zhuǎn)的完整路徑都寫(xiě)清楚包括實(shí)際踩過(guò)的坑。很多人一提到智能問(wèn)答就想到微調(diào)大模型這是最常見(jiàn)的誤區(qū)。汽修領(lǐng)域的故障現(xiàn)象、維修步驟、配件參數(shù)更新得很快微調(diào)一次成本高不說(shuō)知識(shí)還會(huì)過(guò)期。RAG 的思路更聰明——把維修手冊(cè)、技術(shù)通報(bào)、歷史工單切塊向量化存進(jìn) Milvus提問(wèn)時(shí)先檢索出最相關(guān)的知識(shí)片段再把這些片段作為上下文丟給大模型生成答案。這樣知識(shí)更新只需要重新灌庫(kù)模型本身不用動(dòng)。加上工單閉環(huán)之后系統(tǒng)就不再是“一次性問(wèn)答機(jī)器人”而是能持續(xù)從真實(shí)維修記錄里學(xué)到新東西的知識(shí)引擎。工單閉環(huán)是這個(gè)項(xiàng)目的靈魂。傳統(tǒng)問(wèn)答機(jī)器人答完就結(jié)束用戶(hù)問(wèn)完還得自己對(duì)著答案去干活干完了也沒(méi)有反饋。我設(shè)計(jì)的閉環(huán)是問(wèn)答結(jié)果不僅要返回自然語(yǔ)言答復(fù)還會(huì)拆解出建議的維修項(xiàng)目、工時(shí)、配件然后自動(dòng)生成一張草稿工單維修技師實(shí)際完成維修后工單狀態(tài)變更為“已完成”并回寫(xiě)結(jié)論系統(tǒng)定期把已完成的工單再向量化回 Milvus下次遇到相似故障就能檢索到真實(shí)維修案例。這套邏輯讓知識(shí)庫(kù)自己“生長(zhǎng)”越用越準(zhǔn)。2. 技術(shù)選型與架構(gòu)拆解2.1 FastAPI 作為服務(wù)層異步和自動(dòng)文檔是最大紅利后端框架我選 FastAPI 沒(méi)有太多猶豫。首先是異步支持RAG 鏈路里有大量 IO 操作——調(diào)向量庫(kù)查詢(xún)、調(diào)大模型接口、讀寫(xiě)數(shù)據(jù)庫(kù)用 async/await 能把并發(fā)吞吐?lián)纹饋?lái)比如汽修門(mén)店高峰期同時(shí)十幾個(gè)工位在查故障同步框架很容易把線(xiàn)程池打滿(mǎn)。其次是 FastAPI 自帶 OpenAPI 文檔前端、安卓、小程序都能直接看接口契約省掉了手動(dòng)維護(hù)文檔的時(shí)間。還有 Pydantic 做參數(shù)校驗(yàn)工單數(shù)據(jù)結(jié)構(gòu)復(fù)雜時(shí)嵌套模型定義得清清楚楚遠(yuǎn)比 Flask 手動(dòng)校驗(yàn)來(lái)得穩(wěn)妥。在這個(gè)項(xiàng)目里FastAPI 不只是做 HTTP 層它還承擔(dān)了流程編排的職責(zé)。一個(gè)典型的問(wèn)答請(qǐng)求進(jìn)來(lái)先經(jīng)過(guò)POST /api/rag/query然后服務(wù)內(nèi)部依次執(zhí)行查詢(xún) Milvus、拼裝 prompt、調(diào)用 LLM、解析結(jié)構(gòu)化結(jié)果、寫(xiě)工單草稿。每一步都是獨(dú)立的 service 函數(shù)用 FastAPI 的依賴(lài)注入把它們串起來(lái)。這樣寫(xiě)的好處是方便測(cè)試也方便以后替換組件——比如換 embedding 模型或者加一個(gè)多路召回都只是在 service 內(nèi)部改。2.2 Milvus 向量數(shù)據(jù)庫(kù)選型與版本坑選 Milvus 而不是其他向量庫(kù)核心原因是它支持集合collection級(jí)別的動(dòng)態(tài) Schema這對(duì)汽修知識(shí)庫(kù)很重要。維修手冊(cè)和工單的字段差異很大有的需要存故障碼有的需要存車(chē)型用固定 Schema 的庫(kù)會(huì)很痛苦。Milvus 從 2.x 開(kāi)始支持 JSON 字段和動(dòng)態(tài)字段我可以把各種元數(shù)據(jù)一股腦塞進(jìn)去查詢(xún)時(shí)再用 filter 精確過(guò)濾比純向量檢索加后置過(guò)濾要高效得多。但這玩意兒的版本是個(gè)深坑。我最早用的是 Milvus 2.2.x后來(lái)為了用新特性升級(jí)到 2.4.x結(jié)果發(fā)現(xiàn) Attu 客戶(hù)端版本不一樣連接方式全變了。Attu 是一個(gè) Milvus 的可視化管理工具如果你只裝了 Milvus 服務(wù)端而沒(méi)裝 Attu可視化調(diào)試會(huì)非常痛苦。這里強(qiáng)調(diào)一下版本對(duì)應(yīng)關(guān)系A(chǔ)ttu 2.3.0 及以前基本兼容 Milvus 2.2/2.3Milvus 2.4 的 WebUI 其實(shí)是內(nèi)置的不再?gòu)?qiáng)烈依賴(lài) Attu但很多人還是習(xí)慣用 Attu 看數(shù)據(jù)。我是裝了 Milvus 2.4.1然后直接用內(nèi)置 WebUI默認(rèn)端口 9091再用 Attu 2.4.x 連接流暢度還行。如果你剛上手建議就裝 Milvus 2.4.x 版本然后 Access 方式別搞錯(cuò)否則你會(huì)一頭扎進(jìn)“ETCD 報(bào)錯(cuò)”里出不來(lái)。2.3 RAG 流程整體編排從 query 到 answer 的完整鏈路RAG 不是簡(jiǎn)單的“向量檢索 大模型生成”細(xì)拆有以下幾步query 預(yù)處理對(duì)用戶(hù)輸入做去噪、同義詞擴(kuò)展比如“車(chē)子啟動(dòng)不了”擴(kuò)展為“無(wú)法啟動(dòng)”、“打不著火”這些規(guī)則可以先用正則和詞典做不要一開(kāi)始就上模型。embedding 落入向量庫(kù)用同一個(gè) embedding 模型把 query 編碼成向量這一步必須保證 encode 模型和入庫(kù)時(shí)一致否則向量空間錯(cuò)位檢索結(jié)果一塌糊涂。向量召回 元數(shù)據(jù)過(guò)濾先按車(chē)型、系統(tǒng)發(fā)動(dòng)機(jī)/變速箱/電氣過(guò)濾再在子集里算相似度召回 top-k。重排如果召回結(jié)果多了可以用簡(jiǎn)單的 RRF倒數(shù)排名融合加上關(guān)鍵詞 overlap 調(diào)權(quán)比直接依賴(lài)向量距離更穩(wěn)。prompt 組裝把召回片段拼成上下文加上系統(tǒng)提示詞要求模型只依據(jù)上下文回答不要瞎編。結(jié)構(gòu)化抽取讓模型輸出建議的維修項(xiàng)目、工時(shí)、配件存到工單草稿里。我用 langchain 還是直接手寫(xiě)坦率講這個(gè)場(chǎng)景我建議手寫(xiě) pipeline。LangChain 的抽象層確實(shí)方便但版本升級(jí)太頻繁出了問(wèn)題很難排查。RAG 核心鏈路其實(shí)不復(fù)雜自己用 Python 寫(xiě)也就 100 多行。后面我會(huì)把關(guān)鍵代碼貼出來(lái)。3. 環(huán)境準(zhǔn)備與 Milvus 本地部署非 Docker 實(shí)測(cè)3.1 Windows / Linux 下 Milvus 安裝細(xì)節(jié)Milvus 官方推薦用 Docker Compose 部署但是很多公司內(nèi)網(wǎng)或者個(gè)人開(kāi)發(fā)機(jī)沒(méi)有 Docker 環(huán)境尤其 Windows 下要裝 Docker Desktop 一堆麻煩事。我實(shí)際測(cè)試過(guò)Milvus 2.4.x 也提供了不帶 Docker 的安裝方式這里給出幾個(gè)路線(xiàn)。路線(xiàn)一Windows 下用 Docker Desktop 跑。雖然用到了 Docker但只要你裝好 Docker Desktopdocker-compose.yml一拉就能跑起來(lái)。這里有個(gè)坑Windows 下 Milvus 默認(rèn)掛載卷的路徑如果包含中文或空格容器會(huì)起不來(lái)所以最好把目錄設(shè)置成純英文。路線(xiàn)二直接上 Linux 裸機(jī)裝。以 Ubuntu 22.04 為例不依賴(lài) Docker 的安裝步驟大概是這樣先裝 etcd再裝 MinIO然后再裝 Milvus standalone單機(jī)版。Milvus standalone 雖然內(nèi)部依賴(lài) etcd 和 MinIO但它有自己的啟動(dòng)腳本只要配置里指向 etcd 和 MinIO 的端點(diǎn)就行。我用的版本組合是etcd 3.5.9、MinIO RELEASE.2023-03-20T00-00-00Z、Milvus 2.4.1。順序很重要先啟動(dòng) etcd再 MinIO最后啟動(dòng) Milvus。Windows 純本機(jī)非 Docker 安裝我沒(méi)走通官方對(duì) Windows 原生支持不足建議如果不想用 Docker 就裝 WSL2 跑 Ubuntu然后在 WSL 里按照 Linux 方式裝。我測(cè)試下來(lái)這套組合最穩(wěn)定。3.2 Attu 客戶(hù)端連接不同 Milvus 版本的問(wèn)題很多人第一次用 Attu 都懵因?yàn)?Attu 和 Milvus 的版本沒(méi)有嚴(yán)格一一對(duì)應(yīng)。Attu 的 GitHub 倉(cāng)庫(kù)說(shuō)支持 2.x 大版本但實(shí)際連接時(shí)如果 Milvus 版本太新接口路徑變了Attu 會(huì)顯示一堆空數(shù)據(jù)或者直接報(bào)錯(cuò)。比如用 Attu 2.3.8 連 Milvus 2.4.1集群信息能顯示但查詢(xún)數(shù)據(jù)時(shí)可能拿不到向量字段的標(biāo)量值。我的經(jīng)驗(yàn)是Milvus 2.4.x 盡量用 Attu v2.4.0 以上版本Milvus 2.2/2.3 則用 Attu 2.3.x。還有一個(gè)更省心的方法——Milvus 2.4 自帶的 WebUI啟動(dòng)后瀏覽器訪(fǎng)問(wèn)http://localhost:9091/webui能看集合、做搜索、看日志。我后來(lái)基本都在 WebUI 里排查數(shù)據(jù)Attu 只是偶爾用來(lái)做數(shù)據(jù)管理。3.3 etcd 與存儲(chǔ)配置要點(diǎn)Milvus 的元數(shù)據(jù)、分片信息、索引狀態(tài)都存在 etcd 里etcd 掛了 Milvus 就廢了。我有一個(gè)血淚教訓(xùn)之前搭建時(shí) etcd 用的默認(rèn)端口 2379結(jié)果跟本地另一個(gè)服務(wù)沖突Milvus 啟動(dòng)過(guò)程一直在 etcd 連接重試日志大量刷etcdserver: request timed out。排查了半天才找到元兇。建議部署時(shí)把 etcd 的listen-client-urls和listen-peer-urls分開(kāi)客戶(hù)端地址用本機(jī) IP而不要用0.0.0.0這樣安全也好排障。MinIO 的 bucket 名稱(chēng)可以自己定義但 Milvus 啟動(dòng)時(shí)會(huì)自動(dòng)建 bucket如果你之前手動(dòng)建過(guò)同名 bucket 且權(quán)限不對(duì)初始化會(huì)失敗所以最省事的做法是讓 Milvus 自動(dòng)創(chuàng)建。另外Milvus 的配置文件milvus.yaml里有一個(gè)common.threadCount參數(shù)默認(rèn)是 CPU 核數(shù)。如果機(jī)器 CPU 核不多又同時(shí)跑 embedding 模型容易導(dǎo)致環(huán)境卡死。我調(diào)到 8效果穩(wěn)定。4. 后端核心實(shí)現(xiàn)FastAPI 接口與 RAG 鏈路4.1 數(shù)據(jù)切分與向量化汽修數(shù)據(jù)源五花八門(mén)PDF 維修手冊(cè)、Excel 零件表、歷史工單文本。我統(tǒng)一先轉(zhuǎn)成純文本再做結(jié)構(gòu)化切分。直接按固定字符切是最蠢的會(huì)把一句話(huà)砍成兩半。我用的策略是分層切分先按一級(jí)目錄比如“發(fā)動(dòng)機(jī)系統(tǒng)”“變速箱系統(tǒng)”分成大塊再按最小語(yǔ)義單元——段落和列表項(xiàng)——切成 chunk每個(gè) chunk 控制在 500 到 800 個(gè) tokenchunk 之間保留 50 個(gè) token 的 overlap。這里有一個(gè)小技巧對(duì)于維修手冊(cè)把“故障碼 可能原因 排查步驟”作為一個(gè)整體切因?yàn)檫@三者是一個(gè)完整檢索單元拆開(kāi)了檢索噪音很大。對(duì)于歷史工單我字段里用fault_desc、solution、parts_used分別存向量化時(shí)只對(duì)fault_desc solution做 embeddingparts 作為過(guò)濾條件。embedding 模型我選擇了bge-large-zh-v1.5中文場(chǎng)景效果不錯(cuò)維度是 1024。Milvus 建立 collection 時(shí)向量字段類(lèi)型設(shè)為 FLOAT_VECTORdim 1024。如果用 OpenAI 的 embeddingAPI 有調(diào)用費(fèi)用內(nèi)網(wǎng)部署不方便。bge 模型在本地用sentence-transformers加載速度也挺快。切分和向量化代碼大概長(zhǎng)這樣from sentence_transformers import SentenceTransformer from pymilvus import Collection, FieldSchema, CollectionSchema, DataType, connections model SentenceTransformer(BAAI/bge-large-zh-v1.5) def embed_texts(texts): return model.encode(texts, normalize_embeddingsTrue) fields [ FieldSchema(nameid, dtypeDataType.INT64, is_primaryTrue, auto_idFalse), FieldSchema(nametext, dtypeDataType.VARCHAR, max_length65535), FieldSchema(namecar_model, dtypeDataType.VARCHAR, max_length128), FieldSchema(namesystem_tag, dtypeDataType.VARCHAR, max_length64), FieldSchema(namevector, dtypeDataType.FLOAT_VECTOR, dim1024), FieldSchema(namemetadata, dtypeDataType.JSON), ] schema CollectionSchema(fields, descriptioncar repair knowledge) col Collection(namecar_repair, schemaschema)4.2 檢索邏輯dense vector search 的踩坑檢索最簡(jiǎn)單的方式就是col.search()傳 query 向量取 top_k。但如果直接全庫(kù)搜索會(huì)把完全不同的故障問(wèn)混進(jìn)來(lái)。比如用戶(hù)問(wèn)“怠速不穩(wěn)”你召回的是“怠速馬達(dá)更換”這算相關(guān)但如果召回的是“空調(diào)不制冷”那就是噪音。所以要先 filter 再 search用expr參數(shù)把車(chē)型、系統(tǒng)限定住。踩過(guò)最大的坑是metric_type的選擇。Milvus 支持IP內(nèi)積、L2歐氏距離、COSINE。我用 bge 模型的時(shí)候normalize_embeddingsTrue之后用 IP 和 COSINE 等價(jià)但別用 L2。具體看模型說(shuō)明bge 官方建議用 COSINE。若 embedding 沒(méi)歸一化IP 的分?jǐn)?shù)范圍不穩(wěn)定檢索前幾名容易錯(cuò)。還有一個(gè)容易被忽略的是search_params里的ef參數(shù)針對(duì) HNSW 索引。索引類(lèi)型我用HNSW時(shí)ef 越大召回越準(zhǔn)但越慢。在線(xiàn)問(wèn)答場(chǎng)景我設(shè)ef128這能兼顧精度與速度。另一個(gè)參數(shù)nprobe是 IVF 索引的如果老版本用了 IVF 別搞混。檢索代碼加上過(guò)濾條件后query_embedding embed_texts([query])[0].tolist() search_params {metric_type: COSINE, params: {ef: 128}} expr system_tag in [發(fā)動(dòng)機(jī), 電氣] result col.search(data[query_embedding], anns_fieldvector, paramsearch_params, limit5, exprexpr, output_fields[text, car_model])注意expr里字符串要用單引號(hào)包著字段名不能用反引號(hào)。我剛開(kāi)始用習(xí)慣了 SQL 的語(yǔ)法寫(xiě)著寫(xiě)著就報(bào)語(yǔ)法錯(cuò)誤。Milvus 的 expr 語(yǔ)法基本兼容過(guò)濾表達(dá)式的子集但 JSON 字段訪(fǎng)問(wèn)要用metadata[part_no]這種用法具體官方文檔要看一眼。4.3 生成與工單創(chuàng)建聯(lián)動(dòng)召回得到 top-5 片段后就要組裝 prompt。我用了兩個(gè)模型一個(gè)是本地部署的 Qwen2.5-14B通過(guò) vLLM 部署另一個(gè)是 OpenAI 兼容接口?？紤]到大模型輸出的穩(wěn)定性我把 prompt 寫(xiě)得非常死板你是汽修專(zhuān)家。只依據(jù)以下資料回答問(wèn)題不要編造。 資料 1. [片段1] 2. [片段2] ... 問(wèn)題{user_query} 請(qǐng)輸出 JSON字段包括 - answer: 自然語(yǔ)言回答 - likely_causes: 可能原因數(shù)組 - suggestions: 建議操作列表 - parts: 建議配件列表每個(gè)包含名稱(chēng)和數(shù)量 - estimated_hours: 預(yù)計(jì)工時(shí)數(shù)字 如果資料信息不足answer 里明確說(shuō)“資料中未找到請(qǐng)人工核實(shí)”。為什么要讓模型輸出 JSON因?yàn)槲倚枰苯影焉山Y(jié)果映射到工單草稿。FastAPI 的響應(yīng)模型天然支持 Pydantic大模型輸出 JSON 后我用json.loads解析再存為工單對(duì)象的字段。如果允許模型自由發(fā)揮那工單數(shù)據(jù)就是一堆垃圾。在 FastAPI 里創(chuàng)建工單的接口和問(wèn)答接口分開(kāi)更清晰app.post(/api/rag/query) async def rag_query(req: QueryRequest): contexts search_milvus(req) messages build_prompt(contexts, req.query) llm_resp await call_llm(messages) parsed parse_json(llm_resp) draft_id await create_work_order_from_parsed(req, parsed) return {answer: parsed[answer], draft_work_order_id: draft_id}這一步關(guān)聯(lián)了問(wèn)答和工單問(wèn)答結(jié)果不只是給用戶(hù)看的同時(shí)已經(jīng)是半結(jié)構(gòu)化工單。前端可以顯示“已生成草稿工單工單編號(hào) WO-20250521-001”用戶(hù)確認(rèn)后即可進(jìn)入維修流程。5. 工單閉環(huán)從智能問(wèn)答到執(zhí)行反饋5.1 工單數(shù)據(jù)結(jié)構(gòu)設(shè)計(jì)工單表我用 PostgreSQL 存儲(chǔ)但核心業(yè)務(wù)邏輯在 FastAPI 中處理下面是關(guān)鍵的字段設(shè)計(jì)字段名類(lèi)型說(shuō)明work_order_idvarchar工單號(hào)格式 WO-YYYYMMDD-NNNquery_texttext原始問(wèn)題answer_texttext大模型生成的答案car_modelvarchar車(chē)型vinvarchar車(chē)架號(hào)fault_codevarchar故障碼可為空l(shuí)ikely_causesjsonb可能原因數(shù)組suggestionsjsonb建議操作列表partsjsonb配件列表名稱(chēng)、數(shù)量estimated_hoursnumeric預(yù)計(jì)工時(shí)statusvarchar狀態(tài)DRAFT/IN_PROGRESS/DONE/CLOSEDactual_solutiontext修理工實(shí)際處理方法閉環(huán)關(guān)鍵actual_partsjsonb實(shí)際使用配件created_attimestamp創(chuàng)建時(shí)間closed_attimestamp關(guān)閉時(shí)間設(shè)計(jì)時(shí)我特別加了actual_solution和actual_parts。這是跟普通問(wèn)答系統(tǒng)最大的不同問(wèn)答結(jié)束后系統(tǒng)并沒(méi)有完事它等著維修技師干完活把結(jié)果填回來(lái)。有了這兩列才能持續(xù)更新知識(shí)庫(kù)。5.2 問(wèn)答結(jié)果如何映射為工單在create_work_order_from_parsed里面我把解析后的 JSON 映射到上面的表。這里有一個(gè)細(xì)節(jié)如果用戶(hù)問(wèn)的是“這個(gè)故障代碼 P0300 是什么意思”生成結(jié)果里可能沒(méi)有具體配件estimated_hours 可能是 null。沒(méi)關(guān)系工單草稿允許空值維修技師在確認(rèn)草稿時(shí)可以補(bǔ)充。但是如果用戶(hù)問(wèn)的是“換機(jī)油”系統(tǒng)應(yīng)該能自動(dòng)預(yù)測(cè)工時(shí)和機(jī)油濾芯配件這就要靠 prompt 引導(dǎo)。我在 prompt 里增加了規(guī)則“如果問(wèn)題明顯是維修請(qǐng)求必須輸出 parts、estimated_hours如果只是知識(shí)詢(xún)問(wèn)parts 可以為空數(shù)組”。這樣能減少垃圾工單的產(chǎn)生。另外工單創(chuàng)建前我會(huì)調(diào)用一個(gè)簡(jiǎn)單的去重函數(shù)根據(jù)car_model query_text 時(shí)間范圍最近1小時(shí)判斷有沒(méi)有重復(fù)工單防止用戶(hù)一直點(diǎn)同一個(gè)按鈕刷出來(lái)一堆草稿。5.3 閉環(huán)反饋與知識(shí)庫(kù)更新閉環(huán)的落地點(diǎn)在于每天凌晨跑一個(gè)批處理腳本把最近 24 小時(shí)狀態(tài)為CLOSED且actual_solution非空的工單再次切分向量化后寫(xiě)入 Milvus。寫(xiě)入的時(shí)候用text 故障描述 query_text 實(shí)際解決 actual_solution再附上實(shí)際的配件、車(chē)型等信息。這樣知識(shí)庫(kù)里會(huì)不斷加入真實(shí)維修案例而不是只有官方手冊(cè)內(nèi)容。同時(shí)我會(huì)更新舊數(shù)據(jù)的knowledge_source字段讓它區(qū)分是官方手冊(cè)還是歷史工單。檢索時(shí)可以把來(lái)源權(quán)重調(diào)高一點(diǎn)比如官方手冊(cè)的metadata[source]為manual工單的為work_order在重排階段對(duì)work_order的命中做一個(gè)小激勵(lì)因?yàn)檎鎸?shí)維修案例往往更有參考價(jià)值。這一套閉環(huán)跑起來(lái)后系統(tǒng)越用越懂你們門(mén)店的常見(jiàn)問(wèn)題。舉個(gè)例子某品牌車(chē)在店里經(jīng)常出現(xiàn)某個(gè)通病官方手冊(cè)沒(méi)寫(xiě)但第一個(gè)維修師傅手工填了實(shí)際解決過(guò)程之后第二個(gè)師傅再問(wèn)就能檢索到。這就是閉環(huán)的意義。6. 常見(jiàn)問(wèn)題與排查實(shí)錄6.1 Milvus 連接失敗與 etcd 問(wèn)題最典型的現(xiàn)象是 FastAPI 啟動(dòng)時(shí)connections.connect(aliasdefault, hostlocalhost, port19530)報(bào)連接超時(shí)。先別急著查 Milvus 本身先看 etcd 是否正常。排查步驟檢查 etcd 進(jìn)程ps aux | grep etcd。如果沒(méi)有啟動(dòng)/path/to/etcd --data-dir/data/etcd --listen-client-urlshttp://0.0.0.0:2379 --advertise-client-urlshttp://0.0.0.0:2379。檢查 Milvus 日志/var/log/milvus/server.log。如果看到grpc: addrConn.createTransport failed大概率是 Milvus 配置里的 etcd 地址寫(xiě)錯(cuò)了。驗(yàn)證 etcd 連通性curl http://localhost:2379/health返回{health:true}才正常。我遇到最扯的一次是 etcd 啟動(dòng)成功了但防火墻把 2379 端口擋住了Milvus 進(jìn)程在另外一臺(tái)機(jī)器上連不上。所以如果你把 etcd 和 Milvus 分開(kāi)部署請(qǐng)確保端口是通的。6.2 Attu 版本不兼容如果打開(kāi) Attu 后發(fā)現(xiàn)集合列表為空但數(shù)據(jù)明明在里面或者執(zhí)行查詢(xún)時(shí)報(bào)milvus collection not found十有八九是 Attu 的 proto 版本比 Milvus 老。你可以在 Attu 頁(yè)面右上角的設(shè)置里看連接的 Milvus 版本或者看 Attu 的 Release Notes。解決辦法很簡(jiǎn)單升級(jí) Attu 到與 Milvus 匹配的版本。我整理了一張對(duì)照表按這個(gè)來(lái)基本不會(huì)錯(cuò)Milvus 版本Attu 推薦版本備注2.2.x2.2.x老項(xiàng)目常用2.3.x2.3.x較穩(wěn)定2.4.x2.4.x 或內(nèi)置 WebUI內(nèi)置 WebUI 更舒服另外注意Milvus 2.4 開(kāi)始Attu 連接時(shí)默認(rèn)端口 19530我曾經(jīng)在 web UI 之間切換過(guò)結(jié)果同一個(gè)瀏覽器 session 混了導(dǎo)致數(shù)據(jù)看不到清理緩存或換個(gè)無(wú)痕窗口就好了。6.3 RAG 效果不理想如何調(diào)優(yōu)很多剛?cè)腴T(mén)的朋友調(diào) RAG搜索沒(méi)結(jié)果就覺(jué)得是 embedding 模型問(wèn)題其實(shí)大概率是切分方式和過(guò)濾條件的問(wèn)題。比如汽修故障碼 P0300缺火如果按系統(tǒng)切分成“發(fā)動(dòng)機(jī)系統(tǒng)”一個(gè)大塊再 embed 的時(shí)候整塊太長(zhǎng)信息被稀釋了。我的調(diào)優(yōu)順序建議先看召回片段是否相關(guān)。直接在 Milvus WebUI 里手動(dòng)查 query 的 top10。如果前 5 個(gè)都不相關(guān)那就是切分粒度或 embedding 問(wèn)題。如果相關(guān)的排在第 5 位之后那就是重排問(wèn)題。檢查 filter 條件是否太嚴(yán)。比如用戶(hù)沒(méi)填車(chē)型你默認(rèn)過(guò)濾car_model 那必然什么都查不到。應(yīng)該是“有車(chē)型就過(guò)濾沒(méi)有則跳過(guò)”。調(diào)整 overlap。chunk 之間的 overlap 對(duì)跨句語(yǔ)義有影響我測(cè)下來(lái) 50-100 token 的 overlap 對(duì)維修手冊(cè)比較合適。調(diào)整ef參數(shù)。在線(xiàn)服務(wù)里 ef 可以設(shè)為 64 提升速度但離線(xiàn)評(píng)估時(shí)用 256。如果你用 IVF 索引nprobe 通常設(shè)為 8-16數(shù)值太低召回很差。評(píng)估方面我建了一個(gè) 200 條真實(shí)問(wèn)題的評(píng)測(cè)集每條文成兩部分是否命中相關(guān)維修手冊(cè)、大模型答案是否讓修理工滿(mǎn)意。計(jì)算基本指標(biāo)如 hit5、MRR再加上人工打分。僅僅看向量相似度是不靠譜的因?yàn)樵?xún)問(wèn)題目表述和文檔差很遠(yuǎn)相似度數(shù)值不能完全代表語(yǔ)義相關(guān)性。6.4 FastAPI 并發(fā)與超時(shí)優(yōu)化RAG 鏈路里最慢的是調(diào)用大模型我用 Qwen2.5-14B 單卡部署單次生成平均 2-3 秒。如果用戶(hù)在 FastAPI 接口等太久前端會(huì)報(bào)超時(shí)。我這里做了兩個(gè)優(yōu)化第一用asynciohttpx.AsyncClient異步調(diào)用 LLM不要用同步 requests。同步會(huì)阻塞事件循環(huán)并發(fā)一高全部卡死。改成異步之后能支撐 20 個(gè)并發(fā)請(qǐng)求同時(shí)問(wèn)答。第二給 LLM 請(qǐng)求設(shè)置 timeout。我用 openai 的 async client 時(shí)timeout60秒但實(shí)際大部分請(qǐng)求 10 秒內(nèi)能完成。超時(shí)后做降級(jí)不回工單只返回一個(gè)固定提示“系統(tǒng)繁忙請(qǐng)稍后再試”。這個(gè)兜底非常重要不然大模型偶爾卡死了接口就一直掛著數(shù)據(jù)庫(kù)連接也會(huì)被耗盡。還有緩存。同一個(gè)問(wèn)題一周內(nèi)被問(wèn)超過(guò) 3 次完全可以走 Redis 緩存。我實(shí)現(xiàn)了一個(gè)簡(jiǎn)單邏輯把 query 語(yǔ)義 hash 到rag:cache:{md5}TTL 7 天命中了直接返回答案和之前的工單號(hào)。這樣可以顯著降低大模型壓力也提升用戶(hù)感知速度。7. 項(xiàng)目后續(xù)擴(kuò)展與個(gè)人經(jīng)驗(yàn)總結(jié)這套系統(tǒng)已經(jīng)在我們合作的一家連鎖維修廠(chǎng)跑了三個(gè)月從最初的知識(shí)庫(kù)只有 200 份手冊(cè)、一天幾十次問(wèn)答到現(xiàn)在沉淀了 5000 多條真實(shí)工單檢索準(zhǔn)確率大概提升了 15%。但這里有一個(gè)需要特別注意的問(wèn)題工單回寫(xiě)知識(shí)庫(kù)一定要做質(zhì)量過(guò)濾。有些技師隨便寫(xiě)的解決方法可能并不正確直接灌進(jìn)知識(shí)庫(kù)會(huì)污染數(shù)據(jù)源。我的建議是只在知識(shí)庫(kù)里寫(xiě)入狀態(tài)為“已閉環(huán)”且經(jīng)過(guò)主管審核的工單或者至少將工單數(shù)據(jù)權(quán)重調(diào)低避免帶偏后續(xù)檢索結(jié)果。另一個(gè)未來(lái)可以繼續(xù)擴(kuò)展的方向是視覺(jué)能力。很多汽修故障是需要看照片的比如底盤(pán)漏油、電瓶腐蝕只靠文本 RAG 有上限。目前我考慮再用 CLIP/ViT 把維修圖片也向量化存到 Milvus 的同一個(gè) collection 里然后做多模態(tài)搜索。FastAPI 這邊只要增加一個(gè)圖片上傳接口前端拍照就能查問(wèn)題。雖然這個(gè)還沒(méi)完全落地但架構(gòu)上已經(jīng)預(yù)留了向量字段和 metadata 的冗余空間。最后再分享一個(gè)運(yùn)維里的小技巧Milvus 數(shù)據(jù)備份不要只靠 etcd 快照。保險(xiǎn)的做法是定期用milvus_backup這個(gè)官方工具把 collection 數(shù)據(jù)導(dǎo)出到本地磁盤(pán)或者 OSS因?yàn)?etcd 只是元數(shù)據(jù)真正向量數(shù)據(jù)在 MinIO兩者都要備份。曾經(jīng)有一次我不小心刪了 MinIO 里的一個(gè) bucket結(jié)果整個(gè)集合全毀了恢復(fù)只能從備份中拉數(shù)據(jù)?，F(xiàn)在腳本每天晚上自動(dòng)備份算是花錢(qián)買(mǎi)教訓(xùn)。這套項(xiàng)目如果完全重做一遍我仍然會(huì)堅(jiān)持 FastAPI Milvus RAG 這個(gè)組合。FastAPI 的工程效率和類(lèi)型安全對(duì)業(yè)務(wù)快速迭代太友好了Milvus 雖然部署有些小坑但生產(chǎn)可用的特性和成熟度在開(kāi)源向量庫(kù)里是第一梯隊(duì)RAG 則讓 AI 能力真正貼合業(yè)務(wù)。希望這篇實(shí)操記錄能幫少走幾條彎路。