llama_index KeywordTableIndex 检索器完全指南BaseKeywordTableRetriever 与 GPT / Simple / RAKE 三种检索模式深度解析【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文基于 llama_index 仓库 中关于 keyword table 检索器的 API 文档结合llama-index-core的源码实现系统讲解 KeywordTableIndex 的四类检索器BaseKeywordTableRetriever、KeywordTableGPTRetriever、KeywordTableSimpleRetriever、KeywordTableRAKERetriever的设计原理、参数语义、底层检索算法与实战用法。读完本文你将掌握如何在不同场景下选择合适的检索模式并理解关键词表索引从关键词提取 → 关键词匹配 → 分块排序 → 节点召回的完整检索链路。KeywordTableIndex 检索器家族一图看懂四类检索器KeywordTableIndex 是 llama_index 中一种模仿哈希表hash table设计的关键词索引结构构建索引时从每个文本块中提取关键词建立关键词 → 文本块的映射表查询时再从查询语句中提取关键词通过映射表反查候选文本块。与之配套的检索器定义在 llama-index-core/llama_index/core/indices/keyword_table/retrievers.py包括四个类构成清晰的继承与分工体系类名定位关键词提取方式对应retriever_modeBaseKeywordTableRetriever抽象基类定义共享参数与通用检索流程抽象方法_get_keywords由子类实现—KeywordTableGPTRetriever默认检索器调用 LLM 提取关键词self._llm.predict(query_keyword_extract_template, ...)defaultKeywordTableSimpleRetriever轻量检索器正则表达式提取关键词simple_extract_keywordssimpleKeywordTableRAKERetriever使用 RAKE 算法提取关键词rake_extract_keywords依赖 nltk / rake_nltkrake三个具体检索器分别对应 KeywordTableRetrieverMode 枚举中的DEFAULT、SIMPLE、RAKE三个成员。BaseKeywordTableIndex.as_retriever()方法会根据传入的retriever_mode自动分发并实例化对应的检索器见 base.pyretriever_modedefault→KeywordTableGPTRetriever并把索引构建时使用的 LLM 一并传入retriever_modesimple→KeywordTableSimpleRetriever全程不依赖 LLMretriever_moderake→KeywordTableRAKERetriever同样不依赖 LLM其他取值会抛出ValueError(fUnknown retriever mode: {retriever_mode})。注意即使使用KeywordTableIndexGPT 建索引查询时也可以切换为simple或rake模式反之SimpleKeywordTableIndex见 simple_base.py与RAKEKeywordTableIndex见 rake_base.py也各自将默认的retriever_mode固定为SIMPLE与RAKE并复用父类的as_retriever分发逻辑。核心参数详解max_keywords_per_query 与 num_chunks_per_queryBaseKeywordTableRetriever.__init__定义了所有子类共享的构造参数默认值均来自源码见 retrievers.py参数类型默认值作用indexBaseKeywordTableIndex必填检索器绑定的索引对象内部持有index_struct关键词表与docstore节点存储keyword_extract_templateOptional[BasePromptTemplate]DEFAULT_KEYWORD_EXTRACT_TEMPLATE建索引时的关键词提取 Prompt由索引侧使用query_keyword_extract_templateOptional[BasePromptTemplate]DEFAULT_QUERY_KEYWORD_EXTRACT_TEMPLATE查询时的关键词提取 Prompt用于从 query 中提取关键词max_keywords_per_queryint10从查询语句中最多提取的关键词数量直接控制检索的查询面num_chunks_per_queryint10单次查询最多召回并送入后续合成的文本块数量是检索的深度截断上限callback_managerOptional[CallbackManager]Settings.callback_manager回调管理器默认从全局 Settings 获取object_mapOptional[dict]None对象映射用于反序列化场景verboseboolFalse是否输出详细信息其中max_keywords_per_query与num_chunks_per_query是决定检索行为与成本的两个最关键参数max_keywords_per_query越大越能覆盖查询语句的多个语义侧面但也会带来更多噪声关键词增加无效匹配num_chunks_per_query直接限制最终进入答案合成的候选块数量。它在语义上对应官方 README见 llama-index-core/llama_index/core/indices/keyword_table/README.md中描述的截断值 $d$候选文本块按匹配关键词数量从高到低排序后只保留前 $d$ 个。KeywordTableGPTRetriever额外接收llm参数默认取Settings.llm因为 default 模式必须依赖 LLM 完成查询关键词提取。检索主流程源码解析从关键词到节点的三步召回BaseKeywordTableRetriever._retrieveretrievers.py实现了所有模式共用的检索骨架整个流程可拆解为三步第一步提取并过滤查询关键词。调用抽象方法self._get_keywords(query_bundle.query_str)得到关键词列表后立刻用keywords [k for k in keywords if k in self._index_struct.keywords]做过滤——只有索引表中真实存在的关键词才会进入下一步这一步天然屏蔽了查询关键词与索引关键词不匹配造成的无效计算。第二步按匹配数统计并排序文本块。使用defaultdict(int)遍历每个有效关键词对应的节点 ID 列表累计每个文本块命中的关键词数量chunk_indices_count[node_id] 1随后按命中数降序排序并截断到num_chunks_per_query个。第三步从 docstore 批量取回节点。通过self._docstore.get_nodes(sorted_chunk_indices)一次性取回排序后的节点。在 DEBUG 日志级别下会打印每个被查询文本块的内容前缀通过truncate_text(..., 50)截断到 50 字符。最终以NodeWithScore列表返回注意返回的节点本身不携带相似度分数其排序语义蕴含在列表顺序中。三个子类的差异完全集中在第一步的_get_keywords实现KeywordTableGPTRetrieverself._llm.predict(self.query_keyword_extract_template, max_keywords..., questionquery_str)再用extract_keywords_given_response(response, start_tokenKEYWORDS:)解析 LLM 输出要求以KEYWORDS:前缀开头逗号分隔KeywordTableSimpleRetriever直接调用simple_extract_keywords(query_str, max_keywords...)KeywordTableRAKERetriever调用rake_extract_keywords(query_str, max_keywords...)。底层关键词提取算法正则、RAKE 与 LLM 解析三种提取算法均实现于 llama-index-core/llama_index/core/indices/keyword_table/utils.py理解它们有助于判断何时选用哪种模式。simple正则 词频simple_extract_keywords先用re.findall(r\w, text)切出词元并统一转小写然后按globals_helper.stopwords过滤停用词最后用Counter.most_common(max_keywords)按词频从高到低截取。它的特点是零依赖、速度快但只支持单词关键词且对同义改写不敏感。rakeRAKE 算法rake_extract_keywords依赖nltk与rake_nltk两个第三方库缺失时会抛出带安装提示的ImportError提示pip install nltk/pip install rake_nltk。它使用Rake(sentence_tokenizernltk.tokenize.sent_tokenize, word_tokenizernltk.tokenize.wordpunct_tokenize)对文本打分取排名靠前的max_keywords个短语并默认通过expand_tokens_with_subtokens将多词短语展开为子词从而支持短语级关键词如new york city。GPTLLM 解析extract_keywords_given_response负责把 LLM 的返回文本解析为关键词集合剥离可选前缀start_token默认KEYWORDS:按逗号切分、去空白、统一小写最后同样做子词展开。该函数既被索引构建期KeywordTableIndex._extract_keywords见 base.py使用也被查询期GPT 检索器使用。默认 Prompt 模板建索引与查索引的两种提示词KeywordTableGPTRetriever查询时使用的默认模板定义在 llama-index-core/llama_index/core/prompts/default_prompts.py与建索引模板DEFAULT_KEYWORD_EXTRACT_TEMPLATEPromptType.KEYWORD_EXTRACT相对应建索引模板指令为从给定文本中提取至多{max_keywords}个关键词避免停用词要求以KEYWORDS: keywords的逗号分隔格式输出查询模板DEFAULT_QUERY_KEYWORD_EXTRACT_TEMPLATEPromptType.QUERY_KEYWORD_EXTRACT指令为从给定问题中提取至多{max_keywords}个关键词聚焦于能最好地用于查找问题答案的关键词避免停用词同样要求KEYWORDS:前缀输出。两者共享{max_keywords}占位符建索引侧由BaseKeywordTableIndex.__init__通过partial_format(max_keywordsself.max_keywords_per_chunk)预填充默认每块 10 个关键词见 base.py查询侧则由检索器在调用predict时以max_keywordsself.max_keywords_per_query填充。若你想自定义提取行为可在构造检索器时传入自定义的query_keyword_extract_template。实战用法三种模式如何切换官方 README 给出了最基础的用法见 README.mdfrom llama_index.core import KeywordTableIndex, SimpleDirectoryReader # 构建索引默认使用 LLM 提取关键词 documents SimpleDirectoryReader(data).load_data() index KeywordTableIndex.from_documents(documents) # 默认查询GPT 检索器 query_engine index.as_query_engine() response query_engine.query(question text)若需要显式控制检索器模式可通过as_retriever(retriever_mode...)拿到检索器再组装查询引擎三种模式完全等价地切换from llama_index.core import KeywordTableIndex, SimpleDirectoryReader from llama_index.core.schema import QueryBundle index KeywordTableIndex.from_documents( SimpleDirectoryReader(data).load_data() ) # 模式一default —— LLM 提取关键词推荐效果最好 gpt_retriever index.as_retriever(retriever_modedefault) # 模式二simple —— 零 LLM 依赖正则词频 simple_retriever index.as_retriever(retriever_modesimple) # 模式三rake —— 短语级关键词需先 pip install nltk rake_nltk rake_retriever index.as_retriever(retriever_moderake) # 三种检索器都接受 QueryBundle返回按匹配度排序的 NodeWithScore 列表 nodes simple_retriever.retrieve(QueryBundle(Hello)) for node in nodes: print(node.node.get_content())检索到节点后回答的构造遵循create-and-refine先创建、再精炼范式先用第一个文本块生成初始答案再逐个喂入后续文本块进行精炼——精炼可能是保持原答案、小幅修改或彻底重写。这一机制同样是 KeywordTableIndex 查询链路的一部分说明了num_chunks_per_query为何直接影响答案质量与 LLM 调用次数。此外索引构建侧也提供三个独立入口类KeywordTableIndexGPT 提取、SimpleKeywordTableIndex正则提取与RAKEKeywordTableIndexRAKE 提取后两者把关键词提取与查询阶段都固定在无 LLM 模式适合离线、低成本场景仓库还保留了GPTKeywordTableIndex、GPTSimpleKeywordTableIndex、GPTRAKEKeywordTableIndex三个历史别名以兼容旧代码。运行时复杂度与成本特征README 的 FAQ 小节对复杂度与成本给出了明确说明最坏运行时为 O(k·c)其中 $k$ 是提取出的关键词数量$c$ 是每次查询涉及的文本块数量——即关键词 × 候选块的匹配规模对 LLM 的调用次数受 O(d) 限制$d$ 即用户指定的最大查询文本块数对应num_chunks_per_query因此即便候选块很多GPT 调用次数也有明确上界官方 README 还给出了一个历史成本估算示例在num_chunks_per_query10的假设下每次查询约花费 $0.40该数字基于撰写时的 GPT 定价模型仅为历史参考实际成本取决于所选 LLM 的当前价格与调用频率。正因如此simple与rake模式在查询阶段完全不消耗 LLM token仅在建索引阶段若使用 GPT 索引有开销是控制成本的现实选择。测试验证检索行为有据可依仓库中的单元测试 llama-index-core/tests/indices/keyword_table/test_retrievers.py 验证了 simple 模式的端到端检索行为测试通过unittest.mock.patch同时替换索引侧与检索侧的simple_extract_keywords为 mock 实现构建SimpleKeywordTableIndex后调用as_retriever(retriever_modesimple)最终断言retriever.retrieve(QueryBundle(Hello))恰好返回 1 个节点且其内容为Hello world.。这从测试角度印证了simple 检索器返回的是按关键词匹配排序的节点列表且构建与查询两侧的关键词提取可以解耦替换便于在测试中隔离 LLM 依赖。选型建议与总结综合源码结构与官方文档四种检索器的适用场景可归纳如下KeywordTableGPTRetrieverdefault对查询理解能力最强能处理同义改写与短语关键词适合追求召回质量、预算充足的应用也是KeywordTableIndex.as_query_engine()的默认行为KeywordTableSimpleRetrieversimple零外部依赖、毫秒级响应适合关键词以单词为主、对成本与延迟敏感的离线或轻量场景KeywordTableRAKERetrieverrake在无 LLM 的前提下保留短语级关键词提取能力适合需要多词短语匹配但不想引入 GPT 的场景需额外安装 nltk 与 rake_nltkBaseKeywordTableRetriever作为抽象基类不直接实例化但它是理解 KeywordTableIndex 检索链路提取 → 过滤 → 计数排序 → 截断召回的最佳入口也是自定义检索器的扩展点。无论选择哪种模式核心权衡始终围绕关键词提取质量 vs. LLM/计算成本展开而max_keywords_per_query与num_chunks_per_query这两个参数为这一权衡提供了最直接的调节旋钮。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考