行元數(shù)據(jù)提取和檢索優(yōu)化：從文檔解析到可復(fù)制配置)
1. 從一次檢索翻車說起LlamaIndex 元數(shù)據(jù)提取到底解決什么問題先說個(gè)真實(shí)場(chǎng)景。我拿一份 200 多頁的技術(shù)文檔做知識(shí)庫用戶問「這個(gè)接口的超時(shí)參數(shù)默認(rèn)值是多少」向量檢索返回的卻是另一章節(jié)里長(zhǎng)得差不多的配置說明。原因不復(fù)雜純向量檢索只看語義相似度它不知道「這段文字屬于哪個(gè)章節(jié)、講的是哪個(gè)模塊、是概述還是參數(shù)表」。當(dāng)文檔里存在大量結(jié)構(gòu)相似、措辭相近的段落時(shí)檢索就會(huì)在語義空間里迷路。LlamaIndex 的元數(shù)據(jù)提取Metadata Extraction就是沖著這個(gè)痛點(diǎn)來的。它的核心思路是在文檔切分成節(jié)點(diǎn)Node之后、寫入向量索引之前給每個(gè)節(jié)點(diǎn)掛上結(jié)構(gòu)化的附加信息比如這段內(nèi)容回答了哪些問題、它的摘要是什么、它屬于文檔的哪一部分。檢索時(shí)這些元數(shù)據(jù)既能參與向量化metadata_modeEMBED也能作為過濾條件Metadata Filter讓召回結(jié)果從「語義像」升級(jí)到「語義像且結(jié)構(gòu)對(duì)」。適合誰看這篇已經(jīng)在用 LlamaIndex 搭 RAG、但檢索命中率不穩(wěn)定的同學(xué)手里有技術(shù)文檔、產(chǎn)品手冊(cè)、內(nèi)部知識(shí)庫這類半結(jié)構(gòu)化語料想讓問答更準(zhǔn)的開發(fā)者以及想搞清楚 MetadataExtractor、QuestionsAnsweredExtractor、SummaryExtractor 這幾個(gè)類到底怎么配、配完有沒有用的人。我會(huì)按「問題場(chǎng)景 → 前置準(zhǔn)備 → 可復(fù)制配置 → 驗(yàn)證對(duì)比 → 報(bào)錯(cuò)排查」的順序走一遍配置片段都能直接抄。模型調(diào)用這塊我用的是 TaoToken 的兼容接口因?yàn)樗瑫r(shí)支持 OpenAI 風(fēng)格和 Anthropic 風(fēng)格切換模型不用改代碼結(jié)構(gòu)下面會(huì)給出具體配置。需要先明確一個(gè)概念區(qū)分元數(shù)據(jù)提取不等于簡(jiǎn)單的「加個(gè) source 字段」。LlamaIndex 里的提取器是用 LLM 生成元數(shù)據(jù)的也就是說它會(huì)真的去讀你的文本然后產(chǎn)出問題列表、摘要這類語義級(jí)信息。這帶來兩個(gè)后果一是效果好二是要花 token、要控成本。所以配置里的 questions 數(shù)量、summaries 范圍這些參數(shù)都是要在效果和開銷之間做權(quán)衡的后面會(huì)具體講。2. TaoToken 前置準(zhǔn)備Base URL、API Key 與模型 ID 三件套在寫提取器之前得先把模型通道打通。LlamaIndex 默認(rèn)走 OpenAI 的官方地址但實(shí)際項(xiàng)目里我們經(jīng)常需要更靈活的模型接入方式。TaoToken 提供的是 OpenAI 兼容接口所以 LlamaIndex 的OpenAI類可以直接用只需要改api_base和api_key。先拿 Key。打開 https://taotoken.net/api-keys 登錄后創(chuàng)建一個(gè) API Key復(fù)制出來形如sk-...的字符串。這個(gè) Key 就是后面所有配置里的憑證別硬編碼進(jìn)代碼提交到倉庫用環(huán)境變量或者.env管理。Base URL 用https://taotoken.net/api注意這里不帶任何查詢參數(shù)就是干凈的接口根地址。模型 ID 按你實(shí)際要用的填比如gpt-4o-mini、gpt-3.5-turbo這類或者 Anthropic 系的模型 ID。三件套湊齊后LlamaIndex 側(cè)的初始化長(zhǎng)這樣import os from llama_index.llms.openai import OpenAI os.environ[OPENAI_API_KEY] sk-你的key os.environ[OPENAI_API_BASE] https://taotoken.net/api llm OpenAI( modelgpt-4o-mini, temperature0.1, max_tokens512, api_basehttps://taotoken.net/api, api_keyos.environ[OPENAI_API_KEY], )這里有個(gè)容易踩的點(diǎn)LlamaIndex 不同版本對(duì)api_base的讀取方式不完全一致有的版本認(rèn)環(huán)境變量OPENAI_API_BASE有的版本要求你在OpenAI()構(gòu)造時(shí)顯式傳api_base。穩(wěn)妥做法是兩邊都設(shè)上環(huán)境變量兜底、構(gòu)造參數(shù)覆蓋避免出現(xiàn)「明明設(shè)了卻還往官方地址發(fā)請(qǐng)求」的情況。如果你用的是 Anthropic 系模型LlamaIndex 有對(duì)應(yīng)的llama_index.llms.anthropic.Anthropic類同樣把 base 指向 TaoToken 的兼容地址即可。想先確認(rèn)模型通不通可以直接去 https://taotoken.net/models 用對(duì)話界面發(fā)一條測(cè)試消息比在代碼里反復(fù)調(diào)試快得多。關(guān)于成本元數(shù)據(jù)提取是「每個(gè)節(jié)點(diǎn)都要調(diào)一次 LLM」的操作節(jié)點(diǎn)多的時(shí)候 token 消耗不小。建議先用小批量節(jié)點(diǎn)比如 8 到 20 個(gè)跑通流程、看效果確認(rèn)值得再全量跑。這也是我下面驗(yàn)證環(huán)節(jié)只取orig_nodes[20:28]這一小段的原因。3. 可復(fù)制配置MetadataExtractor、節(jié)點(diǎn)切分與索引參數(shù)這一節(jié)是核心把切分器、提取器、索引三部分的配置都攤開講。先看節(jié)點(diǎn)切分因?yàn)樵獢?shù)據(jù)是掛在節(jié)點(diǎn)上的切分粒度直接決定元數(shù)據(jù)的質(zhì)量。from llama_index.core.node_parser import TokenTextSplitter node_parser TokenTextSplitter( separator , chunk_size256, chunk_overlap128, )chunk_size256配合chunk_overlap128是我在技術(shù)文檔上比較常用的組合。重疊給到一半是為了避免一個(gè)完整概念被硬切斷——比如參數(shù)說明和它的默認(rèn)值分在兩個(gè) chunk 里檢索時(shí)只召回一半就答不全。代價(jià)是節(jié)點(diǎn)數(shù)量變多、提取開銷上升你可以按語料密度調(diào)整。接下來是提取器。LlamaIndex 內(nèi)置了好幾種最常用的是QuestionsAnsweredExtractor和SummaryExtractor。前者讓 LLM 針對(duì)每個(gè)節(jié)點(diǎn)生成若干「這段內(nèi)容能回答的問題」后者生成摘要而且SummaryExtractor支持prev、self、next三種范圍也就是能順帶把相鄰節(jié)點(diǎn)的上下文摘要也生成出來。from llama_index.core.schema import MetadataMode from llama_index.core.extractors import ( SummaryExtractor, QuestionsAnsweredExtractor, ) extractors [ SummaryExtractor( summaries[prev, self, next], llmllm, ), QuestionsAnsweredExtractor( questions3, llmllm, metadata_modeMetadataMode.EMBED, ), ]metadata_modeMetadataMode.EMBED這個(gè)參數(shù)值得單獨(dú)說。它決定生成的元數(shù)據(jù)是「嵌入到文本里一起向量化」還是「只作為過濾字段存在」。設(shè)成EMBED時(shí)生成的問題會(huì)被拼進(jìn)節(jié)點(diǎn)文本再算 embedding這樣檢索時(shí)用戶的問題更容易和「節(jié)點(diǎn)能回答的問題」在向量空間對(duì)上召回率提升明顯。如果設(shè)成MetadataMode.LLM元數(shù)據(jù)只在生成答案階段喂給 LLM不參與檢索。兩種模式可以組合使用看你更想優(yōu)化召回還是優(yōu)化生成。把切分和提取串成流水線from llama_index.core.ingestion import IngestionPipeline pipeline IngestionPipeline( transformations[node_parser, *extractors], ) nodes pipeline.run( nodesorig_nodes[20:28], in_placeFalse, show_progressTrue, )in_placeFalse表示不改動(dòng)原始節(jié)點(diǎn)返回帶元數(shù)據(jù)的新節(jié)點(diǎn)方便你做 A/B 對(duì)比。show_progressTrue在節(jié)點(diǎn)多的時(shí)候能讓你看到進(jìn)度不然會(huì)以為卡死了。最后建索引。為了對(duì)比效果我建三個(gè)索引一個(gè)純?cè)脊?jié)點(diǎn)、一個(gè)只加問題提取器、一個(gè)問題加摘要都加。from llama_index.core import VectorStoreIndex index0 VectorStoreIndex(orig_nodes) index1 VectorStoreIndex(orig_nodes[:20] nodes_q orig_nodes[28:]) index2 VectorStoreIndex(orig_nodes[:20] nodes_full orig_nodes[28:])注意這里把替換后的節(jié)點(diǎn)拼回原列表保證三個(gè)索引覆蓋的文檔范圍一致只有中間那 8 個(gè)節(jié)點(diǎn)的元數(shù)據(jù)不同這樣對(duì)比才公平。如果你用外部向量庫比如 Chroma、Milvus配置里還要帶上storage_context但元數(shù)據(jù)的生成邏輯完全一樣。4. 驗(yàn)證請(qǐng)求與成功結(jié)果命中率對(duì)比怎么做才靠譜配置跑通不代表有效得用數(shù)據(jù)說話。驗(yàn)證的核心動(dòng)作是固定一個(gè)查詢分別打到三個(gè)索引上看返回的source_nodes是不是你想要的那段內(nèi)容。query_engine0 index0.as_query_engine(similarity_top_k1) query_engine1 index1.as_query_engine(similarity_top_k1) query_engine2 index2.as_query_engine(similarity_top_k1) query_str 這個(gè)接口的超時(shí)參數(shù)默認(rèn)值是多少單位是什么 for name, qe in [(baseline, query_engine0), (questions, query_engine1), (full, query_engine2)]: resp qe.query(query_str) print(f {name} ) print(resp.source_nodes[0].node.get_content()[:200])similarity_top_k1是為了放大差異——只給一個(gè)名額誰最相關(guān)誰上元數(shù)據(jù)有沒有用一眼就能看出來。實(shí)際生產(chǎn)里 top_k 一般給 3 到 5但做對(duì)比實(shí)驗(yàn)時(shí) top_k1 最直觀。成功的結(jié)果長(zhǎng)什么樣baseline 索引返回的往往是「語義相近但章節(jié)不對(duì)」的段落比如講的是另一個(gè)模塊的超時(shí)配置加了QuestionsAnsweredExtractor之后因?yàn)楣?jié)點(diǎn)文本里嵌入了「這個(gè)接口的超時(shí)默認(rèn)值是多少」這類生成問題用戶 query 和它的向量距離明顯拉近返回的段落開始命中正確章節(jié)再加上SummaryExtractor的prev/next摘要節(jié)點(diǎn)帶上了上下文線索對(duì)于「這個(gè)參數(shù)在整篇文檔里怎么定位」這類問題召回更穩(wěn)。我實(shí)測(cè)下來在技術(shù)文檔語料上只加問題提取器通常就能把 top-1 命中率從六成左右提到八成上下摘要提取器對(duì)「需要跨段理解」的查詢?cè)鲆娓黠@。當(dāng)然這個(gè)數(shù)字跟語料結(jié)構(gòu)強(qiáng)相關(guān)你的文檔越規(guī)整、章節(jié)越清晰元數(shù)據(jù)收益越大如果語料本身就是零散短文本提升可能有限。驗(yàn)證時(shí)建議準(zhǔn)備一組10 到 20 條有標(biāo)準(zhǔn)答案的查詢?nèi)斯?biāo)注每條應(yīng)該命中哪個(gè)節(jié)點(diǎn)然后統(tǒng)計(jì)三個(gè)索引的命中率。單條查詢的對(duì)比只能看趨勢(shì)成組統(tǒng)計(jì)才有說服力。另外記得把resp.source_nodes[0].node.metadata打出來看看確認(rèn)生成的元數(shù)據(jù)字段真的掛上去了而不是提取器靜默失敗。5. 本篇常見錯(cuò)排查401、local proxy failed 與 reading choices跑這套流程報(bào)錯(cuò)基本集中在幾個(gè)地方我按遇到頻率排一下。401 Unauthorized / invalid api key。最常見的原因是 Key 沒設(shè)對(duì)或者沒生效。檢查順序先確認(rèn)os.environ[OPENAI_API_KEY]真的被賦值了打印前幾位看看再確認(rèn)api_base指向的是https://taotoken.net/api而不是官方地址。如果環(huán)境里同時(shí)存在多個(gè) Key 變量LlamaIndex 可能讀到了舊的。還有一種情況是 Key 復(fù)制時(shí)帶了空格或換行肉眼看不出來用.strip()處理一下。local proxy failed / connection error。這類報(bào)錯(cuò)通常是網(wǎng)絡(luò)層的問題不是代碼問題。先確認(rèn)你的運(yùn)行環(huán)境能正常訪問https://taotoken.net/api可以用curl發(fā)一個(gè)最簡(jiǎn)單的請(qǐng)求驗(yàn)證連通性。如果是在容器或受限網(wǎng)絡(luò)里跑檢查出口規(guī)則。注意別把這類問題和「需要特殊網(wǎng)絡(luò)工具」混為一談絕大多數(shù)情況是 DNS、防火墻白名單或者 base url 拼錯(cuò)導(dǎo)致的。Error reading choices / KeyError: choices。這個(gè)報(bào)錯(cuò)說明請(qǐng)求發(fā)出去了、也收到響應(yīng)了但響應(yīng)結(jié)構(gòu)不是 OpenAI 標(biāo)準(zhǔn)格式。常見原因是模型 ID 填錯(cuò)或者用了一個(gè)不兼容 OpenAI 響應(yīng)格式的接口。解決辦法是確認(rèn)模型 ID 在 TaoToken 的模型列表里存在并且走的是兼容接口。如果響應(yīng)體里是error字段而不是choices把完整響應(yīng)打出來看錯(cuò)誤信息通常寫得很清楚。OAuth / authentication 相關(guān)報(bào)錯(cuò)。如果你用的是 Anthropic 系模型認(rèn)證方式和 OpenAI 不同別把 OpenAI 的 Key 塞給 Anthropic 客戶端。兩邊分別用各自的 Key 和 base 配置。LlamaIndex 里 Anthropic 的初始化參數(shù)名也不一樣注意看對(duì)應(yīng)類的簽名。提取器靜默不生效。沒有報(bào)錯(cuò)但node.metadata里空空如也。檢查IngestionPipeline的transformations列表里提取器有沒有真的加進(jìn)去以及pipeline.run()的返回值有沒有被正確使用。有時(shí)候是in_place參數(shù)理解錯(cuò)了以為原節(jié)點(diǎn)被改了其實(shí)返回的是新列表。排查這類問題的通用思路把 LLM 調(diào)用單獨(dú)拎出來測(cè)一次確認(rèn)模型通道沒問題再測(cè)提取器確認(rèn)元數(shù)據(jù)能生成最后測(cè)索引和檢索。分層定位比一上來就懷疑整個(gè)鏈路快得多。6. 把元數(shù)據(jù)用起來從檢索優(yōu)化到長(zhǎng)期編碼工作流元數(shù)據(jù)提取配好之后檢索優(yōu)化只是第一步。真正讓這套東西產(chǎn)生持續(xù)價(jià)值的是把它接進(jìn)你的日常開發(fā)流。比如你在做一個(gè)代碼知識(shí)庫可以把文件路徑、模塊名、函數(shù)簽名作為結(jié)構(gòu)化元數(shù)據(jù)檢索時(shí)用MetadataFilters做精確過濾再疊加語義召回命中率會(huì)比純向量高一個(gè)檔次。如果你經(jīng)常需要跑這類「批量調(diào) LLM 處理文檔」的任務(wù)可以考慮用 Coding Plan 把模型調(diào)用額度固定下來避免按次計(jì)費(fèi)帶來的成本波動(dòng)具體在 https://taotoken.net/coding-plan 看。對(duì)于需要反復(fù)調(diào)試提取器參數(shù)的場(chǎng)景直接在 https://taotoken.net/chat 里用對(duì)話界面快速試 prompt 效果比每次改代碼重跑快得多。接入文檔在 https://taotoken.net/doc 里面有各語言、各框架的完整示例LlamaIndex 的配置也能在里面找到對(duì)應(yīng)說明。API Key 管理還是回到 https://taotoken.net/api-keys 。最后給個(gè)實(shí)用建議元數(shù)據(jù)提取的 prompt 是可以自定義的。QuestionsAnsweredExtractor和SummaryExtractor都接受自定義 prompt 模板你可以針對(duì)自己的領(lǐng)域調(diào)整提問角度。比如技術(shù)文檔就讓它多生成「參數(shù)含義」「調(diào)用示例」「錯(cuò)誤碼」這類問題比默認(rèn)的通用提問更貼合實(shí)際查詢。這一步的調(diào)優(yōu)收益往往比換模型還大。 使用LlamaIndex進(jìn)行元數(shù)據(jù)提取和檢索優(yōu)化：從文檔解析到可復(fù)制配置
1. 從一次檢索翻車說起LlamaIndex 元數(shù)據(jù)提取到底解決什么問題先說個(gè)真實(shí)場(chǎng)景。我拿一份 200 多頁的技術(shù)文檔做知識(shí)庫用戶問「這個(gè)接口的超時(shí)參數(shù)默認(rèn)值是多少」向量檢索返回的卻是另一章節(jié)里長(zhǎng)得差不多的配置說明。原因不復(fù)雜純向量檢索只看語義相似度它不知道「這段文字屬于哪個(gè)章節(jié)、講的是哪個(gè)模塊、是概述還是參數(shù)表」。當(dāng)文檔里存在大量結(jié)構(gòu)相似、措辭相近的段落時(shí)檢索就會(huì)在語義空間里迷路。LlamaIndex 的元數(shù)據(jù)提取Metadata Extraction就是沖著這個(gè)痛點(diǎn)來的。它的核心思路是在文檔切分成節(jié)點(diǎn)Node之后、寫入向量索引之前給每個(gè)節(jié)點(diǎn)掛上結(jié)構(gòu)化的附加信息比如這段內(nèi)容回答了哪些問題、它的摘要是什么、它屬于文檔的哪一部分。檢索時(shí)這些元數(shù)據(jù)既能參與向量化metadata_modeEMBED也能作為過濾條件Metadata Filter讓召回結(jié)果從「語義像」升級(jí)到「語義像且結(jié)構(gòu)對(duì)」。適合誰看這篇已經(jīng)在用 LlamaIndex 搭 RAG、但檢索命中率不穩(wěn)定的同學(xué)手里有技術(shù)文檔、產(chǎn)品手冊(cè)、內(nèi)部知識(shí)庫這類半結(jié)構(gòu)化語料想讓問答更準(zhǔn)的開發(fā)者以及想搞清楚 MetadataExtractor、QuestionsAnsweredExtractor、SummaryExtractor 這幾個(gè)類到底怎么配、配完有沒有用的人。我會(huì)按「問題場(chǎng)景 → 前置準(zhǔn)備 → 可復(fù)制配置 → 驗(yàn)證對(duì)比 → 報(bào)錯(cuò)排查」的順序走一遍配置片段都能直接抄。模型調(diào)用這塊我用的是 TaoToken 的兼容接口因?yàn)樗瑫r(shí)支持 OpenAI 風(fēng)格和 Anthropic 風(fēng)格切換模型不用改代碼結(jié)構(gòu)下面會(huì)給出具體配置。需要先明確一個(gè)概念區(qū)分元數(shù)據(jù)提取不等于簡(jiǎn)單的「加個(gè) source 字段」。LlamaIndex 里的提取器是用 LLM 生成元數(shù)據(jù)的也就是說它會(huì)真的去讀你的文本然后產(chǎn)出問題列表、摘要這類語義級(jí)信息。這帶來兩個(gè)后果一是效果好二是要花 token、要控成本。所以配置里的 questions 數(shù)量、summaries 范圍這些參數(shù)都是要在效果和開銷之間做權(quán)衡的后面會(huì)具體講。2. TaoToken 前置準(zhǔn)備Base URL、API Key 與模型 ID 三件套在寫提取器之前得先把模型通道打通。LlamaIndex 默認(rèn)走 OpenAI 的官方地址但實(shí)際項(xiàng)目里我們經(jīng)常需要更靈活的模型接入方式。TaoToken 提供的是 OpenAI 兼容接口所以 LlamaIndex 的OpenAI類可以直接用只需要改api_base和api_key。先拿 Key。打開 https://taotoken.net/api-keys 登錄后創(chuàng)建一個(gè) API Key復(fù)制出來形如sk-...的字符串。這個(gè) Key 就是后面所有配置里的憑證別硬編碼進(jìn)代碼提交到倉庫用環(huán)境變量或者.env管理。Base URL 用https://taotoken.net/api注意這里不帶任何查詢參數(shù)就是干凈的接口根地址。模型 ID 按你實(shí)際要用的填比如gpt-4o-mini、gpt-3.5-turbo這類或者 Anthropic 系的模型 ID。三件套湊齊后LlamaIndex 側(cè)的初始化長(zhǎng)這樣import os from llama_index.llms.openai import OpenAI os.environ[OPENAI_API_KEY] sk-你的key os.environ[OPENAI_API_BASE] https://taotoken.net/api llm OpenAI( modelgpt-4o-mini, temperature0.1, max_tokens512, api_basehttps://taotoken.net/api, api_keyos.environ[OPENAI_API_KEY], )這里有個(gè)容易踩的點(diǎn)LlamaIndex 不同版本對(duì)api_base的讀取方式不完全一致有的版本認(rèn)環(huán)境變量OPENAI_API_BASE有的版本要求你在OpenAI()構(gòu)造時(shí)顯式傳api_base。穩(wěn)妥做法是兩邊都設(shè)上環(huán)境變量兜底、構(gòu)造參數(shù)覆蓋避免出現(xiàn)「明明設(shè)了卻還往官方地址發(fā)請(qǐng)求」的情況。如果你用的是 Anthropic 系模型LlamaIndex 有對(duì)應(yīng)的llama_index.llms.anthropic.Anthropic類同樣把 base 指向 TaoToken 的兼容地址即可。想先確認(rèn)模型通不通可以直接去 https://taotoken.net/models 用對(duì)話界面發(fā)一條測(cè)試消息比在代碼里反復(fù)調(diào)試快得多。關(guān)于成本元數(shù)據(jù)提取是「每個(gè)節(jié)點(diǎn)都要調(diào)一次 LLM」的操作節(jié)點(diǎn)多的時(shí)候 token 消耗不小。建議先用小批量節(jié)點(diǎn)比如 8 到 20 個(gè)跑通流程、看效果確認(rèn)值得再全量跑。這也是我下面驗(yàn)證環(huán)節(jié)只取orig_nodes[20:28]這一小段的原因。3. 可復(fù)制配置MetadataExtractor、節(jié)點(diǎn)切分與索引參數(shù)這一節(jié)是核心把切分器、提取器、索引三部分的配置都攤開講。先看節(jié)點(diǎn)切分因?yàn)樵獢?shù)據(jù)是掛在節(jié)點(diǎn)上的切分粒度直接決定元數(shù)據(jù)的質(zhì)量。from llama_index.core.node_parser import TokenTextSplitter node_parser TokenTextSplitter( separator , chunk_size256, chunk_overlap128, )chunk_size256配合chunk_overlap128是我在技術(shù)文檔上比較常用的組合。重疊給到一半是為了避免一個(gè)完整概念被硬切斷——比如參數(shù)說明和它的默認(rèn)值分在兩個(gè) chunk 里檢索時(shí)只召回一半就答不全。代價(jià)是節(jié)點(diǎn)數(shù)量變多、提取開銷上升你可以按語料密度調(diào)整。接下來是提取器。LlamaIndex 內(nèi)置了好幾種最常用的是QuestionsAnsweredExtractor和SummaryExtractor。前者讓 LLM 針對(duì)每個(gè)節(jié)點(diǎn)生成若干「這段內(nèi)容能回答的問題」后者生成摘要而且SummaryExtractor支持prev、self、next三種范圍也就是能順帶把相鄰節(jié)點(diǎn)的上下文摘要也生成出來。from llama_index.core.schema import MetadataMode from llama_index.core.extractors import ( SummaryExtractor, QuestionsAnsweredExtractor, ) extractors [ SummaryExtractor( summaries[prev, self, next], llmllm, ), QuestionsAnsweredExtractor( questions3, llmllm, metadata_modeMetadataMode.EMBED, ), ]metadata_modeMetadataMode.EMBED這個(gè)參數(shù)值得單獨(dú)說。它決定生成的元數(shù)據(jù)是「嵌入到文本里一起向量化」還是「只作為過濾字段存在」。設(shè)成EMBED時(shí)生成的問題會(huì)被拼進(jìn)節(jié)點(diǎn)文本再算 embedding這樣檢索時(shí)用戶的問題更容易和「節(jié)點(diǎn)能回答的問題」在向量空間對(duì)上召回率提升明顯。如果設(shè)成MetadataMode.LLM元數(shù)據(jù)只在生成答案階段喂給 LLM不參與檢索。兩種模式可以組合使用看你更想優(yōu)化召回還是優(yōu)化生成。把切分和提取串成流水線from llama_index.core.ingestion import IngestionPipeline pipeline IngestionPipeline( transformations[node_parser, *extractors], ) nodes pipeline.run( nodesorig_nodes[20:28], in_placeFalse, show_progressTrue, )in_placeFalse表示不改動(dòng)原始節(jié)點(diǎn)返回帶元數(shù)據(jù)的新節(jié)點(diǎn)方便你做 A/B 對(duì)比。show_progressTrue在節(jié)點(diǎn)多的時(shí)候能讓你看到進(jìn)度不然會(huì)以為卡死了。最后建索引。為了對(duì)比效果我建三個(gè)索引一個(gè)純?cè)脊?jié)點(diǎn)、一個(gè)只加問題提取器、一個(gè)問題加摘要都加。from llama_index.core import VectorStoreIndex index0 VectorStoreIndex(orig_nodes) index1 VectorStoreIndex(orig_nodes[:20] nodes_q orig_nodes[28:]) index2 VectorStoreIndex(orig_nodes[:20] nodes_full orig_nodes[28:])注意這里把替換后的節(jié)點(diǎn)拼回原列表保證三個(gè)索引覆蓋的文檔范圍一致只有中間那 8 個(gè)節(jié)點(diǎn)的元數(shù)據(jù)不同這樣對(duì)比才公平。如果你用外部向量庫比如 Chroma、Milvus配置里還要帶上storage_context但元數(shù)據(jù)的生成邏輯完全一樣。4. 驗(yàn)證請(qǐng)求與成功結(jié)果命中率對(duì)比怎么做才靠譜配置跑通不代表有效得用數(shù)據(jù)說話。驗(yàn)證的核心動(dòng)作是固定一個(gè)查詢分別打到三個(gè)索引上看返回的source_nodes是不是你想要的那段內(nèi)容。query_engine0 index0.as_query_engine(similarity_top_k1) query_engine1 index1.as_query_engine(similarity_top_k1) query_engine2 index2.as_query_engine(similarity_top_k1) query_str 這個(gè)接口的超時(shí)參數(shù)默認(rèn)值是多少單位是什么 for name, qe in [(baseline, query_engine0), (questions, query_engine1), (full, query_engine2)]: resp qe.query(query_str) print(f {name} ) print(resp.source_nodes[0].node.get_content()[:200])similarity_top_k1是為了放大差異——只給一個(gè)名額誰最相關(guān)誰上元數(shù)據(jù)有沒有用一眼就能看出來。實(shí)際生產(chǎn)里 top_k 一般給 3 到 5但做對(duì)比實(shí)驗(yàn)時(shí) top_k1 最直觀。成功的結(jié)果長(zhǎng)什么樣baseline 索引返回的往往是「語義相近但章節(jié)不對(duì)」的段落比如講的是另一個(gè)模塊的超時(shí)配置加了QuestionsAnsweredExtractor之后因?yàn)楣?jié)點(diǎn)文本里嵌入了「這個(gè)接口的超時(shí)默認(rèn)值是多少」這類生成問題用戶 query 和它的向量距離明顯拉近返回的段落開始命中正確章節(jié)再加上SummaryExtractor的prev/next摘要節(jié)點(diǎn)帶上了上下文線索對(duì)于「這個(gè)參數(shù)在整篇文檔里怎么定位」這類問題召回更穩(wěn)。我實(shí)測(cè)下來在技術(shù)文檔語料上只加問題提取器通常就能把 top-1 命中率從六成左右提到八成上下摘要提取器對(duì)「需要跨段理解」的查詢?cè)鲆娓黠@。當(dāng)然這個(gè)數(shù)字跟語料結(jié)構(gòu)強(qiáng)相關(guān)你的文檔越規(guī)整、章節(jié)越清晰元數(shù)據(jù)收益越大如果語料本身就是零散短文本提升可能有限。驗(yàn)證時(shí)建議準(zhǔn)備一組10 到 20 條有標(biāo)準(zhǔn)答案的查詢?nèi)斯?biāo)注每條應(yīng)該命中哪個(gè)節(jié)點(diǎn)然后統(tǒng)計(jì)三個(gè)索引的命中率。單條查詢的對(duì)比只能看趨勢(shì)成組統(tǒng)計(jì)才有說服力。另外記得把resp.source_nodes[0].node.metadata打出來看看確認(rèn)生成的元數(shù)據(jù)字段真的掛上去了而不是提取器靜默失敗。5. 本篇常見錯(cuò)排查401、local proxy failed 與 reading choices跑這套流程報(bào)錯(cuò)基本集中在幾個(gè)地方我按遇到頻率排一下。401 Unauthorized / invalid api key。最常見的原因是 Key 沒設(shè)對(duì)或者沒生效。檢查順序先確認(rèn)os.environ[OPENAI_API_KEY]真的被賦值了打印前幾位看看再確認(rèn)api_base指向的是https://taotoken.net/api而不是官方地址。如果環(huán)境里同時(shí)存在多個(gè) Key 變量LlamaIndex 可能讀到了舊的。還有一種情況是 Key 復(fù)制時(shí)帶了空格或換行肉眼看不出來用.strip()處理一下。local proxy failed / connection error。這類報(bào)錯(cuò)通常是網(wǎng)絡(luò)層的問題不是代碼問題。先確認(rèn)你的運(yùn)行環(huán)境能正常訪問https://taotoken.net/api可以用curl發(fā)一個(gè)最簡(jiǎn)單的請(qǐng)求驗(yàn)證連通性。如果是在容器或受限網(wǎng)絡(luò)里跑檢查出口規(guī)則。注意別把這類問題和「需要特殊網(wǎng)絡(luò)工具」混為一談絕大多數(shù)情況是 DNS、防火墻白名單或者 base url 拼錯(cuò)導(dǎo)致的。Error reading choices / KeyError: choices。這個(gè)報(bào)錯(cuò)說明請(qǐng)求發(fā)出去了、也收到響應(yīng)了但響應(yīng)結(jié)構(gòu)不是 OpenAI 標(biāo)準(zhǔn)格式。常見原因是模型 ID 填錯(cuò)或者用了一個(gè)不兼容 OpenAI 響應(yīng)格式的接口。解決辦法是確認(rèn)模型 ID 在 TaoToken 的模型列表里存在并且走的是兼容接口。如果響應(yīng)體里是error字段而不是choices把完整響應(yīng)打出來看錯(cuò)誤信息通常寫得很清楚。OAuth / authentication 相關(guān)報(bào)錯(cuò)。如果你用的是 Anthropic 系模型認(rèn)證方式和 OpenAI 不同別把 OpenAI 的 Key 塞給 Anthropic 客戶端。兩邊分別用各自的 Key 和 base 配置。LlamaIndex 里 Anthropic 的初始化參數(shù)名也不一樣注意看對(duì)應(yīng)類的簽名。提取器靜默不生效。沒有報(bào)錯(cuò)但node.metadata里空空如也。檢查IngestionPipeline的transformations列表里提取器有沒有真的加進(jìn)去以及pipeline.run()的返回值有沒有被正確使用。有時(shí)候是in_place參數(shù)理解錯(cuò)了以為原節(jié)點(diǎn)被改了其實(shí)返回的是新列表。排查這類問題的通用思路把 LLM 調(diào)用單獨(dú)拎出來測(cè)一次確認(rèn)模型通道沒問題再測(cè)提取器確認(rèn)元數(shù)據(jù)能生成最后測(cè)索引和檢索。分層定位比一上來就懷疑整個(gè)鏈路快得多。6. 把元數(shù)據(jù)用起來從檢索優(yōu)化到長(zhǎng)期編碼工作流元數(shù)據(jù)提取配好之后檢索優(yōu)化只是第一步。真正讓這套東西產(chǎn)生持續(xù)價(jià)值的是把它接進(jìn)你的日常開發(fā)流。比如你在做一個(gè)代碼知識(shí)庫可以把文件路徑、模塊名、函數(shù)簽名作為結(jié)構(gòu)化元數(shù)據(jù)檢索時(shí)用MetadataFilters做精確過濾再疊加語義召回命中率會(huì)比純向量高一個(gè)檔次。如果你經(jīng)常需要跑這類「批量調(diào) LLM 處理文檔」的任務(wù)可以考慮用 Coding Plan 把模型調(diào)用額度固定下來避免按次計(jì)費(fèi)帶來的成本波動(dòng)具體在 https://taotoken.net/coding-plan 看。對(duì)于需要反復(fù)調(diào)試提取器參數(shù)的場(chǎng)景直接在 https://taotoken.net/chat 里用對(duì)話界面快速試 prompt 效果比每次改代碼重跑快得多。接入文檔在 https://taotoken.net/doc 里面有各語言、各框架的完整示例LlamaIndex 的配置也能在里面找到對(duì)應(yīng)說明。API Key 管理還是回到 https://taotoken.net/api-keys 。最后給個(gè)實(shí)用建議元數(shù)據(jù)提取的 prompt 是可以自定義的。QuestionsAnsweredExtractor和SummaryExtractor都接受自定義 prompt 模板你可以針對(duì)自己的領(lǐng)域調(diào)整提問角度。比如技術(shù)文檔就讓它多生成「參數(shù)含義」「調(diào)用示例」「錯(cuò)誤碼」這類問題比默認(rèn)的通用提問更貼合實(shí)際查詢。這一步的調(diào)優(yōu)收益往往比換模型還大。