我做的這個項(xiàng)目內(nèi)部代號叫 REA。名字沒什么深意就是從 RRetrieval、EExtraction、AAgent三個核心詞里各取了一個字母用來表示檢索—抽取—執(zhí)行這條完整鏈路。做它的初衷也很樸素去年我在整理一批歷史項(xiàng)目文檔和散落在十幾個文件夾里的技術(shù)筆記時發(fā)現(xiàn)真正花時間的不是寫代碼而是找到東西、看懂東西、把東西從上下文里撈出來這個過程。REA 就是針對這個痛點(diǎn)做的一個自動化檢索與摘要抽取工具目標(biāo)用戶是我自己這類需要頻繁翻舊資料、從長文本里提煉關(guān)鍵信息、再把提煉結(jié)果丟給下游流程去用的開發(fā)者。它可以做什么簡單說輸入一段種子關(guān)鍵詞或者問題REA 會在你指定的目錄、代碼倉庫或者本地知識庫里做語義檢索把命中的文檔段落提取出來再通過一個可配置的抽取模型生成結(jié)構(gòu)化摘要最后把結(jié)果以統(tǒng)一格式輸出供后續(xù)腳本、流程或其他工具直接調(diào)用。不是搜索引擎的替代品而是更偏定向抽取和流程編排的那一類工具。這篇我會把整個項(xiàng)目的思路、核心實(shí)現(xiàn)、踩過的坑和調(diào)優(yōu)經(jīng)驗(yàn)完整記錄下來包括一些常規(guī)文檔里不會寫的東西比如為什么選某種切片策略而不是另一種、為什么抽取模型換了三版才穩(wěn)定、以及實(shí)測下來哪些環(huán)節(jié)最容易被低估。適合正在做本地知識庫工具、文檔處理流水線或者準(zhǔn)備自己造輪子做信息抽取的同學(xué)參考。1. 項(xiàng)目要解決的真實(shí)痛點(diǎn)我以為缺的是搜索實(shí)際缺的是定向抽取先說結(jié)論如果你只是嫌本地文件搜不到東西那用一個全文索引工具就夠了REA 這套東西對你來說屬于過度設(shè)計。它的價值在于從檢索結(jié)果里進(jìn)一步提煉結(jié)構(gòu)化信息比如狀態(tài)、責(zé)任人、結(jié)論、參數(shù)、版本號這類可復(fù)用字段。這是普通搜索給不了的東西。我最早的需求場景是這樣的某天下午要寫一份季度復(fù)盤需要從幾十份周報里找出每個階段提到的風(fēng)險項(xiàng)和應(yīng)對措施。用系統(tǒng)自帶搜索把相關(guān)周報一篇篇翻出來眼睛掃一遍提取信息然后手動貼進(jìn)表格。這個過程耗費(fèi)了大概大半天。我當(dāng)時就想如果有一個工具能自動完成檢索—切片—提取—匯總這四步把幾十篇文章變成一個結(jié)構(gòu)化的風(fēng)險清單表格那該多省事。REA 就是順著這條路子走下來的。為了把這個需求講得更清楚我拆成了三個層次第一層是能不能找到。傳統(tǒng)的關(guān)鍵詞匹配在遇到同義表述、口語化描述或者跨文檔信息時基本失效。比如你搜網(wǎng)絡(luò)超時命中不了寫的是連接經(jīng)常斷的文檔。這需要語義檢索也就是把文本轉(zhuǎn)成向量通過空間距離找相似內(nèi)容。第二層是找到了能不能看懂。文檔里的關(guān)鍵信息往往藏在冗長段落中間。比如某篇周報里有句話本周中段出現(xiàn)了支付接口偶發(fā)超時的現(xiàn)象經(jīng)排查是上游回調(diào)延遲導(dǎo)致的后續(xù)接入了重試機(jī)制目前未再復(fù)現(xiàn)。這里面風(fēng)險項(xiàng)是支付接口偶發(fā)超時應(yīng)對措施是加重試機(jī)制狀態(tài)是已解決。人眼能秒讀但機(jī)器要穩(wěn)定地從這類句子里抽取出來就得靠實(shí)體識別加關(guān)系判斷那一套。第三層是抽取出來能不能直接用。如果只是打印在控制臺里那跟人眼讀一遍沒有本質(zhì)區(qū)別。REA 的定位是給流程用的工具所以輸出必須結(jié)構(gòu)化、可二次消費(fèi)比如 JSON 格式、字段固定、附帶原文出處。這樣才能銜接后面的自動化報告生成、定時巡檢、異常預(yù)警這些下游環(huán)節(jié)。這個三層拆解基本決定了 REA 的模塊劃分檢索器負(fù)責(zé)第一層切片器配合抽取模型負(fù)責(zé)第二層輸出格式化器負(fù)責(zé)第三層。整體鏈路清晰每個模塊都能獨(dú)立替換這也是后面迭代時最受益的設(shè)計決策。2. 整體架構(gòu)與關(guān)鍵選型不是所有組件都需要最新最強(qiáng)架構(gòu)上我走了一條非常樸素的管道式路線沒有上任何繁瑣的框架。整個 REA 由五個模塊串聯(lián)輸入解析器、語義檢索器、文檔切片器、信息抽取器、結(jié)構(gòu)化輸出器。每個模塊之間只通過標(biāo)準(zhǔn)數(shù)據(jù)格式通信這意味著你可以在任意環(huán)節(jié)換成自己的實(shí)現(xiàn)。數(shù)據(jù)流大概是這樣的種子問題進(jìn)來解析器把它轉(zhuǎn)成檢索條件并生成向量檢索器從向量庫里召回候選文檔片段切片器把這些片段按語義邊界切成若干 chunk抽取器逐 chunk 掃描并抽取目標(biāo)字段輸出器匯總?cè)ブ睾蟀唇y(tǒng)一 schema 返回。整個過程可以批量跑也可以按需執(zhí)行。選型上我堅持三個原則原則一模型要能本地跑。因?yàn)樘幚淼奈臋n里有一部分是內(nèi)部開會紀(jì)要、未公開的技術(shù)方案不適合送外部接口。所以語義檢索模型和抽取模型都選了可以在本地 CPU/GPU 上運(yùn)行的開源模型數(shù)據(jù)不出內(nèi)網(wǎng)。代價是效果上跟商業(yè)大模型有差距但通過提示詞優(yōu)化和結(jié)構(gòu)化約束可以彌補(bǔ)大部分。原則二組件要能單獨(dú)替換。向量庫一開始用的內(nèi)存字典后來切到更正規(guī)的向量數(shù)據(jù)庫只用改檢索器內(nèi)部實(shí)現(xiàn)其他模塊一點(diǎn)沒動。如果某天想換更強(qiáng)的抽取模型同樣只需要替換抽取器里的模型調(diào)用。原則三避免過度工程。項(xiàng)目初期沒有引入消息隊列、容器編排這類東西。因?yàn)樵趥€人工作流里并發(fā)量根本到不了那一步。REA 就是一個命令行工具加一個 Python API 接口簡單直接。各模塊選型落地如下模塊方案選擇理由輸入解析正則 簡單意圖匹配場景固定不需要上對話理解模型語義檢索本地 embedding 模型 向量庫中文支持好隱私可控支持增量索引文檔切片遞歸字符分割 語義邊界檢測兼顧效率和邊界完整性處理長文檔效果穩(wěn)定信息抽取本地抽取模型 結(jié)構(gòu)化提示詞可控性強(qiáng)輸出字段由 schema 驅(qū)動結(jié)構(gòu)化輸出JSON schema 校驗(yàn) 原文溯源保證下游直接可用方便定位問題這套組合的完整跑通驗(yàn)證了一個觀點(diǎn)不追最新的模型和架構(gòu)把每個環(huán)節(jié)的邊界梳理清楚反而更容易做出可靠的工具。3. 核心模塊拆解實(shí)現(xiàn)檢索、切片、抽取、輸出的完整鏈路這章是全文最核心的部分我會按模塊順序把實(shí)現(xiàn)思路和關(guān)鍵代碼邏輯串一遍。每個模塊都會講清楚做了什么和為什么這么做。3.1 檢索模塊語義召回是怎么從找詞變成找意思的檢索模塊的輸入是一個查詢串輸出是候選文檔片段列表。實(shí)現(xiàn)分三步先把查詢串轉(zhuǎn)成向量然后在向量庫里做相似度檢索最后按相似度閾值過濾并排序返回。向量庫里的數(shù)據(jù)是怎么來的啟動時會掃描你指定的根目錄對每個文件做格式識別。支持純文本、Markdown、Word 和 PDF 這幾種常見格式。文本提取之后按文檔切片器切成 chunk每個 chunk 用 embedding 模型轉(zhuǎn)成一個多維向量連同元信息文件路徑、標(biāo)題、頁碼、chunk 序號一起寫入向量庫。查詢的時候用的是同一個 embedding 模型做向量化。這里有個非常容易踩的坑查詢端的文本規(guī)范化規(guī)則必須跟入庫時完全一致。比如入庫前統(tǒng)一把全角括號轉(zhuǎn)半角那查詢時也要做同樣的轉(zhuǎn)換否則同一個詞在兩端生成向量的細(xì)微差異會被放大導(dǎo)致關(guān)聯(lián)度下降。REA 里我會把文本清洗函數(shù)設(shè)定為全局共用確保兩側(cè)行為一致。相似度計算我用的是內(nèi)積具體來說存儲前會把向量做歸一化然后內(nèi)積等價于余弦相似度。至于為什么不用 L2 距離因?yàn)闅w一化之后內(nèi)積在排序穩(wěn)定性上表現(xiàn)更好對閾值也更好調(diào)。召回流程本身很簡單召回 topK 候選按相似度排序保留高于閾值的片段。def retrieve(query_vec, top_k20, threshold0.42): candidates vector_db.search(query_vec, top_k) results [] for doc_id, chunk_id, vec, meta in candidates: score np.dot(query_vec, vec) if score threshold: results.append({ doc_id: doc_id, chunk_id: chunk_id, text: get_chunk_text(doc_id, chunk_id), score: float(score), meta: meta }) results.sort(keylambda x: x[score], reverseTrue) return results這里 threshold 取 0.42 是我在實(shí)測語料上調(diào)出來的經(jīng)驗(yàn)值稍后會在踩坑章節(jié)展開講?，F(xiàn)在只需要記住閾值太低壓入噪聲閾值太高漏掉相關(guān)片段這個值跟你的語料分布和模型都有關(guān)必須動態(tài)調(diào)。3.2 切片模塊為什么 chunk 切得好不好直接決定抽取效果的上限講切片之前先講一個我踩過的慘痛教訓(xùn)。第一版 REA 用的是固定長度切片每 500 個字符切一段不做任何語義處理。結(jié)果是抽取模塊經(jīng)常從中間斷開的句子里提取出殘缺字段比如把支付接口偶發(fā)超時切成支付接口偶發(fā)和超時經(jīng)排查…兩段后者的關(guān)鍵信息就丟了。后來我把切片策略改了先用遞歸字符分割器按段落拆再對超長段落做邊界檢測。具體邏輯是盡量讓每個 chunk 在 600 到 800 字之間并且只允許在句號、分號、段落換行這些語義邊界處切斷。如果碰到底層沒有邊界的大文本就回退用固定長度但不截斷句子寧可讓 chunk 略微超長也不犧牲完整性。切片模塊的輸出是 chunk 列表每個 chunk 帶上所在文檔 ID 和全局序號。之所以強(qiáng)調(diào) chunk ID 要全局唯一是因?yàn)楹罄m(xù)抽取結(jié)果需要追溯到原文這個操作靠 chunk ID 做映射最穩(wěn)。實(shí)踐里我發(fā)現(xiàn)對高度結(jié)構(gòu)化文檔比如表格型周報按 Markdown 標(biāo)題層級切比按句號切效果更好但對沒有層級的長篇散文式博客句號切分更穩(wěn)。REA 里做了一個簡單策略優(yōu)先按文檔本身的標(biāo)題結(jié)構(gòu)切沒標(biāo)題結(jié)構(gòu)就按段落邊界切。這是性價比很高的一種做法既不需要引入昂貴的分層模型也能覆蓋絕大多數(shù)文檔類型。3.3 抽取模塊如何讓模型穩(wěn)定輸出指定字段而不是自由發(fā)揮信息抽取是 REA 里迭代最多、也最考驗(yàn)?zāi)托牡哪K。我的目標(biāo)是從候選 chunk 里抽取出用戶預(yù)先定義好的字段。比如一個風(fēng)險清單的 schema 可能是這樣的{ risk_item: 風(fēng)險項(xiàng)描述, impact: 影響范圍, solution: 應(yīng)對措施, status: 狀態(tài): 解決中/已解決/未解決 }問題在于抽取模型如果不受約束輸出格式會五花八門。有時候字段名變成了風(fēng)險而不是risk_item有時候憑空多出一段解釋文字。為了穩(wěn)定格式我做了兩件事第一件事把 schema 描述直接寫進(jìn)提示詞幾輪測試調(diào)整后把期望輸出格式固化成了模板要求模型只輸出 JSON不要解釋。第二件事對輸出結(jié)果做后處理校驗(yàn)用 schema 里的字段清單比對模型輸出如果缺失或類型不對就做一次帶修正提示的重抽取。這個機(jī)制把格式錯誤率從最初的 30% 降到了 5% 以下。關(guān)鍵提示詞模板大致是這樣的文本片段\n{text}\n\n請從上述文本中抽取以下字段\n- risk_item: 風(fēng)險項(xiàng)描述\n- impact: 影響范圍\n- solution: 應(yīng)對措施\n- status: 風(fēng)險狀態(tài)\n\n只輸出 JSON不要輸出任何解釋。這套組合的代價是多了一次后處理調(diào)用的開銷但在批量場景下完全可以接受。我更在意的是下游流程能穩(wěn)定吃到結(jié)構(gòu)化數(shù)據(jù)為此多花一點(diǎn)算力是值得的。3.4 輸出模塊帶溯源的結(jié)構(gòu)化結(jié)果才是給流程用的結(jié)果輸出模塊解決的是兼容性。目前我用的是 JSON Lines 格式每行一個抽取結(jié)果。每條結(jié)果包含四個固定字段chunk_id對應(yīng)原文內(nèi)容抽取的字段字典以及相似度得分。帶 chunk_id 的主要目的是溯源。如果下游發(fā)現(xiàn)某條抽取結(jié)果有問題可以瞬間定位到原文位置省去了大海撈針的排查時間。這在使用 REA 生成周報數(shù)據(jù)時特別重要至少提升了數(shù)據(jù)校對的效率。除了 JSON LinesREA 還內(nèi)置了一個簡單的匯總器可以把同一文檔里多條抽取結(jié)果合并成一個條目。比如一個季度幾十份周報都提到支付接口超時匯總器會把它們的處理狀態(tài)、出現(xiàn)時段歸并成表格行這就是我最初想要的自動風(fēng)險清單效果。{chunk_id: doc17-chunk03, text: 本周中段出現(xiàn)了支付接口偶發(fā)超時的現(xiàn)象..., extracted: {risk_item: 支付接口偶發(fā)超時, impact: 支付鏈路可用性下降, solution: 接入重試機(jī)制, status: 已解決}, score: 0.67}輸出模塊還有一個細(xì)節(jié)為了避免下游被空字段打擾我會在輸出前過濾掉字段值為空的 chunk。這個過濾策略看似很簡單但在實(shí)際使用里可以避免大量無效后處理。4. 實(shí)測效果與調(diào)優(yōu)過程從能跑通到好用之間隔著一個調(diào)參地獄項(xiàng)目第一版跑通后我用歷史周報做了一批測試結(jié)論是能跑通但你不會想在日常里用。主要問題有三類召回精度不穩(wěn)、抽取格式錯亂、重復(fù)信息過多。這一節(jié)記錄我是怎么一步步把這些坑填平的。4.1 召回精度對比閾值不是越大越好也不是越小越好我最早把相似度閾值設(shè)成 0.30召回的結(jié)果里混入了大量主題沾邊但實(shí)質(zhì)無關(guān)的 chunk。比如搜支付網(wǎng)關(guān)超時會召回不少講網(wǎng)絡(luò)架構(gòu)演進(jìn)的內(nèi)容因?yàn)槎忌婕熬W(wǎng)絡(luò)。后來我把閾值往上調(diào)到 0.42情況明顯改善。但這不代表閾值越高越好。調(diào)到 0.55 之后相關(guān)內(nèi)容的召回率明顯下降有些只在不同詞面下講同一件事的 chunk 就被篩掉了。調(diào)閾值時一個實(shí)用的思路是先跑一批帶標(biāo)注的樣本畫出召回率和精度的權(quán)衡曲線找拐點(diǎn)。如果沒有標(biāo)注樣本一個粗糙的經(jīng)驗(yàn)法則是把閾值設(shè)在最大相關(guān)命中分?jǐn)?shù)和最大無關(guān)命中分?jǐn)?shù)之間REA 初版就是這樣調(diào)的。實(shí)踐中我還會在檢索模塊里輸出每個 chunk 的得分分布輔助判斷閾值是否合理。如果幾乎所有得分都集中在 0.3 到 0.5 之間那就要考慮是 embedding 模型不匹配語料而不是閾值的問題。4.2 抽取模型的三次換血從通用到領(lǐng)域適配的演進(jìn)第一版抽取模塊用的是通用生成模型。效果怎么說呢摘要味很重抽出來的風(fēng)險項(xiàng)經(jīng)常是原文的重述而不是精準(zhǔn)字段。比如原文上游 DNS 解析偶爾失敗導(dǎo)致部分用戶訪問異常它會抽成存在用戶訪問異常的風(fēng)險丟失了上游 DNS 解析失敗這個真正有價值的實(shí)體。第二版換了抽取能力更強(qiáng)的模型但仍然沒有很好地約束輸出。這在處理幾百個 chunk 時特別明顯結(jié)果里混進(jìn)大量解釋性文本把 schema 變得稀碎。第三次迭代我決定上結(jié)構(gòu)化提示詞 后處理校驗(yàn)的雙保險把字段描述寫死在提示詞里同時在后處理階段校驗(yàn)字段存在性。這次改動帶來的提升很直觀格式正確率到了 95% 上下字段信息也基本能對位原文。由此得到一個經(jīng)驗(yàn)?zāi)Ｐ湍芰Σ皇俏ㄒ粵Q定因素提示詞怎么約束和結(jié)果怎么校驗(yàn)同樣關(guān)鍵。4.3 chunk 大小對抽取效果的直接影響我用同一批周報跑了三組對比分別用 300 字、700 字、1200 字作為目標(biāo) chunk 大小。300 字檔召回效果好但抽取字段經(jīng)常因?yàn)樯舷挛牟蛔愣毙畔⒈热缰恢乐Ц督涌诔瑫r卻不知道已解決這個狀態(tài)。1200 字檔上下文充足但抽取模型面對大段文本時容易漏字段也更容易被無關(guān)信息干擾。最后取了個折中值700 字左右。這個體量既能保留關(guān)鍵上下文又不至于讓模型注意力被稀釋。不同文檔類型可能各有最優(yōu)值比如會議紀(jì)要短段落多400 字更合適技術(shù)方案長段落多1000 字也不嫌大。所以我把 chunk 大小做成了可配置項(xiàng)默認(rèn) 700按場景覆蓋。4.4 一個完整實(shí)例從十篇周報到結(jié)構(gòu)化風(fēng)險清單貼近實(shí)際跑一遍 REA大家會更直觀地看它到底干了多少活。我把 10 篇?dú)v史周報丟進(jìn)測試目錄配置目標(biāo)字段為 risk_item、impact、solution、status然后執(zhí)行檢索和抽取。整個過程大概耗時 40 秒輸出了一共 47 條有效抽取結(jié)果覆蓋了 6 個不同的風(fēng)險主題支付接口超時、數(shù)據(jù)庫慢查詢、告警通道延遲、需求排期沖突、部署腳本權(quán)限問題、第三方回調(diào)節(jié)流。其中支付接口超時這一主題下分散在 4 篇周報里的信息被匯總成一行risk_item支付接口偶發(fā)超時impact支付鏈路可用性下降部分用戶支付失敗solution接入重試機(jī)制排查上游回調(diào)延遲status已解決第 3 周起未再復(fù)現(xiàn)我看了下這個結(jié)果跟人工整理的高度一致而且標(biāo)注了哪些 chunk 支撐的結(jié)論。從輸入到輸出手寫實(shí)現(xiàn)整個過程大概需要半個工作日REA 跑一次是 40 秒。這就是這個東西的價值所在。5. 踩坑記錄與避坑指南那些文檔里不會寫但你遲早會遇到的問題每次復(fù)盤這類項(xiàng)目真正值錢的其實(shí)不是架構(gòu)多漂亮而是那些讓你耗掉一整個下午的問題。下面這幾個坑我都有切膚之痛寫出來希望你能提前避開。第一個坑向量匹配與字符清洗不一致這是檢索效果差的第一大來源。入庫時做了全角轉(zhuǎn)半角、大小寫統(tǒng)一、去多余空格查詢時沒做同樣處理導(dǎo)致同一句話的兩個版本算出來相似度偏低。解決辦法前面提過把清洗函數(shù)做成公共函數(shù)入庫和查詢強(qiáng)制調(diào)用同一套邏輯。我用這個辦法解決了大量為什么我覺得相關(guān)卻召不回的疑惑。第二個坑切片切斷句子直接廢掉候選固定長度切片導(dǎo)致實(shí)體在切割處被拆開抽取模塊就抽不到完整字段。這是抽取效果差的元兇之一。解決辦法是切片時優(yōu)先找句號、分號、換行符這類邊界寧可多留一點(diǎn)上下文也不切半個句子。REA 里還加了一個二次檢查如果 chunk 末尾不是終止標(biāo)點(diǎn)就把末尾不完整句子挪到下一個 chunk 開頭。第三個坑抽取結(jié)果里混入解釋性廢話生成模型默認(rèn)會附帶解釋比如根據(jù)您提供的文本我提取到以下字段。你可以用提示詞約束只輸出 JSON更可靠的辦法是后處理階段剝除多余文本。我的做法是先檢查輸出能否被 json.loads 解析失敗則用正則提取大括號區(qū)域做二次解析再失敗才觸發(fā)重抽取。這套兜底邏輯讓很多偶發(fā)格式錯誤無聲無息地消失了。第四個坑向量庫更新后相關(guān)性反而下降我給一批文檔重新建了索引發(fā)現(xiàn)同類查詢的召回質(zhì)量下降。排查后發(fā)現(xiàn)舊索引里混著一批已被覆蓋的舊 chunk導(dǎo)致檢索結(jié)果里新舊內(nèi)容混雜。解決辦法是每次重建索引前先清理全部舊向量再執(zhí)行增量寫入。經(jīng)驗(yàn)的歸納就是索引管理要像數(shù)據(jù)庫遷移一樣謹(jǐn)慎別圖省事執(zhí)行全量寫入。第五個坑批量處理時內(nèi)存失控處理大批量文檔時如果一次性把所有文檔讀入內(nèi)存再切片再向量化中等體量語料就可能撐爆內(nèi)存。REA 后來改成流式處理掃描隊列里逐個文檔讀取、切片、向量化、寫庫然后釋放內(nèi)存。這個改動讓批量處理能力和穩(wěn)定性都上了一個臺階。第六個坑調(diào)參之后效果沒法復(fù)現(xiàn)REA 的 threshold、chunk_size 等參數(shù)分散在代碼各處改了一次之后回不去。后來我把所有超參數(shù)集中到一個 dataclass 配置類里并且每次跑批都會把配置快照打到結(jié)果文件的頭部。這樣效果好壞都可以復(fù)現(xiàn)、可以對比排查問題時少走很多彎路。從第一版能跑通到后來真正變成我每周都在用的工具中間最大的感悟就是這類工具的價值不在于用最新最強(qiáng)模型而在于把每個環(huán)節(jié)的邊界、格式、異常處理都做扎實(shí)。如果你也在做類似的東西希望這份記錄能幫你省下一些本該花在調(diào)試上的時間。