做 UniRAG 之前我其實先寫了三遍單租戶的 RAG Demo每次都是跑通就丟。真正讓我決定認真做一個多租戶 RAG 平臺的是一次內(nèi)部排期三條業(yè)務(wù)線幾乎同時要做知識庫問答如果各搭各的就會有三個向量庫、三套 Embedding 服務(wù)、三份檢索邏輯全都得長期養(yǎng)著而底層又都是同一批模型和同樣的切分規(guī)則。與其重復(fù)造輪子不如把多租戶當成 RAG 平臺的一等公民從根上重新設(shè)計。UniRAG 就是這么來的。這篇文章不聊 PPT 架構(gòu)只聊我在設(shè)計 UniRAG 時真正糾結(jié)過的取舍以及踩完坑之后沉淀下來的經(jīng)驗。內(nèi)容大致覆蓋這幾塊多租戶到底隔離什么、索引層怎么選型、向量知識庫和結(jié)構(gòu)知識庫怎么共存、檢索參數(shù)怎么定、在 Mac 上怎么從零跑通一個最小多租戶 RAG以及上線后最常見的故障排查。適合正在做 RAG 平臺化、知識庫產(chǎn)品化或者純粹想把多租戶概念落到代碼里的朋友。1. 多租戶 RAG 的問題清單不是把數(shù)據(jù)庫加個字段就行1.1 單租戶到多租戶真正變化的是“邊界”先說一個最常見的誤解很多人覺得多租戶 RAG 就是在文檔表里加一個tenant_id查詢的時候帶上這個字段就完事了。如果是給公司內(nèi)部兩三個人用的工具這么干確實夠了。但 UniRAG 要服務(wù)的都是獨立業(yè)務(wù)單元每個業(yè)務(wù)單元可能有自己的術(shù)語、自己的權(quán)限范圍、自己的文檔更新節(jié)奏甚至自己的模型偏好。單租戶系統(tǒng)只需要考慮“怎么把答案答對”多租戶系統(tǒng)要考慮的是三個邊界數(shù)據(jù)邊界租戶 A 的文檔、切片、檢索結(jié)果絕對不能出現(xiàn)在租戶 B 的上下文里。資源邊界某個租戶如果批量導(dǎo)入文檔或頻繁調(diào)用檢索不能把共享的向量庫和模型服務(wù)打滿導(dǎo)致其他租戶集體超時。配置邊界每個租戶的切分參數(shù)、提示詞模板、知識庫路由規(guī)則都是獨立的改一個租戶的配置不能影響另一個。這三個邊界不是同一個維度的東西。數(shù)據(jù)邊界靠檢索鏈路保證資源邊界靠配額和限流保證配置邊界靠配置管理保證。如果一開始腦子里沒有領(lǐng)域模型寫到后面一定是所有判斷都散在代碼里等租戶多了會很難收場。另外看開源社區(qū)的動向很有意思像 Dify 社區(qū)版這樣的項目也開始在往多租戶上使勁說明這確實是個共性問題。不過開源平臺給的往往是通用能力真正接進自己的業(yè)務(wù)體系后還是要回答“你的租戶到底是什么、怎么隔離、怎么計費、怎么審計”這些問題這些才是 UniRAG 這類自建平臺的核心工作量。1.2 隔離級別怎么選從輕隔離到重隔離再具體說隔離。我梳理了一遍RAG 平臺常見的隔離方案大概分三檔第一檔是共享向量索引通過元數(shù)據(jù)里攜帶租戶 ID 做過濾。這是最省資源的方式索引只有一份存儲和內(nèi)存開銷最小但前提是檢索鏈路的每一環(huán)都要強制帶租戶上下文只要漏一處就會出現(xiàn)文檔串味兒。第二檔是按租戶分 Collection 或分 Partition。索引還是跑在同一個集群里但物理上分區(qū)了隔離性比第一檔好查詢時也不用把租戶過濾條件寫進每一個 filter性能通常更可控。缺點是租戶數(shù)量大了以后collection 數(shù)量膨脹運維模型會變復(fù)雜需要配套自動創(chuàng)建和回收機制。第三檔是每個租戶一套獨立集群。隔離最徹底出問題不容易互相波及但成本非常高無論是機器資源還是運維人力。除非是數(shù)據(jù)合規(guī)要求極高的場景否則沒有必要一上來就做。UniRAG 最終的選擇是“共享索引 租戶過濾為主敏感租戶獨立 Collection 為輔”。這個組合看起來不那么純粹但勝在靈活普通租戶默認進共享區(qū)有合規(guī)要求或數(shù)據(jù)量特別大的租戶通過配置把它提升到獨立 Collection平臺代碼不用改只改租戶的部署策略。選擇這套方案的核心邏輯是“按需隔離而不是按想象隔離”。如果一開始就全做獨立索引100 個租戶就是 100 個索引Embedding 的內(nèi)存占用和后臺任務(wù)數(shù)量都會線性上漲前期根本撐不住。反過來如果全做共享索引遇到一個每天導(dǎo)入幾萬份文檔的大租戶檢索質(zhì)量和你能不能兜住這個并發(fā)都是問題。所以我把隔離級別做成了租戶配置項也不建議把某個隔離方式寫死在代碼里。1.3 UnI RAG 設(shè)計前我定義的四條鐵律動工之前我給自己定了四條約束后面所有細節(jié)的取舍都以這四條為準任何入庫和檢索動作都必須有租戶上下文。沒有租戶 ID 的調(diào)用直接拒絕而不是默認丟進某個公共空間。入庫鏈路和檢索鏈路必須走同一條租戶映射。也就是說文檔切片寫進索引的租戶標簽和查詢時用來過濾的租戶標簽必須來自同一個配置源。任何一次問答輸出都必須能回溯到來源片段和租戶信息。不然出了問題連是哪個租戶的哪份文檔污染了結(jié)果都查不出來。默認不允許租戶自建模型或自選 Embedding除非通過平臺申請。因為這會讓成本模型徹底失控。這幾條看著像廢話但實際項目里很容易被打破。比如有人圖省事直接在某個庫文件里硬編碼了一個tenant_idpublic后面所有沒顯式傳租戶的調(diào)用都跑到了公共區(qū)這就是典型的“默認值污染”。我后來要求所有接口都必須顯式傳遞租戶信息連默認租戶都不給寧可多寫幾行代碼也不留后門。2. UniRAG 的整體架構(gòu)控制面和數(shù)據(jù)面分離2.1 架構(gòu)分層的核心思路UniRAG 的架構(gòu)沒有太多新鮮東西就是經(jīng)典的“控制面 數(shù)據(jù)面”分離?？刂泼尕撠熥鈶艄芾?、知識源注冊、模型路由、參數(shù)配置數(shù)據(jù)面負責文檔采集、文本切分、向量化、索引寫入、檢索問答。為什么要分這么清楚因為這兩部分的變更頻率完全不一樣?？刂泼娴呐渲每赡苊刻於家冃略鲆粋€租戶、調(diào)整某個知識庫的召回參數(shù)、換一個提示詞模板數(shù)據(jù)面底層則相對穩(wěn)定索引結(jié)構(gòu)、Embedding 模型、檢索服務(wù)不會頻繁改。把它們混在一個模塊里會導(dǎo)致“只是為了改一個配置就得重新發(fā)一版檢索服務(wù)”非常影響迭代效率。在技術(shù)選型上UniRAG 采用了一套相對務(wù)實的組合服務(wù)框架用 FastAPI異步接口在檢索場景下天然合適。向量存儲用 Qdrant支持 payload 過濾對于“共享索引 租戶過濾”的模式很友好。關(guān)系型元數(shù)據(jù)用 PostgreSQL保存租戶、知識源、詞庫、配置這類結(jié)構(gòu)化信息。本地開發(fā)環(huán)境里的 Embedding 和 LLM 統(tǒng)一走 Ollama方便 Mac 上直接跑生產(chǎn)環(huán)境再切換到獨立模型服務(wù)。這套組合沒有追求極致的性能但勝在每層都能獨立替換。比如把 Qdrant 換成 es 或其他向量庫只需要改存儲適配層上層檢索邏輯完全不用動。2.2 為什么選“共享索引 租戶過濾”而不是“每租戶一套”1.2 節(jié)里我已經(jīng)說過整體思路這里把決策過程展開對比一下方便你按照自己的場景判斷。對比項共享索引 租戶過濾每租戶獨立 Collection/索引資源占用低一份索引所有人共享高每個租戶都有獨立索引內(nèi)存和磁盤上漲明顯檢索性能受 filter 性能影響需要正確建 payload 索引相對穩(wěn)定查詢天然限定分區(qū)租戶數(shù)量上限可以支持很多但需要配額機制租戶幾百個之后管理成本和故障面都會變大數(shù)據(jù)泄漏風險高必須全鏈路強制過濾低物理隔離天然防串味運維復(fù)雜度低索引統(tǒng)一管理高需要自動創(chuàng)建、備份、遷移機制UniRAG 選擇共享為主主要是想把資源效率拉滿。但在實現(xiàn)上做了一個關(guān)鍵設(shè)計在 Qdrant 里給租戶字段建了專門的索引并且檢索時強制帶租戶過濾條件不是為了省事而是為了保證性能不會隨著租戶數(shù)增長而明顯劣化。如果你是從零開始我建議先做共享方案跑通全流程然后在代碼里把“存儲適配層”抽象出來。也就是說檢索服務(wù)不直接依賴 Qdrant API而是依賴一個VectorStore接口。這樣以后某個大租戶真的飆到需要獨立索引時只需要給這個租戶綁定一個新的 store 實例不用改業(yè)務(wù)代碼。2.3 租戶上下文中間件設(shè)計多租戶系統(tǒng)的第一道防線就是租戶上下文的注入和傳遞。UniRAG 的做法是用 FastAPI 中間件統(tǒng)一解析請求頭里的X-Tenant-ID把租戶對象塞進一個 Context 對象后續(xù)所有業(yè)務(wù)函數(shù)從 Context 里取而不是從參數(shù)里傳來傳去。# tenant_context.py import contextvars from dataclasses import dataclass dataclass class TenantContext: tenant_id: str tenant_config: dict _tenant_context_var contextvars.ContextVar(tenant_context, defaultNone) def get_current_tenant() - TenantContext: ctx _tenant_context_var.get() if ctx is None: raise RuntimeError(tenant context is missing) return ctx def bind_tenant(tenant_id: str, tenant_config: dict): _tenant_context_var.set(TenantContext(tenant_idtenant_id, tenant_configtenant_config))# middleware.py from starlette.middleware.base import BaseHTTPMiddleware from tenant_context import bind_tenant from config_service import get_tenant_config class TenantMiddleware(BaseHTTPMiddleware): async def dispatch(self, request, call_next): tenant_id request.headers.get(X-Tenant-ID) if not tenant_id: return JSONResponse({error: missing tenant}, status_code400) config get_tenant_config(tenant_id) bind_tenant(tenant_id, config) response await call_next(request) return response這個設(shè)計的好處是業(yè)務(wù)代碼里幾乎看不到“租戶”兩個字但每一步都受租戶約束。檢索服務(wù)不用關(guān)心租戶 ID 是從哪來的反正入口已經(jīng)保證了它的存在。這其實也是多租戶最容易踩雷的地方如果讓每個業(yè)務(wù)接口手動接收 tenant_id非常容易在某個內(nèi)部調(diào)用里忘掉一旦忘記就會落到公共索引。3. 知識庫的三種形態(tài)RAG 不是只有“向量 PDF”3.1 向量知識庫解決的是“語義檢索”一提到 RAG很多人默認就是把一堆 PDF 和 Word 文檔切碎然后做向量檢索。這確實是最常見的場景但向量知識庫的能力邊界也很明顯它擅長“語義相似”不擅長“精確計算”和“復(fù)雜關(guān)系查詢”。比如租戶 A 的知識庫里有一份產(chǎn)品手冊用戶問“設(shè)備過熱怎么辦”向量檢索能把相關(guān)章節(jié)撈出來效果好是因為這樣的問題在文檔里往往有對應(yīng)表述。但如果用戶問“2024 年第一季度銷量是多少”而數(shù)據(jù)只存在于一張 Excel 表格里向量檢索就有點勉強了。文本格式的表格被切塊后模型需要自己拼接上下文“精確性”會打折扣。所以在 UniRAG 里我們把向量知識庫定位為“非結(jié)構(gòu)化文本的語義召回入口”而不是唯一的知識形態(tài)。文檔類知識源走切片 Embedding這一點沒有任何懸念。3.2 結(jié)構(gòu)知識庫和知識圖譜什么時候需要結(jié)構(gòu)知識庫解決的是“事實查詢”。它面向的往往是數(shù)據(jù)庫表、Excel 清單、配置列表這類有明確字段的數(shù)據(jù)查詢時需要精確匹配不能靠“語義相近”。典型場景包括查詢某個訂單狀態(tài)、某個商品的庫存、某個員工所屬部門。這種知識不太適合塞進向量庫。你可以把一張訂單表切成多個片段再向量化但查詢“訂單 1024 狀態(tài)是什么”時向量檢索很難保證返回的就是那一行。更合理的方式是先把問題映射成結(jié)構(gòu)化查詢再去數(shù)據(jù)表里精確查找。知識圖譜KG則更進一步它解決的是“實體關(guān)系和多跳推理”。比如“A 產(chǎn)品的供應(yīng)商與 B 產(chǎn)品的供應(yīng)商是哪家公司”這類問題橫跨多份文檔和多個實體純向量檢索往往顧此失彼。知識圖譜會把實體之間的關(guān)系顯式建模查詢時可以沿著邊去走。還有一個常被忽略的價值圖譜里的關(guān)系本身可以為 LLM 提供約束讓答案不會跳出既定的領(lǐng)域框架。三類知識形態(tài)各有各的適用場景我把它們的邊界和典型應(yīng)用整理成了下面這張表知識形態(tài)解決什么問題典型數(shù)據(jù)源最適合的查詢方式向量知識庫語義匹配、模糊召回PDF、Word、網(wǎng)頁、Markdown自然語言相似度檢索結(jié)構(gòu)知識庫精確查詢、固定字段數(shù)據(jù)庫表、Excel、API結(jié)構(gòu)化查詢 SQL/參數(shù)知識圖譜關(guān)系推理、多跳查詢、概念對齊業(yè)務(wù)實體數(shù)據(jù)、本體定義圖遍歷 規(guī)則推理3.3 Ontology 在多租戶場景中的作用在 UniRAG 里除了上面的三類知識我們還引入了一層“本體定義Ontology”。本體不直接存儲文檔而是存儲“這個領(lǐng)域里有哪些概念、概念之間有什么關(guān)系、每個概念對應(yīng)哪些檢索入口”。比如租戶 A 是電子產(chǎn)品售后文檔里大量出現(xiàn)“耗材”租戶 B 是辦公設(shè)備服務(wù)文檔里叫“配件”。表面上這是兩個不同的詞但映射到領(lǐng)域本體后它們都能指向同一個抽象概念。如果沒有這層映射租戶 A 的用戶問“配件壞了怎么辦”系統(tǒng)可能在租戶 A 的知識庫里完全找不到對應(yīng)內(nèi)容。所以 UniRAG 的檢索入口不是“只搜向量”而是先做一次輕量級概念識別把用戶問題中的實體詞映射到當前租戶的本體節(jié)點上再根據(jù)節(jié)點類型決定走向量庫、結(jié)構(gòu)庫還是圖譜。這種實現(xiàn)也對應(yīng)了現(xiàn)在常說的 Ontology RAG 思路核心就是讓檢索不再完全依賴表面詞匯而是依賴概念結(jié)構(gòu)。實現(xiàn)時要注意租戶的本體定義本身也屬于租戶配置的一部分必須納入控制面管理不能全局共用。否則 A 租戶精心調(diào)過的本體映射很可能把 B 租戶的檢索方向帶偏。3.4 UniRAG 的數(shù)據(jù)源抽象設(shè)計為了能讓向量庫、結(jié)構(gòu)庫和圖譜在一個問答接口里共存我設(shè)計了一個數(shù)據(jù)源抽象層。每個知識源都是一個KnowledgeSource它需要暴露統(tǒng)一的能力召回候選片段、返還給上層統(tǒng)一的上下文格式。class KnowledgeSource: def retrieve(self, query: str, tenant_id: str, top_k: int) - list[ContextChunk]: raise NotImplementedError class VectorKnowledgeSource(KnowledgeSource): def retrieve(self, query, tenant_id, top_k): # 生成向量在 qdrant 中按租戶過濾召回 ... class StructuredKnowledgeSource(KnowledgeSource): def retrieve(self, query, tenant_id, top_k): # 用 NL2SQL 或規(guī)則映射從庫里精確查詢 ... class GraphKnowledgeSource(KnowledgeSource): def retrieve(self, query, tenant_id, top_k): # 識別實體和關(guān)系在圖譜中遍歷返回路徑 ...路由層做的事情就是先拿租戶的本體配置把用戶問題分類然后決定調(diào)哪幾個 source。如果問題明顯是“某件事是什么”這種語義問題直接走向量源如果帶“哪個、多少、什么狀態(tài)”這類精確查詢詞優(yōu)先走結(jié)構(gòu)源如果問題里出現(xiàn)了多個實體而且看起來需要比較實體間的關(guān)系則引入圖譜源。多個 source 召回的結(jié)果會在重排階段融合不是只挑一個。4. 入庫和檢索的關(guān)鍵參數(shù)可以照抄的配置4.1 分塊策略不是所有文本都切 512切分參數(shù)直接影響召回率而且沒有一個萬能值。UniRAG 里我按文檔類型做了不同預(yù)設(shè)你拿到后可以先照抄再根據(jù)實際效果調(diào)整。文檔類型分塊大小重疊窗口說明產(chǎn)品手冊/說明文檔512 字符64 字符保留較完整上下文適合說明性文本工單/FAQ256 字符32 字符問題答案通常短而集中小塊召回更精準合同/法律文本768 字符96 字符需要保持條款完整性避免把一個條款切開表格文本按行/塊切少量重疊盡量不跨行列切否則行列關(guān)系會斷代碼或配置文件256 字符32 字符代碼上下文敏感切太大容易混入無關(guān)邏輯分塊大小背后有一個計算邏輯假設(shè)模型上下文窗口是 8K token一次問答要放指令、歷史對話、檢索片段和回答空間。512 個中文字符經(jīng)過模型 Tokenizer 大約會變成 200~300 token。如果檢索 top_k 取 5就有 1000~1500 token 的上下文被文檔占掉留給回答和歷史的余量并不寬裕。所以別再盲目加大塊塊越大召回越多越容易把模型的注意力帶偏。重疊窗口的作用是避免“切點正好斷在一個句子的關(guān)鍵部位”。64 字符大概是兩行正文的長度足夠讓前后塊共享一部分上下文。如果你發(fā)現(xiàn)一些本該能命中的文檔總是召不回來第一件事就是檢查切分是否把關(guān)鍵句子從中間切斷了。4.2 檢索鏈路參數(shù)怎么定UniRAG 的檢索鏈路不是一次查詢就完事而是多級過濾。初始向量召回 top_k 我會取 30目的很簡單先把候選范圍拉大寧可多召回一些不相關(guān)的內(nèi)容也不漏掉真正相關(guān)的片段。召回 30 條之后再用關(guān)鍵詞和結(jié)構(gòu)匹配做一次融合選出 20 條。最后用重排模型Cross Encoder在這 20 條里逐條打分只保留最相關(guān)的 5 條作為上下文。這個“30→20→5”的漏斗很保守但對多租戶共享索引尤其重要。因為共享索引場景下租戶過濾條件已經(jīng)從潛在層面收窄了范圍但文檔本身的噪聲仍然存在。如果 top_k 只取 5可能在第一輪就錯過真正有用的片段而重排救不回來沒召回的文檔。不如一開始多取一些把準確率的重任交給重排階段。相似度閾值方面我會建議一個相對寬的值比如 0.65~0.7。閾值設(shè)太高容易誤傷因為 Embedding 對短問題的表達能力有限很多表述不同的句子向量余弦相似度天然不會太高。你真正要卡的是重排階段的分數(shù)而不是向量檢索階段的初篩分數(shù)。4.3 嵌入模型和重排模型選型Embedding 模型決定了檢索的上限。UniRAG 在中文場景下默認用的是 bge-m3原因是它在中文長文本和變體表述上的表現(xiàn)比較穩(wěn)而且支持 8192 長度的輸入遇到長文檔切片時不用頻繁擔心截斷。生產(chǎn)環(huán)境如果對中文效果要求更高也可以換成基于對比學習訓(xùn)練的領(lǐng)域定制模型但要維護一套訓(xùn)練流程一般不建議只有幾十個租戶的平臺過早投入。重排模型建議和 Embedding 模型解耦。Embedding 負責粗召回重排負責精挑選兩者使用同一個模型其實并不合適。UniRAG 里用的重排模型是 bge-reranker-v2輸入是一對 query 和 document直接輸出相關(guān)度分數(shù)比向量相似度更接近“人類判斷”。需要注意重排模型不能跨租戶共享 prompt 或答案內(nèi)容但模型權(quán)重本身是全局共享的。也就是說重排服務(wù)根據(jù)租戶過濾好的候選片段逐個打分而不是讓模型看到某個租戶的原始數(shù)據(jù)后把結(jié)果存下來再給另一個租戶用。這個邊界一定要守住。5. 在 Mac 上從零跑通一個最小多租戶 RAG5.1 本地環(huán)境的準備很多朋友問怎么在 Mac 上搭建 RAG 知識庫尤其是本地跑一套還帶多租戶能力的其實并不復(fù)雜。我先說下環(huán)境要求macOS 13 及以上安裝 Docker DesktopPython 3.11再加一個 Ollama 用來跑本地模型。如果你不想用 Docker也可以用 Homebrew 直接裝 PostgreSQL 和 Qdrant但 Docker 會讓整個環(huán)境干凈很多卸載也方便。Embedding 模型和 LLM 我建議在 Ollama 里跑。Embedding 模型可以用bge-m3的量化版本LLM 可以用qwen2.5:7b。這樣做的最大好處是隱私可控文檔內(nèi)容不會在調(diào)試階段就發(fā)到外部 API而且不依賴網(wǎng)絡(luò)在咖啡廳也能繼續(xù)開發(fā)。brew install docker brew install python3.11 brew install ollama # 啟動 ollama 服務(wù)后拉取模型 ollama pull bge-m3 ollama pull qwen2.5:7b如果你的 Mac 內(nèi)存只有 16G建議 LLM 換qwen2.5:3b或者llama3.2:3bEmbedding 模型也選擇內(nèi)存占用更小的版本。多租戶開發(fā)和驗證不依賴大模型多聰明關(guān)鍵在于數(shù)據(jù)隔離鏈路通不通。5.2 啟動基礎(chǔ)服務(wù)Docker Compose 一鍵拉起基礎(chǔ)組件我用了三個PostgreSQL 保存租戶和知識源配置Qdrant 保存向量和租戶過濾字段Redis 做緩存和限流。下面這個 Compose 文件可以直接用來起本地環(huán)境。version: 3.8 services: postgres: image: postgres:16 environment: POSTGRES_USER: uniraq POSTGRES_PASSWORD: uniraq_dev POSTGRES_DB: uniraq ports: - 5432:5432 volumes: - pg_data:/var/lib/postgresql/data qdrant: image: qdrant/qdrant:latest ports: - 6333:6333 - 6334:6334 volumes: - qdrant_data:/qdrant/storage redis: image: redis:7 ports: - 6379:6379 volumes: pg_data: qdrant_data:啟動命令很簡單docker compose up -d curl http://localhost:6333 # 看 Qdrant 是否起來在 Mac 本地跑這套組合非常輕量內(nèi)存占用大約是 Postgres 200MB、Qdrant 300MB、Redis 100MB再加上 Ollama 的模型整體 2GB 以內(nèi)能搞定。5.3 最小代碼實現(xiàn)入庫和檢索都強制帶租戶下面這段代碼是一個最小可跑的多租戶 RAG 核心邏輯。我刪掉了大量細節(jié)保留了最關(guān)鍵的兩步寫入時把tenant_id放進 payload檢索時用tenant_id做強制過濾。from qdrant_client import QdrantClient from qdrant_client.models import PointStruct, VectorParams, Distance client QdrantClient(hostlocalhost, port6333) COLLECTION uniraq_docs def ensure_collection(): # 創(chuàng)建共享 collection所有租戶的向量都在這里 client.recreate_collection( collection_nameCOLLECTION, vectors_configVectorParams(size1024, distanceDistance.COSINE), ) def add_document_chunks(tenant_id: str, chunks: list[dict], embeddings: list[list[float]]): points [] for idx, (chunk, emb) in enumerate(zip(chunks, embeddings)): point_id f{tenant_id}_{chunk[doc_id]}_{idx} points.append( PointStruct( idabs(hash(point_id)), vectoremb, payload{ tenant_id: tenant_id, doc_id: chunk[doc_id], text: chunk[text], source: chunk[source], }, ) ) client.upsert(collection_nameCOLLECTION, pointspoints) def search(tenant_id: str, query_vector: list[float], top_k: int 30): # 最關(guān)鍵的一行tenant_id 過濾 results client.search( collection_nameCOLLECTION, query_vectorquery_vector, limittop_k, query_filter{ must: [ {key: tenant_id, match: {value: tenant_id}} ] }, ) return results這里有兩個細節(jié)很關(guān)鍵。第一寫入時用tenant_id doc_id seq生成 point 的 id避免不同租戶的相同文檔 ID 在共享集合里產(chǎn)生主鍵沖突。第二檢索時 query_filter 只用了租戶字段沒有用其他業(yè)務(wù)條件這樣既能保證隔離又不至于把過濾條件擴大成“性能殺手”。實際接生產(chǎn)時tenant_id不是由業(yè)務(wù)代碼傳進來的而是由前面提到的中間件從請求頭解析后綁定到 Context再在 controller 層取出并傳給 search。也就是說業(yè)務(wù)方根本不可能“忘記傳租戶”因為入口已經(jīng)強制了。5.4 驗證隔離效果寫一個檢測腳本本地跑通后強烈建議寫一個“串味檢測”腳本目的是自動化觀察租戶隔離是否失效。這個腳本不需要復(fù)雜邏輯很簡單給租戶 A 插入一條“紅色條款”給租戶 B 插入一條“藍色條款”然后用兩個租戶的身份分別搜索對方的內(nèi)容斷言搜不到即可。python check_isolation.py # 期望輸出 # PASS: tenant_a 搜索 tenant_b 內(nèi)容被攔截 # PASS: tenant_b 搜索 tenant_a 內(nèi)容被攔截這個腳本要放到持續(xù)集成里每次改檢索邏輯后都跑一遍。多租戶系統(tǒng)最怕的不是第一次隔離做錯而是某次重構(gòu)時不小心把 filter 漏了回歸測試又沒覆蓋到。6. 上線之后最常踩的坑問題排查與優(yōu)化方向6.1 多租戶 RAG 問題速查表我把自己遇到過的典型故障整理成一張速查表你可以直接作為排障清單用。現(xiàn)象可能原因排查方法租戶 A 能看到租戶 B 的文檔片段檢索時沒帶租戶過濾或者中間件解析租戶失敗檢查請求頭傳遞、上下文綁定、檢索代碼的 filter明明文檔入庫了但檢索結(jié)果為空切分太小、向量相似度閾值太高、查詢改寫后跑偏先放開閾值再逐個檢查切片和 Embedding檢索結(jié)果相關(guān)但內(nèi)容太碎分塊太小上下文被切斷把分塊調(diào)大增加重疊窗口結(jié)構(gòu)知識庫問題總是答錯誤走了向量檢索NL2SQL 沒有路由到結(jié)構(gòu)庫檢查本體路由規(guī)則確認問題里的實體被正確識別租戶配置改了但線上還走舊配置控制面和數(shù)據(jù)面的配置緩存未失效檢查緩存 key 是否帶租戶版本號一個大租戶批量導(dǎo)入文檔時其他人檢索變慢共享索引寫入占用資源讀寫互相影響在存儲層做讀寫分離或限流必要時給大租戶獨立索引6.2 重新認識的“RAG 瓶頸”網(wǎng)上討論 RAG 瓶頸時很多結(jié)論都指向“幻覺”和“上下文不夠”。 UniRAG 跑到稍大規(guī)模后我的體感完全不同真正的瓶頸幾乎都集中在召回鏈路。最常見的問題是索引里的文檔密度很高但切分策略太粗糙導(dǎo)致真正關(guān)聯(lián)的內(nèi)容被切到了多塊里每塊都只覆蓋一部分語義。模型拿到這些不完整的片段自然會腦補出錯誤信息。另一個常見問題是用戶提問的表述和文檔原文差距太大向量相似度不夠?qū)е孪嚓P(guān)片段沒有被召回。針對這兩個瓶頸我建議的排查路徑是先看租戶的召回日志統(tǒng)計前 30 條候選中是否出現(xiàn)了最終應(yīng)該作為答案的片段如果出現(xiàn)了說明問題出在重排階段如果根本沒出現(xiàn)說明問題出在切分或 Embedding 階段。然后對癥下藥不要一上來就換大模型。同時RAG 不是只做一輪檢索就萬事大吉。UniRAG 在復(fù)雜問題上會嘗試先做查詢改寫比如用戶問“這兩個方案有什么區(qū)別”系統(tǒng)會先拆解出兩個實體分別去檢索各自的定義再統(tǒng)一交給重排。這個過程也被納入租戶配置不同租戶可以選擇不同改寫策略。6.3 運維層面的兩個方向工程上跑通還只是第一步。多租戶系統(tǒng)上線后我建議盡早補齊兩件事租戶級評測集和自動化回歸。給每個租戶準備一份 Golden Set里面包含 30~50 個典型問題和期望答案片段。每次檢索模型或參數(shù)調(diào)整都拿這套集子跑一遍對比召回率和答案命中率。這樣既能防止為了優(yōu)化一個租戶而搞壞另一個租戶也能在新租戶接入時快速估值。另一個方向是租戶級別的監(jiān)控指標。除了 QPS 和延遲更要多關(guān)注每個租戶的召回率、無結(jié)果率、來源片段離散度。無結(jié)果率突然飆升往往不是模型問題而是文檔更新或本體配置被誤動。來源片段離散度則能反映出一份答案是否總是依賴同一段文本如果離散度過低模型很可能在背答案而不理解上下文。寫在最后我搭 UniRAG 的一些體會如果只說一條最核心的經(jīng)驗?zāi)蔷褪嵌嘧鈶?RAG 的難點不在算法而在基礎(chǔ)設(shè)施抽象。向量檢索、Embedding、重排這些技術(shù)都已經(jīng)很成熟真正決定項目能不能長期跑下去的是你有沒有把“租戶”這個概念真正設(shè)計進每一層。我自己的流程是先花兩周把單租戶 RAG 跑通再花兩周把租戶上下文和隔離策略抽出來最后用一周時間處理了十幾個細節(jié)坑。這個節(jié)奏比直接寫“通用平臺”要順得多。因為你只有親自經(jīng)歷過單租戶的檢索鏈才知道哪些地方容易漏隔離、哪些配置需要按租戶區(qū)分。如果你正準備做類似的系統(tǒng)別急著把功能堆全。先保證一個租戶在共享索引和過濾策略下能跑通再逐步放開大租戶獨立索引、本體路由、混合檢索這些能力。多租戶的復(fù)雜度是慢慢長出來的一開始攤太開反而很難收場。