簡(jiǎn)介這是一套面向Python初學(xué)者與課程設(shè)計(jì)者的極簡(jiǎn)RAG知識(shí)庫(kù)系統(tǒng)實(shí)現(xiàn)適用于期末大作業(yè)、畢業(yè)設(shè)計(jì)或人工智能方向課程實(shí)踐旨在幫助學(xué)習(xí)者快速掌握檢索增強(qiáng)生成RAG的核心流程與工程落地方法。資源包共48個(gè)文件含31個(gè)Python源碼覆蓋文檔加載、文本切分、嵌入生成、重排序、Elasticsearch集成及Web服務(wù)等核心模塊、3個(gè)YAML配置文件定義系統(tǒng)參數(shù)與服務(wù)配置、1個(gè)Dockerfile及配套容器化腳本支持一鍵部署另有README.md、Makefile、pyproject.toml等工程化配置文件完整體現(xiàn)現(xiàn)代Python項(xiàng)目開(kāi)發(fā)規(guī)范。壓縮包僅152KB輕量易讀結(jié)構(gòu)清晰——app/、service/、domain/、utils/等目錄劃分明確便于理解RAG各環(huán)節(jié)職責(zé)解耦。目前已有69人學(xué)習(xí)下載讀者可直接運(yùn)行調(diào)試、修改配置適配自有數(shù)據(jù)源并基于現(xiàn)有框架拓展向量數(shù)據(jù)庫(kù)或大模型接口是入門RAG工程實(shí)踐的高性價(jià)比參考方案。 最近把手上一個(gè)RAG項(xiàng)目徹底清了一遍剪掉所有花哨的依賴和配置最后沉淀出一個(gè)Python極簡(jiǎn)RAG知識(shí)庫(kù)系統(tǒng)。這個(gè)zip包里的代碼量不大但核心流程一條沒(méi)少文檔加載、文本切塊、向量化、檢索、拼接上下文、生成回答全鏈路跑通大概只要幾百行Python代碼。今天這篇就把這套系統(tǒng)的設(shè)計(jì)思路、關(guān)鍵代碼和踩坑記錄完整拆出來(lái)想自己做本地知識(shí)庫(kù)問(wèn)答的同學(xué)可以參考著抄作業(yè)尤其是剛接觸RAG、不想一上來(lái)就上LangChain或LlamaIndex這種重框架的人這個(gè)項(xiàng)目應(yīng)該能幫你把核心概念落到能跑的代碼上。先說(shuō)我為什么要做這樣一個(gè)極簡(jiǎn)版本。RAG這個(gè)詞最近被包裝得有點(diǎn)嚇人動(dòng)輒就是知識(shí)圖譜、Agent、多路召回、重排序新人一看就勸退。但本質(zhì)上RAG可以理解成“給大模型開(kāi)卷考試”先從一個(gè)知識(shí)庫(kù)里把和問(wèn)題相關(guān)的內(nèi)容檢索出來(lái)再和大模型的問(wèn)題拼在一起讓模型基于這些內(nèi)容回答。理解了這層邏輯剩下的就是怎么把每一步做得更精細(xì)的問(wèn)題。下面我從整體設(shè)計(jì)開(kāi)始一步步拆開(kāi)這個(gè)項(xiàng)目。1. 項(xiàng)目定位與整體設(shè)計(jì)思路1.1 RAG到底解決什么問(wèn)題大模型有一個(gè)很要命的缺點(diǎn)就是它學(xué)完知識(shí)之后知識(shí)就固定在那了。你問(wèn)它今年剛發(fā)生的事情它大概率會(huì)一本正經(jīng)地編一個(gè)答案這就是所謂的“幻覺(jué)”。而知識(shí)庫(kù)的問(wèn)題在于企業(yè)內(nèi)部的大量文檔、規(guī)范、技術(shù)資料是模型訓(xùn)練時(shí)根本沒(méi)見(jiàn)過(guò)的東西直接問(wèn)模型等于白問(wèn)。RAG的解決思路特別直白。你要回答一個(gè)問(wèn)題之前先不去問(wèn)大模型而是去你自建的知識(shí)庫(kù)里做一次檢索把和問(wèn)題最相關(guān)的幾段文字撈出來(lái)然后把這些文字和問(wèn)題一起交給大模型讓它照著這些材料念答案。這樣一來(lái)大模型不需要“記得”你的知識(shí)庫(kù)內(nèi)容只需要“讀懂”你臨時(shí)塞給它的材料幻覺(jué)問(wèn)題就大幅緩解了。這個(gè)項(xiàng)目和熱詞里反復(fù)出現(xiàn)的“rag是什么”“rag基礎(chǔ)原理”正好對(duì)上了。它解決的問(wèn)題就是在沒(méi)有企業(yè)級(jí)基礎(chǔ)設(shè)施的情況下如何用最少的代碼搭出一個(gè)“能回答問(wèn)題、能引用原文、能擴(kuò)展”的最小閉環(huán)。1.2 極簡(jiǎn)方案的邊界在哪里很多看到“極簡(jiǎn)”兩個(gè)字的人會(huì)問(wèn)那是不是性能很差、功能殘缺其實(shí)不是。極簡(jiǎn)指的是技術(shù)棧和代碼量上的極簡(jiǎn)而不是流程上的缺失。我在設(shè)計(jì)這個(gè)項(xiàng)目時(shí)給自己定了幾條硬約束不引入LangChain這類重框架核心邏輯全部用原生Python和輕量庫(kù)實(shí)現(xiàn)。向量數(shù)據(jù)庫(kù)不用Milvus、Weaviate這類分布式服務(wù)用FAISS本地索引文件就夠了。大模型部分不做微調(diào)通過(guò)OpenAI兼容接口對(duì)接本地或云端模型。整體代碼量控制在幾百行讓一個(gè)能看懂Python的人花半天時(shí)間就能讀完。這個(gè)方案的使用場(chǎng)景很明確個(gè)人知識(shí)庫(kù)、團(tuán)隊(duì)內(nèi)部文檔問(wèn)答、原型驗(yàn)證、教學(xué)演示。數(shù)據(jù)量在幾萬(wàn)到幾十萬(wàn)字符級(jí)別并發(fā)量不高一臺(tái)開(kāi)發(fā)機(jī)就能跑。如果你的數(shù)據(jù)量到了百萬(wàn)級(jí)文檔、需要多人高并發(fā)訪問(wèn)那確實(shí)需要換Milvus、上分布式但那已經(jīng)不是“極簡(jiǎn)”該管的范圍了。為了讓大家更直觀地判斷我列一個(gè)對(duì)比表維度極簡(jiǎn)方案本項(xiàng)目企業(yè)級(jí)方案向量存儲(chǔ)FAISS本地索引Milvus / Qdrant / ES框架依賴原生PythonLangChain / LlamaIndex文檔量級(jí)適合中小規(guī)模百萬(wàn)級(jí)及以上部署方式單機(jī)腳本微服務(wù) / K8s學(xué)習(xí)成本低半天能懂高需要理解一堆抽象概念適用場(chǎng)景個(gè)人知識(shí)庫(kù)、原型生產(chǎn)環(huán)境、高并發(fā)業(yè)務(wù)1.3 技術(shù)選型的邏輯這個(gè)項(xiàng)目里有幾個(gè)核心組件選擇我單獨(dú)說(shuō)一下理由因?yàn)檫@些取舍直接決定了項(xiàng)目為什么能保持“極簡(jiǎn)”向量存儲(chǔ)用FAISS而不是Chroma。Chroma也是一個(gè)很好的輕量向量庫(kù)而且自帶增刪改查的接口用起來(lái)更省事。但我最后還是用了FAISS原因是FAISS更貼近底層你能看到索引是怎么構(gòu)建的、檢索是怎么算相似度的。對(duì)于想學(xué)習(xí)RAG原理的人來(lái)說(shuō)這種“裸”一點(diǎn)的方式反而更友好。而且FAISS是Meta出品的性能和穩(wěn)定性都有保障單機(jī)跑幾十萬(wàn)向量完全沒(méi)問(wèn)題。Embedding模型用BGE系列而不是OpenAI的text-embedding-ada-002。中文場(chǎng)景下本地Embedding模型的效果并不比API差而且不依賴網(wǎng)絡(luò)、不產(chǎn)生費(fèi)用、沒(méi)有數(shù)據(jù)隱私問(wèn)題。我選的是BAAI/bge-small-zh-v1.5維度512體積小普通CPU就能跑效果在中文語(yǔ)義搜索里屬于第一梯隊(duì)。生成端用OpenAI兼容接口。這樣設(shè)計(jì)的好處是無(wú)論是調(diào)云端模型還是用Ollama、vLLM、Xinference啟動(dòng)的本地模型統(tǒng)一走一個(gè)接口代碼完全不用改。項(xiàng)目里默認(rèn)演示的是對(duì)接本地Ollama服務(wù)因?yàn)檫@樣整個(gè)鏈路可以完全不依賴外網(wǎng)真正實(shí)現(xiàn)“本地知識(shí)庫(kù)”。2. 核心模塊拆解一個(gè)RAG系統(tǒng)最不能省的幾塊2.1 文檔加載與文本切塊策略文檔加載這一步?jīng)]什么技術(shù)含量但非常容易踩坑。PDF、Word、Markdown、TXT不同格式有不同的解析方式。我這里用pypdf來(lái)解析PDF用python-docx解析Word純文本直接按編碼讀。這里特別提醒一句PDF看著簡(jiǎn)單實(shí)際解析起來(lái)是最麻煩的很多PDF的文本層是壞掉的或者排版是分欄的直接提取出來(lái)全是亂序。如果你的PDF是掃描件那必須接OCR這不是極簡(jiǎn)項(xiàng)目該干的事所以我默認(rèn)跳過(guò)了。真正有技術(shù)含量的是切塊Chunking。這一步?jīng)Q定了檢索的效果也決定了最終回答的質(zhì)量。切塊的核心矛盾在于塊太小語(yǔ)義不完整檢索出來(lái)上下文碎片化塊太大向量表示的語(yǔ)義會(huì)被稀釋而且超過(guò)模型上下文窗口后會(huì)被截?cái)唷Ｎ夷J(rèn)用的是chunk_size500chunk_overlap50這里的單位是字符不是token。中文場(chǎng)景下一個(gè)字符大概對(duì)應(yīng)0.6到1個(gè)token500個(gè)字符大約就是300到500個(gè)token這個(gè)長(zhǎng)度對(duì)大多數(shù)模型來(lái)說(shuō)都是安全的。重疊的50個(gè)字符用來(lái)銜接前后文的語(yǔ)義避免一句話被硬生生切斷后后半句丟失了前半句的主語(yǔ)。不過(guò)這個(gè)策略只是兜底。我在項(xiàng)目里留了一個(gè)優(yōu)化點(diǎn)切塊時(shí)優(yōu)先在句號(hào)、換行符、問(wèn)號(hào)這些自然邊界處切斷。具體做法是先暴力切成500字符的塊然后檢查這個(gè)塊的結(jié)尾是不是在句子中間如果是就往前退到最近的句號(hào)處。這樣切出來(lái)的塊語(yǔ)義完整性會(huì)好很多檢索的精度也會(huì)明顯提升。2.2 向量化與向量存儲(chǔ)文本切好之后下一步就是把每塊文本變成一串浮點(diǎn)數(shù)也就是Embedding向量。這里有個(gè)概念需要澄清很多人問(wèn)“Embedding模型和普通NLP模型有什么區(qū)別”其實(shí)簡(jiǎn)單說(shuō)Embedding模型的任務(wù)是“把意思相近的文本映射到空間中相近的位置”所以它輸出的向量天然適合做相似度計(jì)算。我在項(xiàng)目里用sentence-transformers庫(kù)加載BGE模型一次把全部分塊編碼成向量。這里有個(gè)小細(xì)節(jié)編碼的時(shí)候一定要設(shè)置normalize_embeddingsTrue也就是對(duì)向量做L2歸一化。原因后面講檢索的時(shí)候再說(shuō)。向量存儲(chǔ)我直接用了FAISS的IndexFlatIP這是最基礎(chǔ)的內(nèi)積索引。構(gòu)建方式很簡(jiǎn)單把歸一化后的向量矩陣傳給index.add()就行然后把索引文件保存到本地。這里要注意FAISS的索引文件和分塊文本元數(shù)據(jù)是分開(kāi)存的索引文件里只有向量數(shù)據(jù)沒(méi)有原文。所以我在旁邊還存了一個(gè)chunks.json里面按順序放著每一塊文本的原文內(nèi)容這樣檢索出向量ID之后可以去JSON里把對(duì)應(yīng)的文本找出來(lái)。2.3 檢索與相似度計(jì)算檢索的原理其實(shí)就是K近鄰搜索。用戶輸入一個(gè)問(wèn)題先把問(wèn)題用同一個(gè)Embedding模型轉(zhuǎn)成向量然后在向量索引里找出和這個(gè)向量最相似的K個(gè)向量返回對(duì)應(yīng)的文本塊。這里解釋一下為什么編碼時(shí)要normalize_embeddingsTrue。因?yàn)镕AISS的IndexFlatIP計(jì)算的是內(nèi)積內(nèi)積的大小受向量長(zhǎng)度影響。如果兩個(gè)向量的模長(zhǎng)差很多即使方向完全一致內(nèi)積也會(huì)被模長(zhǎng)帶偏。歸一化之后所有向量模長(zhǎng)都是1內(nèi)積就等于余弦相似度檢索結(jié)果就純粹由“方向一致性”決定也就是真正的語(yǔ)義相似度。默認(rèn)top_k5也就是召回5個(gè)文本塊。這個(gè)數(shù)量不是拍腦袋定的。太少了可能漏掉關(guān)鍵信息太多了拼接起來(lái)的上下文會(huì)塞滿無(wú)關(guān)內(nèi)容反而干擾模型的判斷。5個(gè)塊通常覆蓋500到2500個(gè)字符足夠回答大多數(shù)事實(shí)性問(wèn)題。如果檢索結(jié)果的相似度普遍低于0.3基本可以斷定檢索失敗了?？赡艹霈F(xiàn)的原因是Embedding模型和知識(shí)庫(kù)內(nèi)容領(lǐng)域不匹配、切塊大小不合理、查詢?cè)~和文檔用詞差異太大。這些在后面的問(wèn)題排查章節(jié)里細(xì)說(shuō)。2.4 生成Prompt拼接與引用溯源檢索到相關(guān)內(nèi)容之后最后一步就是拼Prompt交給大模型生成回答。這個(gè)環(huán)節(jié)看起來(lái)簡(jiǎn)單但有一個(gè)極其重要的設(shè)計(jì)原則我在項(xiàng)目里反復(fù)強(qiáng)調(diào)一定要告訴模型“資料里沒(méi)有就回答不知道”。否則模型還是會(huì)仗著“自己懂很多”開(kāi)始自由發(fā)揮RAG的防幻覺(jué)優(yōu)勢(shì)就全沒(méi)了。項(xiàng)目里的Prompt模板是這樣的基于以下資料回答問(wèn)題。如果資料里沒(méi)有相關(guān)信息請(qǐng)明確說(shuō)不知道。 資料 {context} 問(wèn)題{query} 回答這個(gè)模板里沒(méi)有花哨的系統(tǒng)和角色設(shè)定原因很簡(jiǎn)單極簡(jiǎn)項(xiàng)目不需要。真正的高手不會(huì)指望靠Prompt魔法讓模型變聰明而是靠檢索質(zhì)量讓模型“不得不”從有限的上下文里找答案。關(guān)于引用溯源熱詞里提到的“rag的引用溯源與groundedness”是個(gè)進(jìn)階話題。要讓回答有據(jù)可查一個(gè)很樸素的做法是檢索時(shí)把每個(gè)文本塊編號(hào)在資料里用[1]、[2]這樣的標(biāo)簽標(biāo)出來(lái)然后在Prompt里要求模型在引用到某個(gè)資料的信息時(shí)在句子后面標(biāo)注對(duì)應(yīng)的編號(hào)。輸出之后你再根據(jù)編號(hào)把原文附在回答末尾。這個(gè)功能我在極簡(jiǎn)版本里沒(méi)有做得很復(fù)雜但保留了編號(hào)的接口后續(xù)擴(kuò)展很方便。3. 實(shí)操?gòu)?fù)現(xiàn)從零跑通這個(gè)極簡(jiǎn)系統(tǒng)3.1 環(huán)境準(zhǔn)備先準(zhǔn)備一臺(tái)有Python 3.9以上版本的機(jī)器建議直接用虛擬環(huán)境避免污染全局環(huán)境。我習(xí)慣在項(xiàng)目目錄里創(chuàng)建虛擬環(huán)境python -m venv .venv source .venv/bin/activate # Windows下是 .venv\Scripts\activate然后是安裝依賴。這個(gè)項(xiàng)目的依賴非?？酥凭瓦@六個(gè)庫(kù)pip install faiss-cpu sentence-transformers pypdf python-docx openai這里說(shuō)明一下幾個(gè)容易混淆的點(diǎn)。faiss-cpu是CPU版夠用如果你有NVIDIA顯卡可以裝faiss-gpu但日常使用差距不大因?yàn)镕AISS檢索本身就是毫秒級(jí)的瓶頸主要在Embedding編碼上。openai庫(kù)是用來(lái)調(diào)用OpenAI兼容接口的不只是OpenAI官方服務(wù)才能用Ollama和大部分本地推理框架都兼容。python-docx在只處理純文本的場(chǎng)景下可以不用裝但考慮到Word文檔太常見(jiàn)我還是加上了。首先項(xiàng)目目錄結(jié)構(gòu)是一個(gè)比較清晰的分離式結(jié)構(gòu)rag_demo/ ├── requirements.txt # 依賴清單 ├── build_kb.py # 構(gòu)建知識(shí)庫(kù)加載→切塊→向量化→存索引 ├── query.py # 查詢檢索→拼Prompt→調(diào)用LLM→輸出回答 ├── docs/ # 放原始文檔txt/md/pdf/docx └── index/ # 運(yùn)行時(shí)自動(dòng)生成存放faiss索引和chunks.json3.2 構(gòu)建知識(shí)庫(kù)的完整代碼build_kb.py是第一步要運(yùn)行的腳本它負(fù)責(zé)把docs/目錄下的所有文檔讀進(jìn)來(lái)、切成小塊、編碼成向量、構(gòu)建索引。import os import glob import json import numpy as np import faiss from pypdf import PdfReader from docx import Document from sentence_transformers import SentenceTransformer MODEL_NAME BAAI/bge-small-zh-v1.5 CHUNK_SIZE 500 CHUNK_OVERLAP 50 DOC_DIR docs INDEX_DIR index def read_document(path): if path.endswith((.txt, .md)): with open(path, r, encodingutf-8) as f: return f.read() elif path.endswith(.pdf): reader PdfReader(path) return \n.join(page.extract_text() or for page in reader.pages) elif path.endswith(.docx): doc Document(path) return \n.join(p.text for p in doc.paragraphs) return def chunk_text(text, chunk_sizeCHUNK_SIZE, overlapCHUNK_OVERLAP): chunks [] start 0 while start len(text): end min(start chunk_size, len(text)) if end len(text): last_period max(text.rfind(。, start, end), text.rfind(\n, start, end), text.rfind(, start, end), text.rfind(, start, end)) if last_period start chunk_size // 2: end last_period 1 chunks.append(text[start:end].strip()) if end len(text): break start end - overlap return [c for c in chunks if c] def main(): os.makedirs(INDEX_DIR, exist_okTrue) all_chunks [] infos [] for doc_path in glob.glob(os.path.join(DOC_DIR, **/*.*), recursiveTrue): if not os.path.isfile(doc_path): continue print(fprocessing: {doc_path}) text read_document(doc_path) if not text.strip(): print(f warning: empty content, skip {doc_path}) continue chunks chunk_text(text) for idx, chunk in enumerate(chunks): all_chunks.append(chunk) infos.append({ id: len(infos), source: doc_path, chunk_index: idx, text: chunk, }) print(ftotal chunks: {len(all_chunks)}) model SentenceTransformer(MODEL_NAME) embeddings model.encode(all_chunks, normalize_embeddingsTrue, show_progress_barTrue) embeddings np.asarray(embeddings, dtypefloat32) dimension embeddings.shape[1] index faiss.IndexFlatIP(dimension) index.add(embeddings) faiss.write_index(index, os.path.join(INDEX_DIR, kb.index)) with open(os.path.join(INDEX_DIR, chunks.json), w, encodingutf-8) as f: json.dump(infos, f, ensure_asciiFalse, indent2) print(build done.) if __name__ __main__: main()這段代碼里值得注意的地方有幾個(gè)。第一glob.glob用了遞歸模式docs/下的子目錄也能掃描到。第二切塊時(shí)的if last_period start chunk_size // 2這個(gè)條件是為了避免在一個(gè)塊的太靠前位置切那樣會(huì)導(dǎo)致塊特別短浪費(fèi)上下文。第三show_progress_barTrue會(huì)在編碼時(shí)打印進(jìn)度條文檔多的時(shí)候不至于讓你以為程序卡死了。3.3 查詢腳本與LLM對(duì)接query.py是第二個(gè)腳本負(fù)責(zé)接收用戶問(wèn)題、檢索、調(diào)用大模型生成回答。import json import sys import numpy as np import faiss from openai import OpenAI from sentence_transformers import SentenceTransformer MODEL_NAME BAAI/bge-small-zh-v1.5 INDEX_DIR index TOP_K 5 LLM_BASE_URL http://localhost:11434/v1 # Ollama 默認(rèn)地址 LLM_MODEL qwen2.5:7b # 換成你實(shí)際拉取的模型名 LLM_API_KEY not-needed # 本地服務(wù)一般不校驗(yàn) key def load_model(): model SentenceTransformer(MODEL_NAME) return model def load_index(): index faiss.read_index(f{INDEX_DIR}/kb.index) with open(f{INDEX_DIR}/chunks.json, r, encodingutf-8) as f: infos json.load(f) return index, infos def retrieve(model, index, infos, query, top_kTOP_K): q_vec model.encode([query], normalize_embeddingsTrue) q_vec np.asarray(q_vec, dtypefloat32) scores, ids index.search(q_vec, top_k) results [] for score, idx in zip(scores[0], ids[0]): if idx 0 and idx len(infos): results.append({ score: float(score), source: infos[idx][source], text: infos[idx][text], }) return results def build_prompt(query, retrieved): context_parts [] for i, r in enumerate(retrieved, start1): context_parts.append(f[{i}] {r[text]}) context \n\n---\n\n.join(context_parts) prompt f基于以下資料回答問(wèn)題。如果資料里沒(méi)有相關(guān)信息請(qǐng)明確說(shuō)不知道。 資料 {context} 問(wèn)題{query} 回答 return prompt def main(): if len(sys.argv) 2: print(usage: python query.py \你的問(wèn)題\) return query sys.argv[1] model load_model() index, infos load_index() retrieved retrieve(model, index, infos, query) print(\n retrieved chunks ) for i, r in enumerate(retrieved, start1): print(f[{i}] score{r[score]:.4f} source{r[source]}) print(r[text][:100].replace(\n, )) print() prompt build_prompt(query, retrieved) client OpenAI(base_urlLLM_BASE_URL, api_keyLLM_API_KEY) resp client.chat.completions.create( modelLLM_MODEL, messages[{role: user, content: prompt}], temperature0.1, ) print( answer ) print(resp.choices[0].message.content) if __name__ __main__: main()這個(gè)腳本有幾個(gè)設(shè)計(jì)細(xì)節(jié)。第一temperature0.1知識(shí)庫(kù)問(wèn)答這種場(chǎng)景要的是事實(shí)準(zhǔn)確性不是創(chuàng)造性所以溫度要低。第二我把檢索到的文本塊在拼接前打上了編號(hào)這樣做有兩個(gè)好處你可以直觀看到模型回答時(shí)到底參考了哪些資料后續(xù)加引用溯源也方便。第三retrieve函數(shù)里對(duì)idx做了邊界判斷防止FAISS返回-1這類空結(jié)果導(dǎo)致程序崩潰。3.4 運(yùn)行驗(yàn)證先往docs/目錄里放幾份測(cè)試文檔。建議第一輪先用你自己的技術(shù)方案、簡(jiǎn)歷、公司內(nèi)部制度這類內(nèi)容做測(cè)試因?yàn)檫@些內(nèi)容的準(zhǔn)確性你自己心里有數(shù)能直觀判斷回答對(duì)不對(duì)。然后依次執(zhí)行python build_kb.py python query.py 什么是RAG正常情況下你會(huì)看到腳本先打印檢索到的文本塊和對(duì)應(yīng)的相似度分?jǐn)?shù)再打印模型生成的回答。如果query.py報(bào)錯(cuò)提示連接不上localhost:11434說(shuō)明本地LLM服務(wù)沒(méi)啟動(dòng)。我用的是Ollama先執(zhí)行ollama pull qwen2.5:7b拉模型再執(zhí)行ollama serve啟動(dòng)服務(wù)。如果你有別的推理服務(wù)直接在LLM_BASE_URL里改地址即可。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 高頻問(wèn)題速查表我在做RAG項(xiàng)目的過(guò)程中被問(wèn)得最多的問(wèn)題基本集中在下面幾類我整理成了一張表大家可以直接對(duì)照排查問(wèn)題現(xiàn)象可能原因解決辦法檢索結(jié)果和問(wèn)題完全不相關(guān)Embedding模型不適合你的領(lǐng)域換text2vec-base-chinese、bge-large-zh或使用領(lǐng)域微調(diào)的Embedding模型相似度分?jǐn)?shù)普遍很低低于0.3切塊太小/太大或查詢?cè)~和文檔表述差異大調(diào)整chunk_size在切塊時(shí)做句子邊界檢測(cè)FAISS報(bào)維度不匹配的錯(cuò)誤構(gòu)建索引和查詢時(shí)用了不同模型保證MODEL_NAME完全一致模型回答“不知道”但資料里明明有切塊把關(guān)鍵信息切碎了檢索時(shí)沒(méi)召回增大chunk_overlap或增加TOP_K模型回答答非所問(wèn)像在自由發(fā)揮檢索到的內(nèi)容本身不是答案模型被誤導(dǎo)先檢查檢索結(jié)果優(yōu)化切塊和EmbeddingPDF內(nèi)容提取出來(lái)全是亂的PDF是掃描件沒(méi)有文本層需要接入OCR比如PaddleOCR、Tesseract文檔一多構(gòu)建索引很慢CPU編碼太慢或切塊太多換GPU跑Embedding或減少重疊字符回答沒(méi)有引用來(lái)源像在編Prompt里沒(méi)有強(qiáng)制要求基于資料回答在Prompt中加入“資料里沒(méi)有請(qǐng)說(shuō)不知道”4.2 我踩過(guò)的幾個(gè)典型坑第一個(gè)坑是中文切塊時(shí)把語(yǔ)義切斷了。早期版本我用了一個(gè)特別簡(jiǎn)單的按固定字符數(shù)切塊的邏輯結(jié)果一個(gè)完整的句子被從中間劈開(kāi)比如“公司價(jià)值觀是”被切到一個(gè)塊的末尾下一塊開(kāi)頭變成了“客戶第一”。檢索的時(shí)候這兩個(gè)塊雖然都有“公司價(jià)值觀”的表述但語(yǔ)義完整度都不夠模型看半天也拼不出完整答案。后來(lái)我加了句子邊界檢測(cè)效果立刻好了很多。如果你也自己寫切塊邏輯一定要記住這個(gè)教訓(xùn)。第二個(gè)坑是向量歸一化問(wèn)題。有一版我構(gòu)建索引時(shí)沒(méi)有normalize_embeddingsTrue用的是IndexFlatL2查詢時(shí)手動(dòng)算余弦相似度結(jié)果分?jǐn)?shù)怎么調(diào)都不對(duì)。后來(lái)我統(tǒng)一改成IndexFlatIP加歸一化邏輯就通順了。這里想強(qiáng)調(diào)一個(gè)理念做檢索你只需要關(guān)心“方向一致性”不需要關(guān)心向量本身的長(zhǎng)度。歸一化之后內(nèi)積就是余弦相似度代碼更簡(jiǎn)單結(jié)果也更好解釋。第三個(gè)坑是本地模型的能力上限。我用Qwen2.5-7B做測(cè)試發(fā)現(xiàn)它有時(shí)候會(huì)無(wú)視Prompt里的“資料里沒(méi)有請(qǐng)說(shuō)不知道”強(qiáng)行編一個(gè)答案。后來(lái)我把temperature調(diào)到0.1同時(shí)在Prompt里把這句話換成了更生硬的版本“基于以下資料回答問(wèn)題如果資料中沒(méi)有相關(guān)答案請(qǐng)直接回復(fù)資料中未找到相關(guān)信息。”效果好了很多。這說(shuō)明Prompt的設(shè)計(jì)確實(shí)能影響模型的“服從度”。第四個(gè)坑是增量更新。最開(kāi)始我想的是每次加一個(gè)新文檔就把索引全部重建文檔少的時(shí)候沒(méi)問(wèn)題文檔多了之后構(gòu)建一次要等好久。后來(lái)我才意識(shí)到這種極簡(jiǎn)架構(gòu)本來(lái)就不適合頻繁增量更新干脆改成“批量重建”策略一次性把文檔都丟進(jìn)docs/然后跑一次build_kb.py。如果非要增量就要用FAISS的IndexIDMap維護(hù)文檔級(jí)別的ID映射但這會(huì)讓項(xiàng)目復(fù)雜度上一個(gè)臺(tái)階就需要權(quán)衡取舍了。5. 從“能跑”到“好用”幾個(gè)低成本優(yōu)化方向極簡(jiǎn)版跑通之后你會(huì)發(fā)現(xiàn)它“能用”但距離“好用”還有一段距離。這里我分享幾個(gè)性價(jià)比特別高的優(yōu)化方向它們不會(huì)破壞項(xiàng)目的極簡(jiǎn)性但能明顯提升體驗(yàn)。先說(shuō)說(shuō)重排序Rerank?，F(xiàn)在第一步召回5個(gè)文本塊但這里面可能有三塊是不相關(guān)的因?yàn)樗豢肯蛄肯嗨贫?。向量相似度擅長(zhǎng)捕捉語(yǔ)義相關(guān)性但對(duì)“這個(gè)塊是否真的包含關(guān)鍵答案”這種精確匹配不敏感。重排的做法是先做一次寬松召回比如召回20個(gè)塊然后用一個(gè)專門的Rerank模型比如bge-reranker-base對(duì)這20個(gè)塊重新打分取前5個(gè)。這樣能極大壓縮無(wú)關(guān)內(nèi)容模型看到的結(jié)果更干凈。再說(shuō)說(shuō)引用溯源。我在前面的Prompt里已經(jīng)給文本塊打了編號(hào)但模型可能不會(huì)自動(dòng)用編號(hào)。要真正實(shí)現(xiàn)“回答完能告訴你依據(jù)在哪”可以在Prompt里追加一句“當(dāng)引用到某份資料的內(nèi)容時(shí)在句子末尾標(biāo)注對(duì)應(yīng)的編號(hào)例如[1]?！比缓笤诖a里把編號(hào)映射回原始的文檔路徑和文本塊附加到回答末尾。這算是RAG落地時(shí)客戶和領(lǐng)導(dǎo)最喜歡問(wèn)的東西因?yàn)樗麄円来鸢缚刹豢尚?。然后是元?shù)據(jù)過(guò)濾。如果知識(shí)庫(kù)里同時(shí)有產(chǎn)品文檔、技術(shù)文檔、管理制度查詢“有哪些產(chǎn)品功能”時(shí)可能會(huì)把技術(shù)文檔里的內(nèi)容也撈出來(lái)。一個(gè)簡(jiǎn)單的做法是在infos里保存每個(gè)塊所屬的文檔分類在檢索時(shí)先按分類過(guò)濾再算相似度。這在FAISS里可以用IndexIDMap配合元數(shù)據(jù)過(guò)濾來(lái)實(shí)現(xiàn)比繼續(xù)用裸的IndexFlatIP稍微復(fù)雜一點(diǎn)但很有必要。最后是Agentic RAG這個(gè)方向。熱詞里出現(xiàn)了很多次“agentic rag”在極簡(jiǎn)項(xiàng)目的基礎(chǔ)上它并不神秘。比如當(dāng)?shù)谝淮螜z索結(jié)果相似度都低于0.5時(shí)就說(shuō)明知識(shí)庫(kù)里可能沒(méi)有直接答案這時(shí)候可以讓模型重新組織一個(gè)更寬泛的查詢?cè)~做第二輪檢索再比如當(dāng)用戶問(wèn)的是“對(duì)比A和B”這種復(fù)合問(wèn)題時(shí)可以先拆成兩個(gè)子問(wèn)題分別檢索再把結(jié)果合并。這些邏輯本質(zhì)上就是在RAG的外面包了一圈決策能力但核心的檢索和生成模塊完全不用改。根據(jù)我個(gè)人的實(shí)操經(jīng)驗(yàn)極簡(jiǎn)版系統(tǒng)最值得投入精力的不是換更貴的模型也不是上更復(fù)雜的架構(gòu)而是先把切塊和檢索調(diào)好。這兩個(gè)環(huán)節(jié)做好了哪怕生成端只是一個(gè)7B的本地模型效果也遠(yuǎn)遠(yuǎn)好過(guò)“檢索稀爛、硬上大模型”的方案。拿到這個(gè)zip包之后我建議你先往里丟幾份自己最熟悉的文檔把檢索結(jié)果逐條看一遍熟悉一下什么文本會(huì)被什么樣的檢索詞召回來(lái)這個(gè)手感建立起來(lái)之后后續(xù)所有的優(yōu)化你就知道自己該往哪個(gè)方向使勁了。本文還有配套的精品資源點(diǎn)擊獲取