GraphRAG 常见报错怎么排查
不确定错误来自哪里时，从下面五步开始。前一步没有通过，不要急着重建索引。
五步排查
- 确认当前环境中的
graphrag --version与项目配置版本一致。 - 在项目根目录运行
graphrag index --dry-run。 - 检查
input/是否包含可读文本，.env是否提供有效密钥。 - 正式索引后确认
output/中核心 Parquet 文件存在且非空。 - 使用一条能从样本文本直接回答的问题做 Basic 或 Local 查询。
常见现象
| 现象 | 优先检查 | 不要先做什么 |
|---|---|---|
| 初始化后立即报认证错误 | .env、Provider、端点和部署名 | 反复重建索引 |
| 索引完成但查询无结果 | 运行目录、输出路径、实体抽取质量 | 只增加上下文窗口 |
| Global 很慢或费用高 | 社区层级、报告数量、问题是否真需要全局汇总 | 默认扩大并发和 token |
| 旧教程命令找不到模块 | 改用 graphrag init/index/query/update | 安装旧版本迁就教程 |
需要提交问题时，提供 GraphRAG 版本、完整命令、脱敏后的配置片段和首个错误，而不是只提供最后一行堆栈。