據(jù)導(dǎo)入實(shí)戰(zhàn)：從txt到Markdown的解析與分塊策略)
1. 為什么 RAG 的第一步不是模型而是數(shù)據(jù)導(dǎo)入很多人一上來(lái)就研究向量庫(kù)選型、Embedding 模型對(duì)比、重排序策略結(jié)果折騰了兩周檢索效果還是稀爛。我踩過(guò)這個(gè)坑之后才徹底想明白一件事RAG 的上限在數(shù)據(jù)導(dǎo)入階段就已經(jīng)被鎖死了。你后面換再貴的模型、調(diào)再細(xì)的參數(shù)都救不回來(lái)一份被切得七零八落的原始文檔。這一篇先聚焦最基礎(chǔ)、也最容易被輕視的一環(huán)——通用文本與結(jié)構(gòu)化文本的導(dǎo)入與解析具體就是從純文本 txt 到 Markdown 這一類“半結(jié)構(gòu)化”文檔的處理。為什么先講這個(gè)因?yàn)榻^大多數(shù)人的知識(shí)庫(kù)素材無(wú)非就是幾類隨手記的 txt 筆記、導(dǎo)出的 Markdown 文檔、從網(wǎng)頁(yè)另存下來(lái)的內(nèi)容、以及各種系統(tǒng)導(dǎo)出的結(jié)構(gòu)化文本。這些格式看起來(lái)簡(jiǎn)單但恰恰是解析環(huán)節(jié)翻車最多的地方。我見過(guò)太多案例一份 300 頁(yè)的產(chǎn)品手冊(cè)用默認(rèn)的字符切分器一切表格被攔腰截?cái)啻a塊被拆成兩半標(biāo)題和正文混在一起最后檢索出來(lái)的片段驢唇不對(duì)馬嘴。用戶問“第三章第二節(jié)講了什么”系統(tǒng)返回的是某個(gè)表格中間的一行數(shù)字。這不是模型的問題是導(dǎo)入解析階段沒有把文檔的結(jié)構(gòu)信息保留下來(lái)。所以這篇內(nèi)容適合誰(shuí)看如果你是剛接觸 RAG、正準(zhǔn)備搭建第一個(gè)知識(shí)庫(kù)的開發(fā)者這篇能幫你避開最基礎(chǔ)的坑如果你已經(jīng)踩過(guò)一些坑、檢索效果不理想這篇能幫你回頭檢查數(shù)據(jù)導(dǎo)入環(huán)節(jié)到底哪里出了問題如果你在做企業(yè)級(jí)知識(shí)管理需要處理大量異構(gòu)文檔這篇提供的思路可以直接套用。核心關(guān)鍵詞就幾個(gè)RAG、數(shù)據(jù)導(dǎo)入、解析、txt、Markdown。我會(huì)圍繞這幾個(gè)詞把從原始文本到可檢索片段的完整鏈路拆開講包括格式識(shí)別、結(jié)構(gòu)提取、分塊策略、元數(shù)據(jù)注入以及每一步背后的取舍邏輯。1.1 先搞清楚RAG 里的“數(shù)據(jù)導(dǎo)入”到底在做什么很多人把數(shù)據(jù)導(dǎo)入理解成“把文件讀進(jìn)來(lái)”這個(gè)認(rèn)知太淺了。在 RAG 的語(yǔ)境下數(shù)據(jù)導(dǎo)入實(shí)際上要完成四件事第一是格式歸一化。你的原始素材可能是 txt、Markdown、HTML、PDF、Word甚至是從數(shù)據(jù)庫(kù)導(dǎo)出的 CSV。這些格式的底層結(jié)構(gòu)完全不同但最終都要變成同一種中間表示通常是帶結(jié)構(gòu)的純文本加上元數(shù)據(jù)。第二是結(jié)構(gòu)提取。文檔里的標(biāo)題層級(jí)、段落邊界、列表、表格、代碼塊、引用塊這些結(jié)構(gòu)信息在后續(xù)檢索時(shí)極其重要。一個(gè)標(biāo)題為“安裝步驟”的片段和一個(gè)正文里隨便一句話檢索權(quán)重應(yīng)該是不一樣的。第三是語(yǔ)義分塊。不能簡(jiǎn)單地按固定字符數(shù)切那樣會(huì)把完整的語(yǔ)義單元切碎。理想的分塊應(yīng)該盡量保證每個(gè)塊是一個(gè)自包含的語(yǔ)義單元同時(shí)控制塊的大小在 Embedding 模型的最佳輸入范圍內(nèi)。第四是元數(shù)據(jù)注入。每個(gè)塊需要攜帶來(lái)源信息來(lái)自哪個(gè)文件、哪個(gè)章節(jié)、第幾頁(yè)、什么時(shí)間導(dǎo)入的。這些元數(shù)據(jù)在檢索過(guò)濾和結(jié)果溯源時(shí)必不可少。這四件事里格式歸一化和結(jié)構(gòu)提取是基礎(chǔ)語(yǔ)義分塊是核心難點(diǎn)元數(shù)據(jù)注入是工程細(xì)節(jié)。下面逐個(gè)拆開講。1.2 為什么從 txt 和 Markdown 講起有人會(huì)問現(xiàn)在 PDF 解析工具那么多為什么不直接從 PDF 開始講原因很簡(jiǎn)單txt 和 Markdown 是理解解析本質(zhì)的最佳切入點(diǎn)。PDF 的解析本質(zhì)上是在做逆向工程——從排版結(jié)果反推邏輯結(jié)構(gòu)這個(gè)過(guò)程充滿了不確定性。而 txt 和 Markdown 不一樣它們的結(jié)構(gòu)信息是顯式存在的。Markdown 的#就是標(biāo)題|就是表格 就是代碼塊。你不需要猜只需要正確識(shí)別。先把這兩種格式吃透建立起“結(jié)構(gòu)感知”的思維習(xí)慣再去處理 PDF 這種“結(jié)構(gòu)隱式”的格式會(huì)順暢很多。而且實(shí)際項(xiàng)目中Markdown 正在成為知識(shí)庫(kù)素材的主流格式——很多文檔工具都支持導(dǎo)出 Markdown很多技術(shù)文檔本身就是用 Markdown 寫的。2. 通用文本與結(jié)構(gòu)化文本的解析核心思路2.1 格式識(shí)別與預(yù)處理別急著讀文件內(nèi)容拿到一個(gè)文件第一件事不是直接讀內(nèi)容而是先判斷它到底是什么格式。這里有個(gè)坑文件擴(kuò)展名不可信。我遇到過(guò).txt文件實(shí)際是 HTML 源碼的也遇到過(guò).md文件里混著大量 HTML 標(biāo)簽的。穩(wěn)妥的做法是做一個(gè)輕量的格式探測(cè)讀取文件前 2KB 內(nèi)容檢查是否有 Markdown 特征#開頭的行、|表格、 代碼塊圍欄檢查是否有 HTML 特征html、div、p等標(biāo)簽檢查是否有 CSV 特征逗號(hào)分隔、制表符分隔、行列數(shù)一致如果都沒有按純文本處理這個(gè)探測(cè)邏輯不需要很復(fù)雜幾十行代碼就能搞定。但就是這幾十行代碼能幫你避免后面大量的解析異常。預(yù)處理階段還有幾件事要做編碼統(tǒng)一。中文文檔常見的編碼有 UTF-8、GBK、GB2312甚至還有 GB18030。如果編碼判斷錯(cuò)了讀出來(lái)全是亂碼。我的做法是先用chardet之類的庫(kù)探測(cè)編碼然后用探測(cè)到的編碼讀取讀完之后統(tǒng)一轉(zhuǎn)成 UTF-8。如果探測(cè)置信度低于某個(gè)閾值就嘗試用 UTF-8 讀取失敗再回退到 GBK。換行符統(tǒng)一。Windows 的\r\n、Unix 的\n、老 Mac 的\r這三種換行符混在一起會(huì)讓后續(xù)的分行邏輯出錯(cuò)。統(tǒng)一替換成\n是標(biāo)準(zhǔn)操作?？瞻鬃址謇?。連續(xù)多個(gè)空行、行尾多余空格、制表符和空格混用這些都會(huì)影響結(jié)構(gòu)識(shí)別的準(zhǔn)確性。但注意不要過(guò)度清理比如 Markdown 里行尾兩個(gè)空格表示換行這個(gè)不能刪。提示預(yù)處理階段的所有操作都應(yīng)該是可逆的或者有日志記錄的。一旦發(fā)現(xiàn)解析結(jié)果異常你需要能回溯到原始內(nèi)容判斷是預(yù)處理引入的問題還是解析邏輯本身的問題。2.2 結(jié)構(gòu)提取把文檔的“骨架”抽出來(lái)結(jié)構(gòu)提取的目標(biāo)是回答一個(gè)問題這份文檔的層級(jí)關(guān)系是什么。對(duì)于 Markdown結(jié)構(gòu)是顯式的。#到######對(duì)應(yīng)六級(jí)標(biāo)題標(biāo)題之間的內(nèi)容屬于該標(biāo)題的章節(jié)。解析時(shí)可以用一個(gè)棧來(lái)維護(hù)當(dāng)前的標(biāo)題路徑。比如遇到## 第二章棧變成[第二章]再遇到### 2.1 節(jié)棧變成[第二章, 2.1 節(jié)]。每個(gè)內(nèi)容塊都記錄它所屬的完整標(biāo)題路徑。對(duì)于純文本結(jié)構(gòu)是隱式的但通常有規(guī)律可循。常見的模式包括用數(shù)字編號(hào)的行如1.、1.1、第一章用特殊符號(hào)裝飾的行如、-----、*****全行加粗或全行大寫的行縮進(jìn)層級(jí)變化我一般會(huì)寫一組正則規(guī)則來(lái)識(shí)別這些模式按優(yōu)先級(jí)依次匹配。匹配到的行標(biāo)記為“疑似標(biāo)題”然后根據(jù)編號(hào)的層級(jí)關(guān)系推斷標(biāo)題級(jí)別。比如1.是一級(jí)1.1是二級(jí)1.1.1是三級(jí)。這里有個(gè)經(jīng)驗(yàn)不要追求 100% 的標(biāo)題識(shí)別準(zhǔn)確率。實(shí)際文檔里總有一些奇怪的格式強(qiáng)行識(shí)別反而會(huì)引入噪聲。我的做法是設(shè)置一個(gè)置信度閾值高置信度的直接標(biāo)記為標(biāo)題低置信度的保留為普通段落但在元數(shù)據(jù)里標(biāo)注“疑似標(biāo)題”。后續(xù)檢索時(shí)可以根據(jù)需要決定是否利用這個(gè)信息。表格的提取是另一個(gè)重點(diǎn)。Markdown 表格用|分隔解析相對(duì)簡(jiǎn)單。純文本表格就麻煩了可能是空格對(duì)齊、制表符對(duì)齊、或者用---畫邊框。我的建議是能識(shí)別就識(shí)別識(shí)別不了就整塊保留。千萬(wàn)不要把表格拆成一行一行的文本那樣表格的語(yǔ)義就徹底丟了。代碼塊的識(shí)別相對(duì)簡(jiǎn)單Markdown 用 圍欄純文本通?？靠s進(jìn)或者前后空行判斷。代碼塊在分塊時(shí)應(yīng)該作為一個(gè)整體不要從中間切開。2.3 分塊策略RAG 效果的分水嶺分塊是數(shù)據(jù)導(dǎo)入階段最核心的決策沒有之一。分塊策略直接決定了檢索質(zhì)量的上限。先說(shuō)一個(gè)反直覺的結(jié)論固定長(zhǎng)度分塊幾乎總是錯(cuò)的。很多人圖省事直接按 500 字符切重疊 50 字符。這種做法在簡(jiǎn)單場(chǎng)景下能用但只要文檔有結(jié)構(gòu)就會(huì)出問題。一個(gè)完整的操作步驟被切成兩半前半段說(shuō)“點(diǎn)擊設(shè)置按鈕”后半段說(shuō)“在彈出窗口中選擇高級(jí)選項(xiàng)”檢索時(shí)只召回前半段用戶根本不知道下一步該干什么。我的分塊策略是結(jié)構(gòu)感知的遞歸分塊具體邏輯如下第一優(yōu)先級(jí)是按結(jié)構(gòu)邊界切分。標(biāo)題、章節(jié)、列表項(xiàng)、表格、代碼塊這些都是天然的邊界。一個(gè)章節(jié)的內(nèi)容如果不超過(guò)最大塊大小就整塊作為一個(gè) chunk。如果超過(guò)再往下切。第二優(yōu)先級(jí)是按語(yǔ)義邊界切分。段落是最小的語(yǔ)義單元盡量保證一個(gè)段落不被切開。如果單個(gè)段落就超過(guò)了最大塊大小比如一段超長(zhǎng)的法律條款那就只能按句子切。第三優(yōu)先級(jí)才是按長(zhǎng)度切分。當(dāng)以上邊界都不存在時(shí)才退回到按字符數(shù)切分并且盡量在句子結(jié)束符處斷開。塊大小的選擇需要根據(jù) Embedding 模型來(lái)定。大多數(shù)中文 Embedding 模型的最佳輸入長(zhǎng)度在 256 到 512 個(gè) token 之間。我的經(jīng)驗(yàn)值是目標(biāo)塊大小 400 到 600 字符最大不超過(guò) 800 字符塊之間重疊 10% 到 15%。重疊的目的是防止邊界處的信息丟失但重疊太多會(huì)導(dǎo)致檢索結(jié)果冗余。這里有個(gè)細(xì)節(jié)不同結(jié)構(gòu)的塊應(yīng)該有不同的目標(biāo)大小。表格和代碼塊可以大一些因?yàn)樗鼈兊恼Z(yǔ)義密度高切碎了反而不好。普通敘述性段落可以小一些因?yàn)檎Z(yǔ)義密度低塊太大反而稀釋了關(guān)鍵信息。2.4 元數(shù)據(jù)設(shè)計(jì)讓每個(gè)塊都能“自報(bào)家門”元數(shù)據(jù)在檢索階段的價(jià)值經(jīng)常被低估。一個(gè)好的元數(shù)據(jù)設(shè)計(jì)能讓檢索效果提升一個(gè)檔次。每個(gè) chunk 至少應(yīng)該攜帶以下元數(shù)據(jù)元數(shù)據(jù)字段說(shuō)明用途source_file來(lái)源文件名結(jié)果溯源、按文件過(guò)濾file_type文件類型按類型過(guò)濾、調(diào)試heading_path標(biāo)題路徑結(jié)果展示、按章節(jié)過(guò)濾chunk_index塊序號(hào)排序、去重char_count字符數(shù)質(zhì)量監(jiān)控has_table是否含表格特殊處理標(biāo)記has_code是否含代碼特殊處理標(biāo)記import_time導(dǎo)入時(shí)間增量更新標(biāo)題路徑heading_path是我認(rèn)為最有價(jià)值的元數(shù)據(jù)。它記錄了當(dāng)前塊所屬的完整章節(jié)路徑比如[第三章 安裝部署, 3.2 環(huán)境配置, 3.2.1 依賴安裝]。在檢索結(jié)果展示時(shí)把這個(gè)路徑顯示出來(lái)用戶一眼就能知道這個(gè)片段來(lái)自哪里信任度會(huì)高很多。而且在檢索時(shí)可以利用標(biāo)題路徑做上下文增強(qiáng)。比如用戶問“依賴安裝有哪些步驟”檢索到的塊標(biāo)題路徑里包含“依賴安裝”這個(gè)塊的權(quán)重就應(yīng)該提高。這種基于結(jié)構(gòu)的加權(quán)比單純依賴向量相似度要可靠得多。3. 從 txt 到 Markdown 的完整實(shí)操流程3.1 環(huán)境準(zhǔn)備與依賴選擇我用的技術(shù)棧是 Python核心依賴就幾個(gè)pip install chardet markdown-it-py beautifulsoup4 lxmlchardet編碼探測(cè)處理中文文檔必備markdown-it-pyMarkdown 解析比正則更可靠beautifulsoup4lxml處理混入的 HTML 內(nèi)容如果你不想引入太多依賴純文本處理用標(biāo)準(zhǔn)庫(kù)就夠了。但 Markdown 解析我強(qiáng)烈建議用專門的庫(kù)自己寫正則處理嵌套結(jié)構(gòu)會(huì)瘋掉。3.2 第一步文件讀取與編碼歸一化import chardet def read_file_safely(file_path): with open(file_path, rb) as f: raw f.read() # 探測(cè)編碼 detected chardet.detect(raw[:10000]) encoding detected[encoding] confidence detected[confidence] # 置信度低時(shí)回退 if confidence 0.7 or encoding is None: encoding utf-8 try: text raw.decode(encoding) except UnicodeDecodeError: # 回退鏈 for fallback in [utf-8, gbk, gb18030, latin-1]: try: text raw.decode(fallback) break except UnicodeDecodeError: continue else: text raw.decode(utf-8, errorsreplace) # 換行符統(tǒng)一 text text.replace(\r\n, \n).replace(\r, \n) return text這段代碼的關(guān)鍵在于回退鏈。中文文檔的編碼情況很復(fù)雜單一探測(cè)不一定準(zhǔn)。我實(shí)測(cè)下來(lái)chardet對(duì) UTF-8 和 GBK 的區(qū)分準(zhǔn)確率大概在 85% 左右剩下的 15% 就得靠回退鏈兜底。注意latin-1放在回退鏈最后是有原因的。它能解碼任何字節(jié)序列永遠(yuǎn)不會(huì)拋異常但解出來(lái)的可能是亂碼。所以它只是最后的保底不能作為首選。3.3 第二步格式探測(cè)與路由import re def detect_format(text): sample text[:2000] # Markdown 特征 md_patterns [ r^#{1,6}\s, # 標(biāo)題 r^\|.*\|$, # 表格 r^, # 代碼塊 r^\s*[-*]\s, # 無(wú)序列表 r^\s*\d\.\s, # 有序列表 ] md_score sum(1 for p in md_patterns if re.search(p, sample, re.MULTILINE)) # HTML 特征 html_score len(re.findall(r[a-z][^]*, sample)) # CSV 特征 lines sample.split(\n)[:10] csv_score 0 if len(lines) 1: comma_counts [line.count(,) for line in lines if line.strip()] if comma_counts and len(set(comma_counts)) 1 and comma_counts[0] 0: csv_score 3 if md_score 2: return markdown elif html_score 5: return html elif csv_score 3: return csv else: return plaintext這個(gè)探測(cè)邏輯的核心思想是多特征投票而不是單一特征判斷。因?yàn)閷?shí)際文檔里經(jīng)常出現(xiàn)混合情況比如 Markdown 里嵌了 HTML純文本里用了#做注釋。多特征投票能降低誤判率。3.4 第三步Markdown 結(jié)構(gòu)解析用markdown-it-py把 Markdown 解析成 token 流然后遍歷 token 構(gòu)建結(jié)構(gòu)樹from markdown_it import MarkdownIt def parse_markdown_structure(text): md MarkdownIt() tokens md.parse(text) structure [] heading_stack [] current_content [] for token in tokens: if token.type heading_open: # 保存之前的內(nèi)容 if current_content: structure.append({ type: content, heading_path: list(heading_stack), text: \n.join(current_content) }) current_content [] level int(token.tag[1]) # h1 - 1 # 維護(hù)標(biāo)題棧 while heading_stack and heading_stack[-1][0] level: heading_stack.pop() heading_stack.append((level, )) elif token.type inline and heading_stack and heading_stack[-1][1] : # 標(biāo)題文本 heading_stack[-1] (heading_stack[-1][0], token.content) elif token.type in (fence, code_block): current_content.append(f\n{token.content}\n) elif token.type table_open: # 表格單獨(dú)處理 pass elif token.type inline: current_content.append(token.content) # 處理最后一段 if current_content: structure.append({ type: content, heading_path: [h[1] for h in heading_stack], text: \n.join(current_content) }) return structure這段代碼的核心是標(biāo)題棧。棧里維護(hù)的是當(dāng)前所處的標(biāo)題路徑遇到新標(biāo)題時(shí)根據(jù)級(jí)別彈出舊標(biāo)題、壓入新標(biāo)題。每個(gè)內(nèi)容塊都記錄它被解析時(shí)的標(biāo)題路徑。實(shí)際使用中還需要處理表格和代碼塊的完整提取。markdown-it-py的 token 流里表格會(huì)被拆成table_open、tr_open、td_open等一系列 token需要專門寫邏輯把它們重新組裝成結(jié)構(gòu)化的表格數(shù)據(jù)。3.5 第四步純文本結(jié)構(gòu)推斷純文本沒有顯式結(jié)構(gòu)需要靠正則和啟發(fā)式規(guī)則推斷def infer_plaintext_structure(text): lines text.split(\n) blocks [] current_block [] current_heading None # 標(biāo)題識(shí)別規(guī)則按優(yōu)先級(jí)排列 heading_patterns [ (r^第[一二三四五六七八九十][章節(jié)篇]\s*, 1), (r^\d\.\d\.\d\s, 3), (r^\d\.\d\s, 2), (r^\d\.\s, 1), (r^[一二三四五六七八九十][、.]\s*, 2), (r^{3,}$, 0), # 下劃線裝飾標(biāo)記上一行為標(biāo)題 (r^-{3,}$, 0), ] for i, line in enumerate(lines): stripped line.strip() # 空行作為塊邊界 if not stripped: if current_block: blocks.append({ type: content, heading: current_heading, text: \n.join(current_block) }) current_block [] continue # 檢查是否是標(biāo)題 is_heading False for pattern, level in heading_patterns: if re.match(pattern, stripped): if level 0: # 裝飾線把上一行提升為標(biāo)題 if current_block: current_heading current_block.pop() else: # 保存之前的內(nèi)容 if current_block: blocks.append({ type: content, heading: current_heading, text: \n.join(current_block) }) current_block [] current_heading stripped is_heading True break if not is_heading: current_block.append(line) # 收尾 if current_block: blocks.append({ type: content, heading: current_heading, text: \n.join(current_block) }) return blocks這套規(guī)則不是萬(wàn)能的但覆蓋了中文技術(shù)文檔里 80% 以上的標(biāo)題格式。剩下的 20% 需要根據(jù)具體文檔類型定制規(guī)則。實(shí)操心得我一般會(huì)先拿幾份典型文檔跑一遍把識(shí)別錯(cuò)誤的標(biāo)題打印出來(lái)針對(duì)性調(diào)整正則。這個(gè)過(guò)程通常需要迭代兩三輪但一旦調(diào)好后續(xù)同類文檔都能復(fù)用。3.6 第五步結(jié)構(gòu)感知的分塊有了結(jié)構(gòu)樹之后分塊就變成了一個(gè)遞歸過(guò)程def chunk_by_structure(blocks, max_size600, min_size100, overlap80): chunks [] for block in blocks: text block[text] heading block.get(heading, ) # 塊本身不超過(guò)限制直接作為一個(gè) chunk if len(text) max_size: if len(text) min_size: chunks.append({ text: text, heading: heading, char_count: len(text) }) continue # 超長(zhǎng)塊按段落切分 paragraphs text.split(\n\n) current [] current_len 0 for para in paragraphs: para_len len(para) if current_len para_len max_size and current: chunk_text \n\n.join(current) chunks.append({ text: chunk_text, heading: heading, char_count: len(chunk_text) }) # 保留重疊部分 overlap_text chunk_text[-overlap:] if len(chunk_text) overlap else chunk_text current [overlap_text, para] current_len len(overlap_text) para_len else: current.append(para) current_len para_len if current: chunk_text \n\n.join(current) chunks.append({ text: chunk_text, heading: heading, char_count: len(chunk_text) }) return chunks這里有幾個(gè)關(guān)鍵決策點(diǎn)為什么最小塊大小是 100 字符太小的塊語(yǔ)義不完整Embedding 出來(lái)的向量質(zhì)量差檢索時(shí)容易誤召回。100 字符大約是一到兩句話是語(yǔ)義完整性的下限。為什么重疊是 80 字符這是經(jīng)驗(yàn)值。重疊太少起不到防止邊界信息丟失的作用重疊太多會(huì)導(dǎo)致檢索結(jié)果大量重復(fù)。80 字符大約是一句話的長(zhǎng)度能保證邊界處的語(yǔ)義連續(xù)性。表格和代碼塊怎么處理它們不應(yīng)該參與常規(guī)分塊。表格應(yīng)該整體保留如果太大就按行切分但保留表頭。代碼塊應(yīng)該整體保留如果太大就按函數(shù)或邏輯塊切分。3.7 第六步元數(shù)據(jù)注入與輸出最后一步是把分塊結(jié)果和元數(shù)據(jù)組裝起來(lái)輸出成后續(xù)流程能消費(fèi)的格式import json from datetime import datetime def build_chunks_with_metadata(chunks, source_file, file_type): result [] for i, chunk in enumerate(chunks): result.append({ id: f{source_file}_{i}, text: chunk[text], metadata: { source_file: source_file, file_type: file_type, heading: chunk.get(heading, ), chunk_index: i, char_count: chunk[char_count], has_table: | in chunk[text] and --- in chunk[text], has_code: in chunk[text], import_time: datetime.now().isoformat() } }) return result輸出格式我推薦 JSON Lines每行一個(gè) chunk。這樣便于流式處理也便于后續(xù)增量更新時(shí)按行追加。4. 常見問題與排查技巧實(shí)錄4.1 編碼問題排查速查表現(xiàn)象可能原因排查方法解決方案中文全是亂碼編碼判斷錯(cuò)誤用十六進(jìn)制查看器看字節(jié)嘗試 GBK/GB18030部分字符亂碼混合編碼分段探測(cè)編碼分段解碼后拼接問號(hào)替代中文解碼時(shí) errorsreplace檢查原始字節(jié)換正確編碼重新解碼換行符異?；旌蠐Q行符統(tǒng)計(jì) \r\n 和 \n 數(shù)量統(tǒng)一替換編碼問題我踩過(guò)最坑的一次是一份文檔前半部分是 UTF-8后半部分是 GBK。chardet探測(cè)出來(lái)是 UTF-8結(jié)果后半部分全亂碼。后來(lái)我的做法是分段探測(cè)每 10KB 探測(cè)一次如果發(fā)現(xiàn)編碼不一致就分段解碼。4.2 結(jié)構(gòu)識(shí)別失敗的典型場(chǎng)景場(chǎng)景一標(biāo)題沒有編號(hào)。有些文檔的標(biāo)題就是加粗的一行文字沒有任何編號(hào)。這種情況純文本推斷很難識(shí)別。我的做法是結(jié)合行長(zhǎng)和上下文空行來(lái)判斷如果一行文字長(zhǎng)度小于 30 字符前后都有空行且不以標(biāo)點(diǎn)結(jié)尾就標(biāo)記為疑似標(biāo)題。場(chǎng)景二列表嵌套過(guò)深。Markdown 的嵌套列表用縮進(jìn)表示但縮進(jìn)可能是 2 空格、4 空格、或者 Tab。解析時(shí)需要統(tǒng)一縮進(jìn)單位。我的做法是統(tǒng)計(jì)所有縮進(jìn)取最小公約數(shù)作為一級(jí)縮進(jìn)單位。場(chǎng)景三表格跨頁(yè)。從 PDF 轉(zhuǎn)出來(lái)的文本表格經(jīng)常被分頁(yè)符打斷。這種情況需要在預(yù)處理階段識(shí)別分頁(yè)符嘗試把跨頁(yè)的表格拼接起來(lái)。拼接邏輯是如果上一頁(yè)末尾是表格行下一頁(yè)開頭也是表格行且列數(shù)一致就嘗試合并。4.3 分塊質(zhì)量的快速驗(yàn)證方法分塊做完之后怎么知道分得好不好我一般用三個(gè)快速檢查檢查一隨機(jī)抽樣 20 個(gè) chunk人工閱讀。看每個(gè) chunk 是否語(yǔ)義完整是否包含足夠的上下文。如果發(fā)現(xiàn)大量 chunk 以半句話開頭或結(jié)尾說(shuō)明分塊邊界有問題。檢查二統(tǒng)計(jì) chunk 大小分布。畫個(gè)直方圖看是否集中在目標(biāo)大小附近。如果出現(xiàn)大量極小 chunk小于 50 字符或極大 chunk大于 1000 字符說(shuō)明分塊邏輯有漏洞。檢查三做一輪檢索測(cè)試。準(zhǔn)備 10 個(gè)典型問題看檢索結(jié)果是否相關(guān)。如果檢索結(jié)果經(jīng)常是表格中間的一行、或者代碼塊的片段說(shuō)明結(jié)構(gòu)處理有問題。實(shí)操心得我習(xí)慣在分塊完成后把 chunk 列表導(dǎo)出成 Markdown 文件用編輯器打開快速瀏覽。肉眼掃一遍比看統(tǒng)計(jì)數(shù)字更容易發(fā)現(xiàn)異常。4.4 性能優(yōu)化的幾個(gè)實(shí)用技巧數(shù)據(jù)導(dǎo)入階段如果處理大量文檔性能會(huì)成為瓶頸。幾個(gè)我實(shí)測(cè)有效的優(yōu)化批量讀取。不要一個(gè)文件一個(gè)文件地讀用concurrent.futures做并發(fā)讀取。IO 密集型任務(wù)并發(fā)能帶來(lái)數(shù)倍提升。惰性解析。如果文檔很大不要一次性全部解析成 token 流。markdown-it-py支持流式解析可以邊解析邊處理。緩存中間結(jié)果。結(jié)構(gòu)解析的結(jié)果可以緩存起來(lái)后續(xù)調(diào)整分塊參數(shù)時(shí)不需要重新解析。我用pickle把結(jié)構(gòu)樹緩存到本地調(diào)試分塊邏輯時(shí)能省大量時(shí)間。正則預(yù)編譯。所有正則表達(dá)式在模塊加載時(shí)就編譯好不要每次調(diào)用時(shí)重新編譯。這個(gè)優(yōu)化在小文檔上不明顯但處理上萬(wàn)份文檔時(shí)差距很大。5. 從導(dǎo)入到檢索的銜接要點(diǎn)5.1 導(dǎo)入結(jié)果如何影響檢索策略數(shù)據(jù)導(dǎo)入階段產(chǎn)出的 chunk 和元數(shù)據(jù)直接決定了檢索階段能做什么。如果 chunk 攜帶了heading元數(shù)據(jù)檢索時(shí)就可以做基于標(biāo)題的加權(quán)。具體做法是計(jì)算 query 和 chunk 標(biāo)題的相似度把這個(gè)相似度作為一個(gè)加權(quán)因子和向量相似度做加權(quán)求和。我實(shí)測(cè)下來(lái)這個(gè)加權(quán)能讓檢索準(zhǔn)確率提升 10% 到 15%。如果 chunk 標(biāo)記了has_table和has_code檢索時(shí)就可以做類型感知的展示。表格類結(jié)果用表格渲染代碼類結(jié)果用代碼塊渲染用戶體驗(yàn)會(huì)好很多。如果 chunk 記錄了source_file和chunk_index檢索時(shí)就可以做上下文擴(kuò)展。召回一個(gè) chunk 后把它的前后相鄰 chunk 也取出來(lái)拼成更完整的上下文。這個(gè)技巧對(duì)回答“步驟類”問題特別有效。5.2 增量導(dǎo)入的設(shè)計(jì)考慮實(shí)際項(xiàng)目中知識(shí)庫(kù)是持續(xù)更新的。增量導(dǎo)入的設(shè)計(jì)要點(diǎn)文件指紋。對(duì)每個(gè)文件計(jì)算 MD5 或 SHA256導(dǎo)入前先比對(duì)指紋。指紋沒變就跳過(guò)變了就重新導(dǎo)入。版本管理。每次導(dǎo)入生成一個(gè)版本號(hào)chunk 的 ID 里包含版本信息。這樣檢索時(shí)可以指定只檢索最新版本或者做版本對(duì)比。刪除處理。文件被刪除時(shí)對(duì)應(yīng)的 chunk 也要標(biāo)記刪除。不要物理刪除而是打上deleted標(biāo)記檢索時(shí)過(guò)濾掉。這樣萬(wàn)一誤刪還能恢復(fù)。5.3 質(zhì)量監(jiān)控指標(biāo)導(dǎo)入流程上線后需要持續(xù)監(jiān)控幾個(gè)指標(biāo)指標(biāo)含義健康范圍平均 chunk 大小所有 chunk 的字符數(shù)均值300-600極小 chunk 占比小于 50 字符的 chunk 比例 5%極大 chunk 占比大于 1000 字符的 chunk 比例 3%編碼異常率解碼時(shí)使用回退鏈的比例 2%結(jié)構(gòu)識(shí)別率成功識(shí)別標(biāo)題的文檔比例 80%這些指標(biāo)異常時(shí)說(shuō)明導(dǎo)入流程的某個(gè)環(huán)節(jié)出了問題需要回頭排查。6. 一些踩坑之后的個(gè)人體會(huì)做 RAG 數(shù)據(jù)導(dǎo)入這一年多最大的體會(huì)是慢就是快。剛開始我總想快點(diǎn)把數(shù)據(jù)灌進(jìn)去結(jié)果檢索效果差回頭返工的時(shí)間遠(yuǎn)超當(dāng)初省下的時(shí)間。后來(lái)我養(yǎng)成了一個(gè)習(xí)慣每接入一種新格式的文檔先拿 5 到 10 份樣本做小規(guī)模測(cè)試把解析結(jié)果人工過(guò)一遍確認(rèn)沒問題了再批量導(dǎo)入。另一個(gè)體會(huì)是不要迷信自動(dòng)化。結(jié)構(gòu)識(shí)別、分塊這些環(huán)節(jié)純靠算法很難做到 100% 準(zhǔn)確。我的做法是提供一個(gè)“人工校正”的接口對(duì)于識(shí)別異常的文檔允許手動(dòng)調(diào)整結(jié)構(gòu)標(biāo)記。這個(gè)接口看起來(lái)增加了工作量但實(shí)際上大幅提升了最終質(zhì)量。還有一個(gè)細(xì)節(jié)保留原始文本。不管怎么預(yù)處理、怎么分塊原始文本一定要完整保留。我見過(guò)太多案例預(yù)處理時(shí)做了不可逆的清洗后來(lái)發(fā)現(xiàn)清洗掉了關(guān)鍵信息想恢復(fù)都恢復(fù)不了。我的做法是原始文本單獨(dú)存一份所有處理都是基于副本進(jìn)行的。最后分享一個(gè)小技巧用檢索測(cè)試反推導(dǎo)入質(zhì)量。準(zhǔn)備一組典型問題每次調(diào)整導(dǎo)入?yún)?shù)后跑一遍檢索測(cè)試看召回結(jié)果的變化。這比看統(tǒng)計(jì)指標(biāo)更直觀也更能發(fā)現(xiàn)實(shí)際問題。我一般會(huì)維護(hù)一個(gè) 50 題左右的測(cè)試集覆蓋事實(shí)查詢、步驟查詢、對(duì)比查詢等不同類型每次調(diào)整參數(shù)后都跑一遍記錄準(zhǔn)確率變化。這個(gè)內(nèi)容后續(xù)還可以這樣擴(kuò)展把 PDF、Word、HTML 這些格式的解析也納入進(jìn)來(lái)形成一套完整的異構(gòu)文檔導(dǎo)入方案。另外表格和圖片的專項(xiàng)處理也值得單獨(dú)展開特別是表格的結(jié)構(gòu)化提取和圖片的 OCR 處理都是實(shí)際項(xiàng)目中繞不開的環(huán)節(jié)。 RAG數(shù)據(jù)導(dǎo)入實(shí)戰(zhàn)：從txt到Markdown的解析與分塊策略
1. 為什么 RAG 的第一步不是模型而是數(shù)據(jù)導(dǎo)入很多人一上來(lái)就研究向量庫(kù)選型、Embedding 模型對(duì)比、重排序策略結(jié)果折騰了兩周檢索效果還是稀爛。我踩過(guò)這個(gè)坑之后才徹底想明白一件事RAG 的上限在數(shù)據(jù)導(dǎo)入階段就已經(jīng)被鎖死了。你后面換再貴的模型、調(diào)再細(xì)的參數(shù)都救不回來(lái)一份被切得七零八落的原始文檔。這一篇先聚焦最基礎(chǔ)、也最容易被輕視的一環(huán)——通用文本與結(jié)構(gòu)化文本的導(dǎo)入與解析具體就是從純文本 txt 到 Markdown 這一類“半結(jié)構(gòu)化”文檔的處理。為什么先講這個(gè)因?yàn)榻^大多數(shù)人的知識(shí)庫(kù)素材無(wú)非就是幾類隨手記的 txt 筆記、導(dǎo)出的 Markdown 文檔、從網(wǎng)頁(yè)另存下來(lái)的內(nèi)容、以及各種系統(tǒng)導(dǎo)出的結(jié)構(gòu)化文本。這些格式看起來(lái)簡(jiǎn)單但恰恰是解析環(huán)節(jié)翻車最多的地方。我見過(guò)太多案例一份 300 頁(yè)的產(chǎn)品手冊(cè)用默認(rèn)的字符切分器一切表格被攔腰截?cái)啻a塊被拆成兩半標(biāo)題和正文混在一起最后檢索出來(lái)的片段驢唇不對(duì)馬嘴。用戶問“第三章第二節(jié)講了什么”系統(tǒng)返回的是某個(gè)表格中間的一行數(shù)字。這不是模型的問題是導(dǎo)入解析階段沒有把文檔的結(jié)構(gòu)信息保留下來(lái)。所以這篇內(nèi)容適合誰(shuí)看如果你是剛接觸 RAG、正準(zhǔn)備搭建第一個(gè)知識(shí)庫(kù)的開發(fā)者這篇能幫你避開最基礎(chǔ)的坑如果你已經(jīng)踩過(guò)一些坑、檢索效果不理想這篇能幫你回頭檢查數(shù)據(jù)導(dǎo)入環(huán)節(jié)到底哪里出了問題如果你在做企業(yè)級(jí)知識(shí)管理需要處理大量異構(gòu)文檔這篇提供的思路可以直接套用。核心關(guān)鍵詞就幾個(gè)RAG、數(shù)據(jù)導(dǎo)入、解析、txt、Markdown。我會(huì)圍繞這幾個(gè)詞把從原始文本到可檢索片段的完整鏈路拆開講包括格式識(shí)別、結(jié)構(gòu)提取、分塊策略、元數(shù)據(jù)注入以及每一步背后的取舍邏輯。1.1 先搞清楚RAG 里的“數(shù)據(jù)導(dǎo)入”到底在做什么很多人把數(shù)據(jù)導(dǎo)入理解成“把文件讀進(jìn)來(lái)”這個(gè)認(rèn)知太淺了。在 RAG 的語(yǔ)境下數(shù)據(jù)導(dǎo)入實(shí)際上要完成四件事第一是格式歸一化。你的原始素材可能是 txt、Markdown、HTML、PDF、Word甚至是從數(shù)據(jù)庫(kù)導(dǎo)出的 CSV。這些格式的底層結(jié)構(gòu)完全不同但最終都要變成同一種中間表示通常是帶結(jié)構(gòu)的純文本加上元數(shù)據(jù)。第二是結(jié)構(gòu)提取。文檔里的標(biāo)題層級(jí)、段落邊界、列表、表格、代碼塊、引用塊這些結(jié)構(gòu)信息在后續(xù)檢索時(shí)極其重要。一個(gè)標(biāo)題為“安裝步驟”的片段和一個(gè)正文里隨便一句話檢索權(quán)重應(yīng)該是不一樣的。第三是語(yǔ)義分塊。不能簡(jiǎn)單地按固定字符數(shù)切那樣會(huì)把完整的語(yǔ)義單元切碎。理想的分塊應(yīng)該盡量保證每個(gè)塊是一個(gè)自包含的語(yǔ)義單元同時(shí)控制塊的大小在 Embedding 模型的最佳輸入范圍內(nèi)。第四是元數(shù)據(jù)注入。每個(gè)塊需要攜帶來(lái)源信息來(lái)自哪個(gè)文件、哪個(gè)章節(jié)、第幾頁(yè)、什么時(shí)間導(dǎo)入的。這些元數(shù)據(jù)在檢索過(guò)濾和結(jié)果溯源時(shí)必不可少。這四件事里格式歸一化和結(jié)構(gòu)提取是基礎(chǔ)語(yǔ)義分塊是核心難點(diǎn)元數(shù)據(jù)注入是工程細(xì)節(jié)。下面逐個(gè)拆開講。1.2 為什么從 txt 和 Markdown 講起有人會(huì)問現(xiàn)在 PDF 解析工具那么多為什么不直接從 PDF 開始講原因很簡(jiǎn)單txt 和 Markdown 是理解解析本質(zhì)的最佳切入點(diǎn)。PDF 的解析本質(zhì)上是在做逆向工程——從排版結(jié)果反推邏輯結(jié)構(gòu)這個(gè)過(guò)程充滿了不確定性。而 txt 和 Markdown 不一樣它們的結(jié)構(gòu)信息是顯式存在的。Markdown 的#就是標(biāo)題|就是表格 就是代碼塊。你不需要猜只需要正確識(shí)別。先把這兩種格式吃透建立起“結(jié)構(gòu)感知”的思維習(xí)慣再去處理 PDF 這種“結(jié)構(gòu)隱式”的格式會(huì)順暢很多。而且實(shí)際項(xiàng)目中Markdown 正在成為知識(shí)庫(kù)素材的主流格式——很多文檔工具都支持導(dǎo)出 Markdown很多技術(shù)文檔本身就是用 Markdown 寫的。2. 通用文本與結(jié)構(gòu)化文本的解析核心思路2.1 格式識(shí)別與預(yù)處理別急著讀文件內(nèi)容拿到一個(gè)文件第一件事不是直接讀內(nèi)容而是先判斷它到底是什么格式。這里有個(gè)坑文件擴(kuò)展名不可信。我遇到過(guò).txt文件實(shí)際是 HTML 源碼的也遇到過(guò).md文件里混著大量 HTML 標(biāo)簽的。穩(wěn)妥的做法是做一個(gè)輕量的格式探測(cè)讀取文件前 2KB 內(nèi)容檢查是否有 Markdown 特征#開頭的行、|表格、 代碼塊圍欄檢查是否有 HTML 特征html、div、p等標(biāo)簽檢查是否有 CSV 特征逗號(hào)分隔、制表符分隔、行列數(shù)一致如果都沒有按純文本處理這個(gè)探測(cè)邏輯不需要很復(fù)雜幾十行代碼就能搞定。但就是這幾十行代碼能幫你避免后面大量的解析異常。預(yù)處理階段還有幾件事要做編碼統(tǒng)一。中文文檔常見的編碼有 UTF-8、GBK、GB2312甚至還有 GB18030。如果編碼判斷錯(cuò)了讀出來(lái)全是亂碼。我的做法是先用chardet之類的庫(kù)探測(cè)編碼然后用探測(cè)到的編碼讀取讀完之后統(tǒng)一轉(zhuǎn)成 UTF-8。如果探測(cè)置信度低于某個(gè)閾值就嘗試用 UTF-8 讀取失敗再回退到 GBK。換行符統(tǒng)一。Windows 的\r\n、Unix 的\n、老 Mac 的\r這三種換行符混在一起會(huì)讓后續(xù)的分行邏輯出錯(cuò)。統(tǒng)一替換成\n是標(biāo)準(zhǔn)操作?？瞻鬃址謇?。連續(xù)多個(gè)空行、行尾多余空格、制表符和空格混用這些都會(huì)影響結(jié)構(gòu)識(shí)別的準(zhǔn)確性。但注意不要過(guò)度清理比如 Markdown 里行尾兩個(gè)空格表示換行這個(gè)不能刪。提示預(yù)處理階段的所有操作都應(yīng)該是可逆的或者有日志記錄的。一旦發(fā)現(xiàn)解析結(jié)果異常你需要能回溯到原始內(nèi)容判斷是預(yù)處理引入的問題還是解析邏輯本身的問題。2.2 結(jié)構(gòu)提取把文檔的“骨架”抽出來(lái)結(jié)構(gòu)提取的目標(biāo)是回答一個(gè)問題這份文檔的層級(jí)關(guān)系是什么。對(duì)于 Markdown結(jié)構(gòu)是顯式的。#到######對(duì)應(yīng)六級(jí)標(biāo)題標(biāo)題之間的內(nèi)容屬于該標(biāo)題的章節(jié)。解析時(shí)可以用一個(gè)棧來(lái)維護(hù)當(dāng)前的標(biāo)題路徑。比如遇到## 第二章棧變成[第二章]再遇到### 2.1 節(jié)棧變成[第二章, 2.1 節(jié)]。每個(gè)內(nèi)容塊都記錄它所屬的完整標(biāo)題路徑。對(duì)于純文本結(jié)構(gòu)是隱式的但通常有規(guī)律可循。常見的模式包括用數(shù)字編號(hào)的行如1.、1.1、第一章用特殊符號(hào)裝飾的行如、-----、*****全行加粗或全行大寫的行縮進(jìn)層級(jí)變化我一般會(huì)寫一組正則規(guī)則來(lái)識(shí)別這些模式按優(yōu)先級(jí)依次匹配。匹配到的行標(biāo)記為“疑似標(biāo)題”然后根據(jù)編號(hào)的層級(jí)關(guān)系推斷標(biāo)題級(jí)別。比如1.是一級(jí)1.1是二級(jí)1.1.1是三級(jí)。這里有個(gè)經(jīng)驗(yàn)不要追求 100% 的標(biāo)題識(shí)別準(zhǔn)確率。實(shí)際文檔里總有一些奇怪的格式強(qiáng)行識(shí)別反而會(huì)引入噪聲。我的做法是設(shè)置一個(gè)置信度閾值高置信度的直接標(biāo)記為標(biāo)題低置信度的保留為普通段落但在元數(shù)據(jù)里標(biāo)注“疑似標(biāo)題”。后續(xù)檢索時(shí)可以根據(jù)需要決定是否利用這個(gè)信息。表格的提取是另一個(gè)重點(diǎn)。Markdown 表格用|分隔解析相對(duì)簡(jiǎn)單。純文本表格就麻煩了可能是空格對(duì)齊、制表符對(duì)齊、或者用---畫邊框。我的建議是能識(shí)別就識(shí)別識(shí)別不了就整塊保留。千萬(wàn)不要把表格拆成一行一行的文本那樣表格的語(yǔ)義就徹底丟了。代碼塊的識(shí)別相對(duì)簡(jiǎn)單Markdown 用 圍欄純文本通?？靠s進(jìn)或者前后空行判斷。代碼塊在分塊時(shí)應(yīng)該作為一個(gè)整體不要從中間切開。2.3 分塊策略RAG 效果的分水嶺分塊是數(shù)據(jù)導(dǎo)入階段最核心的決策沒有之一。分塊策略直接決定了檢索質(zhì)量的上限。先說(shuō)一個(gè)反直覺的結(jié)論固定長(zhǎng)度分塊幾乎總是錯(cuò)的。很多人圖省事直接按 500 字符切重疊 50 字符。這種做法在簡(jiǎn)單場(chǎng)景下能用但只要文檔有結(jié)構(gòu)就會(huì)出問題。一個(gè)完整的操作步驟被切成兩半前半段說(shuō)“點(diǎn)擊設(shè)置按鈕”后半段說(shuō)“在彈出窗口中選擇高級(jí)選項(xiàng)”檢索時(shí)只召回前半段用戶根本不知道下一步該干什么。我的分塊策略是結(jié)構(gòu)感知的遞歸分塊具體邏輯如下第一優(yōu)先級(jí)是按結(jié)構(gòu)邊界切分。標(biāo)題、章節(jié)、列表項(xiàng)、表格、代碼塊這些都是天然的邊界。一個(gè)章節(jié)的內(nèi)容如果不超過(guò)最大塊大小就整塊作為一個(gè) chunk。如果超過(guò)再往下切。第二優(yōu)先級(jí)是按語(yǔ)義邊界切分。段落是最小的語(yǔ)義單元盡量保證一個(gè)段落不被切開。如果單個(gè)段落就超過(guò)了最大塊大小比如一段超長(zhǎng)的法律條款那就只能按句子切。第三優(yōu)先級(jí)才是按長(zhǎng)度切分。當(dāng)以上邊界都不存在時(shí)才退回到按字符數(shù)切分并且盡量在句子結(jié)束符處斷開。塊大小的選擇需要根據(jù) Embedding 模型來(lái)定。大多數(shù)中文 Embedding 模型的最佳輸入長(zhǎng)度在 256 到 512 個(gè) token 之間。我的經(jīng)驗(yàn)值是目標(biāo)塊大小 400 到 600 字符最大不超過(guò) 800 字符塊之間重疊 10% 到 15%。重疊的目的是防止邊界處的信息丟失但重疊太多會(huì)導(dǎo)致檢索結(jié)果冗余。這里有個(gè)細(xì)節(jié)不同結(jié)構(gòu)的塊應(yīng)該有不同的目標(biāo)大小。表格和代碼塊可以大一些因?yàn)樗鼈兊恼Z(yǔ)義密度高切碎了反而不好。普通敘述性段落可以小一些因?yàn)檎Z(yǔ)義密度低塊太大反而稀釋了關(guān)鍵信息。2.4 元數(shù)據(jù)設(shè)計(jì)讓每個(gè)塊都能“自報(bào)家門”元數(shù)據(jù)在檢索階段的價(jià)值經(jīng)常被低估。一個(gè)好的元數(shù)據(jù)設(shè)計(jì)能讓檢索效果提升一個(gè)檔次。每個(gè) chunk 至少應(yīng)該攜帶以下元數(shù)據(jù)元數(shù)據(jù)字段說(shuō)明用途source_file來(lái)源文件名結(jié)果溯源、按文件過(guò)濾file_type文件類型按類型過(guò)濾、調(diào)試heading_path標(biāo)題路徑結(jié)果展示、按章節(jié)過(guò)濾chunk_index塊序號(hào)排序、去重char_count字符數(shù)質(zhì)量監(jiān)控has_table是否含表格特殊處理標(biāo)記has_code是否含代碼特殊處理標(biāo)記import_time導(dǎo)入時(shí)間增量更新標(biāo)題路徑heading_path是我認(rèn)為最有價(jià)值的元數(shù)據(jù)。它記錄了當(dāng)前塊所屬的完整章節(jié)路徑比如[第三章 安裝部署, 3.2 環(huán)境配置, 3.2.1 依賴安裝]。在檢索結(jié)果展示時(shí)把這個(gè)路徑顯示出來(lái)用戶一眼就能知道這個(gè)片段來(lái)自哪里信任度會(huì)高很多。而且在檢索時(shí)可以利用標(biāo)題路徑做上下文增強(qiáng)。比如用戶問“依賴安裝有哪些步驟”檢索到的塊標(biāo)題路徑里包含“依賴安裝”這個(gè)塊的權(quán)重就應(yīng)該提高。這種基于結(jié)構(gòu)的加權(quán)比單純依賴向量相似度要可靠得多。3. 從 txt 到 Markdown 的完整實(shí)操流程3.1 環(huán)境準(zhǔn)備與依賴選擇我用的技術(shù)棧是 Python核心依賴就幾個(gè)pip install chardet markdown-it-py beautifulsoup4 lxmlchardet編碼探測(cè)處理中文文檔必備markdown-it-pyMarkdown 解析比正則更可靠beautifulsoup4lxml處理混入的 HTML 內(nèi)容如果你不想引入太多依賴純文本處理用標(biāo)準(zhǔn)庫(kù)就夠了。但 Markdown 解析我強(qiáng)烈建議用專門的庫(kù)自己寫正則處理嵌套結(jié)構(gòu)會(huì)瘋掉。3.2 第一步文件讀取與編碼歸一化import chardet def read_file_safely(file_path): with open(file_path, rb) as f: raw f.read() # 探測(cè)編碼 detected chardet.detect(raw[:10000]) encoding detected[encoding] confidence detected[confidence] # 置信度低時(shí)回退 if confidence 0.7 or encoding is None: encoding utf-8 try: text raw.decode(encoding) except UnicodeDecodeError: # 回退鏈 for fallback in [utf-8, gbk, gb18030, latin-1]: try: text raw.decode(fallback) break except UnicodeDecodeError: continue else: text raw.decode(utf-8, errorsreplace) # 換行符統(tǒng)一 text text.replace(\r\n, \n).replace(\r, \n) return text這段代碼的關(guān)鍵在于回退鏈。中文文檔的編碼情況很復(fù)雜單一探測(cè)不一定準(zhǔn)。我實(shí)測(cè)下來(lái)chardet對(duì) UTF-8 和 GBK 的區(qū)分準(zhǔn)確率大概在 85% 左右剩下的 15% 就得靠回退鏈兜底。注意latin-1放在回退鏈最后是有原因的。它能解碼任何字節(jié)序列永遠(yuǎn)不會(huì)拋異常但解出來(lái)的可能是亂碼。所以它只是最后的保底不能作為首選。3.3 第二步格式探測(cè)與路由import re def detect_format(text): sample text[:2000] # Markdown 特征 md_patterns [ r^#{1,6}\s, # 標(biāo)題 r^\|.*\|$, # 表格 r^, # 代碼塊 r^\s*[-*]\s, # 無(wú)序列表 r^\s*\d\.\s, # 有序列表 ] md_score sum(1 for p in md_patterns if re.search(p, sample, re.MULTILINE)) # HTML 特征 html_score len(re.findall(r[a-z][^]*, sample)) # CSV 特征 lines sample.split(\n)[:10] csv_score 0 if len(lines) 1: comma_counts [line.count(,) for line in lines if line.strip()] if comma_counts and len(set(comma_counts)) 1 and comma_counts[0] 0: csv_score 3 if md_score 2: return markdown elif html_score 5: return html elif csv_score 3: return csv else: return plaintext這個(gè)探測(cè)邏輯的核心思想是多特征投票而不是單一特征判斷。因?yàn)閷?shí)際文檔里經(jīng)常出現(xiàn)混合情況比如 Markdown 里嵌了 HTML純文本里用了#做注釋。多特征投票能降低誤判率。3.4 第三步Markdown 結(jié)構(gòu)解析用markdown-it-py把 Markdown 解析成 token 流然后遍歷 token 構(gòu)建結(jié)構(gòu)樹from markdown_it import MarkdownIt def parse_markdown_structure(text): md MarkdownIt() tokens md.parse(text) structure [] heading_stack [] current_content [] for token in tokens: if token.type heading_open: # 保存之前的內(nèi)容 if current_content: structure.append({ type: content, heading_path: list(heading_stack), text: \n.join(current_content) }) current_content [] level int(token.tag[1]) # h1 - 1 # 維護(hù)標(biāo)題棧 while heading_stack and heading_stack[-1][0] level: heading_stack.pop() heading_stack.append((level, )) elif token.type inline and heading_stack and heading_stack[-1][1] : # 標(biāo)題文本 heading_stack[-1] (heading_stack[-1][0], token.content) elif token.type in (fence, code_block): current_content.append(f\n{token.content}\n) elif token.type table_open: # 表格單獨(dú)處理 pass elif token.type inline: current_content.append(token.content) # 處理最后一段 if current_content: structure.append({ type: content, heading_path: [h[1] for h in heading_stack], text: \n.join(current_content) }) return structure這段代碼的核心是標(biāo)題棧。棧里維護(hù)的是當(dāng)前所處的標(biāo)題路徑遇到新標(biāo)題時(shí)根據(jù)級(jí)別彈出舊標(biāo)題、壓入新標(biāo)題。每個(gè)內(nèi)容塊都記錄它被解析時(shí)的標(biāo)題路徑。實(shí)際使用中還需要處理表格和代碼塊的完整提取。markdown-it-py的 token 流里表格會(huì)被拆成table_open、tr_open、td_open等一系列 token需要專門寫邏輯把它們重新組裝成結(jié)構(gòu)化的表格數(shù)據(jù)。3.5 第四步純文本結(jié)構(gòu)推斷純文本沒有顯式結(jié)構(gòu)需要靠正則和啟發(fā)式規(guī)則推斷def infer_plaintext_structure(text): lines text.split(\n) blocks [] current_block [] current_heading None # 標(biāo)題識(shí)別規(guī)則按優(yōu)先級(jí)排列 heading_patterns [ (r^第[一二三四五六七八九十][章節(jié)篇]\s*, 1), (r^\d\.\d\.\d\s, 3), (r^\d\.\d\s, 2), (r^\d\.\s, 1), (r^[一二三四五六七八九十][、.]\s*, 2), (r^{3,}$, 0), # 下劃線裝飾標(biāo)記上一行為標(biāo)題 (r^-{3,}$, 0), ] for i, line in enumerate(lines): stripped line.strip() # 空行作為塊邊界 if not stripped: if current_block: blocks.append({ type: content, heading: current_heading, text: \n.join(current_block) }) current_block [] continue # 檢查是否是標(biāo)題 is_heading False for pattern, level in heading_patterns: if re.match(pattern, stripped): if level 0: # 裝飾線把上一行提升為標(biāo)題 if current_block: current_heading current_block.pop() else: # 保存之前的內(nèi)容 if current_block: blocks.append({ type: content, heading: current_heading, text: \n.join(current_block) }) current_block [] current_heading stripped is_heading True break if not is_heading: current_block.append(line) # 收尾 if current_block: blocks.append({ type: content, heading: current_heading, text: \n.join(current_block) }) return blocks這套規(guī)則不是萬(wàn)能的但覆蓋了中文技術(shù)文檔里 80% 以上的標(biāo)題格式。剩下的 20% 需要根據(jù)具體文檔類型定制規(guī)則。實(shí)操心得我一般會(huì)先拿幾份典型文檔跑一遍把識(shí)別錯(cuò)誤的標(biāo)題打印出來(lái)針對(duì)性調(diào)整正則。這個(gè)過(guò)程通常需要迭代兩三輪但一旦調(diào)好后續(xù)同類文檔都能復(fù)用。3.6 第五步結(jié)構(gòu)感知的分塊有了結(jié)構(gòu)樹之后分塊就變成了一個(gè)遞歸過(guò)程def chunk_by_structure(blocks, max_size600, min_size100, overlap80): chunks [] for block in blocks: text block[text] heading block.get(heading, ) # 塊本身不超過(guò)限制直接作為一個(gè) chunk if len(text) max_size: if len(text) min_size: chunks.append({ text: text, heading: heading, char_count: len(text) }) continue # 超長(zhǎng)塊按段落切分 paragraphs text.split(\n\n) current [] current_len 0 for para in paragraphs: para_len len(para) if current_len para_len max_size and current: chunk_text \n\n.join(current) chunks.append({ text: chunk_text, heading: heading, char_count: len(chunk_text) }) # 保留重疊部分 overlap_text chunk_text[-overlap:] if len(chunk_text) overlap else chunk_text current [overlap_text, para] current_len len(overlap_text) para_len else: current.append(para) current_len para_len if current: chunk_text \n\n.join(current) chunks.append({ text: chunk_text, heading: heading, char_count: len(chunk_text) }) return chunks這里有幾個(gè)關(guān)鍵決策點(diǎn)為什么最小塊大小是 100 字符太小的塊語(yǔ)義不完整Embedding 出來(lái)的向量質(zhì)量差檢索時(shí)容易誤召回。100 字符大約是一到兩句話是語(yǔ)義完整性的下限。為什么重疊是 80 字符這是經(jīng)驗(yàn)值。重疊太少起不到防止邊界信息丟失的作用重疊太多會(huì)導(dǎo)致檢索結(jié)果大量重復(fù)。80 字符大約是一句話的長(zhǎng)度能保證邊界處的語(yǔ)義連續(xù)性。表格和代碼塊怎么處理它們不應(yīng)該參與常規(guī)分塊。表格應(yīng)該整體保留如果太大就按行切分但保留表頭。代碼塊應(yīng)該整體保留如果太大就按函數(shù)或邏輯塊切分。3.7 第六步元數(shù)據(jù)注入與輸出最后一步是把分塊結(jié)果和元數(shù)據(jù)組裝起來(lái)輸出成后續(xù)流程能消費(fèi)的格式import json from datetime import datetime def build_chunks_with_metadata(chunks, source_file, file_type): result [] for i, chunk in enumerate(chunks): result.append({ id: f{source_file}_{i}, text: chunk[text], metadata: { source_file: source_file, file_type: file_type, heading: chunk.get(heading, ), chunk_index: i, char_count: chunk[char_count], has_table: | in chunk[text] and --- in chunk[text], has_code: in chunk[text], import_time: datetime.now().isoformat() } }) return result輸出格式我推薦 JSON Lines每行一個(gè) chunk。這樣便于流式處理也便于后續(xù)增量更新時(shí)按行追加。4. 常見問題與排查技巧實(shí)錄4.1 編碼問題排查速查表現(xiàn)象可能原因排查方法解決方案中文全是亂碼編碼判斷錯(cuò)誤用十六進(jìn)制查看器看字節(jié)嘗試 GBK/GB18030部分字符亂碼混合編碼分段探測(cè)編碼分段解碼后拼接問號(hào)替代中文解碼時(shí) errorsreplace檢查原始字節(jié)換正確編碼重新解碼換行符異?；旌蠐Q行符統(tǒng)計(jì) \r\n 和 \n 數(shù)量統(tǒng)一替換編碼問題我踩過(guò)最坑的一次是一份文檔前半部分是 UTF-8后半部分是 GBK。chardet探測(cè)出來(lái)是 UTF-8結(jié)果后半部分全亂碼。后來(lái)我的做法是分段探測(cè)每 10KB 探測(cè)一次如果發(fā)現(xiàn)編碼不一致就分段解碼。4.2 結(jié)構(gòu)識(shí)別失敗的典型場(chǎng)景場(chǎng)景一標(biāo)題沒有編號(hào)。有些文檔的標(biāo)題就是加粗的一行文字沒有任何編號(hào)。這種情況純文本推斷很難識(shí)別。我的做法是結(jié)合行長(zhǎng)和上下文空行來(lái)判斷如果一行文字長(zhǎng)度小于 30 字符前后都有空行且不以標(biāo)點(diǎn)結(jié)尾就標(biāo)記為疑似標(biāo)題。場(chǎng)景二列表嵌套過(guò)深。Markdown 的嵌套列表用縮進(jìn)表示但縮進(jìn)可能是 2 空格、4 空格、或者 Tab。解析時(shí)需要統(tǒng)一縮進(jìn)單位。我的做法是統(tǒng)計(jì)所有縮進(jìn)取最小公約數(shù)作為一級(jí)縮進(jìn)單位。場(chǎng)景三表格跨頁(yè)。從 PDF 轉(zhuǎn)出來(lái)的文本表格經(jīng)常被分頁(yè)符打斷。這種情況需要在預(yù)處理階段識(shí)別分頁(yè)符嘗試把跨頁(yè)的表格拼接起來(lái)。拼接邏輯是如果上一頁(yè)末尾是表格行下一頁(yè)開頭也是表格行且列數(shù)一致就嘗試合并。4.3 分塊質(zhì)量的快速驗(yàn)證方法分塊做完之后怎么知道分得好不好我一般用三個(gè)快速檢查檢查一隨機(jī)抽樣 20 個(gè) chunk人工閱讀。看每個(gè) chunk 是否語(yǔ)義完整是否包含足夠的上下文。如果發(fā)現(xiàn)大量 chunk 以半句話開頭或結(jié)尾說(shuō)明分塊邊界有問題。檢查二統(tǒng)計(jì) chunk 大小分布。畫個(gè)直方圖看是否集中在目標(biāo)大小附近。如果出現(xiàn)大量極小 chunk小于 50 字符或極大 chunk大于 1000 字符說(shuō)明分塊邏輯有漏洞。檢查三做一輪檢索測(cè)試。準(zhǔn)備 10 個(gè)典型問題看檢索結(jié)果是否相關(guān)。如果檢索結(jié)果經(jīng)常是表格中間的一行、或者代碼塊的片段說(shuō)明結(jié)構(gòu)處理有問題。實(shí)操心得我習(xí)慣在分塊完成后把 chunk 列表導(dǎo)出成 Markdown 文件用編輯器打開快速瀏覽。肉眼掃一遍比看統(tǒng)計(jì)數(shù)字更容易發(fā)現(xiàn)異常。4.4 性能優(yōu)化的幾個(gè)實(shí)用技巧數(shù)據(jù)導(dǎo)入階段如果處理大量文檔性能會(huì)成為瓶頸。幾個(gè)我實(shí)測(cè)有效的優(yōu)化批量讀取。不要一個(gè)文件一個(gè)文件地讀用concurrent.futures做并發(fā)讀取。IO 密集型任務(wù)并發(fā)能帶來(lái)數(shù)倍提升。惰性解析。如果文檔很大不要一次性全部解析成 token 流。markdown-it-py支持流式解析可以邊解析邊處理。緩存中間結(jié)果。結(jié)構(gòu)解析的結(jié)果可以緩存起來(lái)后續(xù)調(diào)整分塊參數(shù)時(shí)不需要重新解析。我用pickle把結(jié)構(gòu)樹緩存到本地調(diào)試分塊邏輯時(shí)能省大量時(shí)間。正則預(yù)編譯。所有正則表達(dá)式在模塊加載時(shí)就編譯好不要每次調(diào)用時(shí)重新編譯。這個(gè)優(yōu)化在小文檔上不明顯但處理上萬(wàn)份文檔時(shí)差距很大。5. 從導(dǎo)入到檢索的銜接要點(diǎn)5.1 導(dǎo)入結(jié)果如何影響檢索策略數(shù)據(jù)導(dǎo)入階段產(chǎn)出的 chunk 和元數(shù)據(jù)直接決定了檢索階段能做什么。如果 chunk 攜帶了heading元數(shù)據(jù)檢索時(shí)就可以做基于標(biāo)題的加權(quán)。具體做法是計(jì)算 query 和 chunk 標(biāo)題的相似度把這個(gè)相似度作為一個(gè)加權(quán)因子和向量相似度做加權(quán)求和。我實(shí)測(cè)下來(lái)這個(gè)加權(quán)能讓檢索準(zhǔn)確率提升 10% 到 15%。如果 chunk 標(biāo)記了has_table和has_code檢索時(shí)就可以做類型感知的展示。表格類結(jié)果用表格渲染代碼類結(jié)果用代碼塊渲染用戶體驗(yàn)會(huì)好很多。如果 chunk 記錄了source_file和chunk_index檢索時(shí)就可以做上下文擴(kuò)展。召回一個(gè) chunk 后把它的前后相鄰 chunk 也取出來(lái)拼成更完整的上下文。這個(gè)技巧對(duì)回答“步驟類”問題特別有效。5.2 增量導(dǎo)入的設(shè)計(jì)考慮實(shí)際項(xiàng)目中知識(shí)庫(kù)是持續(xù)更新的。增量導(dǎo)入的設(shè)計(jì)要點(diǎn)文件指紋。對(duì)每個(gè)文件計(jì)算 MD5 或 SHA256導(dǎo)入前先比對(duì)指紋。指紋沒變就跳過(guò)變了就重新導(dǎo)入。版本管理。每次導(dǎo)入生成一個(gè)版本號(hào)chunk 的 ID 里包含版本信息。這樣檢索時(shí)可以指定只檢索最新版本或者做版本對(duì)比。刪除處理。文件被刪除時(shí)對(duì)應(yīng)的 chunk 也要標(biāo)記刪除。不要物理刪除而是打上deleted標(biāo)記檢索時(shí)過(guò)濾掉。這樣萬(wàn)一誤刪還能恢復(fù)。5.3 質(zhì)量監(jiān)控指標(biāo)導(dǎo)入流程上線后需要持續(xù)監(jiān)控幾個(gè)指標(biāo)指標(biāo)含義健康范圍平均 chunk 大小所有 chunk 的字符數(shù)均值300-600極小 chunk 占比小于 50 字符的 chunk 比例 5%極大 chunk 占比大于 1000 字符的 chunk 比例 3%編碼異常率解碼時(shí)使用回退鏈的比例 2%結(jié)構(gòu)識(shí)別率成功識(shí)別標(biāo)題的文檔比例 80%這些指標(biāo)異常時(shí)說(shuō)明導(dǎo)入流程的某個(gè)環(huán)節(jié)出了問題需要回頭排查。6. 一些踩坑之后的個(gè)人體會(huì)做 RAG 數(shù)據(jù)導(dǎo)入這一年多最大的體會(huì)是慢就是快。剛開始我總想快點(diǎn)把數(shù)據(jù)灌進(jìn)去結(jié)果檢索效果差回頭返工的時(shí)間遠(yuǎn)超當(dāng)初省下的時(shí)間。后來(lái)我養(yǎng)成了一個(gè)習(xí)慣每接入一種新格式的文檔先拿 5 到 10 份樣本做小規(guī)模測(cè)試把解析結(jié)果人工過(guò)一遍確認(rèn)沒問題了再批量導(dǎo)入。另一個(gè)體會(huì)是不要迷信自動(dòng)化。結(jié)構(gòu)識(shí)別、分塊這些環(huán)節(jié)純靠算法很難做到 100% 準(zhǔn)確。我的做法是提供一個(gè)“人工校正”的接口對(duì)于識(shí)別異常的文檔允許手動(dòng)調(diào)整結(jié)構(gòu)標(biāo)記。這個(gè)接口看起來(lái)增加了工作量但實(shí)際上大幅提升了最終質(zhì)量。還有一個(gè)細(xì)節(jié)保留原始文本。不管怎么預(yù)處理、怎么分塊原始文本一定要完整保留。我見過(guò)太多案例預(yù)處理時(shí)做了不可逆的清洗后來(lái)發(fā)現(xiàn)清洗掉了關(guān)鍵信息想恢復(fù)都恢復(fù)不了。我的做法是原始文本單獨(dú)存一份所有處理都是基于副本進(jìn)行的。最后分享一個(gè)小技巧用檢索測(cè)試反推導(dǎo)入質(zhì)量。準(zhǔn)備一組典型問題每次調(diào)整導(dǎo)入?yún)?shù)后跑一遍檢索測(cè)試看召回結(jié)果的變化。這比看統(tǒng)計(jì)指標(biāo)更直觀也更能發(fā)現(xiàn)實(shí)際問題。我一般會(huì)維護(hù)一個(gè) 50 題左右的測(cè)試集覆蓋事實(shí)查詢、步驟查詢、對(duì)比查詢等不同類型每次調(diào)整參數(shù)后都跑一遍記錄準(zhǔn)確率變化。這個(gè)內(nèi)容后續(xù)還可以這樣擴(kuò)展把 PDF、Word、HTML 這些格式的解析也納入進(jìn)來(lái)形成一套完整的異構(gòu)文檔導(dǎo)入方案。另外表格和圖片的專項(xiàng)處理也值得單獨(dú)展開特別是表格的結(jié)構(gòu)化提取和圖片的 OCR 處理都是實(shí)際項(xiàng)目中繞不開的環(huán)節(jié)。