做RAG最頭痛的不是模型選型而是向量庫(kù)和檢索鏈路沒(méi)對(duì)齊。我前段時(shí)間接了一個(gè)知識(shí)庫(kù)問(wèn)答的項(xiàng)目要求文檔不出內(nèi)網(wǎng)、數(shù)據(jù)本地落盤(pán)、十萬(wàn)級(jí)文檔量下還能快速召回。對(duì)比了一圈方案最后落在Chroma 向量庫(kù) RAG 檢索工具的組合上把文檔拆解、Embedding、向量化入庫(kù)、召回、重排、Prompt 拼接整條鏈路完整跑通了過(guò)程中也踩了不少網(wǎng)上沒(méi)人細(xì)寫(xiě)的坑。這篇文章就把完整集成方案、背后的取舍邏輯以及實(shí)測(cè)中的常見(jiàn)問(wèn)題一次講清楚。剛接觸 RAG 的新手可以照抄代碼已經(jīng)做過(guò)一遍但召回效果不理想的我后面整理的排查經(jīng)驗(yàn)應(yīng)該也能幫到你。1. 為什么最終選了 Chroma方案選型的心路歷程1.1 市面上的向量庫(kù)那么多為什么是 Chroma當(dāng)時(shí)我面前其實(shí)擺了四個(gè)候選人FAISS、Milvus、Qdrant、Chroma。單看各自官網(wǎng)的介紹個(gè)個(gè)都很能打但落到真實(shí)項(xiàng)目里必須算維護(hù)成本和團(tuán)隊(duì)心智負(fù)擔(dān)。我給四個(gè)方案做過(guò)一個(gè)簡(jiǎn)單對(duì)比橫縱維度如下方案部署模式數(shù)據(jù)量建議維護(hù)成本生態(tài)集成FAISS嵌入式純內(nèi)存/本地索引百萬(wàn)級(jí)中索引保存和增量更新要自己寫(xiě)需自行封裝Milvus獨(dú)立服務(wù)可分布式千萬(wàn)級(jí)高需要專(zhuān)門(mén)的數(shù)據(jù)庫(kù)運(yùn)維視角有 SDK但重Qdrant獨(dú)立服務(wù)Docker 可跑百萬(wàn)級(jí)中高有 SDK接口清晰Chroma嵌入式落地為本地文件百萬(wàn)以?xún)?nèi)低pip 裝完直接當(dāng)普通庫(kù)用與 LangChain 高度集成我們項(xiàng)目實(shí)際只有十萬(wàn)級(jí)文檔單機(jī)完全扛得住團(tuán)隊(duì)里也沒(méi)有專(zhuān)職運(yùn)維。Milvus 和 Qdrant 的分布式能力在這個(gè)量級(jí)上屬于殺雞用牛刀反而帶來(lái)額外的服務(wù)部署、監(jiān)控、升級(jí)工作。FAISS 檢索效率沒(méi)得說(shuō)但增量添加、去重、按元數(shù)據(jù)過(guò)濾這些 RAG 高頻操作Chroma 開(kāi)箱即用FAISS 得自己封裝。另外還有個(gè)很務(wù)實(shí)的理由Chroma 的 Collection 天然支持 HNSW 索引、元數(shù)據(jù)過(guò)濾和持久化Python 接口簡(jiǎn)單到像操作字典。團(tuán)隊(duì)里只要會(huì)寫(xiě) Python半小時(shí)內(nèi)就能上手。后來(lái)的事實(shí)證明這個(gè)選擇省掉了大量溝通和排障成本。1.2 完整 RAG 管道應(yīng)該長(zhǎng)什么樣先別急著寫(xiě)代碼把整個(gè)鏈路在腦子里過(guò)一遍RAG 本質(zhì)上做的是兩件事先把私有知識(shí)切成一個(gè)個(gè)能檢索的切片再在回答問(wèn)題時(shí)按需把這些切片挑出來(lái)喂給大模型。完整管道我分成五個(gè)環(huán)節(jié)文檔解析把 PDF、Word、Markdown、網(wǎng)頁(yè)等原始文件轉(zhuǎn)成純文本。文本分塊用合適的切分規(guī)則把長(zhǎng)文本拆成語(yǔ)義相對(duì)完整的 chunk。向量化用 Embedding 模型把每個(gè) chunk 變成高維向量。寫(xiě)入向量庫(kù)Chroma 保存向量同時(shí)附帶 chunk 原文和元數(shù)據(jù)。檢索生成用戶(hù) query 向量化后在庫(kù)中做相似度檢索召回 Top-K 原文拼進(jìn) Prompt交給 LLM。很多人容易忽視第二環(huán)的威力。如果你最后的回答經(jīng)常胡編或者答非所問(wèn)八成問(wèn)題出在分塊和召回而不是生成模型。后面我會(huì)重點(diǎn)展開(kāi)分塊策略那是我在這次項(xiàng)目里花費(fèi)最多精力調(diào)試的地方。2. 落地前必須先想清楚的三件事Embedding、文本拆解和集合結(jié)構(gòu)2.1 Embedding 選型本地模型還是 API 模型Embedding 是整個(gè) RAG 的地基它決定了相似度的語(yǔ)義基礎(chǔ)。同一句話(huà)不同模型召回的 Top-3 可能完全不一樣。我在項(xiàng)目里實(shí)際對(duì)比過(guò)的選項(xiàng)大概有這幾種Embedding 模型維度中文效果部署方式備注text-embedding-ada-0021536中上API 調(diào)用GPT 生態(tài)有網(wǎng)絡(luò)依賴(lài)text-embedding-v31024/1536好API 調(diào)用國(guó)內(nèi)廠(chǎng)商按量計(jì)費(fèi)BAAI/bge-large-zh-v1.51024很好本地中文檢索口碑穩(wěn)定BAAI/bge-m31024很好本地支持多語(yǔ)言綜合能力強(qiáng)nomic-embed-text768一般本地 Ollama部署最省事輕量項(xiàng)目一開(kāi)始為了省事我用的是 Ollama 跑 nomic-embed-text一條命令就能起一個(gè) embedding 接口。用了一段時(shí)間發(fā)現(xiàn)中文長(zhǎng)尾問(wèn)題召回很勉強(qiáng)后來(lái)?yè)Q成了 bge-large-zh-v1.5用sentence-transformers加載到本地中文 Top-K 命中率明顯提升。這里要強(qiáng)調(diào)一句別迷信通用模型拿你自己真實(shí)的幾十條 query 去測(cè)一輪看 Top-5 里有沒(méi)有正確答案比看評(píng)測(cè)榜單重要得多。如果你有聯(lián)網(wǎng)預(yù)算embedding 用 API、生成用本地大模型這種組合也完全可行。但要注意維度和計(jì)費(fèi)新老模型維度不一致時(shí)Chroma 里已經(jīng)存在的向量和新的 query 向量是算不了相似度的必須清空重灌。2.2 Chunk 切分策略RAG 質(zhì)量的一半藏在拆分里網(wǎng)上最常見(jiàn)的參數(shù)是chunk_size500, chunk_overlap50但這個(gè)只能當(dāng)起點(diǎn)。切分策略直接決定最終檢索質(zhì)量我在這個(gè)環(huán)節(jié)花的時(shí)間是最多的。我實(shí)際試過(guò)的切分方式固定窗口切分按字符數(shù)硬切邏輯最簡(jiǎn)單適合公告、新聞這類(lèi)格式統(tǒng)一的文本但很容易切斷句子。遞歸字符切分按換行、句號(hào)、問(wèn)號(hào)、感嘆號(hào)逐級(jí)降級(jí)切分盡量保語(yǔ)義邊界。LangChain 的RecursiveCharacterTextSplitter就走這個(gè)思路絕大多數(shù)文檔用它就夠了。語(yǔ)義切分用 embedding 判斷句子之間的語(yǔ)義突變點(diǎn)切得自然但計(jì)算開(kāi)銷(xiāo)大離線(xiàn)建庫(kù)慢。標(biāo)題/段落感知切分按 Markdown 大標(biāo)題、章節(jié)路徑作為邊界保留文檔層級(jí)能有效緩解知識(shí)割裂?；氐介_(kāi)頭那個(gè)高頻搜索詞有沒(méi)有本地的 RAG 文本拆解工具直接回答LangChain 的遞歸切分器就是首選純本地、零依賴(lài)遇到 PDF、DOCX 再配一個(gè)unstructured或者pypdf就能吃下大部分文檔。如果不想引入 LangChain自己用tiktoken數(shù) token 再寫(xiě)段落拼接函數(shù)也完全夠用。這次項(xiàng)目里我用的具體配置是chunk_size512差不多覆蓋一個(gè)知識(shí)點(diǎn)的體量太長(zhǎng)容易混入無(wú)關(guān)內(nèi)容。chunk_overlap80讓斷點(diǎn)頭尾在相鄰 chunk 里各出現(xiàn)一次防止句子被攔腰截?cái)?。切分?yōu)先級(jí)按中文標(biāo)點(diǎn)走。\n 空格 無(wú)分隔而不是簡(jiǎn)單按字符數(shù)硬切。為什么 overlap 不能省想象一本書(shū)被切成好幾段斷點(diǎn)恰好落在某句話(huà)中間這句話(huà)對(duì)前后兩個(gè) chunk 都只出現(xiàn)半截。用戶(hù)提問(wèn)命中這句話(huà)的時(shí)候兩個(gè)半截的相似度都不夠高信息就漏了。overlap 會(huì)讓窗口重疊區(qū)域在兩個(gè) chunk 里各出現(xiàn)一次召回穩(wěn)定性提升非常明顯代價(jià)只是多占一點(diǎn)存儲(chǔ)完全值得。切分的同時(shí)建議把 chunk 的元數(shù)據(jù)一并帶上來(lái)源文件名、頁(yè)碼、章節(jié)標(biāo)題。這樣召回后在界面上可以展示答案來(lái)自哪份文檔哪一頁(yè)用戶(hù)和開(kāi)發(fā)都能快速判斷召回是否正確。2.3 集合設(shè)計(jì)與元數(shù)據(jù)Chroma 的世界里沒(méi)有表Chroma 的核心概念是 Collection可以把它理解成一張帶有向量的表但它不需要提前定義字段結(jié)構(gòu)。寫(xiě)入時(shí)你給四個(gè)字段就行id、embedding、document原始文本、metadata普通鍵值對(duì)。設(shè)計(jì)上我給這個(gè)項(xiàng)目定了三條原則按業(yè)務(wù)域拆分 Collection。產(chǎn)品手冊(cè)、技術(shù)文檔、客服問(wèn)答分成三個(gè) Collection比全部塞進(jìn)一個(gè)再靠 metadata 硬篩要清爽得多。每條 chunk 都帶完整 metadata。至少包含source、page、category、timestamp這幾個(gè)字段后面做權(quán)限過(guò)濾和按時(shí)間過(guò)濾都靠它們。檢索時(shí)先用where過(guò)濾再做向量檢索。比如客服場(chǎng)景只查{category: customer_service}既提高準(zhǔn)確率又縮小了搜索空間。這里有個(gè)容易踩的坑Chroma 的where是精確匹配Manual和manual是兩個(gè)值不會(huì)歸一化。我從第一個(gè)項(xiàng)目里就吃過(guò)虧后來(lái)統(tǒng)一規(guī)定 metadata 里全部小寫(xiě)入庫(kù)前做一個(gè)normalize_metadata的公共函數(shù)。另外Collection 創(chuàng)建時(shí)可以指定距離函數(shù)metadata{hnsw:space: cosine}對(duì)應(yīng) cosine 距離還有 l2 歐氏距離和 ip 內(nèi)積。RAG 場(chǎng)景直接選 cosine 最穩(wěn)l2 適合向量已經(jīng)歸一化的場(chǎng)景ip 會(huì)受 embedding 本身尺度影響新手不建議碰。3. 從零搭建Chroma RAG 的完整實(shí)操代碼3.1 安裝與初始化PersistentClient 這點(diǎn)不能省代碼從安裝依賴(lài)開(kāi)始pip install chromadb langchain langchain-chroma langchain-community sentence-transformers我建議把版本寫(xiě)進(jìn)requirements.txt給項(xiàng)目鎖死因?yàn)?Chroma 0.4 到 0.5 的升級(jí)里Settings和 API 都有變動(dòng)避免網(wǎng)上教程和你本地環(huán)境版本錯(cuò)位。初始化方式很有講究。很多人圖省事直接chromadb.Client()跑完數(shù)據(jù)全在內(nèi)存里進(jìn)程一結(jié)束全沒(méi)了。正確做法是用PersistentClient指定一個(gè)數(shù)據(jù)目錄Chroma 會(huì)在里面生成chroma.sqlite3和向量索引文件下次啟動(dòng)從同一個(gè)路徑加載就自動(dòng)恢復(fù)數(shù)據(jù)import chromadb from chromadb.config import Settings _client None def get_client(): global _client if _client is None: _client chromadb.PersistentClient( path./chroma_data, settingsSettings(anonymized_telemetryFalse) ) return _client把 client 寫(xiě)成單例很有必要否則每次請(qǐng)求都新建連接、重復(fù)加載索引會(huì)讓系統(tǒng)響應(yīng)時(shí)間成倍上漲。anonymized_telemetryFalse是關(guān)閉匿名遙測(cè)內(nèi)網(wǎng)部署我建議都帶上。另外給開(kāi)發(fā)、測(cè)試、生產(chǎn)各配一套chroma_data_dev/test/prod目錄別共用一套不然你排查問(wèn)題的時(shí)候總是不知道當(dāng)前線(xiàn)上數(shù)據(jù)是誰(shuí)寫(xiě)進(jìn)去的。3.2 文檔入庫(kù)流程拆解、向量化、寫(xiě)入入庫(kù)流程分三步先從源文件抽取文本再做切分和元數(shù)據(jù)標(biāo)注最后寫(xiě)入向量庫(kù)。第一步讀取 PDF我用的pypdf最輕量from pypdf import PdfReader reader PdfReader(manual.pdf) text \n.join(page.extract_text() for page in reader.pages)如果文檔里有表格或者掃描件pypdf提取效果一般需要配合 OCR 組件或者unstructured。這次項(xiàng)目的主體是技術(shù)手冊(cè)都是電子版 PDFpypdf夠用。第二步切分文本并生成 metadatafrom langchain_text_splitters import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size512, chunk_overlap80, separators[\n\n, \n, 。, , , , , , ], keep_separatorend, ) chunks splitter.split_text(text) metadatas [ {source: manual.pdf, page: i // 10, category: manual} for i in range(len(chunks)) ]keep_separatorend強(qiáng)烈建議打開(kāi)。它的作用是讓。留在前一個(gè) chunk 的末尾而不是被切到下一個(gè) chunk 的開(kāi)頭。中文場(chǎng)景下如果不開(kāi)你會(huì)在檢索到的文本里看到很多句子開(kāi)頭莫名其妙掛一個(gè)句號(hào)語(yǔ)義非常奇怪。第三步寫(xiě)入 Chroma。用 LangChain 封裝版代碼更順from langchain_chroma import Chroma from langchain_community.embeddings import HuggingFaceEmbeddings embeddings HuggingFaceEmbeddings( model_nameBAAI/bge-large-zh-v1.5 ) vectorstore Chroma( collection_nameproduct_manual, embedding_functionembeddings, persist_directory./chroma_data, ) vectorstore.add_texts( textschunks, metadatasmetadatas, ids[fmanual_{i} for i in range(len(chunks))], )注意langchain_chroma是老版本langchain_community.vectorstores.Chroma的新包路徑接口幾乎一樣但依賴(lài)更干凈新項(xiàng)目直接用新包。入庫(kù)之后我習(xí)慣先抽查一條數(shù)據(jù)result vectorstore.get(ids[manual_0]) print(result[documents][0][:100])確認(rèn)原文真的寫(xiě)進(jìn)去了。很多排查到最后發(fā)現(xiàn)不是檢索的問(wèn)題而是數(shù)據(jù)壓根沒(méi)入庫(kù)或者寫(xiě)入時(shí)被空行截?cái)嗔?。先?yàn)證這個(gè)后面能省很多事。3.3 檢索鏈路query → 召回 → 過(guò)濾 → 拼 Prompt檢索時(shí)不需要碰底層 APILangChain 的similarity_search就夠用但我更推薦帶分?jǐn)?shù)的那個(gè)接口docs_with_score vectorstore.similarity_search_with_score( query, k5, filter{category: manual}, )這里返回的 score 在 cosine 空間里是距離數(shù)值越小越相似。bge 系列模型實(shí)測(cè)下來(lái)0.4 左右算很接近0.8 以上基本是無(wú)關(guān)內(nèi)容?？梢园礃I(yè)務(wù)接受度設(shè)一個(gè)閾值過(guò)濾掉過(guò)遠(yuǎn)的噪聲filtered_docs [ (doc, score) for doc, score in docs_with_score if score 0.6 ]接下去是拼 Prompt。我建議在 system prompt 里明確告訴模型只能依據(jù)給定資料回答找不到就直接說(shuō)不知道禁止即興編造。同時(shí)把每個(gè) chunk 的來(lái)源元數(shù)據(jù)附在文本里模型回答時(shí)便知道出處context \n\n.join( f[來(lái)源: {doc.metadata.get(source, unknown)}]\n{doc.page_content} for doc, _ in filtered_docs ) prompt f你是一個(gè)知識(shí)庫(kù)問(wèn)答助手。請(qǐng)嚴(yán)格根據(jù)以下資料回答用戶(hù)問(wèn)題。 如果資料中沒(méi)有可靠信息請(qǐng)直接回復(fù)未找到相關(guān)內(nèi)容。 資料 {context} 用戶(hù)問(wèn)題{query} 回答這里要提醒一個(gè)上下文窗口的問(wèn)題。Chroma 召回 5 個(gè) chunk每個(gè) 512 字符拼起來(lái)就有 2500 多字符小參數(shù)模型很容易頂著窗口上限。我習(xí)慣在拼接后按 token 截?cái)嗷蛘甙颜倩財(cái)?shù)量從 5 調(diào)到 3優(yōu)先保質(zhì)量而不是數(shù)量。上下文塞得太滿(mǎn)模型反而抓不住重點(diǎn)。4. 上線(xiàn)前必做的效果評(píng)估與性能優(yōu)化4.1 Hit Rate 到底怎么測(cè)樣本集和判定規(guī)則RAG hit rate是很多人搜爛了但沒(méi)找到規(guī)范做法的詞。Hit Rate 定義本身不復(fù)雜給一批問(wèn)題 → 應(yīng)該命中的文檔 ID作為測(cè)試集統(tǒng)計(jì)檢索結(jié)果 Top-K 里包含目標(biāo)文檔的比例。測(cè)試集怎么建我從項(xiàng)目文檔里隨機(jī)挑 50 到 100 個(gè) chunk 作為錨點(diǎn)每個(gè)錨點(diǎn)人為寫(xiě)一兩個(gè)用戶(hù)可能問(wèn)的問(wèn)題然后把錨點(diǎn)寫(xiě)入時(shí)用的 id 記為金標(biāo)。批量跑一遍檢索total len(test_set) hits 0 for item in test_set: query item[query] golden_id item[golden_id] result vectorstore.max_marginal_relevance_search(query, k5) retrieved_ids [doc.metadata[id] for doc in result] if golden_id in retrieved_ids: hits 1 hit_rate hits / total print(fHit Rate5 {hit_rate:.2%})我手里的幾個(gè) RAG 項(xiàng)目HitRate5 在 85% 以上算健康低于 70% 基本可以斷定問(wèn)題在分塊策略或者 embedding 選型而不是 retriever 參數(shù)沒(méi)調(diào)好。有個(gè)細(xì)節(jié)容易讓人誤判如果測(cè)試集只有問(wèn)題 → 整份文檔級(jí)別粒度過(guò)粗命中率會(huì)被做假高。因?yàn)椴煌?chunk 散落在同一份文檔里隨機(jī)檢索也可能碰對(duì)。所以金標(biāo)盡量收斂到 chunk 級(jí)我會(huì)在入庫(kù)給每一條都留一個(gè)穩(wěn)定的golden_id方便自動(dòng)化評(píng)估。4.2 召回質(zhì)量不行試試 Rerank 和混合檢索純向量檢索有個(gè)天然短板query 里每個(gè)關(guān)鍵詞都很關(guān)鍵但向量召回傾向于整體語(yǔ)義匹配精確關(guān)鍵詞命中反而可能被忽略。比如用戶(hù)報(bào)一個(gè)錯(cuò)誤碼ERR-2048語(yǔ)義檢索很容易把它和錯(cuò)誤碼 2048 處理混在一起最好的結(jié)果排序卻不是第一。解決這個(gè)問(wèn)題有兩條路線(xiàn)可以并行。第一條是混合檢索。向量檢索 BM25 關(guān)鍵詞檢索各跑一路再用 RRFReciprocal Rank Fusion融合排序score sum(1 / (60 rank_i))每個(gè)文檔在兩路結(jié)果里都有自己的排名綜合后的排序會(huì)同時(shí)尊重語(yǔ)義相關(guān)性和關(guān)鍵詞精確性。本地 BM25 我推薦rank_bm25先把所有 chunk 建索引檢索時(shí)對(duì) query 用jieba分詞再跑。這樣ERR-2048這種型號(hào)、錯(cuò)誤碼能通過(guò)關(guān)鍵詞路精確命中語(yǔ)義相近但沒(méi)出現(xiàn)關(guān)鍵詞的內(nèi)容又能在向量路被拉回來(lái)。第二條是重排序。檢索先拉 Top-20再用 cross-encoder 模型逐條打分取 Top-5。cross-encoder 會(huì)把 query 和文檔一起送進(jìn)模型做 token 級(jí)交互比獨(dú)立向量的余弦相似度精確得多。本地中文場(chǎng)景用BAAI/bge-reranker-base就夠了我實(shí)測(cè)每條約幾十毫秒離線(xiàn)驗(yàn)證完全可接受。我的最終組合是先向量檢索 25 條做一遍 MMR 去重避免重復(fù)內(nèi)容霸榜再 rerank 挑 5 條進(jìn) Prompt。這個(gè)改動(dòng)在客服問(wèn)答場(chǎng)景把最終正確率提升了十幾個(gè)百分點(diǎn)效果非常直觀(guān)。4.3 RAG 的瓶頸和知識(shí)割裂問(wèn)題以及 Agentic RAG 的解法RAG 最大瓶頸不是搜不到而是搜出來(lái)的不一定是最相關(guān)的幾段。知識(shí)庫(kù)文檔之間經(jīng)常存在交叉引用和術(shù)語(yǔ)依賴(lài)純向量檢索把它們切割成互不關(guān)聯(lián)的孤島這就是熱詞里說(shuō)的知識(shí)割裂。舉一個(gè)這次項(xiàng)目里真實(shí)踩到的例子A 文檔寫(xiě)該參數(shù)默認(rèn)為 10B 文檔定義該參數(shù)是重試次數(shù)上限。用戶(hù)問(wèn)重試次數(shù)上限是多少理想情況下需要同時(shí)召回 A 和 B讓模型拼出10 次。但純分塊檢索很可能只召回 B模型只能回答含義不知道默認(rèn)值是 10最終答案就是殘缺的。從輕到重有四種緩解方案標(biāo)題/上下文補(bǔ)全切分時(shí)把文檔標(biāo)題、章節(jié)路徑拼進(jìn) chunk 前綴讓模型知道這個(gè)參數(shù)在哪個(gè)模塊上下文里。成本幾乎為零強(qiáng)烈建議先做。建立知識(shí)本體Ontology提前定義實(shí)體、關(guān)系和概念層級(jí)檢索時(shí)先走本體定位到相關(guān)概念再回到向量庫(kù)做補(bǔ)充。適合領(lǐng)域封閉、概念穩(wěn)定的知識(shí)庫(kù)。升級(jí)為 GraphRAG把知識(shí)庫(kù)建成圖結(jié)構(gòu)沿實(shí)體關(guān)系展開(kāi)鄰居節(jié)點(diǎn)再綜合生成。適合多跳復(fù)雜問(wèn)題但建設(shè)和維護(hù)成本最高。引入 Agentic RAG讓 LLM 自己決定檢索策略。比如用戶(hù)問(wèn)今年新增客戶(hù)數(shù)相比去年如何Agent 會(huì)先檢索今年的報(bào)表發(fā)現(xiàn)缺少去年數(shù)據(jù)再發(fā)起一次檢索補(bǔ)齊最后對(duì)比回答。等于把多輪檢索能力交給模型編排。我的建議是不要一上來(lái)就沖 GraphRAG 或者 Agent 框架。先做第 1 條看命中率提升多少文檔量真的到幾百上千份、且關(guān)聯(lián)性強(qiáng)的場(chǎng)景再考慮重方案。復(fù)雜架構(gòu)的維護(hù)成本很容易把項(xiàng)目拖垮。5. 常見(jiàn)問(wèn)題排查實(shí)錄那些網(wǎng)上沒(méi)人寫(xiě)清楚的坑5.1 RAG 知識(shí)庫(kù)能存圖片嗎RAG 知識(shí)庫(kù)能存儲(chǔ)圖片嘛這個(gè)問(wèn)題搜的人非常多這里一次說(shuō)透。默認(rèn)的 Chroma 文本 RAG不能存儲(chǔ)圖片本身。Chroma 存的是一維浮點(diǎn)向量和文本字段document字段本質(zhì)上也是文本。但圖片的信息完全可以存進(jìn)去。業(yè)界有兩條常見(jiàn)落地路線(xiàn)對(duì)圖片做 OCR 或視覺(jué)模型描述生成文字后存入向量庫(kù)。比如調(diào)用 MiniCPM-V 把圖片描述成一句自然語(yǔ)言存進(jìn) Chroma用戶(hù)問(wèn)圖里寫(xiě)了什么時(shí)召回的是描述文字再交給 LLM 組織回答。引入多模態(tài)向量化。用 CLIP 這類(lèi)模型把圖片直接編碼成向量query 的文本也用同樣模型編碼這樣圖文可以在向量空間里做相似度檢索。但這種方式需要額外部署多模態(tài)模型而且要求你知道自己的圖片大致的語(yǔ)義空間門(mén)檻明顯更高。對(duì)絕大多數(shù)項(xiàng)目走 OCR 文本描述 的折中路線(xiàn)就夠了整個(gè)鏈路依然是文本 RAG穩(wěn)定且可控。5.2 新增文檔后檢索結(jié)果不對(duì)持久化目錄的坑這個(gè)問(wèn)題排在我被問(wèn)次數(shù)榜前三。常見(jiàn)原因就幾個(gè)沒(méi)開(kāi)持久化。還是用Client()創(chuàng)建的臨時(shí)內(nèi)存庫(kù)進(jìn)程一重啟數(shù)據(jù)歸零。開(kāi)了持久化但路徑不一致。上次用的./data這次寫(xiě)成./data_newChroma 會(huì)認(rèn)為這是個(gè)全新的空庫(kù)。用了create_collection而不是get_or_create_collection。同名 Collection 已存在時(shí)create_collection會(huì)直接拋錯(cuò)而不是復(fù)用。定時(shí)任務(wù)重復(fù)導(dǎo)入同一批文檔每次都重建 Collection白白重算所有向量還污染線(xiàn)上數(shù)據(jù)。另外新增了文檔但檢索結(jié)果沒(méi)變化還有一種可能是查詢(xún)時(shí) filter 沒(méi)寫(xiě)對(duì)。比如新文檔的category是manual_new你搜索時(shí)where{category: manual}自然搜不到。先查collection.get(include[metadatas])看元數(shù)據(jù)到底怎么寫(xiě)的比在猜哪一步出錯(cuò)高效得多。5.3 并發(fā)寫(xiě)入和版本兼容問(wèn)題Chroma 是嵌入式庫(kù)不是高并發(fā)服務(wù)。我在 FastAPI 里同時(shí)多個(gè)線(xiàn)程寫(xiě)同一個(gè) Collection碰到過(guò) database is locked 的報(bào)錯(cuò)原因就是 SQLite 文件鎖。寫(xiě)鎖粒度是文件級(jí)的多個(gè)線(xiàn)程并發(fā)寫(xiě)會(huì)互相阻塞。我的規(guī)避辦法是把寫(xiě)入操作收口到一個(gè)隊(duì)列串行執(zhí)行查詢(xún)走快照讀不受影響可以放開(kāi)并發(fā)。如果業(yè)務(wù)流量真的很大建議把 Chroma 單獨(dú)封裝成一個(gè)內(nèi)部服務(wù)或者直接遷移到 Qdrant不要讓?xiě)?yīng)用進(jìn)程直接面對(duì)寫(xiě)并發(fā)。版本兼容是最容易被忽略的坑。Chroma 0.4 升到 0.5 之后chromadb.config.Settings的行為有變化LangChain 的封裝也換了新包名。很多網(wǎng)上教程的寫(xiě)法在新版本上會(huì)直接報(bào)錯(cuò)。我的建議是項(xiàng)目里鎖版本chromadb0.5.x別用pip install chromadb一行裝完。升級(jí)前先跑一遍入庫(kù)和檢索的 smoke test。遇到Expected 3D tensor got 2D這種報(bào)錯(cuò)基本是 embedding 維度不匹配。舊庫(kù)里的向量和新模型維度不一致唯一的辦法是清空庫(kù)重新灌。最后補(bǔ)一個(gè)我調(diào)了兩年才養(yǎng)成的排查習(xí)慣檢索效果很差的時(shí)候別急著調(diào)相似度閾值和 Top-K。先用最原始的關(guān)鍵詞在庫(kù)里做一次文本模糊搜索用where_document{$contains: 關(guān)鍵詞}看相關(guān)文本到底在不在庫(kù)里。如果關(guān)鍵詞都搜不到說(shuō)明入庫(kù)環(huán)節(jié)就沒(méi)進(jìn)去如果能搜到但向量檢索排不到前面那才是 embedding 和排序的問(wèn)題。這個(gè)順序能幫你快速定位八成以上的排查場(chǎng)景。我個(gè)人的體會(huì)是Chroma RAG 這套方案真正拉開(kāi)差距的地方全在檢索前的準(zhǔn)備——拆分規(guī)則、embedding 選型、元數(shù)據(jù)設(shè)計(jì)看著不起眼卻決定了準(zhǔn)確率的天花板。工具本身反而是最不需要糾結(jié)的一環(huán)。后續(xù)文檔之間關(guān)系如果變得更復(fù)雜可以試著給每個(gè) chunk 配上知識(shí)本體的注釋再平滑過(guò)渡到 GraphRAG目前這套代碼把 Collection、embedding 函數(shù)和檢索引擎都留了替換空間到時(shí)候把 Chroma 換成 Qdrant改動(dòng)也只需要集中在初始化那一層。先把基礎(chǔ)鏈路跑通用真實(shí)業(yè)務(wù)數(shù)據(jù)拿到 Hit Rate再談下一步優(yōu)化這才是最務(wù)實(shí)的一條路。