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 标签页添加模型

添加模型的完整步骤如下：

1. 导航到Resources标签页；
2. 选择LLMs子标签；
3. 选择Add子标签；
4. 配置要添加的模型：
   • 给它起一个名字（名称必须唯一，应用通过名称标识模型）；
   • 选择供应商/提供商（例如ChatOpenAI）；
   • 提供规格参数（以 YAML 格式填写，选择供应商后界面会自动生成必填参数模板）；
   • （可选）将其设为默认模型；
5. 点击Add完成添加；
6. 切换到Embedding Models子标签，重复第 3～5 步添加一个 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, spec=spec, default=default)）；
• View标签中还提供Test connection功能，向模型发送一条Hi消息来验证连通性（见 libs/ktem/ktem/llms/ui.py 中的check_connection）；
• 支持对已添加模型进行重命名、修改规格、删除（含二次确认）与设置默认等管理操作。

1.2 支持的模型供应商

模型池的供应商列表在 libs/ktem/ktem/llms/manager.py 的load_vendors方法中注册，当前内置以下供应商：

此外，你还可以通过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_BASE=https://api.openai.com/v1 OPENAI_API_KEY=<your OpenAI API key here> OPENAI_CHAT_MODEL=gpt-3.5-turbo OPENAI_EMBEDDINGS_MODEL=text-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_VERSION=2024-02-15-preview # could be different for you AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-35-turbo # change to your deployment name AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT=text-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_MODEL=<full 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标签页，你会看到两个区域：

1. 文件上传（File upload）：

   • 将文件拖拽到界面，或从文件系统中选择，然后点击Upload and Index；
   • 应用需要一些时间处理文件，处理完成后会显示提示消息。

2. 文件列表（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, .zip（zip 压缩包会被解压处理）。文件解析与切分由 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 回答中直接引用证据的位置会被高亮标记，方便你快速核对回答来源；
• 置信度与相关性分数：回答的置信度分数和证据的相关性分数会一并显示，帮助你快速评估回答与检索内容的质量。

各分数的含义如下：

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 使用流程是：

1. 配置模型：在Resources标签页（或.env文件）中添加至少一个 LLM 和一个 Embedding 模型，建议同时设置默认模型；
2. 上传文档：在File Index标签页上传并索引目标文档；
3. 选择检索范围：回到Chat标签页，在对话设置面板中选择文件索引模式（Search All或Select指定文件）；
4. 开始问答：在聊天面板提问，并在信息面板中核对证据引用与各类分数，判断回答质量。

常见问题与排查要点：

• 模型添加后无法使用：先在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