GraphRAG 知识图谱实战完整指南：四步把一堆文本变成能问答的系统

GraphRAG 知识图谱实战完整指南四步把一堆文本变成能问答的系统【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphragGraphRAG 是一个开源的模块化图结构检索增强生成RAG系统它用 LLM 从原始文本中抽取实体和关系自动构建知识图谱再让你对整个语料库提问。本文带你走一遍完整流程——准备环境、建索引、提问、调优每一步都是照着做就能跑通的那种。十分钟准备好Python、API Key 和一份小样本先把三样东西备齐后面就不会卡。新手最容易犯的错误是一上来就丢几 GB 的文档进去建索引——LLM 调用量会非常可观。官方文档也明确建议从小数据集开始。装好 Python 3.10 到 3.12 任一版本。准备一个 LLM 服务的 API KeyOpenAI 或 Azure OpenAI 均可。准备一份小规模文本放进input目录。仓库自带测试数据集可以参考比如 tests/fixtures/text/ 下的样本或者任意几篇你熟悉的文档。如果你需要本地浏览源码和示例 Notebook仓库地址是git clone https://gitcode.com/GitHub_Trending/gr/graphrag大多数场景其实不用克隆直接装包就行python -m pip install graphrag准备工作就绪了接下来花三分钟初始化你的工作区。一条命令建好工作区graphrag init 会生成什么 graphrag init会替你生成三个关键产物知道它们各管什么后面配置才不乱。在你想放项目的位置空目录执行graphrag init。按提示选择默认的聊天模型和向量模型。完成后目录里会多出三样东西文件作用你要做什么.env存放环境变量把GRAPHRAG_API_KEY换成你自己的 Keysettings.yaml整条索引流水线的配置按需微调下一节讲input/输入文档目录把文本文件丢进来把 Key 填进.env就够 OpenAI 场景直接跑。Azure 用户还需要在settings.yaml的models:下补上azure_deployment_name和api_base等字段完整字段说明见 docs/config/overview.md。配置这步其实很轻因为默认配置是开箱即用的设计。但有两处值得动手一是换更省钱的模型二是确认输入格式。改完settings.yaml就可以跑索引了。第一次跑 graphrag index看流水线把文本变成图谱 ⚙️索引是 GraphRAG 的核心动作切文本 → 抽实体和关系 → 做社区检测 → 生成社区报告 → 写向量。整个过程的输出都落在output目录里默认是一组 Parquet 文件。graphrag index跑起来后终端会实时显示每个工作流的进度实体抽取阶段通常最久耐心等它到 100% 即可。完成后重点看这几张表输出文件里面是什么entities.parquetLLM 抽出的实体人物、地点、机构……relationships.parquet实体之间的关系communities.parquet社区检测算出的分层聚类community_reports.parquet每个社区一段 LLM 生成的摘要报告下表字段的完整定义在 docs/index/outputs.md流水线的整体架构在 packages/graphrag/graphrag/index/ 里可以读到。图里每个点是实体、连线是关系一团一团的正是社区结构。看到这张图知识图谱就不再是抽象概念了。索引产物齐了接下来最爽的环节提问。问第一个问题Local、Global、DRIFT 三种检索怎么选 同一个索引问法不同答案质量可以差很多——选对检索方法比调参更见效。打开终端就能问graphrag query 这个故事的主题是什么 graphrag query 谁是主角他和谁关系最密切 --method local三种方法的区别用大白话讲检索方法适合的问题工作原理大白话资源消耗Global默认全局性主题、趋势、整体在讲什么汇总所有社区的报告map-reduce 式回答较高Local实体性某个人、某件事、某段关系定位实体把图谱局部 原文片段拼给 LLM中等DRIFT从具体实体出发但需要更宽的上下文先像 Local 一样定位再借社区报告扩散出更多事实中到高选择口诀问整体用 Global问某个东西用 Local两者都像就用 DRIFT 兜底。更细的原理和参数见 docs/query/overview.md检索实现的代码在 packages/graphrag/graphrag/query/ 下。上面这张图来自仓库里的 unified-search-app 示例左边开关可以同时打开 basic RAG、local、global 几种检索右边并排对比答案是验证检索效果最直观的方式。答案有了但如果你觉得答得不够懂行还有一步很多人漏掉。答案不够专业跑一次自动提示词调优默认提示词是通用的换成贴合你领域的提示词抽取质量会明显改善。这一步官方在文档里明确写了强烈建议执行但新手经常直接跳过导致实体类型泛泛一堆实体 A、实体 B。python -m graphrag prompt-tune --root /path/to/your/project --no-discover-entity-types它会采样你的输入文本让 LLM 反推出适合该领域的实体类型和抽取提示词输出到prompts目录数据主题跨度大时加上--discover-entity-types让模型自动发现实体类型。调优完按 docs/prompt_tuning/auto_prompt_tuning.md 的说明改一下配置里的提示词路径重新graphrag index即可。调优属于第二遍更好的活第一遍先跑通再说。下面这张表帮你把跑不通的情况快速对号入座。报错了别慌一张表自查六个高频问题 ️现象大概率原因处理办法索引启动即报鉴权错误.env里 Key 没填或填错检查GRAPHRAG_API_KEY索引跑了几小时还没完输入量太大或模型太慢换小样本、先换轻量模型试水抽出的实体很笼统、重复多在用默认提示词跑领域数据跑一次graphrag prompt-tune想画图却找不到graph.graphml没开图谱快照settings.yaml里加snapshots: graphml: true全局问题答得偏、实体问题答得空检索方法选错换--method local/ 默认 global 再试升级版本后配置报错配置格式不兼容按官方建议重新graphrag init --root . --force排错完成后建议养成一个习惯用可视化工具亲手看一眼图谱比翻 Parquet 表直观得多。眼见为实用 Gephi 打开你的知识图谱把output/graph.graphml拖进 Gephi图谱长什么样、社区聚得对不对五分钟心里有数。确认settings.yaml里snapshots: graphml: true重新跑一次索引生成graph.graphml。在 Gephi 的Tools → Plugins里安装 Leiden Algorithm 插件并重启。导入图谱文件在 Statistics 面板运行 Average Degree 和 Leiden AlgorithmQuality function 选 ModularityResolution 设为 1。在 Appearance 面板按 Cluster 给节点着色按 Degree 调整节点大小再用 OpenORD 或 ForceAtlas2 排版。完整操作细节、推荐参数都在 docs/visualization_guide.md 里照着点就行。小结你的四步清单准备Python API Key 一份小样本先跑通再谈规模。初始化与配置graphrag init改好.env和settings.yaml。索引与提问graphrag index生成图谱再按问整体用 Global、问实体用 Local选检索方法。打磨graphrag prompt-tune贴合领域Gephi 里目检图谱质量。GraphRAG 的设计就是模块化、可配置见 docs/config/overview.md跑通第一遍之后每个环节你都能单独调整。建议先用仓库自带的小数据集把整条链路走一遍再换成自己的业务数据——顺序反了调试成本会高很多。【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphrag创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考