尧图网页设计 
kotaemon 完整使用指南模型接入、文档索引与带引用的检索问答实战【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon本篇指南围绕开源 RAG 工具 kotaemon 的核心使用流程展开从在Resources标签页接入 LLM 与 Embedding 模型含.env文件与本地模型两种配置方式到上传文档建立文件索引再到在Chat标签页中完成带证据引用、置信度评分的信息检索问答。读完本文你将掌握 kotaemon 从零配置到产出可溯源问答结果的完整链路并理解其检索评分体系背后的实现原理。1. 添加 AI 模型为问答管线接入 LLM 与 Embedding 模型kotaemon 是一个基于 RAG检索增强生成的文档问答工具其 QA 管线中的多项任务如答案生成、证据相关性判断、问题改写等都依赖大语言模型LLM完成。因此在正式使用前你必须先为应用提供可访问的模型。两个基本事实需要提前说明至少提供一个模型应用才能跑通问答流程否则无法工作推荐把所有你有权限访问的模型都加进来加入模型池后你在使用过程中可以随时切换选择最适合当前任务的那个。1.1 通过 Resources 标签页添加模型添加模型的完整步骤如下导航到Resources标签页选择LLMs子标签选择Add子标签配置要添加的模型给它起一个名字名称必须唯一应用通过名称标识模型选择供应商/提供商例如ChatOpenAI提供规格参数以 YAML 格式填写选择供应商后界面会自动生成必填参数模板可选将其设为默认模型点击Add完成添加切换到Embedding Models子标签重复第 35 步添加一个 Embedding嵌入模型。从源码实现看Resources标签页的界面位于 libs/ktem/ktem/llms/ui.py它包含View查看/编辑/删除/测试连接与Add新增两个主标签在Add标签中选择供应商后界面会调用on_llm_vendor_change动态生成该供应商的 YAML 必填参数模板与参数说明表格format_description点击Add LLM后规格 YAML 会被解析并写入 SQLite 数据库llms.add(name, specspec, defaultdefault)View标签中还提供Test connection功能向模型发送一条Hi消息来验证连通性见 libs/ktem/ktem/llms/ui.py 中的check_connection支持对已添加模型进行重命名、修改规格、删除含二次确认与设置默认等管理操作。1.2 支持的模型供应商模型池的供应商列表在 libs/ktem/ktem/llms/manager.py 的load_vendors方法中注册当前内置以下供应商供应商类名说明ChatOpenAIOpenAI 兼容 API也用于 Ollama、Groq、Mistral 等兼容服务AzureChatOpenAIAzure OpenAI 部署LCAnthropicChatAnthropic ClaudeLCGeminiChatGoogle GeminiLCCohereChatCohere Command 系列LCOllamaChatOllama 本地模型长上下文变体LlamaCppChatllama-cpp-python 本地推理此外你还可以通过KH_LLM_EXTRA_VENDORS配置项注册自定义供应商通过import_dotted_string动态导入。这些供应商类的实现位于 libs/kotaemon/kotaemon/llms/其中openai.py与endpoint_based.py是 OpenAI 兼容端点的基础实现。1.3 可选通过 .env 文件配置模型除了在界面中逐个添加你也可以通过.env文件批量配置模型。该文件位于应用目录下如果不存在可以自行创建。仓库根目录提供了模板文件 .env.example可直接复制为.env使用。以下是当前支持的三类配置方式。OpenAI在.env中设置OPENAI_API_KEY即可启用 OpenAI 模型。其余变量可按需修改默认参数对大多数用户已经可用OPENAI_API_BASEhttps://api.openai.com/v1 OPENAI_API_KEYyour OpenAI API key here OPENAI_CHAT_MODELgpt-3.5-turbo OPENAI_EMBEDDINGS_MODELtext-embedding-ada-002.env中的OPENAI_API_BASE是可变的因此这套配置同样适用于任何 OpenAI 兼容的第三方服务例如 vLLM、Groq、Mistral 等。Azure OpenAI通过 Azure 平台使用 OpenAI 模型时需要提供 Azure 的 endpoint 和 API key聊天模型与嵌入模型的部署名deployment name视你在 Azure 中的配置情况而定AZURE_OPENAI_ENDPOINT AZURE_OPENAI_API_KEY OPENAI_API_VERSION2024-02-15-preview # could be different for you AZURE_OPENAI_CHAT_DEPLOYMENTgpt-35-turbo # change to your deployment name AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTtext-embedding-ada-002 # change to your deployment name这些变量会被 flowsettings.py 读取并注册为名为azure的 LLM 与 Embedding 模型对应kotaemon.llms.AzureChatOpenAI与kotaemon.embeddings.AzureOpenAIEmbeddings。本地模型本地部署 LLM 的优缺点非常鲜明优点隐私你的文档全部在本地存储和处理不会外泄选择自由可按体积、领域、语言挑选丰富的开源模型成本免费。缺点质量本地模型通常更小生成质量低于付费 API速度本地模型依赖本机硬件推理处理速度受限于你的机器配置。查找并下载 LLM你可以从 Hugging Face Hub 搜索并下载可本地运行的模型。当前支持的模型格式为GGUF选择模型时模型体积应小于设备可用内存并预留约 2 GB 余量。例如总内存 16 GB、可用 12 GB 时应选择占用不超过 10 GB 的模型。模型越大生成效果通常越好但处理时间也更长。官方文档推荐的入门模型示例Qwen1.5-1.8B-Chat-GGUF约 2 GB启用本地模型在.env文件中将LOCAL_MODEL变量设置为模型文件的完整路径即可把本地模型加入模型池LOCAL_MODELfull path to your model file获取模型文件完整路径的方法Windows 11 下右键点击文件选择Copy as Path。需要说明的是当前 flowsettings.py 中LOCAL_MODEL的实际用法是作为 Ollama 中的模型名默认qwen2.5:7b并通过KH_OLLAMA_URL默认http://localhost:11434/v1/连接同时还会注册ollama-long-context长上下文变体、ollama嵌入模型默认nomic-embed-text由LOCAL_MODEL_EMBEDDINGS指定以及基于 FastEmbed 的fast_embed模型。关于 Ollama、text-generation-webui、llama-cpp-python 三种本地推理服务的完整接入步骤可参考 docs/local_model.md。1.4 模型池与默认模型选择逻辑所有在界面或.env中注册的模型会进入统一的模型池LLMManager见 libs/ktem/ktem/llms/manager.py持久化存储在 SQLite 数据库中。其默认模型的选择逻辑值得注意若设置了默认模型则使用该默认模型若未设置任何默认模型则从模型池中随机挑选一个若设置了多个默认模型则从这些默认模型中随机选择源码get_default_name的注释明确说明了这一行为。这意味着如果你期望某个模型例如本地模型被固定使用务必在添加时勾选 Set default。2. 上传文档构建可检索的文件索引要对文档进行问答QA首先需要把文档上传到应用中。导航到File Index标签页你会看到两个区域文件上传File upload将文件拖拽到界面或从文件系统中选择然后点击Upload and Index应用需要一些时间处理文件处理完成后会显示提示消息。文件列表File list显示所有已上传到应用的文件列表支持删除不需要的文件。关于支持的格式flowsettings.py 中KH_INDICES的supported_file_types配置给出了完整的白名单.png, .jpeg, .jpg, .tiff, .tif, .pdf, .xls, .xlsx, .doc, .docx, .pptx, .csv, .html, .mhtml, .txt, .md, .zipzip 压缩包会被解压处理。文件解析与切分由 libs/kotaemon/kotaemon/loaders/ 与 libs/kotaemon/kotaemon/indices/ 下的组件完成上传后文件内容会被解析、切块并写入向量存储供后续检索使用。3. 与文档对话Chat 标签页的三区域布局回到Chat标签页这里是核心的问答交互界面。整个标签页分为三个区域3.1 对话设置面板Conversation Settings Panel对话管理可以在此选择、创建、重命名和删除对话。默认情况下如果没有选中任何对话会自动创建一个新对话。文件索引选择决定聊天时从哪些文件检索参考内容提供三种模式Disabled禁用不将任何文件作为聊天时的上下文Search All搜索全部聊天时考虑所有已上传的文件Select选择出现下拉框让你指定参与聊天的文件如果未选择任何文件则聊天时同样不会考虑任何文件。3.2 聊天面板Chat Panel这是你与聊天机器人交互的窗口。输入问题后系统会基于所选文件执行检索增强生成先召回相关证据再由 LLM 结合证据生成带引用的回答。当你选择Select模式并输入时还可以通过文件索引快速指定检索范围对应 libs/ktem/ktem/pages/chat/chat_panel.py 中基于 Tribute 实现的文件引用组件。3.3 信息面板Information Panel证据、引用与评分解读信息面板用于展示回答的支撑信息检索证据与参考文献LLM 回答所依据的检索证据和参考来源会展示在这里直接引用高亮LLM 回答中直接引用证据的位置会被高亮标记方便你快速核对回答来源置信度与相关性分数回答的置信度分数和证据的相关性分数会一并显示帮助你快速评估回答与检索内容的质量。各分数的含义如下分数含义Answer confidence回答置信度LLM 对回答的置信度水平Relevance score相关性总分证据与用户问题之间的整体相关性得分Vectorstore score向量库分数基于向量嵌入相似度计算的相关性分数若从全文检索数据库召回则显示为full-text searchLLM relevant scoreLLM 相关性分数LLM 使用特定提示词判断问题与证据相关性的得分Reranking score重排分数来自 Cohere reranking 模型的相关性分数3.4 分数质量排序与默认策略一般而言各类分数的质量排序为LLM relevant score Reranking score Vectorstore score默认情况下整体相关性分数Relevance score直接取自 LLM 相关性分数证据按其整体相关性分数以及是否被引用进行排序后展示。换言之kotaemon 优先信任 LLM 对证据-问题语义相关性的判断其次是专门的重排模型最后才是单纯的向量相似度——这也符合 RAG 检索排序的通用最佳实践。如果希望调整这部分行为例如更换重排模型或关闭 LLM 相关性打分以节省算力可以在flowsettings.py的KH_RERANKINGS、KH_EMBEDDINGS等配置中修改相关重排模型实现位于 libs/kotaemon/kotaemon/rerankings/。4. 完整落地路径与常见问题把上面三个步骤串起来一次完整的 kotaemon 使用流程是配置模型在Resources标签页或.env文件中添加至少一个 LLM 和一个 Embedding 模型建议同时设置默认模型上传文档在File Index标签页上传并索引目标文档选择检索范围回到Chat标签页在对话设置面板中选择文件索引模式Search All或Select指定文件开始问答在聊天面板提问并在信息面板中核对证据引用与各类分数判断回答质量。常见问题与排查要点模型添加后无法使用先在Resources → LLMs → View中使用 Test connection 测试连通性重点检查 API key、base URL 与模型名是否正确未设置默认模型导致行为不确定模型池在没有默认模型时会随机选择请为关键任务模型勾选 Set default本地模型速度慢或内存不足选择更小的 GGUF 模型并确保预留约 2 GB 内存余量Docker 环境下访问宿主机本地服务时需将localhost替换为host.docker.internal详见 docs/local_model.md分数普遍偏低优先关注 LLM relevant score 与 Reranking score若两者均低可尝试更换更强的 LLM 或重排模型或检查所选文件是否真的包含相关问题答案。更多进阶玩法GraphRAG 图索引、Agent 推理、多用户管理等可在应用界面的对应标签页中探索相关文档入口见 docs/index.md。【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 kotaemon 完整使用指南：模型接入、文档索引与带引用的检索问答实战
kotaemon 完整使用指南模型接入、文档索引与带引用的检索问答实战【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon本篇指南围绕开源 RAG 工具 kotaemon 的核心使用流程展开从在Resources标签页接入 LLM 与 Embedding 模型含.env文件与本地模型两种配置方式到上传文档建立文件索引再到在Chat标签页中完成带证据引用、置信度评分的信息检索问答。读完本文你将掌握 kotaemon 从零配置到产出可溯源问答结果的完整链路并理解其检索评分体系背后的实现原理。1. 添加 AI 模型为问答管线接入 LLM 与 Embedding 模型kotaemon 是一个基于 RAG检索增强生成的文档问答工具其 QA 管线中的多项任务如答案生成、证据相关性判断、问题改写等都依赖大语言模型LLM完成。因此在正式使用前你必须先为应用提供可访问的模型。两个基本事实需要提前说明至少提供一个模型应用才能跑通问答流程否则无法工作推荐把所有你有权限访问的模型都加进来加入模型池后你在使用过程中可以随时切换选择最适合当前任务的那个。1.1 通过 Resources 标签页添加模型添加模型的完整步骤如下导航到Resources标签页选择LLMs子标签选择Add子标签配置要添加的模型给它起一个名字名称必须唯一应用通过名称标识模型选择供应商/提供商例如ChatOpenAI提供规格参数以 YAML 格式填写选择供应商后界面会自动生成必填参数模板可选将其设为默认模型点击Add完成添加切换到Embedding Models子标签重复第 35 步添加一个 Embedding嵌入模型。从源码实现看Resources标签页的界面位于 libs/ktem/ktem/llms/ui.py它包含View查看/编辑/删除/测试连接与Add新增两个主标签在Add标签中选择供应商后界面会调用on_llm_vendor_change动态生成该供应商的 YAML 必填参数模板与参数说明表格format_description点击Add LLM后规格 YAML 会被解析并写入 SQLite 数据库llms.add(name, specspec, defaultdefault)View标签中还提供Test connection功能向模型发送一条Hi消息来验证连通性见 libs/ktem/ktem/llms/ui.py 中的check_connection支持对已添加模型进行重命名、修改规格、删除含二次确认与设置默认等管理操作。1.2 支持的模型供应商模型池的供应商列表在 libs/ktem/ktem/llms/manager.py 的load_vendors方法中注册当前内置以下供应商供应商类名说明ChatOpenAIOpenAI 兼容 API也用于 Ollama、Groq、Mistral 等兼容服务AzureChatOpenAIAzure OpenAI 部署LCAnthropicChatAnthropic ClaudeLCGeminiChatGoogle GeminiLCCohereChatCohere Command 系列LCOllamaChatOllama 本地模型长上下文变体LlamaCppChatllama-cpp-python 本地推理此外你还可以通过KH_LLM_EXTRA_VENDORS配置项注册自定义供应商通过import_dotted_string动态导入。这些供应商类的实现位于 libs/kotaemon/kotaemon/llms/其中openai.py与endpoint_based.py是 OpenAI 兼容端点的基础实现。1.3 可选通过 .env 文件配置模型除了在界面中逐个添加你也可以通过.env文件批量配置模型。该文件位于应用目录下如果不存在可以自行创建。仓库根目录提供了模板文件 .env.example可直接复制为.env使用。以下是当前支持的三类配置方式。OpenAI在.env中设置OPENAI_API_KEY即可启用 OpenAI 模型。其余变量可按需修改默认参数对大多数用户已经可用OPENAI_API_BASEhttps://api.openai.com/v1 OPENAI_API_KEYyour OpenAI API key here OPENAI_CHAT_MODELgpt-3.5-turbo OPENAI_EMBEDDINGS_MODELtext-embedding-ada-002.env中的OPENAI_API_BASE是可变的因此这套配置同样适用于任何 OpenAI 兼容的第三方服务例如 vLLM、Groq、Mistral 等。Azure OpenAI通过 Azure 平台使用 OpenAI 模型时需要提供 Azure 的 endpoint 和 API key聊天模型与嵌入模型的部署名deployment name视你在 Azure 中的配置情况而定AZURE_OPENAI_ENDPOINT AZURE_OPENAI_API_KEY OPENAI_API_VERSION2024-02-15-preview # could be different for you AZURE_OPENAI_CHAT_DEPLOYMENTgpt-35-turbo # change to your deployment name AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTtext-embedding-ada-002 # change to your deployment name这些变量会被 flowsettings.py 读取并注册为名为azure的 LLM 与 Embedding 模型对应kotaemon.llms.AzureChatOpenAI与kotaemon.embeddings.AzureOpenAIEmbeddings。本地模型本地部署 LLM 的优缺点非常鲜明优点隐私你的文档全部在本地存储和处理不会外泄选择自由可按体积、领域、语言挑选丰富的开源模型成本免费。缺点质量本地模型通常更小生成质量低于付费 API速度本地模型依赖本机硬件推理处理速度受限于你的机器配置。查找并下载 LLM你可以从 Hugging Face Hub 搜索并下载可本地运行的模型。当前支持的模型格式为GGUF选择模型时模型体积应小于设备可用内存并预留约 2 GB 余量。例如总内存 16 GB、可用 12 GB 时应选择占用不超过 10 GB 的模型。模型越大生成效果通常越好但处理时间也更长。官方文档推荐的入门模型示例Qwen1.5-1.8B-Chat-GGUF约 2 GB启用本地模型在.env文件中将LOCAL_MODEL变量设置为模型文件的完整路径即可把本地模型加入模型池LOCAL_MODELfull path to your model file获取模型文件完整路径的方法Windows 11 下右键点击文件选择Copy as Path。需要说明的是当前 flowsettings.py 中LOCAL_MODEL的实际用法是作为 Ollama 中的模型名默认qwen2.5:7b并通过KH_OLLAMA_URL默认http://localhost:11434/v1/连接同时还会注册ollama-long-context长上下文变体、ollama嵌入模型默认nomic-embed-text由LOCAL_MODEL_EMBEDDINGS指定以及基于 FastEmbed 的fast_embed模型。关于 Ollama、text-generation-webui、llama-cpp-python 三种本地推理服务的完整接入步骤可参考 docs/local_model.md。1.4 模型池与默认模型选择逻辑所有在界面或.env中注册的模型会进入统一的模型池LLMManager见 libs/ktem/ktem/llms/manager.py持久化存储在 SQLite 数据库中。其默认模型的选择逻辑值得注意若设置了默认模型则使用该默认模型若未设置任何默认模型则从模型池中随机挑选一个若设置了多个默认模型则从这些默认模型中随机选择源码get_default_name的注释明确说明了这一行为。这意味着如果你期望某个模型例如本地模型被固定使用务必在添加时勾选 Set default。2. 上传文档构建可检索的文件索引要对文档进行问答QA首先需要把文档上传到应用中。导航到File Index标签页你会看到两个区域文件上传File upload将文件拖拽到界面或从文件系统中选择然后点击Upload and Index应用需要一些时间处理文件处理完成后会显示提示消息。文件列表File list显示所有已上传到应用的文件列表支持删除不需要的文件。关于支持的格式flowsettings.py 中KH_INDICES的supported_file_types配置给出了完整的白名单.png, .jpeg, .jpg, .tiff, .tif, .pdf, .xls, .xlsx, .doc, .docx, .pptx, .csv, .html, .mhtml, .txt, .md, .zipzip 压缩包会被解压处理。文件解析与切分由 libs/kotaemon/kotaemon/loaders/ 与 libs/kotaemon/kotaemon/indices/ 下的组件完成上传后文件内容会被解析、切块并写入向量存储供后续检索使用。3. 与文档对话Chat 标签页的三区域布局回到Chat标签页这里是核心的问答交互界面。整个标签页分为三个区域3.1 对话设置面板Conversation Settings Panel对话管理可以在此选择、创建、重命名和删除对话。默认情况下如果没有选中任何对话会自动创建一个新对话。文件索引选择决定聊天时从哪些文件检索参考内容提供三种模式Disabled禁用不将任何文件作为聊天时的上下文Search All搜索全部聊天时考虑所有已上传的文件Select选择出现下拉框让你指定参与聊天的文件如果未选择任何文件则聊天时同样不会考虑任何文件。3.2 聊天面板Chat Panel这是你与聊天机器人交互的窗口。输入问题后系统会基于所选文件执行检索增强生成先召回相关证据再由 LLM 结合证据生成带引用的回答。当你选择Select模式并输入时还可以通过文件索引快速指定检索范围对应 libs/ktem/ktem/pages/chat/chat_panel.py 中基于 Tribute 实现的文件引用组件。3.3 信息面板Information Panel证据、引用与评分解读信息面板用于展示回答的支撑信息检索证据与参考文献LLM 回答所依据的检索证据和参考来源会展示在这里直接引用高亮LLM 回答中直接引用证据的位置会被高亮标记方便你快速核对回答来源置信度与相关性分数回答的置信度分数和证据的相关性分数会一并显示帮助你快速评估回答与检索内容的质量。各分数的含义如下分数含义Answer confidence回答置信度LLM 对回答的置信度水平Relevance score相关性总分证据与用户问题之间的整体相关性得分Vectorstore score向量库分数基于向量嵌入相似度计算的相关性分数若从全文检索数据库召回则显示为full-text searchLLM relevant scoreLLM 相关性分数LLM 使用特定提示词判断问题与证据相关性的得分Reranking score重排分数来自 Cohere reranking 模型的相关性分数3.4 分数质量排序与默认策略一般而言各类分数的质量排序为LLM relevant score Reranking score Vectorstore score默认情况下整体相关性分数Relevance score直接取自 LLM 相关性分数证据按其整体相关性分数以及是否被引用进行排序后展示。换言之kotaemon 优先信任 LLM 对证据-问题语义相关性的判断其次是专门的重排模型最后才是单纯的向量相似度——这也符合 RAG 检索排序的通用最佳实践。如果希望调整这部分行为例如更换重排模型或关闭 LLM 相关性打分以节省算力可以在flowsettings.py的KH_RERANKINGS、KH_EMBEDDINGS等配置中修改相关重排模型实现位于 libs/kotaemon/kotaemon/rerankings/。4. 完整落地路径与常见问题把上面三个步骤串起来一次完整的 kotaemon 使用流程是配置模型在Resources标签页或.env文件中添加至少一个 LLM 和一个 Embedding 模型建议同时设置默认模型上传文档在File Index标签页上传并索引目标文档选择检索范围回到Chat标签页在对话设置面板中选择文件索引模式Search All或Select指定文件开始问答在聊天面板提问并在信息面板中核对证据引用与各类分数判断回答质量。常见问题与排查要点模型添加后无法使用先在Resources → LLMs → View中使用 Test connection 测试连通性重点检查 API key、base URL 与模型名是否正确未设置默认模型导致行为不确定模型池在没有默认模型时会随机选择请为关键任务模型勾选 Set default本地模型速度慢或内存不足选择更小的 GGUF 模型并确保预留约 2 GB 内存余量Docker 环境下访问宿主机本地服务时需将localhost替换为host.docker.internal详见 docs/local_model.md分数普遍偏低优先关注 LLM relevant score 与 Reranking score若两者均低可尝试更换更强的 LLM 或重排模型或检查所选文件是否真的包含相关问题答案。更多进阶玩法GraphRAG 图索引、Agent 推理、多用户管理等可在应用界面的对应标签页中探索相关文档入口见 docs/index.md。【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考