kotaemon

环境要求

• Docker 环境（推荐使用 Docker 方式部署）
• 支持平台：linux/amd64 或 linux/arm64（较新的 Mac）
• 非 Docker 本地安装需 Python 3.10、git
• 非 Docker 安装推荐使用 uv，也可使用 conda
• 需准备大模型与 Embedding 的 api_key（私有 RAG 可改用 Ollama）

安装与启动步骤

1. 1运行 Docker 镜像

   推荐方式。full 版本含 unstructured 额外包，支持 .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

   复制

2. 2按需切换镜像版本

   lite 版本体积小、多数场景够用；带 ollama 的镜像内置本地模型，适合本地/私有 RAG。

   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

   复制

3. 3指定平台架构

   Mac(arm64) 等场景可在 docker run 中加 --platform 参数显式指定平台。

   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 --platform linux/arm64 ghcr.io/cinnamon/kotaemon:main-lite

   复制

4. 4克隆代码仓库

   不使用 Docker 时的本地安装第一步；项目根目录后续用来创建 .env 文件。

   git clone https://github.com/Cinnamon/kotaemon
   cd kotaemon

   复制

5. 5创建 Python 环境

   推荐用 uv 安装依赖并激活虚拟环境；也可用 conda 方式安装 kotaeom 两个子包。

   uv sync --python 3.10
   source .venv/bin/activate

   复制

6. 6配置 .env 文件

   在项目根目录创建 .env，以 .env.example 为模板，预配置模型 api_key；仅在首次运行时用于填充数据库。

7. 7启动 Web 服务

   运行后应用会自动在浏览器中打开；默认用户名和密码均为 admin，可在界面里新增用户。

   python app.py

   复制

8. 8检查模型配置

   进入 Resources 标签页的 LLMs and Embeddings，确认 api_key 已正确读取，未设置可在此处补填。

关键配置

如何确认成功

浏览器访问 http://localhost:7860/，出现 kotaemon WebUI 即成功；默认用户名和密码均为 admin。

常见问题

注意事项

• README 明确推荐普通用户从最新 release 下载 .zip 直接使用，或参考官方 User Guide。
• Docker 镜像存放在 GHCR，全部镜像可在项目的 Packages 页面查看。
• .env 文件只在首次运行时填充数据库，之后再次启动不会再使用该文件。
• 官方 MS GraphRAG 索引仅支持 OpenAI 或 Ollama API，建议多数用户改用 NanoGraphRAG。