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