GraphRAG 安装与使用

微信 ezpoda免费咨询：AI编程 | AI模型微调| AI私有化部署
AI工具导航 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

如果常规RAG持续给您分散的答案，GraphRAG通常是使响应更智能的升级。它不是将文档视为独立的部分，而是提取实体和关系，构建知识图谱，将相关细节分组为社区，并在检索信息时使用这些摘要。这种方法有助于回答依赖于模式、上下文和跨多个文档连接的问题。

GraphRAG工作空间只是存储文档、设置、提示和输出的项目文件夹。最近的GraphRAG版本通过添加init命令大大简化了这一点，该命令为您创建一个入门配置。现在，您的第一个工作空间是一个实用、可重复的设置，而不是一堆手写的配置文件。

1、GraphRAG与标准RAG的不同之处

标准RAG通常将文档分解为块，并使用向量相似性检索它们。GraphRAG也使用嵌入，但增加了结构：实体成为节点，关系成为边，相关节点被分组为社区，并且在您运行查询之前会先总结这些社区。

在实践中，这意味着GraphRAG可以通过全局搜索回答关于整个集合的广泛问题，通过本地搜索专注于特定实体，并使用DRIFT搜索处理既需要细节又需要概述的问题。

这种额外的能力带来了权衡。索引需要更多资源，因为GraphRAG需要在您提问之前提取信息、构建图谱、聚类数据并进行总结。Microsoft的仓库和DataCamp指南都建议从小数据集开始评估成本和质量，然后再使用更大的数据集。

2、安装GraphRAG之前

Microsoft当前的快速入门建议使用Python 3.10到3.12进行基本的GraphRAG设置。最简单的开始方式是使用干净的虚拟环境、一小部分文档样本、一个可靠的补全模型和一个可靠的嵌入模型。

Microsoft当前的文档使用标准的pip和venv流程进行快速入门，而一些教程（如DataCamp的）显示了基于uv的设置。两者都是常见的Python工作流，但官方快速入门是最简单的起点。

决定您想要什么样的第一个工作空间也很有用。Microsoft CLI是学习工作流最简单的方式。如果您想要更高的隐私性或更低的每次调用成本，使用vLLM和Ollama的本地设置很有帮助。如果您的项目已经使用图数据库，Neo4j效果很好。如果您想要从一开始就具有图存储、向量存储和云笔记本的托管设置，AWS的GraphRAG工具包是一个不错的选择。

3、安装GraphRAG并初始化工作空间

最简单的开始方式是创建一个项目文件夹，激活虚拟环境，安装graphrag，然后运行graphrag init。官方文档还说您可以使用—root在自定义目录中设置，如果您希望工作空间有明确的名称，这很有用。

mkdir my_graphrag_workspace
cd my_graphrag_workspace
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install graphrag
graphrag init --root .

您可能还会注意到在设置期间选择默认聊天模型和嵌入模型的新CLI选项。当前的CLI参考显示init支持—model和—embedding，并列出了默认值。这使您可以将第一个工作空间设置为使用特定的模型对，而不是依赖于提示或继承的默认值。

4、了解GraphRAG为您创建了什么

当您初始化工作空间时，GraphRAG会创建项目所需的所有文件：用于密钥的.env文件、用于管道和模型设置的settings.yaml文件，以及用于提取和总结的提示文件。input文件夹是放置源文档的地方。

DataCamp指南还指出了prompts/目录，因为您以后可以在那里针对法律、金融、生物技术或公司知识等特定领域自定义GraphRAG。

这就是为什么工作空间很重要。您不仅仅是在创建一个文件夹；您是在构建一个可以随着时间的推移进行索引、搜索、调整和更新的项目结构。Microsoft的文档还提到，新版本支持提示调优和增量更新，这对于工作空间发展为真正的知识库很有帮助。

5、将文档添加到input文件夹

