最近知識星球中新加入的一些新手盆友，又集中問到了如何快速入門 RAG 的問題。我早在今年三月初就在星球中做過相關(guān)答疑回復(fù)。簡單來說，從個人 24 年年初開始一路的實踐（踩坑）經(jīng)驗來看，通過原生開發(fā)的方式進行入門，無疑是種更加務(wù)實的學習路線。

這篇結(jié)合最近寫的幾篇書稿的章節(jié)內(nèi)容，試圖說清楚：

RAG 技術(shù)棧生態(tài)、框架與平臺選型策略、企業(yè)規(guī)章制度問答場景拆解、原生 RAG 問答系統(tǒng)的完整技術(shù)實現(xiàn)，以及工程經(jīng)驗和架構(gòu)演進梳理。

1、RAG 技術(shù)棧全景

RAG 的技術(shù)生態(tài)并非一個扁平的技術(shù)集合，而是一個可以自下而上理解的多層次結(jié)構(gòu)。每一層提供了不同程度的抽象和封裝，以滿足開發(fā)者在不同場景下對開發(fā)效率、靈活性和系統(tǒng)性能的權(quán)衡。

需要說明的是，下述劃分中的層級間并非嚴格的單向依賴關(guān)系，跨層組合使用很常見，層級更多是功能分工。此外，某些工具具有跨層特性，可能同時承擔多個層級的功能。不同層次的工具和平臺相輔相成，共同構(gòu)成了從開發(fā)到應(yīng)用的完整技術(shù)體系。理解這個分層架構(gòu)，是做出明智技術(shù)選型的第一步。

