详细阐述了在本地环境中部署 GraphRAG（基于知识图谱的检索增强生成）的完整流程。通过结合 Ollama 本地大模型与 LM Studio 嵌入服务，配置 GraphRAG 核心参数，实现了对私有数据的深度索引与检索。文章对比了 GraphRAG 与传统 RAG 在处理复杂关系查询时的差异，指出 GraphRAG 能更好地捕捉数据全貌与实体关联。同时总结了部署过程中常见的报错原因及解决方案，如模型兼容性、分块大小设置等，为开发者提供了实用的落地参考。
大型语言模型（LLM）的前沿研究中，一个核心挑战与机遇并存的领域是扩展它们的能力，以解决超出其训练数据范畴的问题。虽然 AI Agent 的解决方案使得 LLM 有了自己的分析决策能力，并能通过调用 Tool 来获取外部最新的数据信息，或者使用开源模型均可使得 LLM 有获取最新数据的能力来解决用户提出的问题，但在更多的场景下，用户需要咨询的信息是无法从公开的网络中进行获取，甚至大部分问题可能是某些公司内部业务的领域知识或者是企业的私有数据等。这时候就需要用到在 RAG 方案来增强这样的 AI 场景处理效率。
目前，RAG 是大语言模型搜索增强的主要方案之一。它允许大语言模型在从固定的数据库中抽取相关内容的基础上生成答案，从而限制随意发挥，提升答案的可靠性。可以说，RAG 是目前各类大模型落地项目不可缺少的实用技术组件。目前集团内外基于 AI 知识库问答的功能，大部分使用了 RAG 技术。
GraphRAG 全称为 Graph-based Retrieval Augmented Generation，是一种结合了知识图谱和检索增强生成（RAG）技术的新方法。传统的 RAG 技术通过从外部知识库中检索相关信息，增强生成模型的输出质量。而 GraphRAG 则进一步引入了知识图谱，将信息以节点和边的形式存储，提供更丰富的上下文和关系信息，从而提升生成效果。
相比于传统的 RAG 技术，GraphRAG 在多个方面展现出了显著的优势：
虽然看起来 GraphRAG 确实令人眼前一亮，但从实际反馈来看，大家对 GraphRAG 的使用效果还是有所存疑。带着这个疑问，笔者也准备本地搭建一套 GraphRAG 的 demo 来测试一下检索效果，对比一下传统 RAG 方案与 GraphRAG 到底有没有提升。
本文准备通过 Ollama 工具提供本地 LLM 模型服务，通过 LM Studio 来提供嵌入模型服务，运行环境在 Python venv 下，Python 环境 3.11~3.12 均可。
本地 LLM 使用的是 Gemma，启动命令如下：
ollama run gemma
确保 Ollama 服务正常运行，默认监听端口为 11434。
因为目前 Ollama 无法直接提供符合 OpenAI 标准的嵌入模型接口，所以这里使用 LM Studio 来启动嵌入模型提供服务。大家可以直接去官网下载对应的芯片版本，下载后进行安装。
首次使用的时候，直接通过关键字搜索模型是会报网络错误，核心原因是 LM Studio 通过本地网络访问 HuggingFace 时访问失败，可以通过配置代理或离线下载模型来解决此错误。
搜索 nomic 关键字，选择 nomic-embed-text-v1.5.Q4_K_M.gguf 模型下载，下载成功后加载到 LM Studio。
选择我们刚刚下载的嵌入模型 nomic-embed-text-v1.5.Q4_K_M.gguf，点击启动服务即可。确保 API 模式已开启，默认端口通常为 1234。
新建 Python 工程，类型选择 venv，Python 版本选择 3.11。
在 PyCharm 终端执行命令安装 graphrag：
pip3 install graphrag
安装完成后，再执行如下命令创建资料输入目录：
mkdir -p ./ragtest/input
然后在 input 目录下录入想要测试的文本资料，文件格式 txt。我是选取的内容作为测试内容，大家可以自行选取感兴趣的内容。
终端执行如下代码：
python3 -m graphrag.index --init --root ./ragtest
此时初始化成功后工程结构如下所示，会生成 settings.yaml 等配置文件。
由于我们使用本地环境，所以 env 文件不用去理会，直接开始配置 settings.yaml。以下是修改的配置区块，主要是关于 LLM、embeddings 还有 chunk 的 size 设置，其他保持默认：
api_key: ollama
type: openai_chat # or azure_openai_chat
model: gemma
model_supports_json: false # recommended if this is available for your model.
api_base: http://127.0.0.1:11434/v1
embeddings:
## parallelization: override the global parallelization settings for embeddings
async_mode: threaded # or asyncio
llm:
api_key: lm-studio
type: openai_embedding # or azure_openai_embedding
model: nomic-ai/nomic-embed-text-v1.5-GGUF/nomic-embed-text-v1.5.Q4_K_M.gguf
api_base: http://localhost:1234/v1
chunks:
size: 300
overlap: 100
group_by_columns: [id] # by default, we don't allow chunks to cross documents
配置说明：
api_base: 指向本地 Ollama 和 LM Studio 的服务地址。model: 指定使用的模型名称，需与本地安装的模型一致。chunks: 分块大小直接影响索引效果和内存占用。较小的块能提高检索精度但增加计算量，较大的块可能丢失细节。当 GraphRAG 环境配置完成后，执行如下命令对 input 文件夹 txt 内容建立索引：
python3 -m graphrag.index --root ./ragtest
终端会显示相关的一些 GraphRAG 的流水线执行过程日志，包括文档解析、分块、实体提取、社区发现等步骤。
当执行索引成功后，就会看到 All workflows completed successfully. 提示语。
虽然过程看起来很简单，但其实中间还是有不少的坑，其中一直困扰我的一个报错就是 Columns must be same length as key。尝试搜索了很多资料，甚至也去 debug 了 GraphRAG 包的 Python 源码，但收效甚微。最终笔者尝试了以下几个方向的分析调试：
gemma:latest。曾经一度也放弃过 demo 的搭建，因为在 GraphRAG 的技术人员也明确提出了对本地 Ollama 环境的支持不是特别完善，有很多问题，也委婉表示了暂时没有精力来解决此类问题，以至于认为 GraphRAG 确实不适合通过本地模型环境来进行搭建。建议优先选择官方推荐或经过验证的模型。nomic-embed-text-v1.5.Q5_K_M.gguf，后改用 nomic-embed-text-v1.5.Q4_K_M.gguf。量化级别不同可能导致向量维度或精度差异，影响索引构建。索引建立完成后，可以通过命令执行提问：
python3 -m graphrag.query --root ./ragtest --method global "刘备是谁？"
python3 -m graphrag.query --root ./ragtest --method global "刘备关羽张飞是什么关系？"
由于我只索引了三国演义的第一章（全文需要索引的时间太长了，好像看了要 7~8 个小时，马上就终止了），所以目前能搜索摘要出来的内容有限。
下图是我使用 AnythingLLM，通过传统 RAG 技术搜索出来的结果，能关联的内容较少，而通过 GraphRAG 极大地改进了 RAG 的'检索'部分，用更高相关性的内容来显示检索结果，从而得到更好的答案。
GraphRAG 在处理多跳查询（Multi-hop queries）和聚合性问题时表现尤为出色，因为它利用了图谱中的路径信息，而不仅仅是关键词匹配。
通过搭建 GraphRAG 本地 demo 后，笔者通过少量的文本内容（三国演义第一章），初略对比了一下传统 RAG 方案与 GraphRAG 方案。基于少量文本内容而言，GraphRAG 的效果还是符合其宣传内容的，后续更严谨的测试还是需要海量数据的进行验证。
部署建议：
希望本文能帮助到对 GraphRAG 有兴趣的朋友，毕竟读万卷书不如行万里路，看再多的理论介绍，不如自己亲自去动手验证一把来的实在。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online