对于您的第一个GraphRAG工作空间，纯文本是最简单的格式。Microsoft的快速入门在input文件夹中使用了《圣诞颂歌》的文本副本，而DataCamp教程使用了三个相关的Paul Graham文章，以保持内容小、清晰且易于索引。

更广泛的配置文档还显示GraphRAG可以摄取.txt、.csv和.json输入，但.txt是第一次成功运行的最快途径。

您可以从一个文档开始，但使用三到五个相关文件通常会提供更好的学习体验。这足以创建有意义的社区和关系，而不会减慢或增加第一次索引的成本。MachineLearningMastery指南还指出，大文档会被分成更小的部分，图谱的质量很大程度上取决于这些块中的内容。

# 官方快速入门示例
curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./input/book.txt

6、配置模型和一些有用的设置

至少，您需要将API密钥添加到.env文件。Microsoft的快速入门说OpenAI模式只需要GRAPHRAG_API_KEY，而Azure用户还需要在settings.yaml中设置正确的模型和端点值。在幕后，GraphRAG使用LiteLLM进行模型调用，其配置包括model_provider、model、api_key和api_base等字段。

教程中的默认设置可能因版本而异。例如，DataCamp使用gpt-4o-mini和text-embedding-3-small，而当前CLI文档列出了init的不同默认值。这是一个很好的提醒，不要在没有检查的情况下复制旧设置。最重要的是，您的补全模型为提取返回干净、结构化的输出，并且您的嵌入模型在整个工作流中一致使用。

对于您的第一个工作空间，最好保留大多数设置不变。一旦基础设置正常工作，最有用的调整设置是块大小和重叠、实体类型以及max_gleanings（控制额外提取传递的参数）。DataCamp的示例还显示了cluster_graph.max_cluster_size，它改变了图社区的分组紧密程度。

7、运行索引管道

一旦您的输入文件和配置准备就绪，索引就很简单了。在工作空间内，只需运行graphrag index。如果您从其他位置工作，CLI还支持—root指向您的项目目录。

graphrag index
# 或
graphrag index --root .

在内部，GraphRAG将输入分块，提取实体和关系，将重复项合并到图中，检测社区，编写社区报告，并生成查询所需的嵌入。DataCamp指南清晰地展示了这些管道阶段，MachineLearningMastery文章从系统角度解释了相同的流程：文本变成节点，节点变成图结构，社区被总结，这些摘要帮助创建最终答案。

索引完成后，GraphRAG将输出文件保存到output文件夹，通常为Parquet格式。官方快速入门和DataCamp文章都描述了这一点，DataCamp文章指出实体、关系、社区和文本单元是分开存储的，使图易于检查。

8、提出您的第一个问题

检查工作空间的最快方法是问一个广泛的问题和一个具体的问题。全局搜索用于查找整个集合中的主题，而本地搜索侧重于使用图和源文本推理特定实体。

graphrag query "这个故事中的主要主题是什么？"
graphrag query "谁是Scrooge，他的主要关系是什么？" --method local

GraphRAG还支持—method drift，这是全局搜索和本地搜索之间的中间地带。DRIFT从社区级上下文开始，然后探索更具体的细节，这有助于处理既需要概述又需要具体事实的问题。

graphrag query "主要关系如何与更广泛的主题联系？" --method drift

简单来说，使用全局搜索获取大局概述，使用本地搜索获取关于人员、公司或想法的详细信息，当您的问题从具体开始但也需要上下文时使用DRIFT。这种三部分方法是GraphRAG对于连接数据比标准RAG更有用的关键原因。

9、使用vLLM和Ollama在本地运行GraphRAG

如果您想将数据保留在自己的计算机上或降低持续的API成本，在本地设置GraphRAG是一个不错的选择。本地安装指南的主要思想是使用一个服务进行生成，另一个服务进行嵌入。通常，这意味着使用vLLM作为聊天模型，使用Ollama作为嵌入模型（如nomic-embed-text）。

