kotaemon 如何安装 nano-graphrag 并启用 NanoGraphRAG 索引？-开发者社区

kotaemon 如何安装 nano-graphrag 并启用 NanoGraphRAG 索引？

【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon

如果你的目标是在 Kotaemon 中启用 README.md 推荐的 NanoGraphRAG 索引实现（README 指出官方 MS GraphRAG 索引只支持 OpenAI 或 Ollama API，因此建议大多数用户使用 NanoGraphRAG），需要完成三件事：在 Kotaemon 环境里安装nano-graphrag包、用USE_NANO_GRAPHRAG=true环境变量启动应用、在 Resources 面板设置默认的 LLM 与 Embedding 模型。前提是Kotaemon 已按 README 安装完成（Python >= 3.10），且你使用的是非 Docker 或 Docker 任一部署方式。

前提：Kotaemon 已安装并可启动

以下安装步骤摘自 README.md 的 "Installation" 一节，本文只保留与后续操作相关的部分：

系统要求：Python >= 3.10；如需处理.pdf、.html、.mhtml、.xlsx以外的文件类型，还需按 README 指引安装 Unstructured。
环境准备（两种方式任选其一）：

# 方式 1：uv（README 推荐） uv sync --python 3.10 source .venv/bin/activate # 方式 2：conda conda create -n kotaemon python=3.10 conda activate kotaemon pip install -e "libs/kotaemon[all]" pip install -e "libs/ktem"

启动应用：

python app.py

应用会自动在浏览器中打开，默认用户名和密码均为admin。

按 README 第 6 步，检查Resources页LLMs and Embeddings中的api_key是否已从.env正确填充；未填充时可直接在该页面设置。

第 1 步：安装 nano-graphrag

在激活的 Kotaemon 环境中执行：

pip install nano-graphrag

README 明确提示该安装可能引入版本冲突（README 指向仓库的 issue #440）。文档给出的快速修复命令是：

pip uninstall hnswlib chroma-hnswlib && pip install chroma-hnswlib

副作用说明：这条命令会卸载hnswlib和chroma-hnswlib两个包，然后重新安装chroma-hnswlib。只有当安装nano-graphrag后确实出现依赖冲突、影响到 Kotaemon 运行时才需要执行。

第 2 步：用环境变量启用 NanoGraphRAG

非 Docker 方式下，带环境变量启动：

USE_NANO_GRAPHRAG=true python app.py

USE_NANO_GRAPHRAG的默认值是False（见 flowsettings.py 中config("USE_NANO_GRAPHRAG", default=False, cast=bool)），所以必须显式设置。

设置后，flowsettings.py 会把ktem.index.file.graph.NanoGraphRAGIndex追加进GRAPHRAG_INDEX_TYPES，应用随之注册一个新的索引类型NanoGraphRAG Collection，其支持的文件类型为.png, .jpeg, .jpg, .tiff, .tif, .pdf, .xls, .xlsx, .doc, .docx, .pptx, .csv, .html, .mhtml, .txt, .md, .zip（同一段GRAPHRAG_INDICES配置）。索引的输入/输出管线由 nano_pipelines.py 中的NanoGraphRAGIndexingPipeline与NanoGraphRAGRetrieverPipeline承担，索引类本身见 nano_graph_index.py。

Docker 方式（可选分支）：README 的示例用-e传递环境变量（如-e GRADIO_SERVER_NAME=0.0.0.0），按同一模式，在 README 给出的docker run命令中追加-e USE_NANO_GRAPHRAG=true即可。

第 3 步：设置默认 LLM 与 Embedding 模型

README 的要求是："Set your default LLM & Embedding models in Resources setting and it will be recognized automatically from NanoGraphRAG."

具体操作路径（来自 docs/usage.md）：

进入Resources页，选择LLMs子页，再到Add子页；
填写模型名称、选择供应商（例如ChatOpenAI）、填写规格，并可（Optional）勾选设为默认；
点击Add，然后在Embedding Models子页重复上述步骤添加一个 Embedding 模型；
确认两个模型都已设为默认。

代码层面，nano_pipelines.py 的get_default_models_wrapper()在索引和检索两个阶段都取llms.get_default()与embeddings.get_default()，因此只要 Resources 里设好了默认模型，NanoGraphRAG 就会直接使用它们，不需要为 NanoGraphRAG 单独再配置 API key 或 endpoint（这一点与 MS GraphRAG 需要设置GRAPHRAG_API_KEY不同）。

验证：索引已启用且可用

1. 启动阶段的依赖检查。nano_pipelines.py 在import nano_graphrag失败时会打印：

Nano-GraphRAG dependencies not installed. Try `pip install nano-graphrag` to install. Nano-GraphRAG retriever pipeline will not work properly.

如果启动日志中没有这条提示，说明依赖已就位；出现该提示则回到第 1 步检查安装。

2. 索引进度输出。对文档执行 GraphRAG 索引时，debug 通道会依次输出（文档中的原始字符串，其中数字随实际文件数量变化）：

[GraphRAG] Creating/Updating index... This can take a long time. [GraphRAG] Creating index: 0 / <总数> documents. [GraphRAG] Indexed <已完成> / <总数> documents. [GraphRAG] Indexing finished.

若目标目录下已存在图文件，措辞变为Updating index/Updated ... documents./Update finished.，表示进入增量更新。

3. 图文件的落盘位置。索引数据保存在文件存储目录下的nano_graphrag子目录中，完整路径为{KH_FILESTORAGE_PATH}/nano_graphrag/{graph_id}/input/（KH_FILESTORAGE_PATH定义在 flowsettings.py）。按 README，应用数据默认全部存放在./ktem_app_data目录。该目录下的graph_chunk_entity_relation.graphml是代码判断"图是否已存在"的依据，可用来核对索引是否真正生成。

4. 检索行为。检索器在应用 Settings 页暴露一个 "Search type" 下拉框，默认值local，可选local/global，界面说明为 "Whether to use local or global search in the graph."。local模式下检索结果会附带知识图谱可视化（代码注释明确 only local mode support graph visualization）；global模式直接返回查询上下文。

可选项与边界

索引选项：nano_pipelines.py 的get_user_settings会在 Settings 页暴露索引批大小（默认 4，界面说明 "reduce if you have rate limit issues"）以及 nano-graphrag 内置 prompt 的覆盖项，可按需调整。
适用范围：README 中 "Official MS GraphRAG indexing only works with OpenAI or Ollama API" 的限制针对的是 MS GraphRAG 实现；NanoGraphRAG 使用的是 Resources 中你设定的默认模型。
版本冲突：如第 1 步所述，仅在实际出现依赖冲突时执行 README 给出的hnswlib/chroma-hnswlib修复命令。

启用之后，按 docs/usage.md 的常规流程即可使用该索引：在File Index页拖放文件并点击Upload and Index，然后在Chat页的会话设置面板中选择文件（Disabled / Search All / Select）开始对话。

【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考