kotaemon 文件索引（File Index）深度解析：基础设施、默认管线与自定义索引/检索管线

kotaemon 文件索引File Index深度解析基础设施、默认管线与自定义索引/检索管线【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon导读本文围绕 kotaemonktem中的 File Index 文件索引模块展开系统讲解它如何把上传到本地文件夹的文件切分、向量化并持久化从而支撑与文档对话的检索问答。你将掌握其四大底层基础设施Source 表、Index 表、向量存储、文档存储的职责与接口理解默认索引管线IndexDocumentPipeline与默认检索管线DocumentRetrievalPipeline的完整工作流程并学会通过flowsettings.py定制默认管线或通过子类化BaseFileIndexIndexing/BaseFileIndexRetriever从零构建自己的索引与检索管线。文中所有结论均可对照 libs/ktem/ktem/index/file/ 目录与 flowsettings.py 中的源码进行验证。File Index 是什么本地文件 可检索索引File Index 的核心定位是把文件存储到本地文件夹并对它们建立可供检索的索引FileIndex类的 docstring 即为此描述见 index.py。它与面向图的 GraphRAG 索引如 LightRAG、GraphRAG并列属于 ktem 中普通文档集合形态的索引类型——在 flowsettings.py 中KH_INDEX_TYPES将ktem.index.file.FileIndex列为首项并在KH_INDICES中默认注册了一个名为File Collection的索引实例。File Index 提供了以下四类基础设施来支撑索引与检索SQL 表 Source记录被系统索引的文件清单文件名、路径、大小等向量存储Vector store存放文件文本段的向量embedding文档存储Document store存放文件文本段的原文其中每一段文本都与向量存储中的某个向量一一对应SQL 表 Index记录 Source 与 docstore、Source 与 vector store 之间的关联关系。官方约定原文档明确要求索引与检索管线都应优先使用上述软件基础设施而不是绕过它们自行管理数据这样才能与文件选择、索引展示、删除等 UI 和检索逻辑无缝协作。底层资源如何创建与注入从源码看这些资源由FileIndex._setup_resources()统一创建index.py通过 SQLAlchemy 动态建模Source、Index、FileGroup三张表表名形如index__{self.id}__source/index__{self.id}__index/index__{self.id}__group每个 File Index 实例拥有独立的表与命名空间通过get_vectorstore(findex_{self.id})与get_docstore(findex_{self.id})按索引 ID 获取独立的向量存储与文档存储见 components.py其具体实现由KH_VECTORSTORE/KH_DOCSTORE配置决定默认分别为 Chroma 与 LanceDB见 flowsettings.py文件实体存放在filestorage_path / findex_{self.id}目录下上传时按内容 SHA-256 哈希重命名存储见IndexPipeline.store_filepipelines.py 同目录实现于 pipelines.py。在索引/检索管线实例化完成后ktem 会把Source、Index、VS、DS、FSPath等资源逐一挂到管线对象上obj.Source ...; obj.VS ...这正是自定义管线中self._Source等句柄的来源详见下文。默认索引管线IndexDocumentPipelinektem 内置的默认索引管线为ktem.index.file.pipelines.IndexDocumentPipelinepipelines.py。其契约如下输入文件路径列表也支持单个路径以及http(s)://开头的 URL 字符串输出被成功索引进数据库的节点node列表处理流程按文件类型读取文件为文本不同文件类型使用不同的读取器将文本切分为更小的文本段segment / chunk为每个文本段计算 embedding将 embedding 写入向量存储将每段文本写入文档存储将文件清单写入 Source 表并在 Index 表中记录 Source 与 docstore、vector store 的关联。源码视角默认管线的内部路由IndexDocumentPipeline本质上是一个工厂它根据文件扩展名把具体任务路由给不同的IndexPipeline实例route()方法pipelines.py文件提取器来自KH_DEFAULT_FILE_EXTRACTORSfiles.py默认覆盖.xlsx、.docx、.pptx、.doc、.html、.mhtml、.pdf、.txt、.md及常见图片格式未知扩展名回退到UnstructuredReader若路径是 URL则改用web_readerWebReader抓取网页内容切分器默认使用TokenSplitter(chunk_size1024, chunk_overlap256, separator\n\n)即按 token 粒度切分tiktoken的 gpt-3.5-turbo 编码而不是按字符切分——原文档将这两个参数描述为字符数从源码看实际语义是token 数使用时需注意支持reader_mode切换高级读取器adobe、azure-di、docling、paddle-struct、paddle-vl见get_user_settings与readers参数pipelines.pyIndexPipeline.stream()会先做文件是否已索引检查get_id_if_exists已存在且未强制reindexTrue时直接报错避免重复索引同时将文件正文存入 docstore、embedding 写入 vector store并在 Index 表分别写入relation_typedocument与relation_typevector的记录pipelines.py。定制默认索引管线三个 flowsettings 触点如果你的索引流程与默认管线接近不必重写整条管线只需在 flowsettings.py 中提供三个触点contact points默认管线会自动读取对应源码dev_settings()pipelines.py配置项作用示例值FILE_INDEX_PIPELINE_FILE_EXTRACTORS按文件扩展名覆盖/新增文件读取器。key 为扩展名含点value 为可导入的读取器类路径dotted stringktem 会实例化后并入提取器字典{.pdf: path.to.PDFReader, .xlsx: path.to.ExcelReader}FILE_INDEX_PIPELINE_SPLITTER_CHUNK_SIZE每个文本段期望的 token 数原文档写作字符数实际实现基于 token见上文1024FILE_INDEX_PIPELINE_SPLITTER_CHUNK_OVERLAP相邻文本段之间期望重叠的 token 数用于保持语义连续性256在route()中self.chunk_size or dev_chunk_size的取值逻辑表明若管理员在索引设置中显式配置了 chunk 大小则优先使用管理员配置否则回退到这三个开发触点pipelines.py。开发触点中未设置时最终兜底默认值为chunk_size1024, chunk_overlap256。此外在IndexDocumentPipeline.readers中开发触点配置的提取器会以readers.update(dev_readers)的方式覆盖所有默认与reader_mode选择的提取器优先级最高。自建索引管线子类化 BaseFileIndexIndexing如果你的索引逻辑与默认管线差异过大可以完全自建。自定义索引管线需要继承ktem.index.file.base.BaseFileIndexIndexingbase.py并实现以下方法run(self, file_paths)执行给定文件的索引返回(file_ids, errors)其中每个元素与输入文件路径一一对应失败为None基类还提供了可选的stream()变体用于向 UI 流式输出进度消息get_pipeline(cls, user_settings, index_settings)classmethod返回一个完全初始化、可供 ktem 直接使用的管线实例user_settings字典包含用户在设置页配置的选项例如{pdf_mode: True, num_retrieval: 5}。这些选项通过get_user_settingsclassmethod 声明ktem 会收集到应用 Settings 页面并在调用get_pipeline时传入index_settings字典当前对 File Index 而言为空由索引管理员配置项组成如 embedding 模型名get_user_settingsclassmethod声明用户设置项返回字典键为设置名值为包含name、value、component、choices等字段的设置描述格式同ktem.settings.SettingItem。子类化BaseFileIndexIndexing后你将获得以下资源句柄由 ktem 在实例化后注入句柄含义self.SourceSource 表SQLAlchemy ORM 类self.IndexIndex 表SQLAlchemy ORM 类self.VS向量存储实例self.DS文档存储实例self.FSPath文件存储目录self.user_id/self.private当前用户 ID 与是否为私有索引写好后在 flowsettings.py 注册FILE_INDEX_PIPELINE python.path.to.your.pipeline。注册解析优先级源码佐证FileIndex._setup_indexing_cls()index.py按以下顺序解析索引管线类命中即停FILE_INDEX_PIPELINE出现在该索引的config中管理员创建索引时指定flowsettings 中的FILE_INDEX_{id}_PIPELINE可按索引 ID 单独指定flowsettings 中的FILE_INDEX_PIPELINE兜底为默认的.pipelines.IndexDocumentPipeline。这意味着你既可以为所有 File Index 统一替换管线也可以只针对某个索引 ID 定制。默认检索管线DocumentRetrievalPipelinektem 内置的默认检索管线为ktem.index.file.pipelines.DocumentRetrievalPipelinepipelines.py工作流程如下输入用户文本查询以及可选的源文件 ID 列表输出与用户文本查询匹配的文本段RetrievedDocument 列表处理流程若给定了源文件 ID 列表先从 Index 表中查出与这些文件关联的向量 ID 集合relation_type document的target_id将其作为检索范围scope同时以file_id IN (...)的元数据过滤器进一步限定对用户文本查询进行 embedding查询向量存储若用户限制了文件范围则传入上述 ID 列表缩小检索范围返回匹配的文本段。源码视角可配置的检索行为DocumentRetrievalPipeline提供了一组对用户开放的检索选项get_user_settingspipelines.py包括num_retrieval检索的文档块数量默认 10对应top_kretrieval_modevector/text/hybrid三种模式默认hybridprioritize_table是否优先补充检索结果所在页面的表格节点get_extra_tableTrue时会额外按file_namepage_label拉取同页节点mmr是否使用 MMR最大边际相关重排序去重开启时mmr_threshold0.5use_reranking是否启用重排序默认开启使用reranking_models_manager中的默认重排序模型use_llm_reranking是否使用 LLM 计算相关性分数用于 UI 展示默认由USE_LOW_LLM_REQUESTS环境变量控制实现为LLMTrulensScoringreranking_llm执行 LLM 相关性打分所用的 LLM。从run()实现pipelines.py可以看到检索通过VectorRetrievalkotaemon 的检索组件组合 embedding、vector store、docstore完成并支持do_extendTrue的 top_k 扩展行为。检索完成后命中节点还会携带页码缩略图thumbnail_doc_id等元数据供前端渲染 PDF 定位。自建检索管线子类化 BaseFileIndexRetriever自定义检索管线需要继承ktem.index.file.base.BaseFileIndexRetrieverbase.py。检索管线拥有与索引管线相同的数据库、向量存储与文档存储访问能力self.Source、self.Index、self.VS、self.DS等。需要实现的方法run(self, query, file_ids)检索与query相关的文档若传入file_ids则必须将检索范围限制在这些文件 ID 内get_pipeline(cls, user_settings, index_settings, selected)classmethod返回完全初始化的检索管线user_settings用户设置字典同上index_settings索引设置字典当前 File Index 为空selected用户在 UI 中选中的文件 ID 列表若用户未选择任何文件该值为None注意DocumentRetrievalPipeline.run在doc_ids为空时会直接跳过检索并返回空列表见 pipelines.pyget_user_settingsclassmethod声明用户设置项返回字典。完成类定义后在 flowsettings.py 注册FILE_INDEX_RETRIEVER_PIPELINES [path.to.retrieval.pipeline]由于同一个索引内可能存在多条并行的检索管线该变量接收的是字符串列表而非单个字符串。需要特别提醒原文档中此变量写作FILE_INDEXING_RETRIEVER_PIPELIENS而源码index.py实际校验的名称是FILE_INDEX_RETRIEVER_PIPELINES以及可选的FILE_INDEX_{id}_RETRIEVER_PIPELINES注册时请以源码为准。get_retriever_pipelines会为列表中的每个类调用get_pipeline(...)若返回None则跳过该管线最终把全部非空检索管线装配到索引上index.py。软件基础设施速查表下表汇总了四类基础设施的访问句柄、Schema 与关键接口对应原文档表格并补充了源码中的字段细节基础设施访问句柄Schema / 接口参考实现SQL 表 Sourceself.Sourceid主键自动生成 UUID 字符串name文件名path文件路径/哈希size文件大小字节notedict可存放额外信息如 token 数、所用 loader 名date_created创建时间自动另有user字段用于私有索引隔离私有模式下nameuser唯一SQLAlchemy ORM 类见 index.pySQL 表 Indexself.Indexid自增主键source_idSource 表中文件的 idtarget_iddocstore 或 vector store 中文本段/向量的 idrelation_typedocument或vector标识链接目标另有user字段SQLAlchemy ORM 类见 index.py向量存储self.VSadd(embeddings, metadatas, ids)写入向量可带元数据与 iddelete(ids)按 id 删除向量query(embedding, top_k, ids)按 embedding 检索相似向量drop()清空整个存储BaseVectorStore见 vectorstores/base.py文档存储self.DSadd(docs, ids)写入文本段get(ids)按 id 获取文本段get_all()获取全部文本段count()统计数量query(query, top_k)文本级检索delete(ids)按 id 删除drop()清空整个存储BaseDocumentStore见 docstores/base.py管理侧管理员设置项创建 File Index 时管理员可配置以下选项FileIndex.get_admin_settingsindex.pyembedding使用的 embedding 模型下拉选择取自 embedding 模型管理器supported_file_types允许索引的文件类型逗号分隔默认.pdf, .txt注册的 File Collection 实例扩展为常见办公与图片格式见 flowsettings.pymax_file_size单文件大小上限MB设为 0 表示不限制默认 1000max_number_of_files系统可索引的文件总数上限0 表示不限制private是否私有开启后文件不跨用户可见配合user字段隔离chunk_size/chunk_overlap以 token 计的块大小与重叠量设为 0 则回退到开发触点/默认值。相关代码地图若要在仓库中继续深入推荐按以下路径阅读索引/检索管线核心实现pipelines.py基类与资源句柄定义base.pyFile Index 装配、资源创建与类解析优先级index.py文件选择器与索引管理页 UIui.py默认文件提取器注册表files.py全局索引/存储配置KH_INDEX_TYPES、KH_VECTORSTORE、KH_DOCSTORE等flowsettings.py向量存储与文档存储抽象接口vectorstores/base.py、docstores/base.py小结File Index 是 kotaemon 文档问答能力的基石它以Source Index 两张 SQL 表 向量存储 文档存储四位一体的基础设施统一了索引与检索两条管线的数据访问方式。对大多数场景直接使用内置的IndexDocumentPipeline/DocumentRetrievalPipeline并通过flowsettings.py的三个触点文件提取器、块大小、块重叠微调即可当业务差异较大时则可分别子类化BaseFileIndexIndexing与BaseFileIndexRetriever在获得同等基础设施访问权的前提下完全自定义索引与检索逻辑最后通过FILE_INDEX_PIPELINE/FILE_INDEX_RETRIEVER_PIPELINES完成注册。理解这套扩展机制是深度定制 kotaemon 文档检索能力的关键一步。【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考