根据vLLM的官方快速入门，它可以作为OpenAI兼容服务器运行，默认在http://localhost:8000启动。文档建议在提供模型之前设置新环境并安装vLLM。Ollama的文档显示了一键安装脚本和拉取nomic-embed-text的简单方法，默认本地嵌入端点在端口11434上。

# vLLM
uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto
vllm serve <your-model>

# Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text

重要的GraphRAG细节是配置。当前的GraphRAG配置文档公开了model_provider、model和api_base，Microsoft的模型选择页面说可以通过代理API（如Ollama或LiteLLM Proxy）访问自定义模型。它还警告代理或本地模型有时会因返回格式错误的JSON而失败，因此本地GraphRAG可以很好地工作，但前提是您选择的模型在结构化提取方面可靠。

10、Neo4j和AWS：两个强大替代方案

如果您的项目已经使用图数据库，Neo4j的GraphRAG包是逻辑上的下一步。Neo4j指南显示了一个简单的设置：连接Neo4j驱动程序，创建检索器，附加LLM，然后运行GraphRAG查询。当前文档说您安装包为neo4j-graphrag，它支持Python 3.10及以上版本，并提供OpenAI和Ollama等提供商的可选附加组件。

如果您想要云优先的工作空间，AWS的GraphRAG工具包围绕索引到图存储和向量存储构建。AWS博客的快速入门使用CloudFormation配置Neptune、OpenSearch Serverless和SageMaker笔记本，Bedrock模型处理提取、嵌入和生成。这使其非常适合当您的"第一个工作空间"实际上是团队的第一个内部平台，而不是单独的本地实验。

11、第一次尝试时常见的错误

第一个常见错误是从太多数据开始。GraphRAG在连接数据集上效果最好，但索引比基本向量RAG要求更高、成本更高。最好从小而专注的数据集开始测试您的设置。

第二个错误是在没有验证本地模型是否有效提取信息的情况下，将它们作为即插即用替代品使用。Microsoft的文档说基于代理的自定义模型可以工作，但结构化输出的失败很常见。如果本地GraphRAG似乎不可靠，问题通常是提取模型返回了管道无法解析的输出。

第三个错误是将GraphRAG用于常规RAG已经处理得很好的问题。对于非常小的数据集或简单的事实查找，标准向量RAG通常更便宜且足够快。当问题依赖于关系、需要多步推理或跨越多个文档时，GraphRAG的额外复杂性才值得。

12、常见问题解答

graphrag init实际上做了什么？

它为索引设置入门项目结构：环境变量、设置、提示文件以及用于文档的input文件夹。在新版本中，这是GraphRAG设置比首次推出时容易得多的主要原因。

没有图数据库我可以构建GraphRAG工作空间吗？

可以。Microsoft的参考工作流从工作空间中的本地文件开始，并在索引后写入输出工件。图数据库在Neo4j GraphRAG或AWS的GraphRAG工具包等包中变得更加重要，因为数据库从一开始就是架构的一部分。

GraphRAG值得额外的设置吗？

当您的用户提出跨越文档、依赖关系或需要主题摘要的问题时，GraphRAG通常值得额外的设置。如果任务只是找到最近的块并引用它，则通常不需要。这是GraphRAG与更简单的RAG系统之间的主要区别。

13、最终要点

设置GraphRAG并创建您的第一个工作空间现在比以前容易得多。当前的Microsoft CLI让您快速创建工作空间，添加一些文档，对它们进行索引，并运行您的第一个全局和本地查询。

一旦基础设置正常工作，您可以通过提示调优、增量更新、使用vLLM和Ollama的本地模型服务或基于图的堆栈（如Neo4j或AWS）来扩展您的设置。最好的第一个工作空间足够小，可以在第一次尝试时成功，并且足够详细，以展示基于图的检索为何脱颖而出。

原文链接: How to Install GraphRAG and Create Your First Workspace

汇智网翻译整理，转载请标明出处