據(jù)導(dǎo)入實(shí)戰(zhàn)：從txt到Markdown的結(jié)構(gòu)化解析與語義切塊)
1. RAG 數(shù)據(jù)導(dǎo)入的底層邏輯與方案選型1.1 為什么數(shù)據(jù)導(dǎo)入是 RAG 系統(tǒng)的隱形瓶頸做過 RAG 項(xiàng)目的人都有一個(gè)共同體會(huì)模型選型、向量庫調(diào)優(yōu)、檢索策略這些環(huán)節(jié)固然重要但真正讓項(xiàng)目翻車的往往是數(shù)據(jù)導(dǎo)入這一步。我見過太多團(tuán)隊(duì)在 POC 階段用幾十個(gè)干凈的 PDF 跑得風(fēng)生水起一上生產(chǎn)環(huán)境面對(duì)幾萬個(gè)格式各異的文件就徹底崩盤。問題出在哪出在大家把數(shù)據(jù)導(dǎo)入當(dāng)成了一個(gè)“讀文件”的簡單動(dòng)作而實(shí)際上它是一個(gè)完整的數(shù)據(jù)工程管線。RAG 的核心鏈路是“檢索-增強(qiáng)-生成”檢索質(zhì)量直接決定了生成質(zhì)量的上限。而檢索質(zhì)量又取決于什么取決于你導(dǎo)入的文本塊是否語義完整、結(jié)構(gòu)是否清晰、元數(shù)據(jù)是否豐富。如果導(dǎo)入階段把一份結(jié)構(gòu)良好的技術(shù)文檔切成了語義斷裂的碎片后面用再好的 Embedding 模型也救不回來。這就是所謂的“垃圾進(jìn)垃圾出”。從工程角度看數(shù)據(jù)導(dǎo)入與解析要解決的核心問題有三個(gè)格式兼容性、結(jié)構(gòu)保留度、語義完整性。格式兼容性決定了你能吃進(jìn)多少種數(shù)據(jù)源結(jié)構(gòu)保留度決定了你能否利用標(biāo)題、列表、表格等結(jié)構(gòu)信息做增強(qiáng)檢索語義完整性決定了切塊后的文本是否還能被模型正確理解。這三個(gè)問題層層遞進(jìn)任何一個(gè)環(huán)節(jié)處理不好都會(huì)成為整個(gè) RAG 系統(tǒng)的短板。1.2 從 txt 到 Markdown 的選型考量在眾多文檔格式中為什么我們要專門討論 txt 和 Markdown 這兩種因?yàn)樗鼈兇砹藘蓚€(gè)極端txt 是最簡單的純文本格式?jīng)]有任何結(jié)構(gòu)信息Markdown 則是輕量級(jí)標(biāo)記語言用極低的成本表達(dá)了豐富的結(jié)構(gòu)語義。把 txt 轉(zhuǎn)成 Markdown本質(zhì)上是一個(gè)從無結(jié)構(gòu)到有結(jié)構(gòu)的升維過程。這個(gè)升維過程的價(jià)值在哪里舉個(gè)例子。一份產(chǎn)品需求文檔如果用 txt 存儲(chǔ)你看到的是一堆連續(xù)的段落標(biāo)題和正文混在一起列表項(xiàng)和普通句子沒有區(qū)別。切塊的時(shí)候你只能按固定字?jǐn)?shù)硬切切出來的塊可能前半段在講功能 A后半段突然跳到功能 B。但如果轉(zhuǎn)成 Markdown你可以用#標(biāo)記標(biāo)題層級(jí)用-標(biāo)記列表項(xiàng)用**標(biāo)記重點(diǎn)。切塊時(shí)就可以按標(biāo)題層級(jí)做語義切分每個(gè)塊都自帶“我是哪個(gè)章節(jié)的”這個(gè)上下文信息。Markdown 還有一個(gè)被低估的優(yōu)勢它是 LLM 的原生友好格式。大語言模型在預(yù)訓(xùn)練階段見過海量的 Markdown 文本對(duì)#、##、-、這些符號(hào)有天然的語義理解能力。你把 Markdown 格式的文本喂給模型它比喂純文本能更好地把握文檔結(jié)構(gòu)。這一點(diǎn)在 RAG 的生成階段尤其重要因?yàn)槟Ｐ托枰鶕?jù)檢索到的上下文來組織答案如果上下文本身結(jié)構(gòu)清晰生成質(zhì)量會(huì)明顯提升。至于為什么不是 HTML 或 JSONHTML 太冗余標(biāo)簽噪音大清洗成本高JSON 太結(jié)構(gòu)化適合程序處理但不適合直接喂給模型。Markdown 恰好卡在中間結(jié)構(gòu)足夠表達(dá)語義又足夠簡潔不干擾閱讀。這就是我們選擇 Markdown 作為中間格式的核心原因。1.3 通用文本解析的整體架構(gòu)設(shè)計(jì)一個(gè)健壯的文本導(dǎo)入管線應(yīng)該長什么樣我的經(jīng)驗(yàn)是分成四層接入層、識(shí)別層、轉(zhuǎn)換層、輸出層。接入層負(fù)責(zé)對(duì)接各種數(shù)據(jù)源可能是本地文件系統(tǒng)、對(duì)象存儲(chǔ)、數(shù)據(jù)庫導(dǎo)出甚至是網(wǎng)盤同步目錄。這一層的關(guān)鍵是做好文件類型識(shí)別和編碼檢測。我踩過最大的坑就是編碼問題一份 GBK 編碼的中文 txt用 UTF-8 去讀直接亂碼后面所有處理都白費(fèi)。所以接入層必須做編碼嗅探常用的方案是用chardet或charset-normalizer做檢測然后統(tǒng)一轉(zhuǎn)成 UTF-8。識(shí)別層負(fù)責(zé)判斷文件的實(shí)際格式。這里有個(gè)常見誤區(qū)不能只看擴(kuò)展名。我遇到過.txt文件里裝的是 HTML 內(nèi)容也遇到過.md文件其實(shí)是純文本。更可靠的做法是內(nèi)容嗅探讀取文件頭部若干字節(jié)用魔數(shù)或特征模式來判斷真實(shí)格式。對(duì)于文本類文件還可以用啟發(fā)式規(guī)則比如檢測是否包含 Markdown 語法特征#開頭、[]()鏈接、|表格等。轉(zhuǎn)換層是核心負(fù)責(zé)把各種格式統(tǒng)一轉(zhuǎn)成 Markdown。txt 轉(zhuǎn) Markdown 需要做結(jié)構(gòu)推斷PDF 轉(zhuǎn) Markdown 需要做版面分析HTML 轉(zhuǎn) Markdown 需要做標(biāo)簽映射。這一層的設(shè)計(jì)原則是插件化每種格式一個(gè)轉(zhuǎn)換器統(tǒng)一接口方便擴(kuò)展。輸出層負(fù)責(zé)把 Markdown 文本和元數(shù)據(jù)一起寫入下游存儲(chǔ)。元數(shù)據(jù)包括來源文件路徑、轉(zhuǎn)換時(shí)間、原始格式、字符數(shù)、預(yù)估 token 數(shù)等。這些元數(shù)據(jù)在后續(xù)檢索和溯源時(shí)非常有用。2. 純文本 txt 的結(jié)構(gòu)化解析實(shí)戰(zhàn)2.1 編碼檢測與文本清洗的完整流程處理 txt 文件的第一步永遠(yuǎn)是編碼檢測。我見過太多人直接open(file, r)然后被UnicodeDecodeError教做人。正確的做法是先用二進(jìn)制模式讀取然后做編碼嗅探。import chardet def detect_encoding(file_path, sample_size100000): with open(file_path, rb) as f: raw f.read(sample_size) result chardet.detect(raw) return result[encoding], result[confidence]這里有個(gè)細(xì)節(jié)chardet對(duì)短文本的檢測準(zhǔn)確率不高所以采樣量要足夠大。我的經(jīng)驗(yàn)是至少讀 100KB如果文件本身小于 100KB 就全讀。另外chardet返回的編碼名可能和 Python 的編解碼器名稱不完全一致比如它可能返回GB2312而實(shí)際內(nèi)容是GBK需要做一個(gè)映射表來兼容。檢測到編碼后讀取內(nèi)容并統(tǒng)一轉(zhuǎn)成 UTF-8。這里要注意 BOM 的處理UTF-8 with BOM 的文件開頭會(huì)有\(zhòng)ufeff字符如果不處理會(huì)污染第一個(gè)文本塊。用utf-8-sig編碼讀取可以自動(dòng)去掉 BOM。文本清洗是下一步。原始 txt 里常見的噪音包括連續(xù)空行、行尾空格、制表符和空格的混用、不可見控制字符。清洗策略要克制不要過度清洗導(dǎo)致有意義的內(nèi)容被刪掉。我的原則是只清理確定無意義的字符保留所有可能攜帶語義的格式信息。比如連續(xù)三個(gè)以上空行可以壓縮成兩個(gè)但單個(gè)空行要保留因?yàn)樗赡艽矶温浞指簟?.2 基于規(guī)則的標(biāo)題與段落識(shí)別txt 文件沒有顯式的標(biāo)題標(biāo)記但人類寫的文檔通常有隱式的結(jié)構(gòu)線索。我們需要用規(guī)則來推斷這些結(jié)構(gòu)。最常見的標(biāo)題模式有幾種數(shù)字編號(hào)標(biāo)題如“1. 引言”、“1.1 背景”、中文編號(hào)標(biāo)題如“第一章”、“第一節(jié)”、全大寫或全中文加粗標(biāo)題在純文本中通常表現(xiàn)為單獨(dú)一行且前后有空行、以及用特殊符號(hào)裝飾的標(biāo)題如“ 概述 ”。我通常用一組正則表達(dá)式來匹配這些模式import re HEADING_PATTERNS [ (r^#{1,6}\s(.)$, markdown), # 已經(jīng)是 Markdown 標(biāo)題 (r^(\d\.)\s(.)$, numbered), # 1.1 這種編號(hào) (r^第[一二三四五六七八九十百][章節(jié)部分]\s*(.*)$, chinese), # 第X章 (r^[A-Z][A-Z\s]{3,}$, uppercase), # 全大寫行 ]匹配到標(biāo)題后還要推斷標(biāo)題層級(jí)。數(shù)字編號(hào)的層級(jí)可以從編號(hào)的點(diǎn)分深度來判斷“1”是一級(jí)“1.1”是二級(jí)“1.1.1”是三級(jí)。中文編號(hào)則按“章 節(jié) 部分”的順序映射。這里有個(gè)坑有些文檔的編號(hào)不連續(xù)比如從“1”直接跳到“3”這時(shí)候不能假設(shè)層級(jí)只能按編號(hào)深度來。段落識(shí)別相對(duì)簡單連續(xù)的非空行組成一個(gè)段落空行分隔段落。但要注意一種特殊情況有些 txt 是硬換行的即每行末尾都有換行符但語義上屬于同一段。這種需要做行合并如果一行末尾沒有句號(hào)、問號(hào)、感嘆號(hào)等結(jié)束標(biāo)點(diǎn)且下一行開頭不是標(biāo)題模式就把兩行合并。2.3 列表、表格與代碼塊的啟發(fā)式轉(zhuǎn)換列表的識(shí)別主要靠前綴符號(hào)-、*、、?、·以及數(shù)字加點(diǎn)的形式。但這里有個(gè)歧義一個(gè)以-開頭的行可能是列表項(xiàng)也可能是分隔線還可能是普通文本中的破折號(hào)。我的判斷邏輯是如果連續(xù)多行都以相同符號(hào)開頭且符號(hào)后有空格就判定為列表。單行出現(xiàn)的-開頭行需要結(jié)合上下文判斷。表格的識(shí)別是 txt 轉(zhuǎn) Markdown 中最難的部分。純文本表格通常用空格或制表符對(duì)齊或者用|分隔。對(duì)于|分隔的表格直接按|切分再補(bǔ)上 Markdown 的表頭和分隔行即可。對(duì)于空格對(duì)齊的表格需要檢測列對(duì)齊模式找出多行中空格出現(xiàn)的位置是否一致如果一致就按這些位置切分列。def detect_space_aligned_table(lines): # 找出所有行中空格的位置 space_positions [] for line in lines: positions [i for i, c in enumerate(line) if c ] space_positions.append(set(positions)) # 取交集交集位置就是列分隔點(diǎn) common set.intersection(*space_positions) if space_positions else set() return sorted(common)代碼塊的識(shí)別靠縮進(jìn)或圍欄標(biāo)記。如果連續(xù)多行都有相同的縮進(jìn)通常是 4 個(gè)空格或 1 個(gè)制表符且這些行看起來像代碼包含{}、()、、;等符號(hào)就判定為代碼塊。如果原文有圍欄直接保留即可。注意啟發(fā)式規(guī)則永遠(yuǎn)會(huì)有誤判。我的做法是給每個(gè)轉(zhuǎn)換結(jié)果打一個(gè)置信度分?jǐn)?shù)低置信度的轉(zhuǎn)換結(jié)果標(biāo)記出來后續(xù)可以人工抽檢。不要追求 100% 自動(dòng)化的完美轉(zhuǎn)換那是不現(xiàn)實(shí)的。3. Markdown 結(jié)構(gòu)化解析與元數(shù)據(jù)提取3.1 Markdown 語法樹解析的核心要點(diǎn)Markdown 雖然語法簡單但解析起來并不簡單因?yàn)樗恼Z法有大量邊界情況和方言差異。比如#后面有沒有空格、*和_的嵌套規(guī)則、列表的縮進(jìn)規(guī)則等不同解析器行為可能不一致。我的建議是使用成熟的解析庫Python 生態(tài)里markdown-it-py和mistune都是不錯(cuò)的選擇。markdown-it-py遵循 CommonMark 規(guī)范解析結(jié)果穩(wěn)定mistune性能更好適合大批量處理。選哪個(gè)取決于你的場景如果對(duì)規(guī)范一致性要求高選markdown-it-py如果追求吞吐量選mistune。解析的目標(biāo)是得到一棵語法樹每個(gè)節(jié)點(diǎn)代表一個(gè)結(jié)構(gòu)元素標(biāo)題、段落、列表、代碼塊、表格、引用等。有了語法樹后續(xù)的切塊和元數(shù)據(jù)提取就有了依據(jù)。from markdown_it import MarkdownIt md MarkdownIt() tokens md.parse(markdown_text) def walk_tokens(tokens, depth0): for token in tokens: if token.type heading_open: print( * depth fHeading level {token.tag}) elif token.type inline: print( * depth fText: {token.content[:50]}) # 遞歸處理子 token這里的關(guān)鍵是理解 token 的嵌套結(jié)構(gòu)。Markdown 的 token 流是扁平的但通過_open和_close配對(duì)可以還原出樹形結(jié)構(gòu)。標(biāo)題是heading_openinlineheading_close三個(gè) token 組成一組列表是bullet_list_open包裹多個(gè)list_item_open。3.2 標(biāo)題層級(jí)與文檔大綱的自動(dòng)構(gòu)建從語法樹中提取標(biāo)題層級(jí)就能構(gòu)建出文檔的大綱樹。這棵大綱樹是后續(xù)語義切塊的基礎(chǔ)。構(gòu)建大綱樹的邏輯是維護(hù)一個(gè)棧遇到標(biāo)題時(shí)如果當(dāng)前標(biāo)題層級(jí)比棧頂高就壓棧如果比棧頂?shù)途蛷棗Ｖ钡秸业胶线m的父節(jié)點(diǎn)。最終每個(gè)標(biāo)題節(jié)點(diǎn)都掛載了它下屬的內(nèi)容塊。class OutlineNode: def __init__(self, level, title): self.level level self.title title self.children [] self.content [] def build_outline(tokens): root OutlineNode(0, root) stack [root] for token in tokens: if token.type heading_open: level int(token.tag[1]) # 彈棧直到找到層級(jí)更小的父節(jié)點(diǎn) while stack[-1].level level: stack.pop() node OutlineNode(level, ) stack[-1].children.append(node) stack.append(node) elif token.type inline and stack[-1].level 0: if not stack[-1].title: stack[-1].title token.content else: stack[-1].content.append(token.content) return root這棵大綱樹的價(jià)值在于切塊時(shí)可以按標(biāo)題邊界切保證每個(gè)塊都在同一個(gè)標(biāo)題下不會(huì)跨章節(jié)。同時(shí)每個(gè)塊都可以帶上它的標(biāo)題路徑作為元數(shù)據(jù)比如“第3章 3.2節(jié) 3.2.1小節(jié)”這個(gè)路徑在檢索時(shí)可以作為強(qiáng)力的過濾條件。3.3 元數(shù)據(jù)提取與增強(qiáng)檢索的關(guān)聯(lián)Markdown 解析不僅能得到結(jié)構(gòu)還能提取豐富的元數(shù)據(jù)。這些元數(shù)據(jù)在 RAG 檢索階段能發(fā)揮巨大作用。Front Matter是 Markdown 文件頭部的 YAML 元數(shù)據(jù)塊通常包含標(biāo)題、作者、日期、標(biāo)簽等信息。解析 Front Matter 可以直接得到結(jié)構(gòu)化的元數(shù)據(jù)這些信息應(yīng)該附加到該文檔的所有文本塊上。鏈接和圖片也是重要的元數(shù)據(jù)。文檔中引用的外部鏈接可以提取出來作為該塊的“相關(guān)資源”圖片的 alt 文本可以作為該塊的補(bǔ)充描述。我試過在檢索時(shí)把圖片 alt 文本也納入向量化范圍對(duì)于圖文混排的文檔召回率有明顯提升。代碼塊的語言標(biāo)記同樣有價(jià)值。如果用戶問的是編程問題檢索時(shí)優(yōu)先召回帶對(duì)應(yīng)語言標(biāo)記的代碼塊準(zhǔn)確率會(huì)高很多。表格的結(jié)構(gòu)化數(shù)據(jù)可以單獨(dú)提取出來轉(zhuǎn)成 JSON 或 CSV 存儲(chǔ)。有些問題用表格數(shù)據(jù)直接回答比用文本生成更準(zhǔn)確比如“某產(chǎn)品的參數(shù)是多少”這類問題。元數(shù)據(jù)類型提取方式檢索增強(qiáng)用途Front MatterYAML 解析文檔級(jí)過濾、來源溯源標(biāo)題路徑大綱樹遍歷層級(jí)過濾、上下文補(bǔ)充鏈接正則/AST相關(guān)資源推薦圖片 altAST 提取多模態(tài)檢索補(bǔ)充代碼語言圍欄標(biāo)記按語言過濾表格數(shù)據(jù)AST 提取結(jié)構(gòu)化問答提示元數(shù)據(jù)不是越多越好。我見過有人把文件大小、修改時(shí)間、inode 號(hào)都塞進(jìn)元數(shù)據(jù)結(jié)果向量庫的 payload 膨脹到影響性能。只保留對(duì)檢索有實(shí)際幫助的元數(shù)據(jù)其他的放到外部數(shù)據(jù)庫按需關(guān)聯(lián)。4. 從解析結(jié)果到 RAG 就緒數(shù)據(jù)的完整鏈路4.1 語義切塊策略與參數(shù)計(jì)算切塊是數(shù)據(jù)導(dǎo)入的最后一公里也是最容易出問題的地方。切塊太大檢索精度下降因?yàn)橐粋€(gè)塊里混了太多主題切塊太小上下文丟失模型無法理解。找到平衡點(diǎn)是關(guān)鍵。我的切塊策略是結(jié)構(gòu)優(yōu)先語義兜底。具體來說第一步按 Markdown 的標(biāo)題層級(jí)做粗切。每個(gè)最小標(biāo)題單元比如三級(jí)標(biāo)題下的內(nèi)容作為一個(gè)候選塊。這樣切出來的塊天然有語義邊界。第二步對(duì)超長的候選塊做細(xì)切。如果一個(gè)塊超過max_chunk_size就按段落邊界繼續(xù)切。段落邊界比句子邊界好因?yàn)槎温涫峭暾恼Z義單元。第三步對(duì)過短的候選塊做合并。如果相鄰兩個(gè)塊都屬于同一個(gè)父標(biāo)題且合并后不超過max_chunk_size就合并。參數(shù)怎么定max_chunk_size取決于你的 Embedding 模型的最大輸入長度和檢索粒度需求。以常見的 512 token 模型為例我通常設(shè)max_chunk_size400留出余量給元數(shù)據(jù)和特殊 token。min_chunk_size設(shè)為 100低于這個(gè)值的塊要么合并要么丟棄。def semantic_chunk(outline_node, max_size400, min_size100): chunks [] for child in outline_node.children: text \n.join(child.content) if len(text) max_size: if len(text) min_size: chunks.append({ text: text, heading_path: get_heading_path(child), level: child.level }) else: # 太短嘗試與兄弟節(jié)點(diǎn)合并 pass else: # 太長按段落切分 paragraphs text.split(\n\n) current for p in paragraphs: if len(current) len(p) max_size: current p \n\n else: if current: chunks.append({...}) current p \n\n if current: chunks.append({...}) return chunks這里有個(gè)容易被忽略的點(diǎn)重疊窗口。相鄰塊之間保留一定的重疊通常 10%-20%可以避免關(guān)鍵信息恰好落在切分邊界上導(dǎo)致丟失。但重疊也不能太多否則檢索時(shí)會(huì)召回大量重復(fù)內(nèi)容浪費(fèi)上下文窗口。4.2 批量導(dǎo)入的性能優(yōu)化與錯(cuò)誤處理生產(chǎn)環(huán)境的數(shù)據(jù)導(dǎo)入往往是幾萬到幾十萬個(gè)文件性能是必須考慮的問題。我的優(yōu)化經(jīng)驗(yàn)有這么幾條并行處理。文件解析是 IO 密集型和 CPU 密集型混合的任務(wù)用多進(jìn)程池可以顯著提速。但要注意如果下游是向量化 API并發(fā)太高會(huì)觸發(fā)限流。我的做法是解析階段用多進(jìn)程向量化階段用異步加信號(hào)量控制并發(fā)。增量導(dǎo)入。不要每次都全量重跑。記錄每個(gè)文件的哈希值和修改時(shí)間只處理新增和變更的文件。這能把日常導(dǎo)入的耗時(shí)從小時(shí)級(jí)降到分鐘級(jí)。斷點(diǎn)續(xù)傳。批量導(dǎo)入過程中難免有文件解析失敗不能讓一個(gè)壞文件中斷整個(gè)任務(wù)。每個(gè)文件獨(dú)立處理失敗記錄到錯(cuò)誤日志繼續(xù)處理下一個(gè)。最后統(tǒng)一重試失敗的文件。import hashlib from concurrent.futures import ProcessPoolExecutor def file_hash(path): h hashlib.md5() with open(path, rb) as f: for chunk in iter(lambda: f.read(8192), b): h.update(chunk) return h.hexdigest() def batch_import(file_paths, state_db): to_process [] for path in file_paths: h file_hash(path) if state_db.get(path) ! h: to_process.append(path) with ProcessPoolExecutor(max_workers8) as executor: results executor.map(process_file, to_process) for path, result in zip(to_process, results): if result.success: state_db[path] file_hash(path) else: log_error(path, result.error)錯(cuò)誤處理要分級(jí)別編碼錯(cuò)誤、解析錯(cuò)誤、切塊錯(cuò)誤分別記錄方便定位問題。對(duì)于編碼錯(cuò)誤可以嘗試用errorsreplace強(qiáng)制讀取雖然會(huì)有亂碼但至少不會(huì)丟文件對(duì)于解析錯(cuò)誤可以降級(jí)到純文本模式放棄結(jié)構(gòu)信息但保留內(nèi)容。4.3 導(dǎo)入質(zhì)量校驗(yàn)與常見陷阱導(dǎo)入完成后必須做質(zhì)量校驗(yàn)否則你可能在錯(cuò)誤的道路上跑很久才發(fā)現(xiàn)問題。我通常檢查這幾個(gè)指標(biāo)塊長度分布。如果大量塊的長度集中在max_chunk_size附近說明切塊策略太粗暴可能切斷了語義。如果大量塊低于min_chunk_size說明結(jié)構(gòu)識(shí)別有問題把不該切的地方切了。標(biāo)題覆蓋率。統(tǒng)計(jì)有多少塊帶有標(biāo)題路徑元數(shù)據(jù)。如果覆蓋率很低說明標(biāo)題識(shí)別規(guī)則沒生效需要調(diào)整正則?？諌K和重復(fù)塊比例。空塊通常是清洗不徹底導(dǎo)致的重復(fù)塊可能是重疊窗口設(shè)置過大。抽樣人工檢查。隨機(jī)抽 20-30 個(gè)塊人工看一遍。這是最有效但也最容易被跳過的一步。我每次導(dǎo)入新數(shù)據(jù)源都會(huì)做抽樣幾乎每次都能發(fā)現(xiàn)自動(dòng)化指標(biāo)看不出來的問題。常見陷阱我列幾個(gè)印象最深的第一個(gè)是表格跨頁。PDF 轉(zhuǎn) Markdown 時(shí)跨頁的表格會(huì)被切成兩個(gè)表頭丟失。需要在轉(zhuǎn)換后做表格合并檢測。第二個(gè)是代碼塊誤判。有些文檔的正文縮進(jìn)和代碼塊縮進(jìn)一樣導(dǎo)致正文被誤判為代碼。解決辦法是結(jié)合上下文判斷如果縮進(jìn)行前后都是普通段落就不判定為代碼。第三個(gè)是列表嵌套丟失。txt 轉(zhuǎn) Markdown 時(shí)嵌套列表的縮進(jìn)層級(jí)容易丟失導(dǎo)致所有列表項(xiàng)都變成同級(jí)。需要在轉(zhuǎn)換時(shí)保留原始縮進(jìn)信息。第四個(gè)是特殊字符轉(zhuǎn)義。Markdown 中的*、_、[、]等字符有特殊含義如果原文包含這些字符需要轉(zhuǎn)義否則會(huì)破壞 Markdown 結(jié)構(gòu)。但轉(zhuǎn)義過度又會(huì)影響可讀性需要權(quán)衡。注意質(zhì)量校驗(yàn)不是一次性的應(yīng)該做成持續(xù)監(jiān)控。每次導(dǎo)入后自動(dòng)跑一遍校驗(yàn)?zāi)_本指標(biāo)異常時(shí)告警。我吃過虧有一次上游數(shù)據(jù)源格式變了導(dǎo)入的塊全是亂的過了兩周才發(fā)現(xiàn)不得不全量重跑。5. 常見問題排查與實(shí)操避坑指南5.1 編碼與亂碼問題的系統(tǒng)排查亂碼是文本導(dǎo)入的頭號(hào)殺手而且表現(xiàn)形式多樣排查起來需要系統(tǒng)方法。癥狀一全部亂碼。通常是編碼檢測錯(cuò)誤。排查步驟用十六進(jìn)制編輯器看文件頭幾個(gè)字節(jié)判斷是否有 BOM用chardet檢測并打印置信度如果置信度低于 0.7 就要警惕嘗試用常見編碼UTF-8、GBK、GB18030、Big5分別解碼看哪個(gè)能解出可讀文本。癥狀二部分亂碼。通常是混合編碼即文件里既有 UTF-8 又有 GBK 的內(nèi)容。這種情況最難處理我的做法是逐行檢測編碼按行解碼后再拼接。雖然慢但能最大程度保留內(nèi)容。癥狀三特殊符號(hào)亂碼。比如引號(hào)變成a€?這是 UTF-8 被誤讀為 Latin-1 的典型表現(xiàn)。解決辦法是先用 Latin-1 編碼回去再用 UTF-8 解碼。def fix_mojibake(text): try: return text.encode(latin-1).decode(utf-8) except (UnicodeEncodeError, UnicodeDecodeError): return text癥狀四零寬字符和不可見字符。這些字符肉眼看不見但會(huì)干擾后續(xù)處理。用正則[\u200b-\u200f\ufeff]可以匹配并清除。5.2 結(jié)構(gòu)識(shí)別失敗的典型場景與修復(fù)結(jié)構(gòu)識(shí)別失敗的表現(xiàn)是標(biāo)題沒被識(shí)別、列表變成了普通段落、表格散架了。每種情況都有對(duì)應(yīng)的修復(fù)策略。標(biāo)題識(shí)別失敗的常見原因是標(biāo)題格式不在預(yù)設(shè)規(guī)則內(nèi)。比如有些文檔用【標(biāo)題】這種中文方括號(hào)有些用 標(biāo)題這種箭頭。解決辦法是收集足夠多的樣本不斷補(bǔ)充正則規(guī)則。我維護(hù)了一個(gè)規(guī)則庫每遇到一種新格式就加一條現(xiàn)在已經(jīng)有二十多條規(guī)則了。列表識(shí)別失敗通常是因?yàn)榱斜矸?hào)不標(biāo)準(zhǔn)。比如用→或·作為列表符號(hào)。這種情況需要擴(kuò)展列表符號(hào)的匹配范圍。另一個(gè)原因是列表項(xiàng)跨行即一個(gè)列表項(xiàng)的內(nèi)容分成了多行第二行沒有列表符號(hào)。這需要做行合并判斷。表格識(shí)別失敗最常見于空格對(duì)齊的表格。如果列之間的空格數(shù)量不一致對(duì)齊檢測就會(huì)失敗。我的改進(jìn)方案是用聚類代替精確匹配把所有行的空格位置做聚類取聚類中心作為列分隔點(diǎn)允許一定誤差。from sklearn.cluster import KMeans import numpy as np def cluster_columns(lines, n_cols): all_positions [] for line in lines: positions [i for i, c in enumerate(line) if c ] all_positions.extend(positions) if not all_positions: return [] X np.array(all_positions).reshape(-1, 1) kmeans KMeans(n_clustersn_cols-1, n_init10).fit(X) return sorted(kmeans.cluster_centers_.flatten().astype(int))5.3 大批量導(dǎo)入的性能瓶頸定位當(dāng)導(dǎo)入速度慢到無法接受時(shí)需要定位瓶頸在哪。我用分段計(jì)時(shí)的方法在接入、識(shí)別、轉(zhuǎn)換、切塊、向量化每個(gè)階段打時(shí)間戳統(tǒng)計(jì)各階段耗時(shí)占比。常見的瓶頸和優(yōu)化手段瓶頸階段典型癥狀優(yōu)化手段文件讀取IO 等待高用 SSD、批量讀取、異步 IO編碼檢測CPU 占用高采樣檢測、緩存檢測結(jié)果Markdown 解析單核跑滿多進(jìn)程并行、換更快的解析器向量化網(wǎng)絡(luò)等待高批量請(qǐng)求、異步并發(fā)、本地模型向量庫寫入寫入慢批量 upsert、調(diào)整索引參數(shù)我遇到過一次典型的性能問題導(dǎo)入 10 萬個(gè)文件耗時(shí) 8 小時(shí)分段計(jì)時(shí)后發(fā)現(xiàn) 70% 時(shí)間花在向量化 API 調(diào)用上。優(yōu)化方案是把單條請(qǐng)求改成批量請(qǐng)求每批 100 條耗時(shí)直接降到 1.5 小時(shí)。后來又發(fā)現(xiàn)向量庫的索引構(gòu)建是瓶頸調(diào)整了 HNSW 的參數(shù)后進(jìn)一步降到 40 分鐘。提示性能優(yōu)化要先測量再優(yōu)化不要憑感覺。我見過有人一上來就上多進(jìn)程結(jié)果發(fā)現(xiàn)瓶頸在數(shù)據(jù)庫寫入多進(jìn)程反而因?yàn)殒i競爭更慢了。5.4 導(dǎo)入后檢索效果不佳的歸因方法導(dǎo)入完成后檢索效果不好問題可能出在導(dǎo)入階段也可能出在檢索階段。需要系統(tǒng)歸因。第一步檢查召回內(nèi)容。把檢索到的原始?jí)K打印出來看內(nèi)容是否相關(guān)。如果不相關(guān)問題在檢索階段Embedding 模型或索引參數(shù)如果相關(guān)但生成的答案不好問題在生成階段Prompt 或模型。第二步檢查塊質(zhì)量。如果召回的塊內(nèi)容相關(guān)但語義不完整比如一句話被切斷了問題在切塊策略。調(diào)整max_chunk_size和重疊窗口。第三步檢查元數(shù)據(jù)。如果檢索時(shí)無法按來源過濾或者無法按標(biāo)題層級(jí)過濾問題在元數(shù)據(jù)提取。補(bǔ)充缺失的元數(shù)據(jù)字段。第四步檢查覆蓋率。如果某些文檔的內(nèi)容完全檢索不到可能是這些文檔在導(dǎo)入時(shí)被跳過了或者切塊后塊太小被過濾了。檢查導(dǎo)入日志和塊長度分布。我總結(jié)了一個(gè)歸因速查表現(xiàn)象可能原因排查方向召回內(nèi)容不相關(guān)Embedding 質(zhì)量差換模型、微調(diào)召回內(nèi)容相關(guān)但答案差塊語義不完整調(diào)整切塊策略部分文檔檢索不到導(dǎo)入遺漏或塊太小檢查導(dǎo)入日志無法按來源過濾元數(shù)據(jù)缺失補(bǔ)充元數(shù)據(jù)重復(fù)召回同一內(nèi)容重疊窗口過大減小重疊比例長文檔檢索效果差塊太大主題混雜減小 max_chunk_size這套歸因方法我用了很多次基本能在半小時(shí)內(nèi)定位到問題所在。關(guān)鍵是要有完整的日志和可觀測性否則就是盲人摸象。6. 工程化落地的經(jīng)驗(yàn)沉淀6.1 配置化與可擴(kuò)展的管線設(shè)計(jì)數(shù)據(jù)導(dǎo)入管線最忌諱寫死。不同數(shù)據(jù)源、不同文檔類型、不同業(yè)務(wù)場景需求差異很大。我的做法是把所有可變部分做成配置。配置分三層全局配置定義默認(rèn)參數(shù)比如max_chunk_size、overlap_ratio、encoding_fallback數(shù)據(jù)源配置針對(duì)特定來源覆蓋參數(shù)比如某個(gè)目錄下的文件都是 GBK 編碼就單獨(dú)配置文件級(jí)配置針對(duì)特殊文件做定制比如某個(gè) PDF 需要特殊的版面分析參數(shù)。global: max_chunk_size: 400 min_chunk_size: 100 overlap_ratio: 0.15 encoding_fallback: [utf-8, gbk, gb18030] sources: - path: /data/tech_docs encoding: utf-8 chunk_size: 500 - path: /data/legacy_txt encoding: gbk chunk_size: 300可擴(kuò)展性體現(xiàn)在轉(zhuǎn)換器的插件化。每個(gè)轉(zhuǎn)換器實(shí)現(xiàn)統(tǒng)一的接口can_handle(file) - bool和convert(file) - Markdown。新增一種格式只需要加一個(gè)轉(zhuǎn)換器不用改主流程。6.2 導(dǎo)入日志與可觀測性建設(shè)沒有日志的導(dǎo)入管線就是黑盒。我要求日志至少記錄這些信息每個(gè)文件的處理狀態(tài)成功/失敗/跳過、耗時(shí)、字符數(shù)、塊數(shù)、編碼、格式、錯(cuò)誤信息。這些日志匯總后可以生成報(bào)表一眼看出導(dǎo)入健康度。import logging import json logger logging.getLogger(rag_import) def log_import(file_path, status, duration, char_count, chunk_count, errorNone): record { file: file_path, status: status, duration_ms: duration, chars: char_count, chunks: chunk_count, error: str(error) if error else None } logger.info(json.dumps(record, ensure_asciiFalse))日志用 JSON 格式方便后續(xù)用 ELK 或類似工具做聚合分析。關(guān)鍵指標(biāo)包括成功率、平均耗時(shí)、平均塊大小、編碼分布、格式分布。這些指標(biāo)做成儀表盤導(dǎo)入異常時(shí)能第一時(shí)間發(fā)現(xiàn)。6.3 增量更新與版本管理策略生產(chǎn)環(huán)境的文檔是不斷更新的全量重跑不現(xiàn)實(shí)。增量更新需要解決兩個(gè)問題識(shí)別變更和處理刪除。識(shí)別變更用文件哈希加修改時(shí)間雙重判斷。哈希變了說明內(nèi)容變了修改時(shí)間變了但哈希沒變說明只是 touch 了一下不需要重新處理。處理刪除稍微復(fù)雜。如果源文件被刪了對(duì)應(yīng)的向量也應(yīng)該刪掉。我的做法是維護(hù)一個(gè)文件到塊 ID 的映射表文件刪除時(shí)根據(jù)映射表刪除對(duì)應(yīng)的向量。但要注意如果多個(gè)文件的內(nèi)容有重疊刪除一個(gè)文件不應(yīng)該影響另一個(gè)文件的檢索結(jié)果。所以映射表要精確到塊級(jí)別。版本管理方面我建議保留最近 N 個(gè)版本的塊檢索時(shí)默認(rèn)只搜最新版本但支持按版本過濾。這樣既能保證檢索到最新內(nèi)容又能在需要時(shí)回溯歷史。6.4 從單機(jī)腳本到生產(chǎn)服務(wù)的演進(jìn)路徑很多 RAG 項(xiàng)目都是從單機(jī)腳本開始的一個(gè) Python 文件跑完全流程。但隨著數(shù)據(jù)量增長和需求復(fù)雜化必須演進(jìn)到生產(chǎn)服務(wù)。第一階段單機(jī)腳本。適合 POC 和小數(shù)據(jù)量特點(diǎn)是簡單直接缺點(diǎn)是沒法并行、沒法監(jiān)控、沒法增量。第二階段模塊化管線。把接入、解析、切塊、向量化拆成獨(dú)立模塊用消息隊(duì)列串聯(lián)。每個(gè)模塊可以獨(dú)立擴(kuò)展和部署。這個(gè)階段解決了并行和增量問題。第三階段服務(wù)化。把管線封裝成 API 服務(wù)支持按需觸發(fā)和定時(shí)調(diào)度。加上任務(wù)隊(duì)列、重試機(jī)制、監(jiān)控告警。這個(gè)階段解決了運(yùn)維和可觀測性問題。第四階段平臺(tái)化。提供 Web 界面配置數(shù)據(jù)源和參數(shù)支持多租戶支持 A/B 測試不同的切塊策略。這個(gè)階段適合有多團(tuán)隊(duì)協(xié)作的大型組織。我個(gè)人的建議是不要過度設(shè)計(jì)。大部分項(xiàng)目到第二階段就夠了第三階段按需演進(jìn)。我見過有人一上來就搞平臺(tái)化結(jié)果三個(gè)月沒跑通一個(gè)數(shù)據(jù)源得不償失。6.5 我踩過的那些坑與最終建議最后分享幾個(gè)我實(shí)際踩過的坑都是血淚教訓(xùn)?？右缓雎晕募?quán)限。批量導(dǎo)入時(shí)遇到?jīng)]有讀權(quán)限的文件整個(gè)任務(wù)崩潰。后來加了權(quán)限檢查無權(quán)限的文件跳過并記錄?？佣?hào)鏈接循環(huán)。目錄里有指向父目錄的符號(hào)鏈接遞歸遍歷時(shí)無限循環(huán)。后來加了 inode 去重和最大深度限制。坑三超大文件。一個(gè) 2GB 的日志文件讀進(jìn)內(nèi)存直接 OOM。后來加了文件大小限制超過閾值的文件流式處理或跳過?？铀牟l(fā)寫入沖突。多進(jìn)程同時(shí)寫向量庫導(dǎo)致部分?jǐn)?shù)據(jù)丟失。后來改成單進(jìn)程寫入或者用支持并發(fā)寫的向量庫?？游搴雎詴r(shí)區(qū)。文件修改時(shí)間沒帶時(shí)區(qū)增量更新時(shí)判斷錯(cuò)誤。后來統(tǒng)一用 UTC 時(shí)間戳。這些坑看起來都是小問題但每一個(gè)都可能導(dǎo)致導(dǎo)入失敗或數(shù)據(jù)錯(cuò)誤。我的最終建議是把數(shù)據(jù)導(dǎo)入當(dāng)成一個(gè)正式的數(shù)據(jù)工程項(xiàng)目來做而不是一個(gè)臨時(shí)腳本。投入在導(dǎo)入階段的每一分精力都會(huì)在檢索和生成階段得到回報(bào)。數(shù)據(jù)質(zhì)量是 RAG 系統(tǒng)的地基地基不牢上面蓋什么都是危房。 RAG數(shù)據(jù)導(dǎo)入實(shí)戰(zhàn)：從txt到Markdown的結(jié)構(gòu)化解析與語義切塊
1. RAG 數(shù)據(jù)導(dǎo)入的底層邏輯與方案選型1.1 為什么數(shù)據(jù)導(dǎo)入是 RAG 系統(tǒng)的隱形瓶頸做過 RAG 項(xiàng)目的人都有一個(gè)共同體會(huì)模型選型、向量庫調(diào)優(yōu)、檢索策略這些環(huán)節(jié)固然重要但真正讓項(xiàng)目翻車的往往是數(shù)據(jù)導(dǎo)入這一步。我見過太多團(tuán)隊(duì)在 POC 階段用幾十個(gè)干凈的 PDF 跑得風(fēng)生水起一上生產(chǎn)環(huán)境面對(duì)幾萬個(gè)格式各異的文件就徹底崩盤。問題出在哪出在大家把數(shù)據(jù)導(dǎo)入當(dāng)成了一個(gè)“讀文件”的簡單動(dòng)作而實(shí)際上它是一個(gè)完整的數(shù)據(jù)工程管線。RAG 的核心鏈路是“檢索-增強(qiáng)-生成”檢索質(zhì)量直接決定了生成質(zhì)量的上限。而檢索質(zhì)量又取決于什么取決于你導(dǎo)入的文本塊是否語義完整、結(jié)構(gòu)是否清晰、元數(shù)據(jù)是否豐富。如果導(dǎo)入階段把一份結(jié)構(gòu)良好的技術(shù)文檔切成了語義斷裂的碎片后面用再好的 Embedding 模型也救不回來。這就是所謂的“垃圾進(jìn)垃圾出”。從工程角度看數(shù)據(jù)導(dǎo)入與解析要解決的核心問題有三個(gè)格式兼容性、結(jié)構(gòu)保留度、語義完整性。格式兼容性決定了你能吃進(jìn)多少種數(shù)據(jù)源結(jié)構(gòu)保留度決定了你能否利用標(biāo)題、列表、表格等結(jié)構(gòu)信息做增強(qiáng)檢索語義完整性決定了切塊后的文本是否還能被模型正確理解。這三個(gè)問題層層遞進(jìn)任何一個(gè)環(huán)節(jié)處理不好都會(huì)成為整個(gè) RAG 系統(tǒng)的短板。1.2 從 txt 到 Markdown 的選型考量在眾多文檔格式中為什么我們要專門討論 txt 和 Markdown 這兩種因?yàn)樗鼈兇砹藘蓚€(gè)極端txt 是最簡單的純文本格式?jīng)]有任何結(jié)構(gòu)信息Markdown 則是輕量級(jí)標(biāo)記語言用極低的成本表達(dá)了豐富的結(jié)構(gòu)語義。把 txt 轉(zhuǎn)成 Markdown本質(zhì)上是一個(gè)從無結(jié)構(gòu)到有結(jié)構(gòu)的升維過程。這個(gè)升維過程的價(jià)值在哪里舉個(gè)例子。一份產(chǎn)品需求文檔如果用 txt 存儲(chǔ)你看到的是一堆連續(xù)的段落標(biāo)題和正文混在一起列表項(xiàng)和普通句子沒有區(qū)別。切塊的時(shí)候你只能按固定字?jǐn)?shù)硬切切出來的塊可能前半段在講功能 A后半段突然跳到功能 B。但如果轉(zhuǎn)成 Markdown你可以用#標(biāo)記標(biāo)題層級(jí)用-標(biāo)記列表項(xiàng)用**標(biāo)記重點(diǎn)。切塊時(shí)就可以按標(biāo)題層級(jí)做語義切分每個(gè)塊都自帶“我是哪個(gè)章節(jié)的”這個(gè)上下文信息。Markdown 還有一個(gè)被低估的優(yōu)勢它是 LLM 的原生友好格式。大語言模型在預(yù)訓(xùn)練階段見過海量的 Markdown 文本對(duì)#、##、-、這些符號(hào)有天然的語義理解能力。你把 Markdown 格式的文本喂給模型它比喂純文本能更好地把握文檔結(jié)構(gòu)。這一點(diǎn)在 RAG 的生成階段尤其重要因?yàn)槟Ｐ托枰鶕?jù)檢索到的上下文來組織答案如果上下文本身結(jié)構(gòu)清晰生成質(zhì)量會(huì)明顯提升。至于為什么不是 HTML 或 JSONHTML 太冗余標(biāo)簽噪音大清洗成本高JSON 太結(jié)構(gòu)化適合程序處理但不適合直接喂給模型。Markdown 恰好卡在中間結(jié)構(gòu)足夠表達(dá)語義又足夠簡潔不干擾閱讀。這就是我們選擇 Markdown 作為中間格式的核心原因。1.3 通用文本解析的整體架構(gòu)設(shè)計(jì)一個(gè)健壯的文本導(dǎo)入管線應(yīng)該長什么樣我的經(jīng)驗(yàn)是分成四層接入層、識(shí)別層、轉(zhuǎn)換層、輸出層。接入層負(fù)責(zé)對(duì)接各種數(shù)據(jù)源可能是本地文件系統(tǒng)、對(duì)象存儲(chǔ)、數(shù)據(jù)庫導(dǎo)出甚至是網(wǎng)盤同步目錄。這一層的關(guān)鍵是做好文件類型識(shí)別和編碼檢測。我踩過最大的坑就是編碼問題一份 GBK 編碼的中文 txt用 UTF-8 去讀直接亂碼后面所有處理都白費(fèi)。所以接入層必須做編碼嗅探常用的方案是用chardet或charset-normalizer做檢測然后統(tǒng)一轉(zhuǎn)成 UTF-8。識(shí)別層負(fù)責(zé)判斷文件的實(shí)際格式。這里有個(gè)常見誤區(qū)不能只看擴(kuò)展名。我遇到過.txt文件里裝的是 HTML 內(nèi)容也遇到過.md文件其實(shí)是純文本。更可靠的做法是內(nèi)容嗅探讀取文件頭部若干字節(jié)用魔數(shù)或特征模式來判斷真實(shí)格式。對(duì)于文本類文件還可以用啟發(fā)式規(guī)則比如檢測是否包含 Markdown 語法特征#開頭、[]()鏈接、|表格等。轉(zhuǎn)換層是核心負(fù)責(zé)把各種格式統(tǒng)一轉(zhuǎn)成 Markdown。txt 轉(zhuǎn) Markdown 需要做結(jié)構(gòu)推斷PDF 轉(zhuǎn) Markdown 需要做版面分析HTML 轉(zhuǎn) Markdown 需要做標(biāo)簽映射。這一層的設(shè)計(jì)原則是插件化每種格式一個(gè)轉(zhuǎn)換器統(tǒng)一接口方便擴(kuò)展。輸出層負(fù)責(zé)把 Markdown 文本和元數(shù)據(jù)一起寫入下游存儲(chǔ)。元數(shù)據(jù)包括來源文件路徑、轉(zhuǎn)換時(shí)間、原始格式、字符數(shù)、預(yù)估 token 數(shù)等。這些元數(shù)據(jù)在后續(xù)檢索和溯源時(shí)非常有用。2. 純文本 txt 的結(jié)構(gòu)化解析實(shí)戰(zhàn)2.1 編碼檢測與文本清洗的完整流程處理 txt 文件的第一步永遠(yuǎn)是編碼檢測。我見過太多人直接open(file, r)然后被UnicodeDecodeError教做人。正確的做法是先用二進(jìn)制模式讀取然后做編碼嗅探。import chardet def detect_encoding(file_path, sample_size100000): with open(file_path, rb) as f: raw f.read(sample_size) result chardet.detect(raw) return result[encoding], result[confidence]這里有個(gè)細(xì)節(jié)chardet對(duì)短文本的檢測準(zhǔn)確率不高所以采樣量要足夠大。我的經(jīng)驗(yàn)是至少讀 100KB如果文件本身小于 100KB 就全讀。另外chardet返回的編碼名可能和 Python 的編解碼器名稱不完全一致比如它可能返回GB2312而實(shí)際內(nèi)容是GBK需要做一個(gè)映射表來兼容。檢測到編碼后讀取內(nèi)容并統(tǒng)一轉(zhuǎn)成 UTF-8。這里要注意 BOM 的處理UTF-8 with BOM 的文件開頭會(huì)有\(zhòng)ufeff字符如果不處理會(huì)污染第一個(gè)文本塊。用utf-8-sig編碼讀取可以自動(dòng)去掉 BOM。文本清洗是下一步。原始 txt 里常見的噪音包括連續(xù)空行、行尾空格、制表符和空格的混用、不可見控制字符。清洗策略要克制不要過度清洗導(dǎo)致有意義的內(nèi)容被刪掉。我的原則是只清理確定無意義的字符保留所有可能攜帶語義的格式信息。比如連續(xù)三個(gè)以上空行可以壓縮成兩個(gè)但單個(gè)空行要保留因?yàn)樗赡艽矶温浞指簟?.2 基于規(guī)則的標(biāo)題與段落識(shí)別txt 文件沒有顯式的標(biāo)題標(biāo)記但人類寫的文檔通常有隱式的結(jié)構(gòu)線索。我們需要用規(guī)則來推斷這些結(jié)構(gòu)。最常見的標(biāo)題模式有幾種數(shù)字編號(hào)標(biāo)題如“1. 引言”、“1.1 背景”、中文編號(hào)標(biāo)題如“第一章”、“第一節(jié)”、全大寫或全中文加粗標(biāo)題在純文本中通常表現(xiàn)為單獨(dú)一行且前后有空行、以及用特殊符號(hào)裝飾的標(biāo)題如“ 概述 ”。我通常用一組正則表達(dá)式來匹配這些模式import re HEADING_PATTERNS [ (r^#{1,6}\s(.)$, markdown), # 已經(jīng)是 Markdown 標(biāo)題 (r^(\d\.)\s(.)$, numbered), # 1.1 這種編號(hào) (r^第[一二三四五六七八九十百][章節(jié)部分]\s*(.*)$, chinese), # 第X章 (r^[A-Z][A-Z\s]{3,}$, uppercase), # 全大寫行 ]匹配到標(biāo)題后還要推斷標(biāo)題層級(jí)。數(shù)字編號(hào)的層級(jí)可以從編號(hào)的點(diǎn)分深度來判斷“1”是一級(jí)“1.1”是二級(jí)“1.1.1”是三級(jí)。中文編號(hào)則按“章 節(jié) 部分”的順序映射。這里有個(gè)坑有些文檔的編號(hào)不連續(xù)比如從“1”直接跳到“3”這時(shí)候不能假設(shè)層級(jí)只能按編號(hào)深度來。段落識(shí)別相對(duì)簡單連續(xù)的非空行組成一個(gè)段落空行分隔段落。但要注意一種特殊情況有些 txt 是硬換行的即每行末尾都有換行符但語義上屬于同一段。這種需要做行合并如果一行末尾沒有句號(hào)、問號(hào)、感嘆號(hào)等結(jié)束標(biāo)點(diǎn)且下一行開頭不是標(biāo)題模式就把兩行合并。2.3 列表、表格與代碼塊的啟發(fā)式轉(zhuǎn)換列表的識(shí)別主要靠前綴符號(hào)-、*、、?、·以及數(shù)字加點(diǎn)的形式。但這里有個(gè)歧義一個(gè)以-開頭的行可能是列表項(xiàng)也可能是分隔線還可能是普通文本中的破折號(hào)。我的判斷邏輯是如果連續(xù)多行都以相同符號(hào)開頭且符號(hào)后有空格就判定為列表。單行出現(xiàn)的-開頭行需要結(jié)合上下文判斷。表格的識(shí)別是 txt 轉(zhuǎn) Markdown 中最難的部分。純文本表格通常用空格或制表符對(duì)齊或者用|分隔。對(duì)于|分隔的表格直接按|切分再補(bǔ)上 Markdown 的表頭和分隔行即可。對(duì)于空格對(duì)齊的表格需要檢測列對(duì)齊模式找出多行中空格出現(xiàn)的位置是否一致如果一致就按這些位置切分列。def detect_space_aligned_table(lines): # 找出所有行中空格的位置 space_positions [] for line in lines: positions [i for i, c in enumerate(line) if c ] space_positions.append(set(positions)) # 取交集交集位置就是列分隔點(diǎn) common set.intersection(*space_positions) if space_positions else set() return sorted(common)代碼塊的識(shí)別靠縮進(jìn)或圍欄標(biāo)記。如果連續(xù)多行都有相同的縮進(jìn)通常是 4 個(gè)空格或 1 個(gè)制表符且這些行看起來像代碼包含{}、()、、;等符號(hào)就判定為代碼塊。如果原文有圍欄直接保留即可。注意啟發(fā)式規(guī)則永遠(yuǎn)會(huì)有誤判。我的做法是給每個(gè)轉(zhuǎn)換結(jié)果打一個(gè)置信度分?jǐn)?shù)低置信度的轉(zhuǎn)換結(jié)果標(biāo)記出來后續(xù)可以人工抽檢。不要追求 100% 自動(dòng)化的完美轉(zhuǎn)換那是不現(xiàn)實(shí)的。3. Markdown 結(jié)構(gòu)化解析與元數(shù)據(jù)提取3.1 Markdown 語法樹解析的核心要點(diǎn)Markdown 雖然語法簡單但解析起來并不簡單因?yàn)樗恼Z法有大量邊界情況和方言差異。比如#后面有沒有空格、*和_的嵌套規(guī)則、列表的縮進(jìn)規(guī)則等不同解析器行為可能不一致。我的建議是使用成熟的解析庫Python 生態(tài)里markdown-it-py和mistune都是不錯(cuò)的選擇。markdown-it-py遵循 CommonMark 規(guī)范解析結(jié)果穩(wěn)定mistune性能更好適合大批量處理。選哪個(gè)取決于你的場景如果對(duì)規(guī)范一致性要求高選markdown-it-py如果追求吞吐量選mistune。解析的目標(biāo)是得到一棵語法樹每個(gè)節(jié)點(diǎn)代表一個(gè)結(jié)構(gòu)元素標(biāo)題、段落、列表、代碼塊、表格、引用等。有了語法樹后續(xù)的切塊和元數(shù)據(jù)提取就有了依據(jù)。from markdown_it import MarkdownIt md MarkdownIt() tokens md.parse(markdown_text) def walk_tokens(tokens, depth0): for token in tokens: if token.type heading_open: print( * depth fHeading level {token.tag}) elif token.type inline: print( * depth fText: {token.content[:50]}) # 遞歸處理子 token這里的關(guān)鍵是理解 token 的嵌套結(jié)構(gòu)。Markdown 的 token 流是扁平的但通過_open和_close配對(duì)可以還原出樹形結(jié)構(gòu)。標(biāo)題是heading_openinlineheading_close三個(gè) token 組成一組列表是bullet_list_open包裹多個(gè)list_item_open。3.2 標(biāo)題層級(jí)與文檔大綱的自動(dòng)構(gòu)建從語法樹中提取標(biāo)題層級(jí)就能構(gòu)建出文檔的大綱樹。這棵大綱樹是后續(xù)語義切塊的基礎(chǔ)。構(gòu)建大綱樹的邏輯是維護(hù)一個(gè)棧遇到標(biāo)題時(shí)如果當(dāng)前標(biāo)題層級(jí)比棧頂高就壓棧如果比棧頂?shù)途蛷棗Ｖ钡秸业胶线m的父節(jié)點(diǎn)。最終每個(gè)標(biāo)題節(jié)點(diǎn)都掛載了它下屬的內(nèi)容塊。class OutlineNode: def __init__(self, level, title): self.level level self.title title self.children [] self.content [] def build_outline(tokens): root OutlineNode(0, root) stack [root] for token in tokens: if token.type heading_open: level int(token.tag[1]) # 彈棧直到找到層級(jí)更小的父節(jié)點(diǎn) while stack[-1].level level: stack.pop() node OutlineNode(level, ) stack[-1].children.append(node) stack.append(node) elif token.type inline and stack[-1].level 0: if not stack[-1].title: stack[-1].title token.content else: stack[-1].content.append(token.content) return root這棵大綱樹的價(jià)值在于切塊時(shí)可以按標(biāo)題邊界切保證每個(gè)塊都在同一個(gè)標(biāo)題下不會(huì)跨章節(jié)。同時(shí)每個(gè)塊都可以帶上它的標(biāo)題路徑作為元數(shù)據(jù)比如“第3章 3.2節(jié) 3.2.1小節(jié)”這個(gè)路徑在檢索時(shí)可以作為強(qiáng)力的過濾條件。3.3 元數(shù)據(jù)提取與增強(qiáng)檢索的關(guān)聯(lián)Markdown 解析不僅能得到結(jié)構(gòu)還能提取豐富的元數(shù)據(jù)。這些元數(shù)據(jù)在 RAG 檢索階段能發(fā)揮巨大作用。Front Matter是 Markdown 文件頭部的 YAML 元數(shù)據(jù)塊通常包含標(biāo)題、作者、日期、標(biāo)簽等信息。解析 Front Matter 可以直接得到結(jié)構(gòu)化的元數(shù)據(jù)這些信息應(yīng)該附加到該文檔的所有文本塊上。鏈接和圖片也是重要的元數(shù)據(jù)。文檔中引用的外部鏈接可以提取出來作為該塊的“相關(guān)資源”圖片的 alt 文本可以作為該塊的補(bǔ)充描述。我試過在檢索時(shí)把圖片 alt 文本也納入向量化范圍對(duì)于圖文混排的文檔召回率有明顯提升。代碼塊的語言標(biāo)記同樣有價(jià)值。如果用戶問的是編程問題檢索時(shí)優(yōu)先召回帶對(duì)應(yīng)語言標(biāo)記的代碼塊準(zhǔn)確率會(huì)高很多。表格的結(jié)構(gòu)化數(shù)據(jù)可以單獨(dú)提取出來轉(zhuǎn)成 JSON 或 CSV 存儲(chǔ)。有些問題用表格數(shù)據(jù)直接回答比用文本生成更準(zhǔn)確比如“某產(chǎn)品的參數(shù)是多少”這類問題。元數(shù)據(jù)類型提取方式檢索增強(qiáng)用途Front MatterYAML 解析文檔級(jí)過濾、來源溯源標(biāo)題路徑大綱樹遍歷層級(jí)過濾、上下文補(bǔ)充鏈接正則/AST相關(guān)資源推薦圖片 altAST 提取多模態(tài)檢索補(bǔ)充代碼語言圍欄標(biāo)記按語言過濾表格數(shù)據(jù)AST 提取結(jié)構(gòu)化問答提示元數(shù)據(jù)不是越多越好。我見過有人把文件大小、修改時(shí)間、inode 號(hào)都塞進(jìn)元數(shù)據(jù)結(jié)果向量庫的 payload 膨脹到影響性能。只保留對(duì)檢索有實(shí)際幫助的元數(shù)據(jù)其他的放到外部數(shù)據(jù)庫按需關(guān)聯(lián)。4. 從解析結(jié)果到 RAG 就緒數(shù)據(jù)的完整鏈路4.1 語義切塊策略與參數(shù)計(jì)算切塊是數(shù)據(jù)導(dǎo)入的最后一公里也是最容易出問題的地方。切塊太大檢索精度下降因?yàn)橐粋€(gè)塊里混了太多主題切塊太小上下文丟失模型無法理解。找到平衡點(diǎn)是關(guān)鍵。我的切塊策略是結(jié)構(gòu)優(yōu)先語義兜底。具體來說第一步按 Markdown 的標(biāo)題層級(jí)做粗切。每個(gè)最小標(biāo)題單元比如三級(jí)標(biāo)題下的內(nèi)容作為一個(gè)候選塊。這樣切出來的塊天然有語義邊界。第二步對(duì)超長的候選塊做細(xì)切。如果一個(gè)塊超過max_chunk_size就按段落邊界繼續(xù)切。段落邊界比句子邊界好因?yàn)槎温涫峭暾恼Z義單元。第三步對(duì)過短的候選塊做合并。如果相鄰兩個(gè)塊都屬于同一個(gè)父標(biāo)題且合并后不超過max_chunk_size就合并。參數(shù)怎么定max_chunk_size取決于你的 Embedding 模型的最大輸入長度和檢索粒度需求。以常見的 512 token 模型為例我通常設(shè)max_chunk_size400留出余量給元數(shù)據(jù)和特殊 token。min_chunk_size設(shè)為 100低于這個(gè)值的塊要么合并要么丟棄。def semantic_chunk(outline_node, max_size400, min_size100): chunks [] for child in outline_node.children: text \n.join(child.content) if len(text) max_size: if len(text) min_size: chunks.append({ text: text, heading_path: get_heading_path(child), level: child.level }) else: # 太短嘗試與兄弟節(jié)點(diǎn)合并 pass else: # 太長按段落切分 paragraphs text.split(\n\n) current for p in paragraphs: if len(current) len(p) max_size: current p \n\n else: if current: chunks.append({...}) current p \n\n if current: chunks.append({...}) return chunks這里有個(gè)容易被忽略的點(diǎn)重疊窗口。相鄰塊之間保留一定的重疊通常 10%-20%可以避免關(guān)鍵信息恰好落在切分邊界上導(dǎo)致丟失。但重疊也不能太多否則檢索時(shí)會(huì)召回大量重復(fù)內(nèi)容浪費(fèi)上下文窗口。4.2 批量導(dǎo)入的性能優(yōu)化與錯(cuò)誤處理生產(chǎn)環(huán)境的數(shù)據(jù)導(dǎo)入往往是幾萬到幾十萬個(gè)文件性能是必須考慮的問題。我的優(yōu)化經(jīng)驗(yàn)有這么幾條并行處理。文件解析是 IO 密集型和 CPU 密集型混合的任務(wù)用多進(jìn)程池可以顯著提速。但要注意如果下游是向量化 API并發(fā)太高會(huì)觸發(fā)限流。我的做法是解析階段用多進(jìn)程向量化階段用異步加信號(hào)量控制并發(fā)。增量導(dǎo)入。不要每次都全量重跑。記錄每個(gè)文件的哈希值和修改時(shí)間只處理新增和變更的文件。這能把日常導(dǎo)入的耗時(shí)從小時(shí)級(jí)降到分鐘級(jí)。斷點(diǎn)續(xù)傳。批量導(dǎo)入過程中難免有文件解析失敗不能讓一個(gè)壞文件中斷整個(gè)任務(wù)。每個(gè)文件獨(dú)立處理失敗記錄到錯(cuò)誤日志繼續(xù)處理下一個(gè)。最后統(tǒng)一重試失敗的文件。import hashlib from concurrent.futures import ProcessPoolExecutor def file_hash(path): h hashlib.md5() with open(path, rb) as f: for chunk in iter(lambda: f.read(8192), b): h.update(chunk) return h.hexdigest() def batch_import(file_paths, state_db): to_process [] for path in file_paths: h file_hash(path) if state_db.get(path) ! h: to_process.append(path) with ProcessPoolExecutor(max_workers8) as executor: results executor.map(process_file, to_process) for path, result in zip(to_process, results): if result.success: state_db[path] file_hash(path) else: log_error(path, result.error)錯(cuò)誤處理要分級(jí)別編碼錯(cuò)誤、解析錯(cuò)誤、切塊錯(cuò)誤分別記錄方便定位問題。對(duì)于編碼錯(cuò)誤可以嘗試用errorsreplace強(qiáng)制讀取雖然會(huì)有亂碼但至少不會(huì)丟文件對(duì)于解析錯(cuò)誤可以降級(jí)到純文本模式放棄結(jié)構(gòu)信息但保留內(nèi)容。4.3 導(dǎo)入質(zhì)量校驗(yàn)與常見陷阱導(dǎo)入完成后必須做質(zhì)量校驗(yàn)否則你可能在錯(cuò)誤的道路上跑很久才發(fā)現(xiàn)問題。我通常檢查這幾個(gè)指標(biāo)塊長度分布。如果大量塊的長度集中在max_chunk_size附近說明切塊策略太粗暴可能切斷了語義。如果大量塊低于min_chunk_size說明結(jié)構(gòu)識(shí)別有問題把不該切的地方切了。標(biāo)題覆蓋率。統(tǒng)計(jì)有多少塊帶有標(biāo)題路徑元數(shù)據(jù)。如果覆蓋率很低說明標(biāo)題識(shí)別規(guī)則沒生效需要調(diào)整正則?？諌K和重復(fù)塊比例。空塊通常是清洗不徹底導(dǎo)致的重復(fù)塊可能是重疊窗口設(shè)置過大。抽樣人工檢查。隨機(jī)抽 20-30 個(gè)塊人工看一遍。這是最有效但也最容易被跳過的一步。我每次導(dǎo)入新數(shù)據(jù)源都會(huì)做抽樣幾乎每次都能發(fā)現(xiàn)自動(dòng)化指標(biāo)看不出來的問題。常見陷阱我列幾個(gè)印象最深的第一個(gè)是表格跨頁。PDF 轉(zhuǎn) Markdown 時(shí)跨頁的表格會(huì)被切成兩個(gè)表頭丟失。需要在轉(zhuǎn)換后做表格合并檢測。第二個(gè)是代碼塊誤判。有些文檔的正文縮進(jìn)和代碼塊縮進(jìn)一樣導(dǎo)致正文被誤判為代碼。解決辦法是結(jié)合上下文判斷如果縮進(jìn)行前后都是普通段落就不判定為代碼。第三個(gè)是列表嵌套丟失。txt 轉(zhuǎn) Markdown 時(shí)嵌套列表的縮進(jìn)層級(jí)容易丟失導(dǎo)致所有列表項(xiàng)都變成同級(jí)。需要在轉(zhuǎn)換時(shí)保留原始縮進(jìn)信息。第四個(gè)是特殊字符轉(zhuǎn)義。Markdown 中的*、_、[、]等字符有特殊含義如果原文包含這些字符需要轉(zhuǎn)義否則會(huì)破壞 Markdown 結(jié)構(gòu)。但轉(zhuǎn)義過度又會(huì)影響可讀性需要權(quán)衡。注意質(zhì)量校驗(yàn)不是一次性的應(yīng)該做成持續(xù)監(jiān)控。每次導(dǎo)入后自動(dòng)跑一遍校驗(yàn)?zāi)_本指標(biāo)異常時(shí)告警。我吃過虧有一次上游數(shù)據(jù)源格式變了導(dǎo)入的塊全是亂的過了兩周才發(fā)現(xiàn)不得不全量重跑。5. 常見問題排查與實(shí)操避坑指南5.1 編碼與亂碼問題的系統(tǒng)排查亂碼是文本導(dǎo)入的頭號(hào)殺手而且表現(xiàn)形式多樣排查起來需要系統(tǒng)方法。癥狀一全部亂碼。通常是編碼檢測錯(cuò)誤。排查步驟用十六進(jìn)制編輯器看文件頭幾個(gè)字節(jié)判斷是否有 BOM用chardet檢測并打印置信度如果置信度低于 0.7 就要警惕嘗試用常見編碼UTF-8、GBK、GB18030、Big5分別解碼看哪個(gè)能解出可讀文本。癥狀二部分亂碼。通常是混合編碼即文件里既有 UTF-8 又有 GBK 的內(nèi)容。這種情況最難處理我的做法是逐行檢測編碼按行解碼后再拼接。雖然慢但能最大程度保留內(nèi)容。癥狀三特殊符號(hào)亂碼。比如引號(hào)變成a€?這是 UTF-8 被誤讀為 Latin-1 的典型表現(xiàn)。解決辦法是先用 Latin-1 編碼回去再用 UTF-8 解碼。def fix_mojibake(text): try: return text.encode(latin-1).decode(utf-8) except (UnicodeEncodeError, UnicodeDecodeError): return text癥狀四零寬字符和不可見字符。這些字符肉眼看不見但會(huì)干擾后續(xù)處理。用正則[\u200b-\u200f\ufeff]可以匹配并清除。5.2 結(jié)構(gòu)識(shí)別失敗的典型場景與修復(fù)結(jié)構(gòu)識(shí)別失敗的表現(xiàn)是標(biāo)題沒被識(shí)別、列表變成了普通段落、表格散架了。每種情況都有對(duì)應(yīng)的修復(fù)策略。標(biāo)題識(shí)別失敗的常見原因是標(biāo)題格式不在預(yù)設(shè)規(guī)則內(nèi)。比如有些文檔用【標(biāo)題】這種中文方括號(hào)有些用 標(biāo)題這種箭頭。解決辦法是收集足夠多的樣本不斷補(bǔ)充正則規(guī)則。我維護(hù)了一個(gè)規(guī)則庫每遇到一種新格式就加一條現(xiàn)在已經(jīng)有二十多條規(guī)則了。列表識(shí)別失敗通常是因?yàn)榱斜矸?hào)不標(biāo)準(zhǔn)。比如用→或·作為列表符號(hào)。這種情況需要擴(kuò)展列表符號(hào)的匹配范圍。另一個(gè)原因是列表項(xiàng)跨行即一個(gè)列表項(xiàng)的內(nèi)容分成了多行第二行沒有列表符號(hào)。這需要做行合并判斷。表格識(shí)別失敗最常見于空格對(duì)齊的表格。如果列之間的空格數(shù)量不一致對(duì)齊檢測就會(huì)失敗。我的改進(jìn)方案是用聚類代替精確匹配把所有行的空格位置做聚類取聚類中心作為列分隔點(diǎn)允許一定誤差。from sklearn.cluster import KMeans import numpy as np def cluster_columns(lines, n_cols): all_positions [] for line in lines: positions [i for i, c in enumerate(line) if c ] all_positions.extend(positions) if not all_positions: return [] X np.array(all_positions).reshape(-1, 1) kmeans KMeans(n_clustersn_cols-1, n_init10).fit(X) return sorted(kmeans.cluster_centers_.flatten().astype(int))5.3 大批量導(dǎo)入的性能瓶頸定位當(dāng)導(dǎo)入速度慢到無法接受時(shí)需要定位瓶頸在哪。我用分段計(jì)時(shí)的方法在接入、識(shí)別、轉(zhuǎn)換、切塊、向量化每個(gè)階段打時(shí)間戳統(tǒng)計(jì)各階段耗時(shí)占比。常見的瓶頸和優(yōu)化手段瓶頸階段典型癥狀優(yōu)化手段文件讀取IO 等待高用 SSD、批量讀取、異步 IO編碼檢測CPU 占用高采樣檢測、緩存檢測結(jié)果Markdown 解析單核跑滿多進(jìn)程并行、換更快的解析器向量化網(wǎng)絡(luò)等待高批量請(qǐng)求、異步并發(fā)、本地模型向量庫寫入寫入慢批量 upsert、調(diào)整索引參數(shù)我遇到過一次典型的性能問題導(dǎo)入 10 萬個(gè)文件耗時(shí) 8 小時(shí)分段計(jì)時(shí)后發(fā)現(xiàn) 70% 時(shí)間花在向量化 API 調(diào)用上。優(yōu)化方案是把單條請(qǐng)求改成批量請(qǐng)求每批 100 條耗時(shí)直接降到 1.5 小時(shí)。后來又發(fā)現(xiàn)向量庫的索引構(gòu)建是瓶頸調(diào)整了 HNSW 的參數(shù)后進(jìn)一步降到 40 分鐘。提示性能優(yōu)化要先測量再優(yōu)化不要憑感覺。我見過有人一上來就上多進(jìn)程結(jié)果發(fā)現(xiàn)瓶頸在數(shù)據(jù)庫寫入多進(jìn)程反而因?yàn)殒i競爭更慢了。5.4 導(dǎo)入后檢索效果不佳的歸因方法導(dǎo)入完成后檢索效果不好問題可能出在導(dǎo)入階段也可能出在檢索階段。需要系統(tǒng)歸因。第一步檢查召回內(nèi)容。把檢索到的原始?jí)K打印出來看內(nèi)容是否相關(guān)。如果不相關(guān)問題在檢索階段Embedding 模型或索引參數(shù)如果相關(guān)但生成的答案不好問題在生成階段Prompt 或模型。第二步檢查塊質(zhì)量。如果召回的塊內(nèi)容相關(guān)但語義不完整比如一句話被切斷了問題在切塊策略。調(diào)整max_chunk_size和重疊窗口。第三步檢查元數(shù)據(jù)。如果檢索時(shí)無法按來源過濾或者無法按標(biāo)題層級(jí)過濾問題在元數(shù)據(jù)提取。補(bǔ)充缺失的元數(shù)據(jù)字段。第四步檢查覆蓋率。如果某些文檔的內(nèi)容完全檢索不到可能是這些文檔在導(dǎo)入時(shí)被跳過了或者切塊后塊太小被過濾了。檢查導(dǎo)入日志和塊長度分布。我總結(jié)了一個(gè)歸因速查表現(xiàn)象可能原因排查方向召回內(nèi)容不相關(guān)Embedding 質(zhì)量差換模型、微調(diào)召回內(nèi)容相關(guān)但答案差塊語義不完整調(diào)整切塊策略部分文檔檢索不到導(dǎo)入遺漏或塊太小檢查導(dǎo)入日志無法按來源過濾元數(shù)據(jù)缺失補(bǔ)充元數(shù)據(jù)重復(fù)召回同一內(nèi)容重疊窗口過大減小重疊比例長文檔檢索效果差塊太大主題混雜減小 max_chunk_size這套歸因方法我用了很多次基本能在半小時(shí)內(nèi)定位到問題所在。關(guān)鍵是要有完整的日志和可觀測性否則就是盲人摸象。6. 工程化落地的經(jīng)驗(yàn)沉淀6.1 配置化與可擴(kuò)展的管線設(shè)計(jì)數(shù)據(jù)導(dǎo)入管線最忌諱寫死。不同數(shù)據(jù)源、不同文檔類型、不同業(yè)務(wù)場景需求差異很大。我的做法是把所有可變部分做成配置。配置分三層全局配置定義默認(rèn)參數(shù)比如max_chunk_size、overlap_ratio、encoding_fallback數(shù)據(jù)源配置針對(duì)特定來源覆蓋參數(shù)比如某個(gè)目錄下的文件都是 GBK 編碼就單獨(dú)配置文件級(jí)配置針對(duì)特殊文件做定制比如某個(gè) PDF 需要特殊的版面分析參數(shù)。global: max_chunk_size: 400 min_chunk_size: 100 overlap_ratio: 0.15 encoding_fallback: [utf-8, gbk, gb18030] sources: - path: /data/tech_docs encoding: utf-8 chunk_size: 500 - path: /data/legacy_txt encoding: gbk chunk_size: 300可擴(kuò)展性體現(xiàn)在轉(zhuǎn)換器的插件化。每個(gè)轉(zhuǎn)換器實(shí)現(xiàn)統(tǒng)一的接口can_handle(file) - bool和convert(file) - Markdown。新增一種格式只需要加一個(gè)轉(zhuǎn)換器不用改主流程。6.2 導(dǎo)入日志與可觀測性建設(shè)沒有日志的導(dǎo)入管線就是黑盒。我要求日志至少記錄這些信息每個(gè)文件的處理狀態(tài)成功/失敗/跳過、耗時(shí)、字符數(shù)、塊數(shù)、編碼、格式、錯(cuò)誤信息。這些日志匯總后可以生成報(bào)表一眼看出導(dǎo)入健康度。import logging import json logger logging.getLogger(rag_import) def log_import(file_path, status, duration, char_count, chunk_count, errorNone): record { file: file_path, status: status, duration_ms: duration, chars: char_count, chunks: chunk_count, error: str(error) if error else None } logger.info(json.dumps(record, ensure_asciiFalse))日志用 JSON 格式方便后續(xù)用 ELK 或類似工具做聚合分析。關(guān)鍵指標(biāo)包括成功率、平均耗時(shí)、平均塊大小、編碼分布、格式分布。這些指標(biāo)做成儀表盤導(dǎo)入異常時(shí)能第一時(shí)間發(fā)現(xiàn)。6.3 增量更新與版本管理策略生產(chǎn)環(huán)境的文檔是不斷更新的全量重跑不現(xiàn)實(shí)。增量更新需要解決兩個(gè)問題識(shí)別變更和處理刪除。識(shí)別變更用文件哈希加修改時(shí)間雙重判斷。哈希變了說明內(nèi)容變了修改時(shí)間變了但哈希沒變說明只是 touch 了一下不需要重新處理。處理刪除稍微復(fù)雜。如果源文件被刪了對(duì)應(yīng)的向量也應(yīng)該刪掉。我的做法是維護(hù)一個(gè)文件到塊 ID 的映射表文件刪除時(shí)根據(jù)映射表刪除對(duì)應(yīng)的向量。但要注意如果多個(gè)文件的內(nèi)容有重疊刪除一個(gè)文件不應(yīng)該影響另一個(gè)文件的檢索結(jié)果。所以映射表要精確到塊級(jí)別。版本管理方面我建議保留最近 N 個(gè)版本的塊檢索時(shí)默認(rèn)只搜最新版本但支持按版本過濾。這樣既能保證檢索到最新內(nèi)容又能在需要時(shí)回溯歷史。6.4 從單機(jī)腳本到生產(chǎn)服務(wù)的演進(jìn)路徑很多 RAG 項(xiàng)目都是從單機(jī)腳本開始的一個(gè) Python 文件跑完全流程。但隨著數(shù)據(jù)量增長和需求復(fù)雜化必須演進(jìn)到生產(chǎn)服務(wù)。第一階段單機(jī)腳本。適合 POC 和小數(shù)據(jù)量特點(diǎn)是簡單直接缺點(diǎn)是沒法并行、沒法監(jiān)控、沒法增量。第二階段模塊化管線。把接入、解析、切塊、向量化拆成獨(dú)立模塊用消息隊(duì)列串聯(lián)。每個(gè)模塊可以獨(dú)立擴(kuò)展和部署。這個(gè)階段解決了并行和增量問題。第三階段服務(wù)化。把管線封裝成 API 服務(wù)支持按需觸發(fā)和定時(shí)調(diào)度。加上任務(wù)隊(duì)列、重試機(jī)制、監(jiān)控告警。這個(gè)階段解決了運(yùn)維和可觀測性問題。第四階段平臺(tái)化。提供 Web 界面配置數(shù)據(jù)源和參數(shù)支持多租戶支持 A/B 測試不同的切塊策略。這個(gè)階段適合有多團(tuán)隊(duì)協(xié)作的大型組織。我個(gè)人的建議是不要過度設(shè)計(jì)。大部分項(xiàng)目到第二階段就夠了第三階段按需演進(jìn)。我見過有人一上來就搞平臺(tái)化結(jié)果三個(gè)月沒跑通一個(gè)數(shù)據(jù)源得不償失。6.5 我踩過的那些坑與最終建議最后分享幾個(gè)我實(shí)際踩過的坑都是血淚教訓(xùn)?？右缓雎晕募?quán)限。批量導(dǎo)入時(shí)遇到?jīng)]有讀權(quán)限的文件整個(gè)任務(wù)崩潰。后來加了權(quán)限檢查無權(quán)限的文件跳過并記錄?？佣?hào)鏈接循環(huán)。目錄里有指向父目錄的符號(hào)鏈接遞歸遍歷時(shí)無限循環(huán)。后來加了 inode 去重和最大深度限制。坑三超大文件。一個(gè) 2GB 的日志文件讀進(jìn)內(nèi)存直接 OOM。后來加了文件大小限制超過閾值的文件流式處理或跳過?？铀牟l(fā)寫入沖突。多進(jìn)程同時(shí)寫向量庫導(dǎo)致部分?jǐn)?shù)據(jù)丟失。后來改成單進(jìn)程寫入或者用支持并發(fā)寫的向量庫?？游搴雎詴r(shí)區(qū)。文件修改時(shí)間沒帶時(shí)區(qū)增量更新時(shí)判斷錯(cuò)誤。后來統(tǒng)一用 UTC 時(shí)間戳。這些坑看起來都是小問題但每一個(gè)都可能導(dǎo)致導(dǎo)入失敗或數(shù)據(jù)錯(cuò)誤。我的最終建議是把數(shù)據(jù)導(dǎo)入當(dāng)成一個(gè)正式的數(shù)據(jù)工程項(xiàng)目來做而不是一個(gè)臨時(shí)腳本。投入在導(dǎo)入階段的每一分精力都會(huì)在檢索和生成階段得到回報(bào)。數(shù)據(jù)質(zhì)量是 RAG 系統(tǒng)的地基地基不牢上面蓋什么都是危房。