、召回、重排、生成)
在本地跑了幾個(gè)月RAG項(xiàng)目我越來越覺得大多數(shù)人第一次接觸 LlamaIndex 時(shí)不是被模型難倒而是被“建庫(kù)、召回、重排、生成”這四個(gè)環(huán)節(jié)之間的脫節(jié)搞崩潰。你辛辛苦苦寫完 Embedding 和建庫(kù)邏輯到了查詢階段又得處理 Retriever 返回的節(jié)點(diǎn)還要為了效果再掛一層 Rerank最后手動(dòng)拼接 Prompt 調(diào)用 LLM。每一步單獨(dú)看都不復(fù)雜可串起來卻總在細(xì)節(jié)上翻車。折騰過幾次之后我把這套流程收斂成了一個(gè)腳本一行命令直接跑完先判斷索引存不存在不存在就自動(dòng)建庫(kù)存在就直接進(jìn)入召回→重排→生成整個(gè)過程每一步都有日志輸出。如果你正在做文檔問答、私有知識(shí)庫(kù)、技術(shù)客服這類項(xiàng)目這篇東西應(yīng)該能幫你少走不少?gòu)澛贰?. RAG 全鏈路的核心矛盾與一條命令的價(jià)值1.1 建庫(kù)→召回→重排→生成四個(gè)環(huán)節(jié)到底在做什么先別急著寫代碼把四個(gè)詞拆開看清楚。建庫(kù)解決的是“知識(shí)在哪里”的問題。原始文檔是一堆散文、表格、標(biāo)題模型不能直接理解整本書。你需要先按一定策略把文檔切成文本塊給每塊文本算一個(gè)向量然后把向量和原始文本一起存到索引里。這一步?jīng)Q定了后續(xù)所有鏈路的上限。很多人把建庫(kù)想得太簡(jiǎn)單以為扔給框架就行實(shí)際上切分粒度、元數(shù)據(jù)、存儲(chǔ)方式都會(huì)直接影響最終回答質(zhì)量。召回解決的是“找哪些內(nèi)容”的問題。用戶提問后系統(tǒng)把問句向量化在向量索引里找最相似的 K 個(gè)文本塊。這里的關(guān)鍵是“速度快、別漏”寧可多召回一些不相關(guān)的也不能漏掉真正包含答案的片段。這個(gè)過程類似海選標(biāo)準(zhǔn)可以寬松一點(diǎn)。重排解決的是“哪些內(nèi)容真正有用”的問題。向量召回基于embedding相似度但語(yǔ)義相似不等于能回答問題。比如“年假怎么算”和“年假的申請(qǐng)流程”向量距離很近但后者可能根本不包含答案。重排模型會(huì)更精細(xì)地計(jì)算“查詢-片段”的相關(guān)性把真正有用的片段排到最前。海選之后做一輪復(fù)試過濾掉噪音這是RAG效果質(zhì)變的關(guān)鍵。生成解決的是“如何有依據(jù)地說人話”的問題。把重排后的少量片段按模板拼進(jìn)Prompt交給大模型生成答案。同時(shí)要求模型引用片段中的內(nèi)容能顯著降低幻覺。如果少做或跳過重排Prompt里塞進(jìn)去的噪音太多大模型就容易被帶偏。這四個(gè)環(huán)節(jié)缺一不可。但傳統(tǒng)的做法是四個(gè)環(huán)節(jié)各自獨(dú)立腳本開發(fā)者既要管中間產(chǎn)物又要小心不同腳本里模型配置不一致。我實(shí)際遇到過的案例建庫(kù)腳本里用的 Embedding 模型是英文版查詢腳本里換成了中文模型向量維度都沒變運(yùn)行不報(bào)錯(cuò)結(jié)果檢索結(jié)果莫名其妙。一條命令把全流程串起來至少能減少這類低級(jí)錯(cuò)誤。1.2 為什么選擇 LlamaIndex而不是從零輪子如果你只是做原型手動(dòng)用 SentenceTransformer 算向量再加 sklearn 的余弦相似度也能跑通但那僅限于幾十個(gè)文本塊的 Demo。一旦進(jìn)入真實(shí)場(chǎng)景你很快會(huì)遇到這些問題文檔格式多種多樣有 PDF、Word、Markdown、HTML一個(gè)文檔可能幾百頁(yè)切分策略需要定制你需要保存中間狀態(tài)下次啟動(dòng)不能全部重新算你還可能要接不同的向量庫(kù)、不同的大模型接口。LlamaIndex 最核心的價(jià)值不是某個(gè)單一算法多強(qiáng)而是把“文檔加載→文本解析→索引構(gòu)建→檢索→后處理→生成”整條鏈路抽象成了統(tǒng)一接口。它的數(shù)據(jù)連接器能讀一堆文件格式節(jié)點(diǎn)解析器負(fù)責(zé)切分VectorStoreIndex 負(fù)責(zé)向量化與存儲(chǔ)Retriever 負(fù)責(zé)召回NodePostprocessor 負(fù)責(zé)重排最后通過 Query Engine 或者自定義流程交給 LLM。傳入同樣的數(shù)據(jù)你可以在不改變主流程的情況下切換不同的 Embedding 模型、向量數(shù)據(jù)庫(kù)和后端大模型。更關(guān)鍵的是LlamaIndex 在工程上留了持久化機(jī)制索引構(gòu)建好之后向量、文檔映射、索引元數(shù)據(jù)都能存到本地目錄。下次啟動(dòng)直接從磁盤加載而不是每次從零建模。這一條直接讓“一條命令跑全流程”成為可能——建庫(kù)是一次性工作之后每次啟動(dòng)都只是加載索引并查詢。1.3 “一條命令”不是炫技而是工程化的基石為什么不寫多個(gè)腳本比如build_index.py和query.py而非要合并成一個(gè)命令因?yàn)椤叭肟趩我弧北旧砭褪且环N工程約束。在團(tuán)隊(duì)協(xié)作中新同事拿到倉(cāng)庫(kù)后只需要跑一條命令不用去翻 README“先執(zhí)行 A 再執(zhí)行 B”在自動(dòng)化任務(wù)中定時(shí)重建索引也只需要在 Cron 里寫一行在排障時(shí)我們只需要看一條命令的日志流中間不會(huì)出現(xiàn)“上次重建索引用的模型和這次不一致”的詭異問題。有人會(huì)覺得“一條命令”意味著參數(shù)被寫死、擴(kuò)展性差其實(shí)恰恰相反。一個(gè)設(shè)計(jì)良好的 CLI 入口可以通過參數(shù)控制文檔目錄、索引目錄、Top K 值、重排數(shù)量、是否強(qiáng)制重建默認(rèn)值滿足大多數(shù)場(chǎng)景同時(shí)開放自定義。這也是我推薦大家照著這個(gè)思路去搭建自己項(xiàng)目的核心原因。2. 環(huán)境準(zhǔn)備與組件選型2.1 依賴清單與安裝命令在開始寫代碼前先把環(huán)境準(zhǔn)備好。我建議用 Python 3.10 或更高版本開一個(gè)干凈的虛擬環(huán)境避免和項(xiàng)目依賴沖突。以下是我在這套流程里實(shí)際使用的核心依賴pip install llama-index-core pip install llama-index-readers-file pip install llama-index-embeddings-huggingface pip install llama-index-llms-ollama pip install sentence-transformersllama-index-core是 LlamaIndex 的核心庫(kù)提供文檔加載、索引、檢索等主流程llama-index-readers-file讓 SimpleDirectoryReader 支持更多文檔格式llama-index-embeddings-huggingface負(fù)責(zé)接入 Hugging Face 上的 Embedding 模型llama-index-llms-ollama用于連接本地部署的推理服務(wù)sentence-transformers是我們自定義重排器時(shí)要用到的 CrossEncoder 工具包。如果你后面打算用 Chroma、Qdrant 或者 Milvus需要再裝對(duì)應(yīng)的擴(kuò)展包。但在起步階段我強(qiáng)烈建議先用 LlamaIndex 自帶的SimpleVectorStore它不需要額外啟動(dòng)服務(wù)索引可以直接持久化到本地目錄足夠跑通整條鏈路。2.2 Embedding、Rerank、LLM 三個(gè)模型的選型Embedding 模型這個(gè)環(huán)節(jié)決定文本向量化的質(zhì)量。中文場(chǎng)景下我優(yōu)先推薦 BGE 系列尤其BAAI/bge-small-zh-v1.5維度 512對(duì) CPU 和內(nèi)存都比較友好效果也能滿足大多數(shù)場(chǎng)景。如果機(jī)器條件更好可以換BAAI/bge-base-zh-v1.5維度 768準(zhǔn)確率會(huì)更高一些。再往上還有BAAI/bge-m3支持多語(yǔ)言和長(zhǎng)文本但資源占用也大很多。記住一個(gè)原則建庫(kù)和查詢必須使用同一個(gè) Embedding 模型換模型就必須重新建庫(kù)。Rerank 模型我用的是BAAI/bge-reranker-base。它和bge-reranker-large相比速度更快效果差距并沒有想象中那么大。重排模型通常比 Embedding 模型大不少如果內(nèi)存緊張建議用量化版本或者放在 GPU 上。還有一個(gè)無法回避的現(xiàn)實(shí)重排是逐對(duì)計(jì)算的性能和 Top K 直接相關(guān)所以不要一開始就把重排數(shù)量設(shè)成好幾十。LLM 模型為了隱私和成本控制我優(yōu)先用本地 Ollama 部署的開源模型比如qwen2.5:7b。你只需要在代碼里替換成你自己的服務(wù)地址和模型名就行。如果公司內(nèi)部有其他兼容 OpenAI 協(xié)議的統(tǒng)一推理平臺(tái)也完全可以接入LlamaIndex 的 LLM 抽象層會(huì)幫你統(tǒng)一處理。2.3 存儲(chǔ)方案與向量檢索的直觀理解起步階段默認(rèn)的SimpleVectorStore是最合適的。它本質(zhì)上就是把向量存在內(nèi)存里然后序列化到本地目錄。你不需要去裝一個(gè) Vector Database也不用配置連接字符串。等你索引條目到了幾十萬(wàn)級(jí)或者需要多人并發(fā)查詢、復(fù)雜過濾、動(dòng)態(tài)更新時(shí)再遷移到 Chroma 或 Milvus 也不遲。向量檢索是怎么工作的簡(jiǎn)單說每個(gè)文本塊被 Embedding 模型映射成一個(gè)高維向量查詢時(shí)同樣把問句映射成向量然后計(jì)算兩個(gè)向量之間的余弦相似度。余弦相似度公式是向量點(diǎn)積除以模長(zhǎng)乘積結(jié)果區(qū)間在 -1 到 1 之間越接近 1 表示方向越一致、語(yǔ)義越相關(guān)。比如二維向量 [1,0] 和 [0,1] 的余弦相似度是 0它們正交可以理解成完全不相關(guān)[1,0] 和 [0.99,0.01] 的余弦相似度接近 1則方向非常接近。這也是為什么 RAG 要配合重排——余弦相似度衡量的是語(yǔ)義分布是否接近但無法直接判斷“這段文字是否包含問題的答案”。重排器會(huì)以更精細(xì)的交互方式把查詢和候選文本拼起來重新打分把相似但無用的內(nèi)容壓下去。3. 從零搭建索引構(gòu)建與核心參數(shù)取舍3.1 文檔加載與常見格式坑LlamaIndex 里最簡(jiǎn)單的方式是用SimpleDirectoryReader讀取一個(gè)目錄下的所有文件。它的實(shí)現(xiàn)足夠聰明能根據(jù)文件擴(kuò)展名自動(dòng)選擇解析器。但實(shí)際項(xiàng)目里文檔格式往往是最大的坑。先說 PDF。很多 PDF 是從打印系統(tǒng)導(dǎo)出的沒有文本層直接解析會(huì)得到一堆亂碼或者大量空白。即便有文本層復(fù)雜的表格和排版也會(huì)被打亂順序。我的建議是PDF 優(yōu)先轉(zhuǎn)成 Markdown 或者純文本再喂給索引器如果 PDF 是掃描件先走一層 OCR 轉(zhuǎn)換否則后續(xù)無論檢索還是重排都會(huì)受到極大影響。再說 Word。SimpleDirectoryReader對(duì) docx 的支持不錯(cuò)但前提是你安裝了對(duì)應(yīng)的依賴。如果你遇到“文件存在但讀取不到內(nèi)容”的情況先檢查是不是缺少解析庫(kù)比如讀取 docx 需要安裝python-docx。表格數(shù)據(jù)是另一類麻煩。如果文檔里全是表格直接按段落切分會(huì)把表格拆得七零八落。我建議在進(jìn)入 RAG 之前把表格轉(zhuǎn)換為 Markdown 表格格式因?yàn)?Markdown 表格在文本切分時(shí)還能保留結(jié)構(gòu)語(yǔ)義。標(biāo)題、列表、注釋也同理盡量保留結(jié)構(gòu)信息有助于后續(xù)檢索時(shí)區(qū)分主次。3.2 文本切分參數(shù)chunk_size、overlap、metadata文本切分是建庫(kù)環(huán)節(jié)最值得花時(shí)間調(diào)的部分。LlamaIndex 默認(rèn)的SentenceSplitter已經(jīng)能處理大多數(shù)情況但你需要理解兩個(gè)關(guān)鍵參數(shù)chunk_size和chunk_overlap。chunk_size控制每個(gè)文本塊的最大字符數(shù)。我實(shí)測(cè)下來中文場(chǎng)景下512是一個(gè)比較穩(wěn)的起步值。這個(gè)數(shù)字太小比如 128一個(gè)完整的技術(shù)方案會(huì)被切成好幾塊回答問題時(shí)就容易找不到完整上下文數(shù)字太大比如 2048一個(gè)塊里包含太多段落向量語(yǔ)義會(huì)被稀釋而且最終 Prompt 塞進(jìn)去也容易超長(zhǎng)。當(dāng)然這不是死的如果你的文檔本身邏輯塊很大可以適當(dāng)調(diào)大。chunk_overlap控制相鄰文本塊之間的重疊字符數(shù)。為什么要重疊因?yàn)榍蟹贮c(diǎn)很可能落在一個(gè)句子或概念中間有了重疊后半段文檔的起始部分會(huì)在前一個(gè)塊里再出現(xiàn)一次避免關(guān)鍵信息正好被切掉。我通常設(shè)置為50到100大約控制在chunk_size的 10% 到 20%。如果你的文檔里天然有清晰的 Markdown 標(biāo)題分級(jí)也可以考慮用MarkdownNodeParser它會(huì)更智能地按標(biāo)題層級(jí)切分而不是硬切長(zhǎng)度。還有一個(gè)容易被忽略但非常重要的點(diǎn)給文本塊掛 metadata。比如file_path或page_number這樣生成答案時(shí)可以通過node.metadata拿到來源在 Prompt 里展示“參考來源”或者在 UI 上高亮對(duì)應(yīng)的 PDF 頁(yè)碼。沒有來源的 RAG 很難讓人信任。3.3 向量化與索引持久化文檔切好之后就到了 Embedding 和索引構(gòu)建環(huán)節(jié)。LlamaIndex 的VectorStoreIndex會(huì)逐塊調(diào)用 Embedding 模型把文本塊向量化然后寫入存儲(chǔ)。如果你有 1 萬(wàn)個(gè)文本塊每個(gè)塊在 CPU 上做 Embedding 大約需要 0.1 到 0.5 秒全量建庫(kù)可能就得半小時(shí)以上。耐心等不要在中途頻繁打斷進(jìn)程否則容易寫出不完整的向量文件。持久化其實(shí)很簡(jiǎn)單核心代碼如下storage_context StorageContext.from_defaults(persist_dir./storage) index VectorStoreIndex.from_documents(documents, storage_contextstorage_context) storage_context.persist()持久化之后storage目錄里會(huì)出現(xiàn)多個(gè) JSON 文件分別存向量、文檔關(guān)系、索引元數(shù)據(jù)。以后加載索引只需要storage_context StorageContext.from_defaults(persist_dir./storage) index load_index_from_storage(storage_context)這里有一個(gè)很重要的工程經(jīng)驗(yàn)索引和 Embedding 模型是綁定在一起的。如果你升級(jí)了 Embedding 模型或者改變了切分參數(shù)必須強(qiáng)制重建索引否則舊索引和新查詢向量無法對(duì)齊。這也是為什么我的腳本里保留了一個(gè)--force-rebuild參數(shù)專門用于這種“配置變更后的重建”。4. 一條命令跑通全流程完整的可復(fù)現(xiàn)工程4.1 工程目錄與 CLI 設(shè)計(jì)我做這套腳本時(shí)目錄約定如下rag_pipeline/ ├── data/ # 放原始文檔 ├── storage/ # 索引持久化目錄 └── local_rag.py # 主腳本主腳本接收以下參數(shù)參數(shù)作用默認(rèn)值--query用戶提問必填--data-dir原始文檔目錄./data--index-dir索引持久化目錄./storage--force-rebuild強(qiáng)制重建索引False--top-k召回候選數(shù)20--rerank-top-n重排后保留數(shù)5我不建議一開始設(shè)計(jì)一堆花哨的接口上面這幾個(gè)參數(shù)已經(jīng)覆蓋絕大多數(shù)場(chǎng)景。top-k和rerank-top-n是你在做效果評(píng)測(cè)時(shí)最常調(diào)整的兩個(gè)旋鈕后面會(huì)細(xì)講。4.2 完整代碼從建庫(kù)到生成一步到位下面是完整的local_rag.py。我把流程拆成了四個(gè)子步驟并且用日志打印每一步方便排查。這段代碼基于 LlamaIndex 0.10.x 的 API 編寫如果你用的是其他版本可能需要小幅適配。import argparse import os import time from typing import List # LlamaIndex 核心 from llama_index.core import ( SimpleDirectoryReader, VectorStoreIndex, StorageContext, load_index_from_storage, Settings, ) from llama_index.core.schema import BaseNode from llama_index.core.schema import QueryBundle from llama_index.core.node_parser import SentenceSplitter from llama_index.core.postprocessor.types import BaseNodePostprocessor # Embedding 和 LLM from llama_index.embeddings.huggingface import HuggingFaceEmbedding from llama_index.llms.ollama import Ollama # 重排模型 from sentence_transformers import CrossEncoder # 配置全局模型 Settings.embed_model HuggingFaceEmbedding( model_nameBAAI/bge-small-zh-v1.5 ) # 根據(jù)你的本地推理服務(wù)修改 model 和 base_url Settings.llm Ollama( modelqwen2.5:7b, request_timeout120.0, ) # 自定義重排后處理器 class LocalReranker(BaseNodePostprocessor): def __init__(self, model_name: str BAAI/bge-reranker-base, top_n: int 5): super().__init__() self._model CrossEncoder(model_name) self._top_n top_n property def _node_type(self) - str: return Node def postprocess_nodes( self, nodes: List[BaseNode], query_bundle: QueryBundle, **kwargs ) - List[BaseNode]: if not nodes: return nodes pairs [(query_bundle.query_str, node.get_content()) for node in nodes] scores self._model.predict(pairs) scored_nodes list(zip(scores, nodes)) scored_nodes.sort(keylambda x: x[0], reverseTrue) return [node for _, node in scored_nodes[: self._top_n]] def build_index(data_dir: str, index_dir: str, force_rebuild: bool): 建庫(kù)讀取文檔→切分→向量化→持久化 if os.path.exists(index_dir) and not force_rebuild: print([建庫(kù)] 檢測(cè)到已有索引跳過建庫(kù)步驟) storage_context StorageContext.from_defaults(persist_dirindex_dir) return load_index_from_storage(storage_context) print(f[建庫(kù)] 開始讀取目錄: {data_dir}) documents SimpleDirectoryReader( input_dirdata_dir, required_exts[.md, .txt, .docx, .pdf], recursiveTrue, ).load_data() print([建庫(kù)] 開始切分文本...) splitter SentenceSplitter(chunk_size512, chunk_overlap50) nodes splitter.get_nodes_from_documents(documents) print(f[建庫(kù)] 共切分 {len(nodes)} 個(gè)文本塊開始向量化...) storage_context StorageContext.from_defaults(persist_dirindex_dir) index VectorStoreIndex(nodes, storage_contextstorage_context) storage_context.persist() print([建庫(kù)] 索引構(gòu)建完成并已持久化) return index def retrieve(index, query: str, top_k: int): 召回從索引中獲取候選節(jié)點(diǎn) print(f[召回] 開始向量召回 top {top_k} ...) retriever index.as_retriever(similarity_top_ktop_k) nodes retriever.retrieve(query) print(f[召回] 得到 {len(nodes)} 個(gè)候選片段) return nodes def rerank(nodes, query: str, rerank_top_n: int): 重排用 CrossEncoder 對(duì)候選片段二次打分 print(f[重排] 開始精排保留 top {rerank_top_n} ...) processor LocalReranker( model_nameBAAI/bge-reranker-base, top_nrerank_top_n, ) query_bundle QueryBundle(query_strquery) filtered_nodes processor.postprocess_nodes(nodes, query_bundle) print(f[重排] 最終保留 {len(filtered_nodes)} 個(gè)片段) return filtered_nodes def generate(query: str, nodes): 生成拼接 Prompt 并調(diào)用 LLM print([生成] 拼接上下文調(diào)用大模型...) context \n\n.join( f[片段{i1}]\n{node.get_content()} for i, node in enumerate(nodes) ) prompt f請(qǐng)根據(jù)下面的參考片段回答用戶問題。 參考片段 {context} 用戶問題{query} 要求 1. 優(yōu)先使用參考片段中的信息回答 2. 如果參考片段中沒有相關(guān)內(nèi)容請(qǐng)直接回答“未在資料中找到相關(guān)信息” 3. 回答盡量簡(jiǎn)潔、準(zhǔn)確 回答 response Settings.llm.complete(prompt) print(\n * 40) print(問答結(jié)果) print(response.text) print( * 40) return response.text def run_pipeline(): parser argparse.ArgumentParser(description一條命令跑完 RAG 全流程) parser.add_argument(--query, requiredTrue, help用戶提問) parser.add_argument(--data-dir, default./data, help原始文檔目錄) parser.add_argument(--index-dir, default./storage, help索引持久化目錄) parser.add_argument(--force-rebuild, actionstore_true, help強(qiáng)制重建索引) parser.add_argument(--top-k, typeint, default20, help召回候選數(shù)) parser.add_argument(--rerank-top-n, typeint, default5, help重排后保留數(shù)) args parser.parse_args() # 步驟 1建庫(kù) time_start time.time() index build_index(args.data_dir, args.index_dir, args.force_rebuild) # 步驟 2召回 nodes retrieve(index, args.query, args.top_k) # 步驟 3重排 filtered_nodes rerank(nodes, args.query, args.rerank_top_n) # 步驟 4生成 generate(args.query, filtered_nodes) time_end time.time() print(f\n[完成] 總耗時(shí): {time_end - time_start:.2f} 秒) if __name__ __main__: run_pipeline()4.3 執(zhí)行效果與預(yù)期輸出假設(shè)你的data目錄里放了幾份員工手冊(cè)然后執(zhí)行python local_rag.py \ --query 新員工的年假天數(shù)是怎么計(jì)算的 \ --data-dir ./data \ --top-k 20 \ --rerank-top-n 5第一次運(yùn)行時(shí)如果storage目錄不存在會(huì)自動(dòng)進(jìn)入建庫(kù)流程。你會(huì)看到類似這樣的日志[建庫(kù)] 開始讀取目錄: ./data [建庫(kù)] 開始切分文本... [建庫(kù)] 共切分 128 個(gè)文本塊開始向量化... [建庫(kù)] 索引構(gòu)建完成并已持久化 [召回] 開始向量召回 top 20 ... [召回] 得到 20 個(gè)候選片段 [重排] 開始精排保留 top 5 ... [重排] 最終保留 5 個(gè)片段 [生成] 拼接上下文調(diào)用大模型... 問答結(jié)果 根據(jù)員工手冊(cè)新員工的年假天數(shù)根據(jù)入職時(shí)間按比例折算具體為…… [完成] 總耗時(shí): 18.23 秒第二次再執(zhí)行同一條命令時(shí)建庫(kù)步驟會(huì)直接跳過總耗時(shí)通常能降到 5 秒以內(nèi)取決于重排模型和 LLM 的速度。這就是“一條命令跑完全流程”的直觀體驗(yàn)。4.4 參數(shù)調(diào)節(jié)建議表調(diào)參是 RAG 的日常。下面這張表列出的默認(rèn)值是我在多個(gè)文檔問答項(xiàng)目里反復(fù)試出來的起點(diǎn)但最終取值一定要基于你自己的文檔做評(píng)測(cè)。參數(shù)默認(rèn)值設(shè)置過低的后果設(shè)置過高的后果chunk_size512上下文碎片化關(guān)鍵信息被切斷向量語(yǔ)義被稀釋檢索精度下降Prompt 易超長(zhǎng)chunk_overlap50切分點(diǎn)可能切斷完整句子文本塊之間大量重復(fù)索引體積膨脹top_k20漏召回正確答案不在候選中重排負(fù)擔(dān)重單次查詢延遲變高rerank_top_n5過濾掉了潛在正確答案LLM 上下文噪聲增加生成變慢且容易跑偏我自己的習(xí)慣是先固定chunk_size512和chunk_overlap50然后用一組真實(shí)問題做評(píng)測(cè)。如果發(fā)現(xiàn)答案沒找到先把top_k從 20 升到 40看是不是召回階段漏了如果召回候選里能找到正確答案但最終答案不對(duì)那就把rerank_top_n從 5 調(diào)到 8或者檢查重排模型是否與領(lǐng)域匹配如果整體延遲太高優(yōu)先降top_k和rerank_top_n。5. 實(shí)測(cè)遇到的高頻問題和排查技巧5.1 召回結(jié)果為空或根本檢索不到最典型的癥狀是索引構(gòu)建成功日志也提示得到了候選片段但生成出的答案胡編亂造或者壓根沒有用上參考內(nèi)容。首先檢查 Embedding 模型是否加載成功。如果 Hugging Face 模型第一次下載失敗Settings.embed_model可能變成空對(duì)象LlamaIndex 不會(huì)直接報(bào)錯(cuò)而是用默認(rèn)的模擬模型結(jié)果檢索結(jié)果全部是隨機(jī)序。我踩過這個(gè)坑花費(fèi)大量時(shí)間排查后才發(fā)現(xiàn)是模型文件沒下全。解決辦法是啟動(dòng)時(shí)打印Settings.embed_model的關(guān)鍵屬性或者單獨(dú)跑一次embedding Settings.embed_model.get_text_embedding(測(cè)試)看維度是否正常。其次檢查文檔切分是否成功。如果原始文檔里全是圖片掃描件文本切分之后可能一個(gè)有效節(jié)點(diǎn)都沒有。你可以臨時(shí)打印建庫(kù)后的節(jié)點(diǎn)內(nèi)容和數(shù)量確認(rèn)至少有一個(gè)完整句子級(jí)的文本塊。我見過某項(xiàng)目把掃描版 PDF 直接扔進(jìn)去索引建了但節(jié)點(diǎn)里全是空行最后召回一堆空白。還有幾種低概率原因查詢語(yǔ)言與文檔語(yǔ)言不一致比如文檔是中文查詢用了英文模塊文本切分后只有寥寥幾個(gè)塊向量空間上的區(qū)分度不夠又或者你有多個(gè)storage目錄命令行參數(shù)--index-dir指錯(cuò)了位置。排查時(shí)先看日志里的索引路徑再打印幾個(gè)召回節(jié)點(diǎn)的node.get_content()開頭 100 個(gè)字符基本就能定位。5.2 重排階段超時(shí)、內(nèi)存爆炸CrossEncoder 是逐對(duì)計(jì)算的當(dāng)top_k20時(shí)一次查詢要做 20 次模型推理這比 Embedding 一次查詢要多得多。如果你把top_k設(shè)成 100單次重排耗時(shí)可能長(zhǎng)達(dá)十幾秒在 CPU 機(jī)器上甚至可能把內(nèi)存打滿。解決辦法有三個(gè)方向把top_k控制在合理區(qū)間比如 20 到 50使用更小的重排模型比如bge-reranker-base而不是large對(duì)重排模型做量化或者干脆跑在 GPU 上。如果業(yè)務(wù)場(chǎng)景對(duì)首字延遲特別敏感可以考慮把重排模型做成獨(dú)立服務(wù)批量異步處理但這就超出了單命令的范疇屬于上線架構(gòu)問題。另外sentence_transformers在predict的時(shí)候默認(rèn)會(huì)使用你本機(jī)最大的 batch size如果顯存或內(nèi)存不夠可以在調(diào)用時(shí)加一個(gè)batch_size16參數(shù)scores self._model.predict(pairs, batch_size16)這個(gè)參數(shù)并不影響結(jié)果只是限制同時(shí)處理的樣本數(shù)能明顯降低內(nèi)存尖峰。5.3 生成結(jié)果亂說、引用錯(cuò)誤RAG 最大的風(fēng)險(xiǎn)是 LLM 無視參考片段自由發(fā)揮。我的排查經(jīng)驗(yàn)是先看 Prompt 模板有沒有做強(qiáng)約束。如果直接寫“根據(jù)以下內(nèi)容回答問題”模型自由度太高。更穩(wěn)的寫法是明確要求“如果參考片段中沒有對(duì)應(yīng)信息請(qǐng)直接回答未找到”同時(shí)給片段編號(hào)讓答案中帶上[片段1]這樣的引用標(biāo)記。下面是我常用的 Prompt 約束1. 優(yōu)先使用參考片段中的信息回答 2. 如果參考片段中沒有相關(guān)內(nèi)容請(qǐng)直接回答“未在資料中找到相關(guān)信息” 3. 回答中引用內(nèi)容時(shí)請(qǐng)標(biāo)注來源編號(hào)第二個(gè)常見原因是沒有做好重排噪聲片段被塞進(jìn)上下文。某個(gè)片段雖然和問題有較高的向量相似度但內(nèi)容其實(shí)是另一個(gè)部門的制度LLM 看到一堆相似但不相關(guān)的片段很容易被帶偏。建議把重排后的片段打印到一個(gè)調(diào)試日志里人工檢查每個(gè)片段是否真的回答問題再?zèng)Q定是否調(diào)rerank_top_n。第三個(gè)原因是 LLM 上下文被截?cái)唷Ｈ绻鹯erank_top_n8且每個(gè)片段 512 字符上下文很容易超過 4000 字符模型在長(zhǎng)上下文中容易“遺忘”靠后的內(nèi)容。解決辦法是減小chunk_size或rerank_top_n或者在 Prompt 中讓模型優(yōu)先關(guān)注前幾個(gè)片段。5.4 增量更新與索引失效最簡(jiǎn)單的索引更新方式是全量重建。如果你的文檔量不大直接跑一遍--force-rebuild是最省心的絕對(duì)不會(huì)出現(xiàn)新文檔和舊向量混存的臟狀態(tài)。如果文檔量很大全量重建的時(shí)間不可接受就需要做增量插入。LlamaIndex 的VectorStoreIndex本身支持插入新節(jié)點(diǎn)new_documents SimpleDirectoryReader(input_files[./data/new_file.md]).load_data() new_nodes splitter.get_nodes_from_documents(new_documents) index.insert_nodes(new_nodes) storage_context.persist()但增量更新的難點(diǎn)不在于 API而在于“去重”。如果你重復(fù)插入同一份文檔索引里會(huì)出現(xiàn)重復(fù)向量檢索結(jié)果就會(huì)有大量相同內(nèi)容。我建議在文檔層面維護(hù)一個(gè) hash 表用文件內(nèi)容 hash 作為唯一標(biāo)識(shí)插入前先查這次是不是已經(jīng)處理過。更進(jìn)一步如果你做了復(fù)雜的增量更新最好在索引目錄名里加上版本號(hào)比如storage_v2_20250101萬(wàn)一線上效果衰減還能快速回滾。5.5 高頻問題速查表現(xiàn)象可能原因排查方向檢索結(jié)果全部隨機(jī)Embedding 模型沒加載成功打印Settings.embed_model單獨(dú)測(cè)向量維度召回到空節(jié)點(diǎn)文檔解析失敗檢查 PDF 是否有文本層打印節(jié)點(diǎn)數(shù)量答案沒有引用參考內(nèi)容Prompt 約束太弱加強(qiáng) Prompt 要求強(qiáng)制引用片段編號(hào)重排特別慢top_k太大降低top_k加batch_size索引越來越大重復(fù)插入/切分重疊太大做文件 hash 去重減小chunk_overlap換模型后結(jié)果變差索引和查詢模型不一致強(qiáng)制重建索引6. 影響范圍與進(jìn)階方向6.1 誰(shuí)最需要這套一條命令的 RAG很多人以為 RAG 是算法工程師的專屬工具但我在實(shí)際落地中接觸到的用戶真正高頻使用它的反而是技術(shù)負(fù)責(zé)人、產(chǎn)品經(jīng)理、客服主管和知識(shí)管理專員。技術(shù)人員拿它做內(nèi)部開發(fā)文檔問答把散落在 Confluence 和 GitLab Wiki 里的資料集中成一個(gè)可查詢?nèi)肟诳头F(tuán)隊(duì)拿它接產(chǎn)品 FAQ用戶問“退款多久到賬”系統(tǒng)能從幾十份客服手冊(cè)里快速給出帶出處的話術(shù)產(chǎn)品經(jīng)理拿它分析競(jìng)品文檔和用戶調(diào)研減少大量翻文檔的時(shí)間個(gè)人用戶則用它做論文筆記和電子書查詢本質(zhì)上是一樣的鏈路。這套方案的門檻低到什么程度只要你能把文檔放進(jìn)data目錄會(huì)運(yùn)行一條命令就能得到一個(gè)相對(duì)靠譜的問答系統(tǒng)。這非常符合實(shí)際團(tuán)隊(duì)的協(xié)作方式——不要求每個(gè)人都懂向量數(shù)據(jù)庫(kù)只需要維護(hù)入口和文檔更新。6.2 從“跑通”到“跑好”的演進(jìn)方向如果你已經(jīng)能順利跑通全流程下一步我建議按以下順序做優(yōu)化。第一加入BM25 混合檢索。向量召回擅長(zhǎng)語(yǔ)義相似但不擅長(zhǎng)精確關(guān)鍵詞匹配比如型號(hào)編碼、錯(cuò)誤代碼、合同編號(hào)這類信息。把 BM25 的關(guān)鍵詞命中和向量召回的候選結(jié)果加權(quán)合并可以顯著提升準(zhǔn)確率。第二做查詢改寫。復(fù)雜問題里經(jīng)常有口語(yǔ)化表達(dá)和指代比如“它是不是支持這個(gè)功能”中的“它”需要結(jié)合多輪對(duì)話上下文才能理解。在進(jìn)入召回前先讓 LLM 將用戶問題改寫成一個(gè)標(biāo)準(zhǔn)檢索式往往能給召回帶來很大的提升。第三建立效果評(píng)估集。找業(yè)務(wù)方要 50 到 100 個(gè)真實(shí)問題把參考標(biāo)準(zhǔn)答案標(biāo)注好每次調(diào)整參數(shù)后自動(dòng)跑一遍統(tǒng)計(jì)“檢索命中率”和“答案正確率”。這套機(jī)制比任何人的主觀感覺都可靠也是項(xiàng)目從 Demo 走向上線的關(guān)鍵一步。第四把單命令腳本擴(kuò)展為HTTP 服務(wù)。用 FastAPI 包一層接收查詢請(qǐng)求復(fù)用同一個(gè)storage目錄加上緩存和流式輸出就成了一個(gè)標(biāo)準(zhǔn)的 RAG 推理服務(wù)。第五考慮多租戶與元數(shù)據(jù)過濾。不同團(tuán)隊(duì)的知識(shí)庫(kù)可能混在一起通過給文本塊打team_id元數(shù)據(jù)在檢索時(shí)做條件過濾可以避免跨團(tuán)隊(duì)的信息串味。我個(gè)人在實(shí)際操作中的體會(huì)是不要一開始就追求大而全的架構(gòu)。先用這一條命令把閉環(huán)跑起來讓真實(shí)業(yè)務(wù)問題驅(qū)動(dòng)你去加深對(duì)每個(gè)環(huán)節(jié)的理解。踩過幾次坑之后你會(huì)發(fā)現(xiàn)真正決定 RAG 上限的不是用了多強(qiáng)的模型而是索引構(gòu)建時(shí)有沒有把文檔結(jié)構(gòu)想清楚Prompt 里有沒有把約束寫明白。最后再分享一個(gè)小技巧給你的storage目錄加上構(gòu)建日期作為后綴比如storage_20250101這樣哪怕改了切分策略也能隨時(shí)對(duì)比新舊版本的問答效果。等到你覺得當(dāng)前方案的工作流已經(jīng)穩(wěn)定了再往混合檢索和評(píng)估體系上擴(kuò)展整個(gè)系統(tǒng)會(huì)越用越順手。 用LlamaIndex一條命令跑通RAG全鏈路：建庫(kù)、召回、重排、生成
在本地跑了幾個(gè)月RAG項(xiàng)目我越來越覺得大多數(shù)人第一次接觸 LlamaIndex 時(shí)不是被模型難倒而是被“建庫(kù)、召回、重排、生成”這四個(gè)環(huán)節(jié)之間的脫節(jié)搞崩潰。你辛辛苦苦寫完 Embedding 和建庫(kù)邏輯到了查詢階段又得處理 Retriever 返回的節(jié)點(diǎn)還要為了效果再掛一層 Rerank最后手動(dòng)拼接 Prompt 調(diào)用 LLM。每一步單獨(dú)看都不復(fù)雜可串起來卻總在細(xì)節(jié)上翻車。折騰過幾次之后我把這套流程收斂成了一個(gè)腳本一行命令直接跑完先判斷索引存不存在不存在就自動(dòng)建庫(kù)存在就直接進(jìn)入召回→重排→生成整個(gè)過程每一步都有日志輸出。如果你正在做文檔問答、私有知識(shí)庫(kù)、技術(shù)客服這類項(xiàng)目這篇東西應(yīng)該能幫你少走不少?gòu)澛贰?. RAG 全鏈路的核心矛盾與一條命令的價(jià)值1.1 建庫(kù)→召回→重排→生成四個(gè)環(huán)節(jié)到底在做什么先別急著寫代碼把四個(gè)詞拆開看清楚。建庫(kù)解決的是“知識(shí)在哪里”的問題。原始文檔是一堆散文、表格、標(biāo)題模型不能直接理解整本書。你需要先按一定策略把文檔切成文本塊給每塊文本算一個(gè)向量然后把向量和原始文本一起存到索引里。這一步?jīng)Q定了后續(xù)所有鏈路的上限。很多人把建庫(kù)想得太簡(jiǎn)單以為扔給框架就行實(shí)際上切分粒度、元數(shù)據(jù)、存儲(chǔ)方式都會(huì)直接影響最終回答質(zhì)量。召回解決的是“找哪些內(nèi)容”的問題。用戶提問后系統(tǒng)把問句向量化在向量索引里找最相似的 K 個(gè)文本塊。這里的關(guān)鍵是“速度快、別漏”寧可多召回一些不相關(guān)的也不能漏掉真正包含答案的片段。這個(gè)過程類似海選標(biāo)準(zhǔn)可以寬松一點(diǎn)。重排解決的是“哪些內(nèi)容真正有用”的問題。向量召回基于embedding相似度但語(yǔ)義相似不等于能回答問題。比如“年假怎么算”和“年假的申請(qǐng)流程”向量距離很近但后者可能根本不包含答案。重排模型會(huì)更精細(xì)地計(jì)算“查詢-片段”的相關(guān)性把真正有用的片段排到最前。海選之后做一輪復(fù)試過濾掉噪音這是RAG效果質(zhì)變的關(guān)鍵。生成解決的是“如何有依據(jù)地說人話”的問題。把重排后的少量片段按模板拼進(jìn)Prompt交給大模型生成答案。同時(shí)要求模型引用片段中的內(nèi)容能顯著降低幻覺。如果少做或跳過重排Prompt里塞進(jìn)去的噪音太多大模型就容易被帶偏。這四個(gè)環(huán)節(jié)缺一不可。但傳統(tǒng)的做法是四個(gè)環(huán)節(jié)各自獨(dú)立腳本開發(fā)者既要管中間產(chǎn)物又要小心不同腳本里模型配置不一致。我實(shí)際遇到過的案例建庫(kù)腳本里用的 Embedding 模型是英文版查詢腳本里換成了中文模型向量維度都沒變運(yùn)行不報(bào)錯(cuò)結(jié)果檢索結(jié)果莫名其妙。一條命令把全流程串起來至少能減少這類低級(jí)錯(cuò)誤。1.2 為什么選擇 LlamaIndex而不是從零輪子如果你只是做原型手動(dòng)用 SentenceTransformer 算向量再加 sklearn 的余弦相似度也能跑通但那僅限于幾十個(gè)文本塊的 Demo。一旦進(jìn)入真實(shí)場(chǎng)景你很快會(huì)遇到這些問題文檔格式多種多樣有 PDF、Word、Markdown、HTML一個(gè)文檔可能幾百頁(yè)切分策略需要定制你需要保存中間狀態(tài)下次啟動(dòng)不能全部重新算你還可能要接不同的向量庫(kù)、不同的大模型接口。LlamaIndex 最核心的價(jià)值不是某個(gè)單一算法多強(qiáng)而是把“文檔加載→文本解析→索引構(gòu)建→檢索→后處理→生成”整條鏈路抽象成了統(tǒng)一接口。它的數(shù)據(jù)連接器能讀一堆文件格式節(jié)點(diǎn)解析器負(fù)責(zé)切分VectorStoreIndex 負(fù)責(zé)向量化與存儲(chǔ)Retriever 負(fù)責(zé)召回NodePostprocessor 負(fù)責(zé)重排最后通過 Query Engine 或者自定義流程交給 LLM。傳入同樣的數(shù)據(jù)你可以在不改變主流程的情況下切換不同的 Embedding 模型、向量數(shù)據(jù)庫(kù)和后端大模型。更關(guān)鍵的是LlamaIndex 在工程上留了持久化機(jī)制索引構(gòu)建好之后向量、文檔映射、索引元數(shù)據(jù)都能存到本地目錄。下次啟動(dòng)直接從磁盤加載而不是每次從零建模。這一條直接讓“一條命令跑全流程”成為可能——建庫(kù)是一次性工作之后每次啟動(dòng)都只是加載索引并查詢。1.3 “一條命令”不是炫技而是工程化的基石為什么不寫多個(gè)腳本比如build_index.py和query.py而非要合并成一個(gè)命令因?yàn)椤叭肟趩我弧北旧砭褪且环N工程約束。在團(tuán)隊(duì)協(xié)作中新同事拿到倉(cāng)庫(kù)后只需要跑一條命令不用去翻 README“先執(zhí)行 A 再執(zhí)行 B”在自動(dòng)化任務(wù)中定時(shí)重建索引也只需要在 Cron 里寫一行在排障時(shí)我們只需要看一條命令的日志流中間不會(huì)出現(xiàn)“上次重建索引用的模型和這次不一致”的詭異問題。有人會(huì)覺得“一條命令”意味著參數(shù)被寫死、擴(kuò)展性差其實(shí)恰恰相反。一個(gè)設(shè)計(jì)良好的 CLI 入口可以通過參數(shù)控制文檔目錄、索引目錄、Top K 值、重排數(shù)量、是否強(qiáng)制重建默認(rèn)值滿足大多數(shù)場(chǎng)景同時(shí)開放自定義。這也是我推薦大家照著這個(gè)思路去搭建自己項(xiàng)目的核心原因。2. 環(huán)境準(zhǔn)備與組件選型2.1 依賴清單與安裝命令在開始寫代碼前先把環(huán)境準(zhǔn)備好。我建議用 Python 3.10 或更高版本開一個(gè)干凈的虛擬環(huán)境避免和項(xiàng)目依賴沖突。以下是我在這套流程里實(shí)際使用的核心依賴pip install llama-index-core pip install llama-index-readers-file pip install llama-index-embeddings-huggingface pip install llama-index-llms-ollama pip install sentence-transformersllama-index-core是 LlamaIndex 的核心庫(kù)提供文檔加載、索引、檢索等主流程llama-index-readers-file讓 SimpleDirectoryReader 支持更多文檔格式llama-index-embeddings-huggingface負(fù)責(zé)接入 Hugging Face 上的 Embedding 模型llama-index-llms-ollama用于連接本地部署的推理服務(wù)sentence-transformers是我們自定義重排器時(shí)要用到的 CrossEncoder 工具包。如果你后面打算用 Chroma、Qdrant 或者 Milvus需要再裝對(duì)應(yīng)的擴(kuò)展包。但在起步階段我強(qiáng)烈建議先用 LlamaIndex 自帶的SimpleVectorStore它不需要額外啟動(dòng)服務(wù)索引可以直接持久化到本地目錄足夠跑通整條鏈路。2.2 Embedding、Rerank、LLM 三個(gè)模型的選型Embedding 模型這個(gè)環(huán)節(jié)決定文本向量化的質(zhì)量。中文場(chǎng)景下我優(yōu)先推薦 BGE 系列尤其BAAI/bge-small-zh-v1.5維度 512對(duì) CPU 和內(nèi)存都比較友好效果也能滿足大多數(shù)場(chǎng)景。如果機(jī)器條件更好可以換BAAI/bge-base-zh-v1.5維度 768準(zhǔn)確率會(huì)更高一些。再往上還有BAAI/bge-m3支持多語(yǔ)言和長(zhǎng)文本但資源占用也大很多。記住一個(gè)原則建庫(kù)和查詢必須使用同一個(gè) Embedding 模型換模型就必須重新建庫(kù)。Rerank 模型我用的是BAAI/bge-reranker-base。它和bge-reranker-large相比速度更快效果差距并沒有想象中那么大。重排模型通常比 Embedding 模型大不少如果內(nèi)存緊張建議用量化版本或者放在 GPU 上。還有一個(gè)無法回避的現(xiàn)實(shí)重排是逐對(duì)計(jì)算的性能和 Top K 直接相關(guān)所以不要一開始就把重排數(shù)量設(shè)成好幾十。LLM 模型為了隱私和成本控制我優(yōu)先用本地 Ollama 部署的開源模型比如qwen2.5:7b。你只需要在代碼里替換成你自己的服務(wù)地址和模型名就行。如果公司內(nèi)部有其他兼容 OpenAI 協(xié)議的統(tǒng)一推理平臺(tái)也完全可以接入LlamaIndex 的 LLM 抽象層會(huì)幫你統(tǒng)一處理。2.3 存儲(chǔ)方案與向量檢索的直觀理解起步階段默認(rèn)的SimpleVectorStore是最合適的。它本質(zhì)上就是把向量存在內(nèi)存里然后序列化到本地目錄。你不需要去裝一個(gè) Vector Database也不用配置連接字符串。等你索引條目到了幾十萬(wàn)級(jí)或者需要多人并發(fā)查詢、復(fù)雜過濾、動(dòng)態(tài)更新時(shí)再遷移到 Chroma 或 Milvus 也不遲。向量檢索是怎么工作的簡(jiǎn)單說每個(gè)文本塊被 Embedding 模型映射成一個(gè)高維向量查詢時(shí)同樣把問句映射成向量然后計(jì)算兩個(gè)向量之間的余弦相似度。余弦相似度公式是向量點(diǎn)積除以模長(zhǎng)乘積結(jié)果區(qū)間在 -1 到 1 之間越接近 1 表示方向越一致、語(yǔ)義越相關(guān)。比如二維向量 [1,0] 和 [0,1] 的余弦相似度是 0它們正交可以理解成完全不相關(guān)[1,0] 和 [0.99,0.01] 的余弦相似度接近 1則方向非常接近。這也是為什么 RAG 要配合重排——余弦相似度衡量的是語(yǔ)義分布是否接近但無法直接判斷“這段文字是否包含問題的答案”。重排器會(huì)以更精細(xì)的交互方式把查詢和候選文本拼起來重新打分把相似但無用的內(nèi)容壓下去。3. 從零搭建索引構(gòu)建與核心參數(shù)取舍3.1 文檔加載與常見格式坑LlamaIndex 里最簡(jiǎn)單的方式是用SimpleDirectoryReader讀取一個(gè)目錄下的所有文件。它的實(shí)現(xiàn)足夠聰明能根據(jù)文件擴(kuò)展名自動(dòng)選擇解析器。但實(shí)際項(xiàng)目里文檔格式往往是最大的坑。先說 PDF。很多 PDF 是從打印系統(tǒng)導(dǎo)出的沒有文本層直接解析會(huì)得到一堆亂碼或者大量空白。即便有文本層復(fù)雜的表格和排版也會(huì)被打亂順序。我的建議是PDF 優(yōu)先轉(zhuǎn)成 Markdown 或者純文本再喂給索引器如果 PDF 是掃描件先走一層 OCR 轉(zhuǎn)換否則后續(xù)無論檢索還是重排都會(huì)受到極大影響。再說 Word。SimpleDirectoryReader對(duì) docx 的支持不錯(cuò)但前提是你安裝了對(duì)應(yīng)的依賴。如果你遇到“文件存在但讀取不到內(nèi)容”的情況先檢查是不是缺少解析庫(kù)比如讀取 docx 需要安裝python-docx。表格數(shù)據(jù)是另一類麻煩。如果文檔里全是表格直接按段落切分會(huì)把表格拆得七零八落。我建議在進(jìn)入 RAG 之前把表格轉(zhuǎn)換為 Markdown 表格格式因?yàn)?Markdown 表格在文本切分時(shí)還能保留結(jié)構(gòu)語(yǔ)義。標(biāo)題、列表、注釋也同理盡量保留結(jié)構(gòu)信息有助于后續(xù)檢索時(shí)區(qū)分主次。3.2 文本切分參數(shù)chunk_size、overlap、metadata文本切分是建庫(kù)環(huán)節(jié)最值得花時(shí)間調(diào)的部分。LlamaIndex 默認(rèn)的SentenceSplitter已經(jīng)能處理大多數(shù)情況但你需要理解兩個(gè)關(guān)鍵參數(shù)chunk_size和chunk_overlap。chunk_size控制每個(gè)文本塊的最大字符數(shù)。我實(shí)測(cè)下來中文場(chǎng)景下512是一個(gè)比較穩(wěn)的起步值。這個(gè)數(shù)字太小比如 128一個(gè)完整的技術(shù)方案會(huì)被切成好幾塊回答問題時(shí)就容易找不到完整上下文數(shù)字太大比如 2048一個(gè)塊里包含太多段落向量語(yǔ)義會(huì)被稀釋而且最終 Prompt 塞進(jìn)去也容易超長(zhǎng)。當(dāng)然這不是死的如果你的文檔本身邏輯塊很大可以適當(dāng)調(diào)大。chunk_overlap控制相鄰文本塊之間的重疊字符數(shù)。為什么要重疊因?yàn)榍蟹贮c(diǎn)很可能落在一個(gè)句子或概念中間有了重疊后半段文檔的起始部分會(huì)在前一個(gè)塊里再出現(xiàn)一次避免關(guān)鍵信息正好被切掉。我通常設(shè)置為50到100大約控制在chunk_size的 10% 到 20%。如果你的文檔里天然有清晰的 Markdown 標(biāo)題分級(jí)也可以考慮用MarkdownNodeParser它會(huì)更智能地按標(biāo)題層級(jí)切分而不是硬切長(zhǎng)度。還有一個(gè)容易被忽略但非常重要的點(diǎn)給文本塊掛 metadata。比如file_path或page_number這樣生成答案時(shí)可以通過node.metadata拿到來源在 Prompt 里展示“參考來源”或者在 UI 上高亮對(duì)應(yīng)的 PDF 頁(yè)碼。沒有來源的 RAG 很難讓人信任。3.3 向量化與索引持久化文檔切好之后就到了 Embedding 和索引構(gòu)建環(huán)節(jié)。LlamaIndex 的VectorStoreIndex會(huì)逐塊調(diào)用 Embedding 模型把文本塊向量化然后寫入存儲(chǔ)。如果你有 1 萬(wàn)個(gè)文本塊每個(gè)塊在 CPU 上做 Embedding 大約需要 0.1 到 0.5 秒全量建庫(kù)可能就得半小時(shí)以上。耐心等不要在中途頻繁打斷進(jìn)程否則容易寫出不完整的向量文件。持久化其實(shí)很簡(jiǎn)單核心代碼如下storage_context StorageContext.from_defaults(persist_dir./storage) index VectorStoreIndex.from_documents(documents, storage_contextstorage_context) storage_context.persist()持久化之后storage目錄里會(huì)出現(xiàn)多個(gè) JSON 文件分別存向量、文檔關(guān)系、索引元數(shù)據(jù)。以后加載索引只需要storage_context StorageContext.from_defaults(persist_dir./storage) index load_index_from_storage(storage_context)這里有一個(gè)很重要的工程經(jīng)驗(yàn)索引和 Embedding 模型是綁定在一起的。如果你升級(jí)了 Embedding 模型或者改變了切分參數(shù)必須強(qiáng)制重建索引否則舊索引和新查詢向量無法對(duì)齊。這也是為什么我的腳本里保留了一個(gè)--force-rebuild參數(shù)專門用于這種“配置變更后的重建”。4. 一條命令跑通全流程完整的可復(fù)現(xiàn)工程4.1 工程目錄與 CLI 設(shè)計(jì)我做這套腳本時(shí)目錄約定如下rag_pipeline/ ├── data/ # 放原始文檔 ├── storage/ # 索引持久化目錄 └── local_rag.py # 主腳本主腳本接收以下參數(shù)參數(shù)作用默認(rèn)值--query用戶提問必填--data-dir原始文檔目錄./data--index-dir索引持久化目錄./storage--force-rebuild強(qiáng)制重建索引False--top-k召回候選數(shù)20--rerank-top-n重排后保留數(shù)5我不建議一開始設(shè)計(jì)一堆花哨的接口上面這幾個(gè)參數(shù)已經(jīng)覆蓋絕大多數(shù)場(chǎng)景。top-k和rerank-top-n是你在做效果評(píng)測(cè)時(shí)最常調(diào)整的兩個(gè)旋鈕后面會(huì)細(xì)講。4.2 完整代碼從建庫(kù)到生成一步到位下面是完整的local_rag.py。我把流程拆成了四個(gè)子步驟并且用日志打印每一步方便排查。這段代碼基于 LlamaIndex 0.10.x 的 API 編寫如果你用的是其他版本可能需要小幅適配。import argparse import os import time from typing import List # LlamaIndex 核心 from llama_index.core import ( SimpleDirectoryReader, VectorStoreIndex, StorageContext, load_index_from_storage, Settings, ) from llama_index.core.schema import BaseNode from llama_index.core.schema import QueryBundle from llama_index.core.node_parser import SentenceSplitter from llama_index.core.postprocessor.types import BaseNodePostprocessor # Embedding 和 LLM from llama_index.embeddings.huggingface import HuggingFaceEmbedding from llama_index.llms.ollama import Ollama # 重排模型 from sentence_transformers import CrossEncoder # 配置全局模型 Settings.embed_model HuggingFaceEmbedding( model_nameBAAI/bge-small-zh-v1.5 ) # 根據(jù)你的本地推理服務(wù)修改 model 和 base_url Settings.llm Ollama( modelqwen2.5:7b, request_timeout120.0, ) # 自定義重排后處理器 class LocalReranker(BaseNodePostprocessor): def __init__(self, model_name: str BAAI/bge-reranker-base, top_n: int 5): super().__init__() self._model CrossEncoder(model_name) self._top_n top_n property def _node_type(self) - str: return Node def postprocess_nodes( self, nodes: List[BaseNode], query_bundle: QueryBundle, **kwargs ) - List[BaseNode]: if not nodes: return nodes pairs [(query_bundle.query_str, node.get_content()) for node in nodes] scores self._model.predict(pairs) scored_nodes list(zip(scores, nodes)) scored_nodes.sort(keylambda x: x[0], reverseTrue) return [node for _, node in scored_nodes[: self._top_n]] def build_index(data_dir: str, index_dir: str, force_rebuild: bool): 建庫(kù)讀取文檔→切分→向量化→持久化 if os.path.exists(index_dir) and not force_rebuild: print([建庫(kù)] 檢測(cè)到已有索引跳過建庫(kù)步驟) storage_context StorageContext.from_defaults(persist_dirindex_dir) return load_index_from_storage(storage_context) print(f[建庫(kù)] 開始讀取目錄: {data_dir}) documents SimpleDirectoryReader( input_dirdata_dir, required_exts[.md, .txt, .docx, .pdf], recursiveTrue, ).load_data() print([建庫(kù)] 開始切分文本...) splitter SentenceSplitter(chunk_size512, chunk_overlap50) nodes splitter.get_nodes_from_documents(documents) print(f[建庫(kù)] 共切分 {len(nodes)} 個(gè)文本塊開始向量化...) storage_context StorageContext.from_defaults(persist_dirindex_dir) index VectorStoreIndex(nodes, storage_contextstorage_context) storage_context.persist() print([建庫(kù)] 索引構(gòu)建完成并已持久化) return index def retrieve(index, query: str, top_k: int): 召回從索引中獲取候選節(jié)點(diǎn) print(f[召回] 開始向量召回 top {top_k} ...) retriever index.as_retriever(similarity_top_ktop_k) nodes retriever.retrieve(query) print(f[召回] 得到 {len(nodes)} 個(gè)候選片段) return nodes def rerank(nodes, query: str, rerank_top_n: int): 重排用 CrossEncoder 對(duì)候選片段二次打分 print(f[重排] 開始精排保留 top {rerank_top_n} ...) processor LocalReranker( model_nameBAAI/bge-reranker-base, top_nrerank_top_n, ) query_bundle QueryBundle(query_strquery) filtered_nodes processor.postprocess_nodes(nodes, query_bundle) print(f[重排] 最終保留 {len(filtered_nodes)} 個(gè)片段) return filtered_nodes def generate(query: str, nodes): 生成拼接 Prompt 并調(diào)用 LLM print([生成] 拼接上下文調(diào)用大模型...) context \n\n.join( f[片段{i1}]\n{node.get_content()} for i, node in enumerate(nodes) ) prompt f請(qǐng)根據(jù)下面的參考片段回答用戶問題。 參考片段 {context} 用戶問題{query} 要求 1. 優(yōu)先使用參考片段中的信息回答 2. 如果參考片段中沒有相關(guān)內(nèi)容請(qǐng)直接回答“未在資料中找到相關(guān)信息” 3. 回答盡量簡(jiǎn)潔、準(zhǔn)確 回答 response Settings.llm.complete(prompt) print(\n * 40) print(問答結(jié)果) print(response.text) print( * 40) return response.text def run_pipeline(): parser argparse.ArgumentParser(description一條命令跑完 RAG 全流程) parser.add_argument(--query, requiredTrue, help用戶提問) parser.add_argument(--data-dir, default./data, help原始文檔目錄) parser.add_argument(--index-dir, default./storage, help索引持久化目錄) parser.add_argument(--force-rebuild, actionstore_true, help強(qiáng)制重建索引) parser.add_argument(--top-k, typeint, default20, help召回候選數(shù)) parser.add_argument(--rerank-top-n, typeint, default5, help重排后保留數(shù)) args parser.parse_args() # 步驟 1建庫(kù) time_start time.time() index build_index(args.data_dir, args.index_dir, args.force_rebuild) # 步驟 2召回 nodes retrieve(index, args.query, args.top_k) # 步驟 3重排 filtered_nodes rerank(nodes, args.query, args.rerank_top_n) # 步驟 4生成 generate(args.query, filtered_nodes) time_end time.time() print(f\n[完成] 總耗時(shí): {time_end - time_start:.2f} 秒) if __name__ __main__: run_pipeline()4.3 執(zhí)行效果與預(yù)期輸出假設(shè)你的data目錄里放了幾份員工手冊(cè)然后執(zhí)行python local_rag.py \ --query 新員工的年假天數(shù)是怎么計(jì)算的 \ --data-dir ./data \ --top-k 20 \ --rerank-top-n 5第一次運(yùn)行時(shí)如果storage目錄不存在會(huì)自動(dòng)進(jìn)入建庫(kù)流程。你會(huì)看到類似這樣的日志[建庫(kù)] 開始讀取目錄: ./data [建庫(kù)] 開始切分文本... [建庫(kù)] 共切分 128 個(gè)文本塊開始向量化... [建庫(kù)] 索引構(gòu)建完成并已持久化 [召回] 開始向量召回 top 20 ... [召回] 得到 20 個(gè)候選片段 [重排] 開始精排保留 top 5 ... [重排] 最終保留 5 個(gè)片段 [生成] 拼接上下文調(diào)用大模型... 問答結(jié)果 根據(jù)員工手冊(cè)新員工的年假天數(shù)根據(jù)入職時(shí)間按比例折算具體為…… [完成] 總耗時(shí): 18.23 秒第二次再執(zhí)行同一條命令時(shí)建庫(kù)步驟會(huì)直接跳過總耗時(shí)通常能降到 5 秒以內(nèi)取決于重排模型和 LLM 的速度。這就是“一條命令跑完全流程”的直觀體驗(yàn)。4.4 參數(shù)調(diào)節(jié)建議表調(diào)參是 RAG 的日常。下面這張表列出的默認(rèn)值是我在多個(gè)文檔問答項(xiàng)目里反復(fù)試出來的起點(diǎn)但最終取值一定要基于你自己的文檔做評(píng)測(cè)。參數(shù)默認(rèn)值設(shè)置過低的后果設(shè)置過高的后果chunk_size512上下文碎片化關(guān)鍵信息被切斷向量語(yǔ)義被稀釋檢索精度下降Prompt 易超長(zhǎng)chunk_overlap50切分點(diǎn)可能切斷完整句子文本塊之間大量重復(fù)索引體積膨脹top_k20漏召回正確答案不在候選中重排負(fù)擔(dān)重單次查詢延遲變高rerank_top_n5過濾掉了潛在正確答案LLM 上下文噪聲增加生成變慢且容易跑偏我自己的習(xí)慣是先固定chunk_size512和chunk_overlap50然后用一組真實(shí)問題做評(píng)測(cè)。如果發(fā)現(xiàn)答案沒找到先把top_k從 20 升到 40看是不是召回階段漏了如果召回候選里能找到正確答案但最終答案不對(duì)那就把rerank_top_n從 5 調(diào)到 8或者檢查重排模型是否與領(lǐng)域匹配如果整體延遲太高優(yōu)先降top_k和rerank_top_n。5. 實(shí)測(cè)遇到的高頻問題和排查技巧5.1 召回結(jié)果為空或根本檢索不到最典型的癥狀是索引構(gòu)建成功日志也提示得到了候選片段但生成出的答案胡編亂造或者壓根沒有用上參考內(nèi)容。首先檢查 Embedding 模型是否加載成功。如果 Hugging Face 模型第一次下載失敗Settings.embed_model可能變成空對(duì)象LlamaIndex 不會(huì)直接報(bào)錯(cuò)而是用默認(rèn)的模擬模型結(jié)果檢索結(jié)果全部是隨機(jī)序。我踩過這個(gè)坑花費(fèi)大量時(shí)間排查后才發(fā)現(xiàn)是模型文件沒下全。解決辦法是啟動(dòng)時(shí)打印Settings.embed_model的關(guān)鍵屬性或者單獨(dú)跑一次embedding Settings.embed_model.get_text_embedding(測(cè)試)看維度是否正常。其次檢查文檔切分是否成功。如果原始文檔里全是圖片掃描件文本切分之后可能一個(gè)有效節(jié)點(diǎn)都沒有。你可以臨時(shí)打印建庫(kù)后的節(jié)點(diǎn)內(nèi)容和數(shù)量確認(rèn)至少有一個(gè)完整句子級(jí)的文本塊。我見過某項(xiàng)目把掃描版 PDF 直接扔進(jìn)去索引建了但節(jié)點(diǎn)里全是空行最后召回一堆空白。還有幾種低概率原因查詢語(yǔ)言與文檔語(yǔ)言不一致比如文檔是中文查詢用了英文模塊文本切分后只有寥寥幾個(gè)塊向量空間上的區(qū)分度不夠又或者你有多個(gè)storage目錄命令行參數(shù)--index-dir指錯(cuò)了位置。排查時(shí)先看日志里的索引路徑再打印幾個(gè)召回節(jié)點(diǎn)的node.get_content()開頭 100 個(gè)字符基本就能定位。5.2 重排階段超時(shí)、內(nèi)存爆炸CrossEncoder 是逐對(duì)計(jì)算的當(dāng)top_k20時(shí)一次查詢要做 20 次模型推理這比 Embedding 一次查詢要多得多。如果你把top_k設(shè)成 100單次重排耗時(shí)可能長(zhǎng)達(dá)十幾秒在 CPU 機(jī)器上甚至可能把內(nèi)存打滿。解決辦法有三個(gè)方向把top_k控制在合理區(qū)間比如 20 到 50使用更小的重排模型比如bge-reranker-base而不是large對(duì)重排模型做量化或者干脆跑在 GPU 上。如果業(yè)務(wù)場(chǎng)景對(duì)首字延遲特別敏感可以考慮把重排模型做成獨(dú)立服務(wù)批量異步處理但這就超出了單命令的范疇屬于上線架構(gòu)問題。另外sentence_transformers在predict的時(shí)候默認(rèn)會(huì)使用你本機(jī)最大的 batch size如果顯存或內(nèi)存不夠可以在調(diào)用時(shí)加一個(gè)batch_size16參數(shù)scores self._model.predict(pairs, batch_size16)這個(gè)參數(shù)并不影響結(jié)果只是限制同時(shí)處理的樣本數(shù)能明顯降低內(nèi)存尖峰。5.3 生成結(jié)果亂說、引用錯(cuò)誤RAG 最大的風(fēng)險(xiǎn)是 LLM 無視參考片段自由發(fā)揮。我的排查經(jīng)驗(yàn)是先看 Prompt 模板有沒有做強(qiáng)約束。如果直接寫“根據(jù)以下內(nèi)容回答問題”模型自由度太高。更穩(wěn)的寫法是明確要求“如果參考片段中沒有對(duì)應(yīng)信息請(qǐng)直接回答未找到”同時(shí)給片段編號(hào)讓答案中帶上[片段1]這樣的引用標(biāo)記。下面是我常用的 Prompt 約束1. 優(yōu)先使用參考片段中的信息回答 2. 如果參考片段中沒有相關(guān)內(nèi)容請(qǐng)直接回答“未在資料中找到相關(guān)信息” 3. 回答中引用內(nèi)容時(shí)請(qǐng)標(biāo)注來源編號(hào)第二個(gè)常見原因是沒有做好重排噪聲片段被塞進(jìn)上下文。某個(gè)片段雖然和問題有較高的向量相似度但內(nèi)容其實(shí)是另一個(gè)部門的制度LLM 看到一堆相似但不相關(guān)的片段很容易被帶偏。建議把重排后的片段打印到一個(gè)調(diào)試日志里人工檢查每個(gè)片段是否真的回答問題再?zèng)Q定是否調(diào)rerank_top_n。第三個(gè)原因是 LLM 上下文被截?cái)唷Ｈ绻鹯erank_top_n8且每個(gè)片段 512 字符上下文很容易超過 4000 字符模型在長(zhǎng)上下文中容易“遺忘”靠后的內(nèi)容。解決辦法是減小chunk_size或rerank_top_n或者在 Prompt 中讓模型優(yōu)先關(guān)注前幾個(gè)片段。5.4 增量更新與索引失效最簡(jiǎn)單的索引更新方式是全量重建。如果你的文檔量不大直接跑一遍--force-rebuild是最省心的絕對(duì)不會(huì)出現(xiàn)新文檔和舊向量混存的臟狀態(tài)。如果文檔量很大全量重建的時(shí)間不可接受就需要做增量插入。LlamaIndex 的VectorStoreIndex本身支持插入新節(jié)點(diǎn)new_documents SimpleDirectoryReader(input_files[./data/new_file.md]).load_data() new_nodes splitter.get_nodes_from_documents(new_documents) index.insert_nodes(new_nodes) storage_context.persist()但增量更新的難點(diǎn)不在于 API而在于“去重”。如果你重復(fù)插入同一份文檔索引里會(huì)出現(xiàn)重復(fù)向量檢索結(jié)果就會(huì)有大量相同內(nèi)容。我建議在文檔層面維護(hù)一個(gè) hash 表用文件內(nèi)容 hash 作為唯一標(biāo)識(shí)插入前先查這次是不是已經(jīng)處理過。更進(jìn)一步如果你做了復(fù)雜的增量更新最好在索引目錄名里加上版本號(hào)比如storage_v2_20250101萬(wàn)一線上效果衰減還能快速回滾。5.5 高頻問題速查表現(xiàn)象可能原因排查方向檢索結(jié)果全部隨機(jī)Embedding 模型沒加載成功打印Settings.embed_model單獨(dú)測(cè)向量維度召回到空節(jié)點(diǎn)文檔解析失敗檢查 PDF 是否有文本層打印節(jié)點(diǎn)數(shù)量答案沒有引用參考內(nèi)容Prompt 約束太弱加強(qiáng) Prompt 要求強(qiáng)制引用片段編號(hào)重排特別慢top_k太大降低top_k加batch_size索引越來越大重復(fù)插入/切分重疊太大做文件 hash 去重減小chunk_overlap換模型后結(jié)果變差索引和查詢模型不一致強(qiáng)制重建索引6. 影響范圍與進(jìn)階方向6.1 誰(shuí)最需要這套一條命令的 RAG很多人以為 RAG 是算法工程師的專屬工具但我在實(shí)際落地中接觸到的用戶真正高頻使用它的反而是技術(shù)負(fù)責(zé)人、產(chǎn)品經(jīng)理、客服主管和知識(shí)管理專員。技術(shù)人員拿它做內(nèi)部開發(fā)文檔問答把散落在 Confluence 和 GitLab Wiki 里的資料集中成一個(gè)可查詢?nèi)肟诳头F(tuán)隊(duì)拿它接產(chǎn)品 FAQ用戶問“退款多久到賬”系統(tǒng)能從幾十份客服手冊(cè)里快速給出帶出處的話術(shù)產(chǎn)品經(jīng)理拿它分析競(jìng)品文檔和用戶調(diào)研減少大量翻文檔的時(shí)間個(gè)人用戶則用它做論文筆記和電子書查詢本質(zhì)上是一樣的鏈路。這套方案的門檻低到什么程度只要你能把文檔放進(jìn)data目錄會(huì)運(yùn)行一條命令就能得到一個(gè)相對(duì)靠譜的問答系統(tǒng)。這非常符合實(shí)際團(tuán)隊(duì)的協(xié)作方式——不要求每個(gè)人都懂向量數(shù)據(jù)庫(kù)只需要維護(hù)入口和文檔更新。6.2 從“跑通”到“跑好”的演進(jìn)方向如果你已經(jīng)能順利跑通全流程下一步我建議按以下順序做優(yōu)化。第一加入BM25 混合檢索。向量召回擅長(zhǎng)語(yǔ)義相似但不擅長(zhǎng)精確關(guān)鍵詞匹配比如型號(hào)編碼、錯(cuò)誤代碼、合同編號(hào)這類信息。把 BM25 的關(guān)鍵詞命中和向量召回的候選結(jié)果加權(quán)合并可以顯著提升準(zhǔn)確率。第二做查詢改寫。復(fù)雜問題里經(jīng)常有口語(yǔ)化表達(dá)和指代比如“它是不是支持這個(gè)功能”中的“它”需要結(jié)合多輪對(duì)話上下文才能理解。在進(jìn)入召回前先讓 LLM 將用戶問題改寫成一個(gè)標(biāo)準(zhǔn)檢索式往往能給召回帶來很大的提升。第三建立效果評(píng)估集。找業(yè)務(wù)方要 50 到 100 個(gè)真實(shí)問題把參考標(biāo)準(zhǔn)答案標(biāo)注好每次調(diào)整參數(shù)后自動(dòng)跑一遍統(tǒng)計(jì)“檢索命中率”和“答案正確率”。這套機(jī)制比任何人的主觀感覺都可靠也是項(xiàng)目從 Demo 走向上線的關(guān)鍵一步。第四把單命令腳本擴(kuò)展為HTTP 服務(wù)。用 FastAPI 包一層接收查詢請(qǐng)求復(fù)用同一個(gè)storage目錄加上緩存和流式輸出就成了一個(gè)標(biāo)準(zhǔn)的 RAG 推理服務(wù)。第五考慮多租戶與元數(shù)據(jù)過濾。不同團(tuán)隊(duì)的知識(shí)庫(kù)可能混在一起通過給文本塊打team_id元數(shù)據(jù)在檢索時(shí)做條件過濾可以避免跨團(tuán)隊(duì)的信息串味。我個(gè)人在實(shí)際操作中的體會(huì)是不要一開始就追求大而全的架構(gòu)。先用這一條命令把閉環(huán)跑起來讓真實(shí)業(yè)務(wù)問題驅(qū)動(dòng)你去加深對(duì)每個(gè)環(huán)節(jié)的理解。踩過幾次坑之后你會(huì)發(fā)現(xiàn)真正決定 RAG 上限的不是用了多強(qiáng)的模型而是索引構(gòu)建時(shí)有沒有把文檔結(jié)構(gòu)想清楚Prompt 里有沒有把約束寫明白。最后再分享一個(gè)小技巧給你的storage目錄加上構(gòu)建日期作為后綴比如storage_20250101這樣哪怕改了切分策略也能隨時(shí)對(duì)比新舊版本的問答效果。等到你覺得當(dāng)前方案的工作流已經(jīng)穩(wěn)定了再往混合檢索和評(píng)估體系上擴(kuò)展整個(gè)系統(tǒng)會(huì)越用越順手。