1.1基礎(chǔ)層 ((Foundation Layer)

提供關(guān)鍵的編程環(huán)境和科學計算支持，可為所有上層應(yīng)用的開發(fā)、訓練和推理提供最基礎(chǔ)的計算能力。代表技術(shù)有 Python（主流開發(fā)語言）、NumPy（數(shù)值計算庫）、PyTorch（深度學習框架）等。

1.2組件層 (Components Layer)

由實現(xiàn)單一具體功能的底層庫組成，是構(gòu)建 RAG 工作流程的基礎(chǔ)組件。代表技術(shù)：PyPDF2（PDF 內(nèi)容提?。?、Transformers（模型庫）、FAISS（向量檢索）等?？芍苯诱{(diào)用這些庫，以最大靈活度手動實現(xiàn) RAG 流程的每個步驟。

1.3工具層 (Tools Layer)

該層級提供針對 RAG 特定環(huán)節(jié)的專業(yè)化、生產(chǎn)級解決方案，產(chǎn)品化程度更高。代表技術(shù)：Pinecone（生產(chǎn)級向量數(shù)據(jù)庫）、MinerU（復(fù)雜文檔解析）、Ragas（RAG 應(yīng)用評估）等。

1.4框架層 (Framework Layer)

該層級是高度封裝的集成框架，提供標準化接口來串聯(lián)和管理底層組件與工具。代表技術(shù)：LangChain、LlamaIndex、Haystack 等?？梢韵窠M合積木一樣快速搭建和切換不同的 RAG 配置，在開發(fā)效率和靈活性間取得平衡。

1.5應(yīng)用層 (Application Layer)

該層級抽象層次最高，以可視化界面和開箱即用平臺的形式存在。代表技術(shù)：RAGFlow、Dify、Flowise 等。將技術(shù)實現(xiàn)細節(jié)完全封裝，通過拖拽和配置即可快速構(gòu)建完整的 RAG 應(yīng)用，極大降低技術(shù)門檻。但同樣不好之處在于對新手是個黑箱，實際調(diào)試過程會相對麻煩。

2、框架與平臺選型策略

技術(shù)選型的本質(zhì)在于在多重約束條件下尋找最適合的平衡點。從組件層理解原理，到框架層快速迭代，再到工具層優(yōu)化關(guān)鍵環(huán)節(jié)的漸進式演進路徑，已經(jīng)是RAG過去大半年一線從業(yè)者逐步形成的共識。無論選擇哪種技術(shù)棧，關(guān)鍵在于明確當前階段的核心目標，并為未來的技術(shù)演進預(yù)留足夠的靈活性。

3、制度問答場景拆解

企業(yè)規(guī)章制度類文檔（以下簡稱“制度文檔”）天然具有格式異構(gòu)性，存儲格式通常是由制度文檔的性質(zhì)和用途決定。例如，為了保證格式的統(tǒng)一性和內(nèi)容不可篡改，正式發(fā)布的《員工手冊》通常是以 PDF 格式歸檔；而對于需要內(nèi)部流轉(zhuǎn)與頻繁修訂的《差旅報銷細則》，則一般是多以 DOCX 格式存在。一言以蔽之，這種也算是個典型的多源異構(gòu)的文檔問答場景。是 RAG 問答比較適合先去落地解決的問題。

在正式開始介紹技術(shù)實現(xiàn)前，先給各位大致看下后續(xù)問答測試所使用的兩份文檔。這兩份文檔也是今年 2 月底我最早一批做的項目中的原始材料（已脫敏）。員工手冊.pdf 文檔中包括了人力資源管理的各個方面，包括雙通道職級體系（專業(yè)序列 P1-P6，管理序列 M1-M5）、工作時間考勤、假期管理、薪酬福利和績效評估等制度。

差旅報銷細則.docx 文檔中包括基于職級和城市等級（一、二、三線）的差旅費用標準體系，包括交通工具選擇權(quán)限、住宿費用上限和餐飲通訊補貼標準。

后續(xù)技術(shù)實現(xiàn)部分的兩個問題測試，也試圖從實際場景出發(fā)，分別檢驗系統(tǒng)在單文檔信息定位和跨文檔信息整合場景方面的表現(xiàn)。

4、技術(shù)實現(xiàn)

4.1核心架構(gòu)

以下按照四個核心模塊展開：全局配置與參數(shù)管理、文檔解析與結(jié)構(gòu)化分塊、向量化與索引存儲系統(tǒng)、檢索與生成核心引擎。

4.2全局配置與參數(shù)管理

config.py 作為系統(tǒng)的配置中心，采用集中化管理策略，實現(xiàn)配置與業(yè)務(wù)邏輯的解耦，確保系統(tǒng)的可維護性和靈活性。系統(tǒng)支持本地 Ollama 和在線 SiliconFlow 兩種部署模式，通過環(huán)境變量和模型標識符進行區(qū)分，其核心配置代碼如下。

# API密鑰配置
SILICONFLOW_API_KEY = os.getenv("SILICONFLOW_API_KEY")


# 本地模式配置
LOCAL_EMBEDDING_MODEL = "BAAI/bge-small-zh-v1.5"
LOCAL_LLM_MODEL = "qwen3:30b" # 根據(jù)配置進行調(diào)整
OLLAMA_BASE_URL = "http://localhost:11434"


# 在線模式配置  
ONLINE_EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-8B"
ONLINE_LLM_MODEL = "deepseek-ai/DeepSeek-R1"
SILICONFLOW_BASE_URL = "https://api.siliconflow.cn/v1"

注：Ollma 上的問答模型中，在中等尺寸模型中 Qwen3:30B 效果較為出色，有條件的可以切換成這個模型進行測試。配置有限也可換成 8b 尺寸。

直接影響檢索效果和問答質(zhì)量的關(guān)鍵參數(shù)，在本系統(tǒng)中的具體設(shè)定如下。

文本分塊配置CHUNK_SIZE = 600           # 文本塊目標大小
CHUNK_OVERLAP = 120                  # 相鄰塊重疊長度檢索調(diào)優(yōu)配置DEFAULT_RETRIEVAL_K = 5             # 檢索返回數(shù)量
DEFAULT_RETRIEVAL_THRESHOLD = 0.4   # 相似度過濾閾值

這些參數(shù)的設(shè)定遵循以下原則：CHUNK_SIZE 設(shè)為 600 字符，既保證了語義的完整性，又控制了向量化的計算開銷；CHUNK_OVERLAP 設(shè)為 120 字符（約 20%重疊率），有效防止重要信息在塊邊界處被切斷；檢索參數(shù) K=5 和閾值 0.4 的組合，在保證召回質(zhì)量的同時控制了上下文長度。通過這種集中化配置策略，后續(xù)各模塊只需引入相應(yīng)參數(shù)即可，大幅提升了系統(tǒng)的可配置性和維護效率。

4.3文檔解析與結(jié)構(gòu)化分塊

這個模塊采用混合分塊方案：在語義分塊的基礎(chǔ)上結(jié)合遞歸字符分塊，形成“先語義預(yù)分塊，后遞歸精細切分”的兩階段處理策略。具體實現(xiàn)由 document_parser.py 和 text_chunker.py 兩個腳本協(xié)同完成。前者負責基于文檔結(jié)構(gòu)特征的語義預(yù)分塊，后者則采用遞歸字符分塊算法進行精細化處理。

語義預(yù)分塊

PDF 文檔處理采用 PyMuPDF 庫進行文本提取，通過正則表達式識別章節(jié)標題模式，實現(xiàn)按章節(jié)的結(jié)構(gòu)化分割。該策略在 _load_pdf_document 函數(shù)中的核心代碼實現(xiàn)如下。

def _load_pdf_document(file_path: str) -> list[LangchainDocument]:
doc = fitz.open(file_path)
# 提取全文并按章節(jié)分割
chapter_pattern = r'第[一二三四五六七八九十\d]+章[：:].'
chapter_matches = list(re.finditer(chapter_pattern, full_text))
# ... 按章節(jié)位置精確分割邏輯

DOCX 文檔處理通過 pypandoc 轉(zhuǎn)換為 Markdown 格式，保留結(jié)構(gòu)信息并按一級標題進行語義分割。該處理邏輯在 _load_docx_document 函數(shù)中核心代碼實現(xiàn)如下。

def _load_docx_document(file_path: str) -> list[LangchainDocument]:
    # 轉(zhuǎn)換為Markdown保留結(jié)構(gòu)
    md_content = pypandoc.convert_file(file_path, 'gfm', format='docx')
    # 按一級標題分割
    chunks = re.split(r'(^#\s[^#].*)', md_content, flags=re.MULTILINE)

系統(tǒng)通過統(tǒng)一的入口函數(shù)根據(jù)文件類型自動選擇解析策略。這個調(diào)度邏輯由 load_document 函數(shù)實現(xiàn)，其核心代碼實現(xiàn)如下。

def load_document(file_path: str) -> list[LangchainDocument]:
    file_extension = os.path.splitext(file_path)[1].lower()
    if file_extension == ".docx":
        return _load_docx_document(file_path)
    elif file_extension == ".pdf":

遞歸精細切分

遞歸精細切分階段由 text_chunker.py 執(zhí)行，使用 RecursiveCharacterTextSplitter 對預(yù)分塊結(jié)果進行精細化處理。該分割器按照雙換行符、單換行符、空格的優(yōu)先級遞歸切分，有效保護句子完整性。該功能的核心實現(xiàn)封裝在 split_documents 函數(shù)中，其核心代碼實現(xiàn)如下。

def split_documents(documents: List[Document]) -> List[Document]:
    text_splitter = RecursiveCharacterTextSplitter(
        chunk_size=CHUNK_SIZE,           # 400字符目標大小
        chunk_overlap=CHUNK_OVERLAP,     # 80字符重疊防止切斷
        add_start_index=True             # 記錄原文位置索引
    )
    return text_splitter.split_documents(documents)

兩階段分塊策略的核心優(yōu)勢在于結(jié)合了語義保持和檢索優(yōu)化。通過這種兩階段處理策略，系統(tǒng)將異構(gòu)的制度文檔高效轉(zhuǎn)換為標準化的 Document 對象列表，為后續(xù)向量化流程提供高質(zhì)量的結(jié)構(gòu)化輸入。

4.4向量化與索引存儲系統(tǒng)

核心實現(xiàn)位于 vector_indexer.py 腳本中，主要包含雙模式文本向量化、FAISS 索引構(gòu)建與優(yōu)化、以及索引持久化機制三個功能模塊。文本向量化部分不做贅述了，著重介紹后兩部分。

FAISS 索引構(gòu)建

系統(tǒng)選用 Meta AI（原 Facebook AI Research）開源的 FAISS 庫構(gòu)建向量索引，VectorIndexer 類的 build_index 方法實現(xiàn)索引構(gòu)建的完整流程。該方法集成了批量向量化、索引創(chuàng)建和 L2 歸一化等關(guān)鍵步驟，其核心代碼實現(xiàn)如下。

# 批量向量化與索引構(gòu)建
embeddings = self.embedding_model.encode(texts)
embedding_dim = embeddings.shape[1]
# 創(chuàng)建內(nèi)積索引并執(zhí)行L2歸一化
self.index = faiss.IndexFlatIP(embedding_dim)
faiss.normalize_L2(embeddings)  # 歸一化后內(nèi)積等價于余弦相似度
self.index.add(embeddings.astype(np.float32))

注：IndexFlatIP 是 FAISS 中的內(nèi)積索引類型（IP 即 Inner Product，通過計算向量間的內(nèi)積來衡量相似性）。L2 歸一化是將向量長度標準化為 1 的數(shù)學操作，經(jīng)過 L2 歸一化后，兩個向量的內(nèi)積運算在數(shù)學上等價于余弦相似度計算。余弦相似度專門用于衡量向量方向的一致性，忽略向量長度差異，因此更適合度量文本語義相似性

索引持久化

為避免重復(fù)執(zhí)行耗時的向量化和索引構(gòu)建，系統(tǒng)實現(xiàn)了索引持久化機制。save_index 方法將構(gòu)建完成的索引和元數(shù)據(jù)分別存儲。該方法將 FAISS 索引與文檔數(shù)據(jù)分離存儲，以確保高效讀寫，其核心代碼實現(xiàn)如下。

# 分離存儲FAISS索引和文檔數(shù)據(jù)
faiss.write_index(self.index, f"{self.index_path}.faiss")
with open(f"{self.index_path}_docs.pkl", 'wb') as f:
    pickle.dump({
        'documents': [doc.page_content for doc in self.documents],
        'metadata': self.document_metadata
    }, f)

注：FAISS 索引以二進制格式（即計算機直接讀取的 0 和 1 編碼格式，相比文本格式具有存儲緊湊、讀取速度快的優(yōu)勢）保存為.faiss 文件。由于 FAISS 專門針對向量數(shù)據(jù)優(yōu)化，僅存儲數(shù)值向量而不包含原始文本，因此系統(tǒng)需要單獨保存文本內(nèi)容和元數(shù)據(jù)。pickle 是 Python 的對象序列化工具，能將復(fù)雜的數(shù)據(jù)結(jié)構(gòu)（如包含文本和字典的列表）轉(zhuǎn)換為字節(jié)流并保存為.pkl 文件，實現(xiàn)完整數(shù)據(jù)結(jié)構(gòu)的持久化存儲。對應(yīng)的 load_index 方法在系統(tǒng)啟動時從磁盤快速恢復(fù)索引器的完整狀態(tài)。

4.5檢索與生成模塊

檢索與生成核心模塊負責處理員工查詢的完整流程：從向量檢索到答案生成。由 retriever.py 和 generator.py 兩個腳本構(gòu)成，分別承擔檢索上下文和生成答案的職責，協(xié)同完成 RAG 系統(tǒng)的核心問答流程。

文檔檢索器

retriever.py 腳本中的 DocumentRetriever 類負責從 FAISS 索引中高效檢索與員工問題語義最相關(guān)的文檔塊。核心的 retrieve 方法實現(xiàn)了完整的檢索流程：

它首先調(diào)用與索引構(gòu)建時相同的嵌入模型將查詢文本向量化，并進行 L2 歸一化以匹配索引格式；隨后，在 FAISS 索引中執(zhí)行相似度搜索，獲取 Top-K 個最相似的文檔塊；最后，應(yīng)用配置的相似度閾值對結(jié)果進行過濾，并將最終結(jié)果封裝為 RetrievalResult 對象返回。該方法封裝了這一完整的檢索邏輯，其核心代碼實現(xiàn)如下。

# retrieve方法核心邏輯
def retrieve(self, query: str, k: int, score_threshold: float):
    # 調(diào)用向量索引器執(zhí)行語義搜索
    raw_results = self.indexer.search(query, k=k)
    # 應(yīng)用相似度閾值過濾低質(zhì)量結(jié)果
    if score_threshold is not None:
        raw_results = [r for r in raw_results if r['score'] >= score_threshold]
    # 封裝檢索結(jié)果并返回檢索指標
    return results, metrics

答案生成器

generator.py 腳本中的 AnswerGenerator 類負責整合檢索信息并調(diào)用大模型生成最終答案。PromptTemplate 類負責構(gòu)建結(jié)構(gòu)化的大模型輸入。build_prompt 方法將檢索到的文檔塊格式化為清晰的上下文，與員工問題一同填入以下預(yù)定義模板。

# 員工指令模板示例
DEFAULT_USER_TEMPLATE = """基于以下文檔內(nèi)容，請回答員工的問題。
**員工問題：**
{query}
**相關(guān)文檔內(nèi)容：**
{context}
**請?zhí)峁蚀_、有條理的回答：**"""

generate_answer 方法實現(xiàn)完整的生成過程。首先調(diào)用 PromptTemplate 構(gòu)建完整提示詞，然后傳遞給對應(yīng)模式的大模型客戶端獲取生成結(jié)果。

# generate_answer方法核心邏輯
def generate_answer(self, query: str, retrieval_results: List[RetrievalResult]):
    # 構(gòu)建結(jié)構(gòu)化提示詞
    system, user_prompt = PromptTemplate.build_prompt(query, retrieval_results)
    # 調(diào)用大模型生成答案
    answer, prompt_tokens, completion_tokens = self.llm_client.generate(
        system, user_prompt
    )
    # 封裝生成結(jié)果并返回完整指標
    return GenerationResult(...)

5、交互界面問題測試

我選擇了 Gradio 庫快速構(gòu)建一個 Web 界面，整體界面采用雙欄布局，主要目的是方便對分塊效果，召回結(jié)果以及思維鏈和最終回答的對比展示。先初始化界面上傳“差旅報銷細節(jié).docx”和“員工手冊.pdf”兩份制度文檔，系統(tǒng)自動完成解析、分塊和索引構(gòu)建。以下通過兩個測試問題，分別檢驗系統(tǒng)在不同層面的能力。

5.1差旅餐費補貼查詢

在問題輸入框中，輸入第一個測試問題：“部門主管可以選擇什么艙位的機票？一天餐費是多少錢？”

這個測試問題需要系統(tǒng)同時獲取部門主管的交通工具權(quán)限標準和餐飲補貼費用信息兩個維度的數(shù)據(jù)。提交問題后，系統(tǒng)在右側(cè)召回片段詳情區(qū)域展示了三個高度相關(guān)的文檔塊：片段 1（相似度 0.613）精準召回了餐飲補貼標準表格，清晰顯示各城市等級的費用標準；片段 2（相似度 0.604）準確定位到交通工具標準條款，明確了部門主管的艙位選擇權(quán)限；片段 3（相似度 0.549）提供了任職標準的補充信息。

左側(cè)答案顯示區(qū)域呈現(xiàn)了系統(tǒng)的完整回答，展現(xiàn)了清晰的思維鏈推理過程：首先明確“部門主管”的職級定義，然后分別針對機票艙位和餐費標準給出精確答案。系統(tǒng)準確識別了部門主管可選擇經(jīng)濟艙或在特定條件下預(yù)訂公務(wù)艙，并根據(jù)出差城市等級提供了 150 元、120 元、100 元的差異化餐費標準，充分驗證了單文檔信息整合和精準回答的能力。

5.2跨文檔職級住宿查詢

接下來測試更具挑戰(zhàn)性的問題：“M3 級別員工去上海出差住宿標準”。這個問題看似更簡單，但實際需要系統(tǒng)進行跨文檔信息整合，從不同文檔中獲取職級定義和住宿標準信息。系統(tǒng)展現(xiàn)了出色的跨文檔檢索能力，召回了 5 個高度相關(guān)的文檔片段，相似度分數(shù)分布在 0.543 至 0.620 區(qū)間。

系統(tǒng)的跨文檔推理過程清晰可見：首先從片段 5“員工手冊.pdf”（相似度 0.543）中準確識別出“M1-M2：項目經(jīng)理/部門主管，M3：部門總監(jiān)”的職級對應(yīng)關(guān)系，確定 M3 級別對應(yīng)部門總監(jiān)；然后從片段 2“差旅報銷細則.docx”（相似度 0.620）中獲取城市分級信息，明確上海屬于一線城市；最后從片段 1 的住宿標準表格中查找到部門總監(jiān)在一線城市的住宿標準為 1000 元/晚。左側(cè)答案顯示區(qū)域完整展現(xiàn)了這三步推理過程，系統(tǒng)準確執(zhí)行了“職級映射→城市分級→標準匹配”的邏輯鏈條，最終給出了精確的住宿費用標準。

6、工程經(jīng)驗與架構(gòu)演進

6.1工程經(jīng)驗

config.py 的集中化配置策略在實踐中展現(xiàn)出顯著優(yōu)勢，支持本地 Ollama 與云端 SiliconFlow 的無縫切換，使相同業(yè)務(wù)邏輯能夠適配不同技術(shù)棧。

雙模式架構(gòu)設(shè)計體現(xiàn)了重要的工程價值。本地模式提供完全自主可控的解決方案，適合數(shù)據(jù)安全要求嚴格的環(huán)境；云端模式獲得更強的模型能力和服務(wù)穩(wěn)定性。這種設(shè)計為技術(shù)驗證提供了漸進式路徑，開發(fā)者可先用云端 API 驗證業(yè)務(wù)邏輯，成熟后再切換到本地部署。

原生實現(xiàn)使每個技術(shù)環(huán)節(jié)完全可見、可控制，從 PyMuPDF 的文檔解析到 FAISS 的向量檢索，所有核心邏輯都以最直接方式呈現(xiàn)。當系統(tǒng)出現(xiàn)問題時，透明的實現(xiàn)方式使問題定位變得簡單，每個模塊的輸入輸出都是標準 Python 對象，便于添加調(diào)試信息和修改處理邏輯。這種可控性在原型開發(fā)和算法調(diào)優(yōu)階段具有不可替代的價值。

6.2架構(gòu)演進

當前原生實現(xiàn)在處理復(fù)雜業(yè)務(wù)邏輯時暴露出開發(fā)成本高、功能擴展困難等問題。每增加一個新功能都需要從底層開始實現(xiàn)，如添加多輪對話支持需要自建會話管理、實現(xiàn)混合檢索需要整合多種算法。成熟的 RAG 框架通過標準化的組件和接口，能夠顯著降低這些高級功能的實現(xiàn)復(fù)雜度，讓開發(fā)者將更多精力集中在業(yè)務(wù)邏輯優(yōu)化上。

LangChain 作為當前最主流的 RAG 開發(fā)框架，提供了完整的組件生態(tài)系統(tǒng)。遷移路徑可以采用漸進式策略：首先用 LangChain 的 Document Loaders 替代自建的文檔解析器，利用其豐富的格式支持；然后采用 VectorStores 統(tǒng)一向量存儲接口，獲得更好的擴展性；最后通過 Chains 將檢索和生成邏輯串聯(lián)，實現(xiàn)更復(fù)雜的 RAG 工作流。LangChain 的最大優(yōu)勢在于其豐富的集成能力和活躍的社區(qū)生態(tài)，能夠快速適配各種模型和向量數(shù)據(jù)庫。

LlamaIndex 專門針對文檔理解和知識問答場景進行了深度優(yōu)化，在處理結(jié)構(gòu)化文檔和復(fù)雜查詢方面表現(xiàn)突出。其提供的 Index 抽象層能夠更好地處理文檔間的層次關(guān)系，Query Engine 支持多種高級檢索策略。對于需要深度文檔理解的應(yīng)用場景，LlamaIndex 往往能提供更精準的檢索和生成效果。

實際遷移過程中建議采用混合策略，保留原生實現(xiàn)中驗證有效的核心邏輯，逐步引入框架組件替代復(fù)雜度高的部分。這種方式既能享受框架帶來的開發(fā)效率提升，又能保持對關(guān)鍵邏輯的控制力。

7、寫在最后

在 Agent 和 Context Engineering 概念滿天飛的時候，回過頭來重溫下原生 RAG 似乎有些逆潮流。但正本清源或許是更加務(wù)實的做法。anyway，下周進一步介紹利用 LangChain、LlamaIndex 等框架，結(jié)合簡歷篩選分析場景，構(gòu)建更加一個復(fù)雜 RAG 應(yīng)用，感興趣的可以蹲一蹲。然后9月第一周更新鴿了很久的京東joyagent二開案例演示。