Cinnamon/kotaemon · 上手攻略

• 仓库：Cinnamon/kotaemon
• 链接：https://github.com/Cinnamon/kotaemon
• 分类：ai
• 作者：Jay
• 更新：2026-07-12

📌 是什么

Kotaemon 是一个开源的 RAG 文档问答 UI 工具，专注于为文档提供「聊天式问答」体验。它的目标是同时服务两类用户：

• 普通用户：上传 PDF/文档，向 AI 提问，获取带引用的精准答案
• 开发者：基于 Kotaemon 的 RAG 框架构建自己的问答 pipeline

核心特点：干净的界面 + 混合检索 + 强引用展示 + 多模态文档支持。

🔍 解决什么问题

• 有大量技术文档/论文/合同，想基于这些文档向 AI 提问
• 需要 AI 的回答有明确的文档来源引用，不能胡编
• 需要处理包含图表、表格、LaTeX 公式的复杂 PDF
• 想在本地（离线）部署一个私有文档问答机器人
• 需要对检索和生成过程有可视化调参能力

⚡ 快速安装

方式一：Docker 一键部署（推荐）

# 完整版（支持更多文件格式，如 doc/docx）
docker run \
  -e GRADIO_SERVER_NAME=0.0.0.0 \
  -e GRADIO_SERVER_PORT=7860 \
  -v ./ktem_app_data:/app/ktem_app_data \
  -p 7860:7860 -it --rm \
  ghcr.io/cinnamon/kotaemon:main-full

# 访问 http://localhost:7860
# 默认账号：admin
# 默认密码：admin

Lite 版（仅支持 PDF、HTML、XLSX，镜像更小）：

docker run \
  -e GRADIO_SERVER_NAME=0.0.0.0 \
  -e GRADIO_SERVER_PORT=7860 \
  -v ./ktem_app_data:/app/ktem_app_data \
  -p 7860:7860 -it --rm \
  ghcr.io/cinnamon/kotaemon:main-lite

自带 Ollama 的版本（本地离线 RAG）：

docker run \
  -v ./ktem_app_data:/app/ktem_app_data \
  -p 7860:7860 -it --rm \
  ghcr.io/cinnamon/kotaemon:main-ollama

方式二：源码手动安装

前置依赖：Python ≥ 3.10、Git

# 1. 克隆仓库
git clone https://github.com/Cinnamon/kotaemon
cd kotaemon

# 2. 创建虚拟环境（推荐 uv）
uv sync --python 3.10
source .venv/bin/activate

# 或使用 conda
conda create -n kotaemon python=3.10
conda activate kotaemon

# 3. 安装核心库
pip install -e "libs/kotaemon[all]"
pip install -e "libs/ktem"

# 4. 创建环境配置文件
cp .env.example .env
# 编辑 .env 填入 API Key（见下方配置说明）

# 5. 可选：下载 PDF.js 以支持内置 PDF 预览
# 下载地址：https://github.com/mozilla/pdf.js/releases/download/v4.0.379/pdfjs-4.0.379-dist.zip
# 解压到 libs/ktem/ktem/assets/prebuilt/

# 6. 启动
python app.py
# 自动打开浏览器访问 http://localhost:7860

🧩 核心功能与用法

1. 配置 LLM（启动后第一步）

首次登录后，在 UI 中配置使用的语言模型：

设置路径：Resources → LLMs and Embeddings

支持的主流 LLM 提供商：

# .env 配置示例 - OpenAI
OPENAI_API_KEY=sk-xxxxx
OPENAI_CHAT_MODEL=gpt-4o
OPENAI_EMBEDDINGS_MODEL=text-embedding-3-small

# .env 配置示例 - Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com
AZURE_OPENAI_API_KEY=xxxxx
AZURE_CHAT_MODEL=your-deployment-name

# .env 配置示例 - Ollama（本地）
OLLAMA_API_KEY=not-needed
OLLAMA_CHAT_MODEL=llama3
OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
OLLAMA_API_BASE=http://localhost:11434

2. 上传文档并提问

# 在 UI 中操作：
# 1. 点击「Add Files」上传 PDF/文档
# 2. 选择文件集合（可设为私有或公开）
# 3. 在聊天框输入问题
# 4. AI 回答并展示引用来源

支持的文件格式（完整版）： - PDF（含扫描件）、DOCX、PPTX - HTML、MHTML、XLSX - Markdown、TXT

3. 高级检索 pipeline 配置

Kotaemon 支持多种 RAG pipeline，可在设置中选择：

NanoGraphRAG（推荐，兼容性最好）：

pip install nano-graphrag
# 如遇版本冲突：
pip uninstall hnswlib chroma-hnswlib && pip install chroma-hnswlib

# 启动时设置环境变量：
USE_NANO_GRAPHRAG=true python app.py

LightRAG：

pip install git+https://github.com/HKUDS/LightRAG.git
USE_LIGHTRAG=true python app.py

Microsoft GraphRAG（仅支持 OpenAI 或 Ollama）：

pip install "graphrag"
USE_GRAPH_RAG=true python app.py

4. 文档解析器配置

复杂文档（扫描 PDF、含图表/表格/LaTeX）需要配置解析器：

5. 多模态问答

启用多模态支持（需多模态模型，如 GPT-4o）：

# 在 .env 或 UI 设置中开启
KH_REASONINGS_USE_MULTIMODAL=True

这样 AI 就能「看到」文档中的图片和表格，并基于它们回答问题。

💻 典型适用场景

1. 研究人员：上传论文 PDF，向 AI 询问论文方法论、实验设计等细节
2. 法务/合规：上传合同 PDF，询问特定条款含义，AI 标注引用来源
3. 工程师：上传技术文档，以问答方式快速定位信息
4. 学生：上传教材/课件，构建个人学习问答助手
5. 企业内网文档库：部署私有文档问答，作为内部知识检索工具

⚠️ 坑与注意

1. 首次运行需配置 API Key：不配置 LLM API Key 则无法生成答案，纯本地需配合 Ollama
2. 版本冲突问题：nano-graphrag 和 lightrag 安装时可能与 hnswlib 冲突，遇到问题先执行冲突解决命令（见上方）
3. PDF.js 预览：需手动下载 PDF.js 文件才能启用内置 PDF 阅读器内的引用高亮，否则只能看到外部预览
4. Ollama 离线使用：如需完全离线，必须使用 Ollama 版本的 Docker 镜像，并提前下载模型
5. 检索质量依赖 Embedding 模型：默认 embedding 模型质量直接影响检索效果，建议使用 text-embedding-3-large 或本地 nomic-embed-text
6. 多用户权限：支持多用户登录，但公开分享功能（多人协作）相对有限
7. 不是完整 RAG 系统：Kotaemon 本质是一个 UI + RAG 框架，数据存储（向量库、文档库）需要自行维护
8. 大规模文档：处理上千份文档时，检索延迟可能增加，建议配置外部向量数据库（Qdrant / Milvus）而非使用默认配置

🔄 与同类对比

核心差异：Kotaemon 专注于文档问答的精度和引用体验，是三者中 UI 最简洁、引用展示最直观的；RAGFlow 在文档解析质量上更强；FastGPT/Dify 则偏向完整应用平台的构建。

✅ 一句话推荐结论

如果你只需要「上传文档，向 AI 提问，看到答案从哪里来的」这一个功能，Kotaemon 是最轻量、最精准的选择；它是一个真正以「引用准确性」为中心的 RAG 工具，特别适合研究人员和法务场景；如果你还需要工作流编排或外部系统集成，FastGPT 或 Dify 是更好的配套平台。

来源：GitHub README、HuggingFace Demo、官方文档