GraphRAG 新手上手指南：init、index、query 三步跑通你的第一份知识图谱

GraphRAG 新手上手指南init、index、query 三步跑通你的第一份知识图谱【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphragGraphRAG 是微软开源的模块化图结构检索增强生成RAG系统它用 LLM 从非结构化文本里抽出实体、关系和社区报告存成知识图谱再基于图谱回答问题。本文给你一份从零到能查的实操路径一条最小可抄的初始化配置、两套索引方法怎么选、哪些参数值得动、哪些坑官方文档里明说了但你大概率会踩。GraphRAG 数据处理管道运行界面展示 CLI 索引各工作流的执行进度先搞清楚 GraphRAG 替你干了什么这一节回答这东西能干什么为什么值得用。普通向量 RAG 是把文档切成块存进向量库问得着、问不深GraphRAG 多了一步先让 LLM 把文档里的实体、关系抽出来聚类成社区再为每个社区生成摘要报告。于是它多了一类普通 RAG 答不了的题——这批文档整体在讲什么主题这种全局性问题靠社区报告做 map-reduce 聚合回答。代价是索引阶段要发大量 LLM 请求官方在 docs/get_started.md 里明确写了GraphRAG indexing can be an expensive operation务必从小数据集开始。这一点后面坑那节还会再提一次。内部能力是怎么分层的这一节给你一张地图后面所有操作都在这张图上。仓库把能力拆成了几个独立包都在 packages/ 下索引主流程packages/graphrag/graphrag/index/里是一串 workflow抽实体关系、聚类、生成社区报告、算向量graphrag/query/是查询引擎。模型调用packages/graphrag-llm/负责补全、embedding、重试、限流、缓存这些脏活。存储与向量packages/graphrag-storage/ 管文件/blob 读写packages/graphrag-vectors/ 管 LanceDB、CosmosDB 等向量库。输入解析与切块packages/graphrag-input/ 支持 txt/csv/json/jsonl/parquet/MarkItDown 等格式packages/graphrag-chunking/ 负责按 token 或句子切块。用 Gephi 打开 GraphRAG 导出的 GraphML 快照可交互查看实体关系网络分层的好处很实际想换向量库、换模型供应商、加自定义切块逻辑都是改配置或替换对应包不用动主流程。最小可用配置长什么样这一节是可以直接抄走的步骤。先建一个干净的目录装包初始化mkdir graphrag_quickstart cd graphrag_quickstart python -m venv .venv source .venv/bin/activate python -m pip install graphrag graphrag initgraphrag init会在当前目录生成三样东西settings.yaml流水线配置、.env只放一行GRAPHRAG_API_KEY你的key、prompts/默认的 LLM 提示词。然后把任何文本丢进input/目录——仓库里就带了个现成的教程数据集docs/data/operation_dulce/Operation Dulce v2 1 1.md一个关于真实历史计划的档案文本官方推荐用它跑通第一遍。真正需要动手改的配置只有三个地方# settings.yaml 中需要关注的片段 input: type: text # 你的文件格式text/csv/json/jsonl chunking: size: 3000 # 每块最大 token 数 overlap: 150 # 相邻块重叠 token 数 extract_graph: entity_types: [organization, person, location, event]改完就是两条命令从索引到提问graphrag index graphrag query What are the top themes in this story? # 全局搜索 graphrag query Who is the main character? --method local # 局部搜索index跑完后会多出一个output/目录里面是一堆 parquet 表entities、relationships、communities、community_reports 等加一个向量库。上面这段是干什么的size/overlap决定切块粒度entity_types决定让 LLM 识别哪几类实体——换成你自己的领域比如product、api就是最直接的领域定制。索引方法怎么选standard 还是 fast这一节解决跑起来太贵、太慢怎么办。docs/index/methods.md 给了两条路standard默认实体、关系、摘要全靠 LLM 推理实体和关系都有文字描述图谱质量高、还能脱离 GraphRAG 单独用。官方估算图抽取占索引成本的约 75%所以它是最贵的那条路。fast用 NLTK/spaCy 做名词短语抽取实体关系靠共现统计只有最后的社区报告还走 LLM。便宜很多但产出的图更吵且不太适合拿去做图谱探索。选择逻辑就一句话你要看实体、要探索图谱用 standard你只要问全局摘要题这类用途用 fast 省钱。命令上加个--method fast即可。fast 模式官方还建议把切块调小到 50~100 token因为共现统计在小块上更准——这是和 standard 完全相反的调参方向别混用。参数怎么调哪些点反直觉这一节只讲真正影响结果的旋钮以及官方文档里明说、但新手容易忽略的点。先调提示词再调参数。docs/prompt_tuning/overview.md 的立场很直接默认提示词开箱即用但未必是你数据上的最优解官方强烈建议先跑graphrag prompt-tune自动调优让它根据你的输入数据生成领域化的提示词再去跑索引。很多人上来就调 chunk size其实提示词适配的收益更大。分块大小反直觉。对 standard 方法块越大 LLM 一次看的信息越多、实体抽取的上下文越完整代价是单条请求 token 更多对 fast 方法则相反要小不要大。没有跨场景的最优值需要拿你自己的数据实测。社区报告是全局搜索的命根。community_reports段的max_input_length控制生成报告时喂给 LLM 的上下文上限调小了报告质量会肉眼可见地变差extract_claims主张抽取默认关闭官方原因是 claim 类提示词必须人工调过才有意义没把握就先别开。全量重跑其实很便宜。cache段默认是json文件缓存同一份输入、同一份提示词重跑索引时LLM 结果直接命中缓存重复调参基本不产生重复费用——前提是别改提示词。这些坑官方都替你写好了这一节是避坑清单全部来自仓库里的明文提示不是推测。索引很贵先跑小数据。这是 docs/get_started.md 开头第一条警告也是 README.md 的红色警告。正确姿势先用docs/data/operation_dulce/这个教程数据集跑通全流程看懂output/里的表长什么样再考虑上生产数据且先换便宜快速的模型试。跨小版本升级后一定要重新 init。README.md 写了每次 minor 版本升级后跑graphrag init --root [path] --force刷新配置格式跨大版本则跑仓库里docs/examples_notebooks/下的迁移 notebook但注意它会覆盖你的settings.yaml和prompts/动手前先备份。输出默认存 parquet向量默认进 LanceDB。想在 Gephi 里看图去snapshots段打开graphml: true索引完导出的 GraphML 拖进 Gephi 就能交互浏览这也是官方 docs/visualization_guide.md 的推荐调试方式——调试提示词和实体类型时肉眼看图比看表快得多。一句话回顾GraphRAG 就是先用 LLM 把文档变成图谱和社区报告再基于图谱回答的模块化流水线init → index → query三步就能跑通。下一步建议拿docs/data/operation_dulce/数据集完整跑一遍然后按 docs/prompt_tuning/overview.md 把自动提示词调优也跑一遍再上你的真实数据。【免费下载链接】graphragA modular graph-based Retrieval-Augmented Generation (RAG) system项目地址: https://gitcode.com/GitHub_Trending/gr/graphrag创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考