kotaemon Chat 功能详解基于 RAG 的文档问答、引用溯源与会话管理【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemonkotaemon 是一个开源的 RAG检索增强生成工具其核心定位是与你的文档对话。本文围绕 docs/pages/app/features.md 中介绍的 Chat 功能展开结合 docs/pages/app/functional-description.md 的功能规格说明与 libs/ktem/ktem/index/file/ 下的真实源码实现系统讲解 kotaemon 聊天功能的工作机制如何上传语料、如何向机器人提问、如何查看回答中的引用来源以及支撑这一切的文件索引与检索管道。读完本文你将掌握 kotaemon 聊天模块的完整交互流程、底层 RAG 数据流以及如何通过配置项和自定义管道定制检索行为。Chat 功能概述kotaemon 的 Chat 功能聚焦于在语料库上进行问答question and answering over a corpus of data。根据 docs/pages/app/features.md其核心能力可以概括为三点上传语料文件用户可以将一组文件上传到系统中作为问答的知识来源与聊天机器人对话用户围绕上传的语料向聊天机器人提问获得回答查看文件中的引用用户可以查看回答所依据的原文引用reference实现答案可溯源。这三点分别对应了 RAG 应用的三个关键环节——语料入库Indexing、检索生成Retrieval Generation与引用溯源Citation也是本文后续展开的主线。Chat 界面的组成从 docs/pages/app/functional-description.md 的Chat to the bot一节可以看到每次聊天会话chat由以下四个 UI 组件构成组件作用Chat message聊天消息区展示机器人与用户之间的对话往来Text input send button输入框与发送按钮供用户输入消息Data source panel数据源面板选择用于限定机器人回答上下文的文件Information panel信息面板在机器人回答时展示支撑证据evidence其中数据源面板是 RAG 语义下的关键交互用户可以主动勾选文件来缩小检索范围如果用户不做任何选择则系统内全部文件都会作为机器人的上下文。这也意味着检索范围是可人为控制的而不仅是纯向量相似度匹配。对话交互流程一次完整的问答交互按如下流程进行可选选择数据源用户先在数据源面板中选择要作为上下文的文件若不选则默认使用全部文件发送消息用户点击发送按钮或按下 Enter 键发送消息支持多行输入使用Shift Enter换行等待处理机器人在处理期间显示Thinking...占位符展示证据右侧信息面板开始展示与用户问题相关的检索数据生成回答机器人开始流式生成回答Thinking...占位符消失。交互细节与产品规格functional-description.md 中还明确了以下交互预期消息操作支持Shift Enter多行输入用户可以对 AI 回答点赞thumbs up或点踩thumbs down该反馈会记录到数据库中每条聊天消息带有复制按钮可一键复制内容到剪贴板。信息面板面板展示最新的证据latest evidence点击某条消息后该消息对应的引用会在Reference panel中展示该功能处于规划阶段点击面板标题可以展开/收起内容整个信息面板支持整体折叠对话质量要求机器人应以自然语言方式回答用户请求回答必须流式输出streamed to the UI而不是等待全部文本生成完毕后一次性吐出——这与 docs/pages/app/customize-flows.md 中介绍的流式输出机制async def runself.report_output直接对应。会话Conversation管理kotaemon 支持多会话并行管理用户可以在不同话题之间自由切换。切换会话点击会话下拉框展示全部会话列表选择其中一个旧会话后聊天消息、信息面板和已选数据源都会恢复为该会话的历史状态用户可以基于旧会话的上下文继续聊天。产品规格要求会话列表按创建日期排序当没有任何会话时列表为空即使没有会话用户依然可以直接与机器人对话此时系统会自动创建新会话。新建会话点击 New 按钮即可显式开启新会话。新会话的默认名称为当前日期时间创建后自动成为选中状态并追加到会话列表。重命名会话用户可以在重命名输入框中输入新名称并点击 Rename 按钮。重命名成功时下拉框中显示的名称同步更新失败时在重命名区域下方以红色文字显示错误信息。重命名的约束条件名称最少 1 个字符最多 40 个字符不能与同一用户的现有会话重名。删除会话点击 Delete 按钮后弹出确认对话框Delete / Cancel 两个按钮点击 Delete删除当前会话并自动切换到下一个最旧的会话点击 Cancel仅关闭确认对话框。支撑 Chat 的底层基础设施文件索引File IndexChat 之所以能基于语料回答问题依赖的是 kotaemon 的文件索引体系。根据 docs/pages/app/index/file.md文件索引将文件保存在本地文件夹中并建立检索所需的索引其基础设施包含四部分基础设施作用SQL 表Source存储系统已索引的文件清单向量存储Vector store存放文件片段segment的嵌入向量文档存储Document store存放文件片段的原文文本每条文本与向量存储中的某个向量一一关联SQL 表Index记录 Source 与 docstore、Source 与 vectorstore 之间的关联关系该文档建议索引管道和检索管道都基于这套软件基础设施来实现以保证数据一致性与可复用性。软件基础设施的访问接口对开发自定义管道而言这些资源分别通过以下属性访问来源docs/pages/app/index/file.md 及 libs/ktem/ktem/index/file/base.py资源访问属性主要接口SQL 表 Sourceself._Sourceid、name、path、size、note、date_created等字段SQLAlchemy ORMSQL 表 Indexself._Indexid、source_id、target_id、relation_type值为document或vector向量存储self._VSadd加入嵌入向量、delete按 id 删除、query按向量查询文档存储self._DSadd、get按 id 取片段、get_all、delete其中relation_type的设计很关键同一文件片段在 docstore 和 vectorstore 中各有一条记录通过Index表把 文件 → 文本片段document与 文件 → 向量vector两条链路分别记录下来删除文件时可以据此同步清理两侧数据。索引管道从文件到向量默认索引管道的工作流程ktem 的默认索引管道为ktem.index.file.pipelines.IndexDocumentPipeline实现在 libs/ktem/ktem/index/file/pipelines.py其流程如下输入文件路径列表输出已写入数据库的节点列表处理过程将文件读取为文本——不同文件类型有不同的读取方式PDF、Word、Excel、网页等各有专属 reader将文本切分为更小的片段chunk为每个片段计算嵌入向量将向量写入向量存储、片段文本写入文档存储、文件清单写入 Source 表并在 Index 表中记录 Source 与 docstore/vectorstore 的关联。从源码看IndexDocumentPipeline.stream会逐文件处理并实时向 UI 汇报进度channelindex/channeldebug两种消息通道单文件索引流程由IndexPipeline.stream完成包括检查文件是否已索引get_id_if_exists、去重判定是否强制重索引reindex、存储文件按 SHA-256 哈希命名见store_file、调用 reader 解析、切分、写入 docstore/vectorstore 并登记 Index 关联handle_chunks_docstore/handle_chunks_vectorstore。按文件类型路由 reader源码中的IndexPipeline.routelibs/ktem/ktem/index/file/pipelines.py展示了默认的读取器路由策略URL 使用网页 readerweb_reader其余文件按扩展名在self.readers中查找对应的 reader未匹配到扩展名时回退到unstructured通用解析器若配置的 reader 为 None则抛出NotImplementedError提示在设置中为该文件类型指定合适的管道。默认的TokenSplitter以chunk_size默认 1024与chunk_overlap默认 256为参数进行切分。在 flowsettings.py 中定制默认索引管道默认管道在 flowsettings.py 中提供了三个可覆盖的接触点文档原文说明FILE_INDEX_PIPELINE_FILE_EXTRACTORS按文件扩展名覆盖解析器例如{.pdf: path.to.PDFReader, .xlsx: path.to.ExcelReader}FILE_INDEX_PIPELINE_SPLITTER_CHUNK_SIZE每个文本片段的期望字符数例如1024FILE_INDEX_PIPELINE_SPLITTER_CHUNK_OVERLAP相邻片段之间期望的重叠字符数例如256。这些配置在 libs/ktem/ktem/index/file/pipelines.py 的dev_settings()中被读取并注入到管道中与源码中TokenSplitter的默认参数chunk_size or 1024、chunk_overlap or 256相互印证。创建自定义索引管道如果默认管道与你的索引逻辑差异过大可以自行实现。自定义索引管道需要继承BaseFileIndexIndexing定义于 libs/ktem/ktem/index/file/base.py并实现以下方法run(self, file_paths)执行索引逻辑get_pipeline(cls, user_settings, index_settings)返回完全初始化、可被 ktem 直接调用的管道对象user_settings包含用户设置的字典例如{pdf_mode: True, num_retrieval: 5}可通过get_user_settings类方法声明ktem 会把这些设置收集到应用 Settings 页面并在调用get_pipeline时传入index_settings字典类型目前对 File Index 为空get_user_settings声明用户可配置项返回一个字典。继承BaseFileIndexIndexing后管道内部即可通过self._Source、self._Index、self._VS、self._DS访问上述四类基础设施。管道准备好后在flowsettings.py中注册FILE_INDEX_PIPELINE python.path.to.your.pipeline。检索管道从问题到证据默认检索管道的工作流程ktem 的默认检索管道为ktem.index.file.pipelines.DocumentRetrievalPipeline实现于 libs/ktem/ktem/index/file/pipelines.py流程如下输入用户文本查询以及可选的源文件 id 列表输出与用户查询匹配的文本片段处理过程如果给定了源文件 id 列表先从 Index 表中查出与这些文件关联的向量 id用于限定检索范围对用户查询文本做嵌入查询向量存储若用户限制了范围则传入向量 id 列表进行限定返回匹配的文本片段。从源码实现看DocumentRetrievalPipeline.run有更多细节值得注意doc_ids 展开传入的doc_ids会被展开支持以 JSON 字符串形式传入的分组 id范围限定通过查询Index表relation_type document且source_id命中拿到 chunk id 列表并同时使用MetadataFiltersfile_id IN doc_ids做双重限定检索模式retrieval_mode支持vector、text、hybrid三种取值默认hybridMMR 支持当mmr开启时使用VectorStoreQueryMode.MMR并设置mmr_threshold 0.5以提升结果多样性表格增强get_extra_table当prioritize_table开启时会对检索结果中每个文件对应的页码再次检索同页的表格节点补充进结果这对包含大量表格的文档问答很有价值相关性评分可选地通过LLMTrulensScoring为每个检索片段生成相关性分数用于在 UI 的信息面板上展示对应generate_relevant_scores方法。检索管道的用户可配置项DocumentRetrievalPipeline.get_user_settingslibs/ktem/ktem/index/file/pipelines.py声明了以下用户设置ktem 会在 Settings 页面渲染它们设置 id名称默认值组件说明reranking_llmLLM for relevant scoring默认 LLMdropdown用于相关性评分的 LLMnum_retrievalNumber of document chunks to retrieve10number检索返回的文档片段数量即 top_kretrieval_modeRetrieval modehybriddropdown可选vector/text/hybridprioritize_tablePrioritize tableFalsecheckbox是否优先补充同页表格节点mmrUse MMRFalsecheckbox是否使用 MMR 提升结果多样性use_rerankingUse rerankingTruecheckbox是否启用重排序use_llm_rerankingUse LLM relevant scoring视USE_LOW_LLM_REQUESTS而定checkbox是否启用 LLM 相关性评分结合get_pipeline的源码逻辑当use_reranking为 False 时清空 rerankersnum_retrieval直接作为top_k传入向量检索prioritize_table控制get_extra_table。这些设置正是用户侧调整检索质量的主要旋钮。创建自定义检索管道自定义检索管道继承BaseFileIndexRetrieverlibs/ktem/ktem/index/file/base.py其数据库、向量存储、文档存储访问方式与索引管道一致。需要实现run(self, query, file_ids)根据查询检索相关文档如果给定了file_ids应把检索范围限制在这些文件内get_pipeline(cls, user_settings, index_settings, selected)返回初始化完毕的管道user_settings用户设置字典index_settings索引设置字典目前 File Index 为空selected用户选择的文件 id 列表用户未选择任何文件时为Noneget_user_settings声明用户可配置项返回字典。注册方式与索引管道略有不同因为同一索引内可以存在多条并行检索管道所以注册变量是列表FILE_INDEXING_RETRIEVER_PIPELIENS [path.to.retrieval.pipeline]注意文档原文中的该变量名拼写。引用溯源与证据展示Chat 功能中的查看文件中的引用与检索管道产出的证据evidence直接相关。在 ktem 的扩展机制中见 docs/pages/app/customize-flows.md推理管道可以通过self.report_output向 UI 输出字典字典支持两个键output流式输出到聊天消息区evidence流式输出到信息面板。也就是说机器人在生成回答时检索到的片段以 evidence 形式同步推送到右侧信息面板用户据此核对答案依据。再结合 functional-description.md 中信息面板展示最新证据点击标题可展开/收起内容整个面板可折叠的交互规格便构成了 kotaemon答案可溯源的完整链路数据源选择 → 向量/混合检索 → 重排序 → 证据面板展示 → 流式回答生成。从界面到源码的完整调用链小结用户操作界面组件底层实现仓库路径上传文件并索引File 页面上传区IndexDocumentPipeline见 libs/ktem/ktem/index/file/pipelines.py选择数据源限定范围Chat 数据源面板doc_ids参数传入检索管道run(text, doc_ids)提问Chat 输入框推理管道 DocumentRetrievalPipeline见 libs/ktem/ktem/index/file/pipelines.py查看引用证据信息面板检索片段以evidence通道流入面板见 docs/pages/app/customize-flows.md会话管理会话下拉框 / New / Rename / Delete会话数据持久化于用户数据库KH_DATABASE见 flowsettings.py整体上kotaemon 的 Chat 功能把上传语料 → 建立索引 → 限定检索 → 流式问答 → 引用溯源串成了一条完整的 RAG 链路界面交互规格记录在功能文档中索引与检索管道实现在libs/ktem/ktem/index/file/下而开发者则可以通过flowsettings.py中的FILE_INDEX_PIPELINE_*系列配置和自定义BaseFileIndexIndexing/BaseFileIndexRetriever子类自由定制属于自己业务的文档问答方案。【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考