GraphRAG 配置体系详解settings.yaml 核心参数与模型 Provider 配置终于到了工程实践部分。GraphRAG 的配置体系是很多人踩坑的重灾区——一个参数调错轻则索引失败重则整个系统跑偏。这篇文章把settings.yaml的每一个核心参数讲透并给出生产环境的配置建议。一、GraphRAG 配置文件的整体结构GraphRAG 使用 YAML 格式的配置文件默认路径为settings.yaml。完整的配置结构如下settings.yaml │ ├── llm # LLM 配置实体抽取/社区摘要生成/问答生成 │ ├── api_base │ ├── api_key │ ├── model │ ├── max_tokens │ ├── max_retries │ └── timeout │ ├── embedding # Embedding 模型配置向量化 │ ├── api_base │ ├── api_key │ ├── model │ ├── batch_size │ └── max_tokens │ ├── chunks # TextUnit 切分配置 │ ├── chunk_size │ ├── chunk_overlap │ └── overlap_subsample │ ├── extraction # 实体抽取配置 │ ├── num_threads │ ├── max_gleanings # 多轮补充抽取轮数 │ └── entity_types │ ├── graph # 图构建配置 │ ├── max_graph_degree │ ├── max_input_tokens │ └── link_weights │ ├── community_report # 社区摘要配置 │ ├── max_length │ ├── depth │ └── prompt │ ├── storage # 存储配置 │ ├── type # file / blob / memory │ ├── base_dir │ └── ... │ └── input # 输入配置 ├── type # file / blob └── source_dir二、LLM 配置最关键的参数组2.1 基本 LLM 参数llm:api_key:${OPENAI_API_KEY}# 环境变量引用api_base:https://api.openai.com/v1model:gpt-4o# 抽取用模型通常需要较强能力max_tokens:2000# 单次 LLM 输出的最大 Token 数max_retries:3# API 调用失败重试次数timeout:60# 单次调用超时秒temperature:0# 抽取和摘要用 0保证确定性2.2 不同任务的模型选择策略GraphRAG 中有多个 LLM 调用场景并不是所有场景都需要最强模型┌──────────────────────────────────────────────────────────────┐ │ 不同任务的模型选择策略 │ └──────────────────────────────────────────────────────────────┘ ┌──────────────────┬──────────────┬────────────────────────┐ │ 任务 │ 推荐模型 │ 理由 │ ├──────────────────┼──────────────┼────────────────────────┤ │ 实体关系抽取 │ gpt-4o │ 需要强语义理解 │ │ 社区摘要生成 │ gpt-4o-mini │ 摘要质量要求高但成本可控│ │ Global Map-Reduce│ gpt-4o-mini │ 并发量大用小模型节省成本│ │ Local Search 生成 │ gpt-4o │ 上下文复杂需要强理解力 │ └──────────────────┴──────────────┴────────────────────────┘ 优化技巧 - 抽取用 gpt-4o摘要和生成用 gpt-4o-mini - 这样配置可以节省约 60-70% 的 LLM 调用成本2.3 多 Provider 支持GraphRAG 支持多个 LLM Provider不一定非要用 OpenAI# 方案1: OpenAIllm:api_base:https://api.openai.com/v1model:gpt-4oapi_key:${OPENAI_API_KEY}# 方案2: Azure OpenAIllm:api_base:https://your-resource.openai.azure.commodel:gpt-4oapi_key:${AZURE_OPENAI_KEY}api_version:2024-06-01# 方案3: Ollama本地模型llm:api_base:http://localhost:11434/v1model:llama3.1:70bapi_key:ollama# Ollama 不需要真实 key随便填# 方案4: DeepSeekllm:api_base:https://api.deepseek.com/v1model:deepseek-chatapi_key:${DEEPSEEK_API_KEY}# 方案5: OpenRouter统一网关支持多个模型llm:api_base:https://openrouter.ai/v1model:anthropic/claude-3.5-sonnetapi_key:${OPENROUTER_API_KEY}实战经验生产环境推荐用 Azure OpenAI 或 OpenRouter。Azure 有企业级 SLA保障OpenRouter 让你可以随时切换模型Claude vs GPT-4o vs Gemini应对价格波动和模型可用性问题。三、Embedding 配置容易被忽视的性能瓶颈3.1 基础配置embeddings:async_thread:16# Embedding 并发线程数batch_size:1000# 每批次的文档数控制内存llm:api_key:${OPENAI_API_KEY}model:text-embedding-3-large# 1536 维适合精确检索# 也可以用 text-embedding-3-small256 维更快更便宜3.2 Embedding 模型对比模型维度特点适用场景text-embedding-3-large3072精度最高速度最慢社区摘要、精确检索text-embedding-3-small1536→256性价比高可降维大规模 TextUnittext-embedding-ada-0021536经典模型稳定过渡期项目四、TextUnit 切分配置直接影响抽取质量4.1 核心参数chunks:size:300# 每个 TextUnit 的目标 Token 数overlap:100# 相邻 TextUnit 重叠 Token 数overlap_subsample:0.3# 重叠部分的二次采样率降采样减少重复group_by:matches_nearest# 切分策略匹配最近邻4.2 切分策略的实战调优不同文档类型的切分建议 ┌─────────────────────────────────────────────────────────────┐ │ 文档类型 │ chunk_size │ chunk_overlap │ 注意事项 │ ├─────────────────────────────────────────────────────────────┤ │ 论文/技术报告 │ 400-500 │ 150 │ 段落本身长 │ │ 新闻/资讯 │ 200-300 │ 50 │ 短段落密集 │ │ 法律文书 │ 300-400 │ 100 │ 需保证条款完整│ │ 财务报表 │ 200-300 │ 50 │ 表格要单独处理│ │ 聊天记录 │ 100-200 │ 30 │ 本身就很短 │ └─────────────────────────────────────────────────────────────┘五、实体抽取配置最影响图谱质量的环节5.1 核心参数extraction:num_threads:16# 并发抽取的线程数max_gleanings:1# 多轮补充抽取轮数0只抽一轮# 设为1时每段文本最多抽2轮# 可选自定义实体类型entity_types:-ORGANIZATION-PERSON-LOCATION-EVENT-CONCEPT-TECHNOLOGY-PRODUCT# 可选自定义抽取 Prompt覆盖默认# prompt: path/to/entity_extraction_prompt.yaml5.2 max_gleanings 参数详解这个参数控制多轮抽取的轮数是成本和召回率的折中max_gleanings 0 (只抽一轮): - 成本最低但容易漏掉实体和关系 - 适合预算极其有限、快速验证场景 max_gleanings 1 (最多抽两轮): - 平衡方案绝大多数实体在第一轮被捕获 - 第二轮补充遗漏的边缘实体 - 适合大多数生产场景 ← 推荐从此起步 max_gleanings 2 (最多抽三轮): - 召回率最高但 Token 消耗增加约 40% - 适合数据质量要求极高的场景如法律、金融合规5.3 自定义实体类型示例# 对于金融知识库添加专业实体类型extraction:entity_types:-PERSON-ORGANIZATION-LOCATION-EVENT-PRODUCT-FINANCIAL_INSTRUMENT# 金融工具股票、债券、基金-REGULATORY_DOCUMENT# 监管文件法律、规定、指引-MARKET_INDEX# 市场指数沪深300、标普500六、社区检测与摘要配置6.1 图构建参数graph:max_graph_degree:100# 单个节点的最多邻居数防稀疏图膨胀max_input_tokens:5000# 社区摘要输入的最大 Token 数link_weights:true# 累加关系权重compute_rdf_triples:false# 是否计算 RDF 三元组通常关闭6.2 社区报告参数community_report:max_length:2000# 社区摘要最大长度tokensdepth:2# 摘要生成的层级深度prompt:null# 使用默认 Prompt可自定义# 摘要质量的控制参数generate_an_edge_reports:false# 是否为边也生成摘要关闭以节省成本max_nodes_per_generation:1000# 单次摘要调用最多处理多少个节点七、存储配置数据持久化的选择7.1 三种存储模式# 方案1: 本地文件存储默认最简单storage:type:filebase_dir:./output# 输出目录结构# ./output/# ├── entities.parquet# ├── relationships.parquet# ├── communities.parquet# ├── community_reports/# └── embeddings/# 方案2: Azure Blob Storage分布式团队storage:type:blobconnection_string:${AZURE_STORAGE_CONNECTION_STRING}container:graphrag-outputbase_dir:/# 方案3: 内存存储仅测试用重启丢失storage:type:memory7.2 向量存储配置# 默认使用 LanceDB嵌入式无需额外部署vector_store:type:lancedb# 可选切换到 Milvus需要 Milvus 服务vector_store:type:milvusuri:http://localhost:19530collection:graphrag_entities# 可选PostgreSQL pgvector已有 PG 环境时vector_store:type:pgvectorconnection_string:${PG_CONNECTION_STRING}table_name:graphrag_embeddings八、生产环境完整配置示例# settings.yaml - 生产环境配置llm:api_key:${OPENAI_API_KEY}api_base:https://api.openai.com/v1model:gpt-4omax_tokens:2000max_retries:3timeout:120# 摘要和 Map 阶段用小模型省钱summarization_llm:api_key:${OPENAI_API_KEY}api_base:https://api.openai.com/v1model:gpt-4o-minimax_tokens:2000embeddings:llm:api_key:${OPENAI_API_KEY}model:text-embedding-3-smallbatch_size:500chunks:size:300overlap:100overlap_subsample:0.3extraction:num_threads:8max_gleanings:1entity_types:-ORGANIZATION-PERSON-LOCATION-EVENT-CONCEPT-TECHNOLOGY-PRODUCTgraph:max_graph_degree:100max_input_tokens:4000link_weights:truecommunity_report:max_length:1500depth:2generate_an_edge_reports:falsestorage:type:filebase_dir:./graphrag_outputinput:type:filesource_dir:./input九、常见配置错误及排查┌─────────────────────────────────────────────────────────────┐ │ 常见配置错误与排查 │ └─────────────────────────────────────────────────────────────┘ 错误1: API Key 未设置 Error: No API key provided → 检查环境变量是否正确 export在 YAML 中用 ${VAR} 引用 错误2: Model 不存在 Error: Invalid model name → 确认 API Provider 支持该模型名称Azure 的模型名称格式不同 错误3: Token 超出限制 Error: This models maximum context length is... → 降低 chunk_size或增加 overlap 时启用 overlap_subsample 错误4: 存储目录无写入权限 Error: Permission denied: ./output → 检查 output 目录权限或切换到有权限的路径 错误5: 抽取结果为空 → 检查文档解析是否成功PDF 乱码Markdown 格式问题 → 检查 entity_types 是否与文档内容匹配 错误6: 索引内存溢出 (OOM) → 降低 num_threads并发数 → 降低 batch_sizeEmbedding 批次大小 → 减少 chunk_size十、总结配置的核心原则 1. 模型选择抽取用强模型gpt-4o摘要用小模型gpt-4o-mini 2. 并发控制num_threads 和 batch_size 不要贪多内存扛不住 3. 切分策略先做小规模测试确定 chunk_size 再全量跑 4. 存储选型小团队用文件存储有 Azure 基础设施用 Blob 5. 向量库LanceDB 是默认最优解够用且零运维相关阅读GraphRAG 生产环境部署从源码安装到 Docker 容器化实践GraphRAG FastGraphRAG 优化实战成本削减与速度提升的混合策略GraphRAG 索引工作流深度拆解从原始文本到知识图谱的构建 pipeline觉得有用点赞 收藏更多 GraphRAG 实战文章持续更新。
GraphRAG 配置体系详解：settings.yaml 核心参数与模型 Provider 配置
发布时间：2026/6/15 6:00:49
GraphRAG 配置体系详解settings.yaml 核心参数与模型 Provider 配置终于到了工程实践部分。GraphRAG 的配置体系是很多人踩坑的重灾区——一个参数调错轻则索引失败重则整个系统跑偏。这篇文章把settings.yaml的每一个核心参数讲透并给出生产环境的配置建议。一、GraphRAG 配置文件的整体结构GraphRAG 使用 YAML 格式的配置文件默认路径为settings.yaml。完整的配置结构如下settings.yaml │ ├── llm # LLM 配置实体抽取/社区摘要生成/问答生成 │ ├── api_base │ ├── api_key │ ├── model │ ├── max_tokens │ ├── max_retries │ └── timeout │ ├── embedding # Embedding 模型配置向量化 │ ├── api_base │ ├── api_key │ ├── model │ ├── batch_size │ └── max_tokens │ ├── chunks # TextUnit 切分配置 │ ├── chunk_size │ ├── chunk_overlap │ └── overlap_subsample │ ├── extraction # 实体抽取配置 │ ├── num_threads │ ├── max_gleanings # 多轮补充抽取轮数 │ └── entity_types │ ├── graph # 图构建配置 │ ├── max_graph_degree │ ├── max_input_tokens │ └── link_weights │ ├── community_report # 社区摘要配置 │ ├── max_length │ ├── depth │ └── prompt │ ├── storage # 存储配置 │ ├── type # file / blob / memory │ ├── base_dir │ └── ... │ └── input # 输入配置 ├── type # file / blob └── source_dir二、LLM 配置最关键的参数组2.1 基本 LLM 参数llm:api_key:${OPENAI_API_KEY}# 环境变量引用api_base:https://api.openai.com/v1model:gpt-4o# 抽取用模型通常需要较强能力max_tokens:2000# 单次 LLM 输出的最大 Token 数max_retries:3# API 调用失败重试次数timeout:60# 单次调用超时秒temperature:0# 抽取和摘要用 0保证确定性2.2 不同任务的模型选择策略GraphRAG 中有多个 LLM 调用场景并不是所有场景都需要最强模型┌──────────────────────────────────────────────────────────────┐ │ 不同任务的模型选择策略 │ └──────────────────────────────────────────────────────────────┘ ┌──────────────────┬──────────────┬────────────────────────┐ │ 任务 │ 推荐模型 │ 理由 │ ├──────────────────┼──────────────┼────────────────────────┤ │ 实体关系抽取 │ gpt-4o │ 需要强语义理解 │ │ 社区摘要生成 │ gpt-4o-mini │ 摘要质量要求高但成本可控│ │ Global Map-Reduce│ gpt-4o-mini │ 并发量大用小模型节省成本│ │ Local Search 生成 │ gpt-4o │ 上下文复杂需要强理解力 │ └──────────────────┴──────────────┴────────────────────────┘ 优化技巧 - 抽取用 gpt-4o摘要和生成用 gpt-4o-mini - 这样配置可以节省约 60-70% 的 LLM 调用成本2.3 多 Provider 支持GraphRAG 支持多个 LLM Provider不一定非要用 OpenAI# 方案1: OpenAIllm:api_base:https://api.openai.com/v1model:gpt-4oapi_key:${OPENAI_API_KEY}# 方案2: Azure OpenAIllm:api_base:https://your-resource.openai.azure.commodel:gpt-4oapi_key:${AZURE_OPENAI_KEY}api_version:2024-06-01# 方案3: Ollama本地模型llm:api_base:http://localhost:11434/v1model:llama3.1:70bapi_key:ollama# Ollama 不需要真实 key随便填# 方案4: DeepSeekllm:api_base:https://api.deepseek.com/v1model:deepseek-chatapi_key:${DEEPSEEK_API_KEY}# 方案5: OpenRouter统一网关支持多个模型llm:api_base:https://openrouter.ai/v1model:anthropic/claude-3.5-sonnetapi_key:${OPENROUTER_API_KEY}实战经验生产环境推荐用 Azure OpenAI 或 OpenRouter。Azure 有企业级 SLA保障OpenRouter 让你可以随时切换模型Claude vs GPT-4o vs Gemini应对价格波动和模型可用性问题。三、Embedding 配置容易被忽视的性能瓶颈3.1 基础配置embeddings:async_thread:16# Embedding 并发线程数batch_size:1000# 每批次的文档数控制内存llm:api_key:${OPENAI_API_KEY}model:text-embedding-3-large# 1536 维适合精确检索# 也可以用 text-embedding-3-small256 维更快更便宜3.2 Embedding 模型对比模型维度特点适用场景text-embedding-3-large3072精度最高速度最慢社区摘要、精确检索text-embedding-3-small1536→256性价比高可降维大规模 TextUnittext-embedding-ada-0021536经典模型稳定过渡期项目四、TextUnit 切分配置直接影响抽取质量4.1 核心参数chunks:size:300# 每个 TextUnit 的目标 Token 数overlap:100# 相邻 TextUnit 重叠 Token 数overlap_subsample:0.3# 重叠部分的二次采样率降采样减少重复group_by:matches_nearest# 切分策略匹配最近邻4.2 切分策略的实战调优不同文档类型的切分建议 ┌─────────────────────────────────────────────────────────────┐ │ 文档类型 │ chunk_size │ chunk_overlap │ 注意事项 │ ├─────────────────────────────────────────────────────────────┤ │ 论文/技术报告 │ 400-500 │ 150 │ 段落本身长 │ │ 新闻/资讯 │ 200-300 │ 50 │ 短段落密集 │ │ 法律文书 │ 300-400 │ 100 │ 需保证条款完整│ │ 财务报表 │ 200-300 │ 50 │ 表格要单独处理│ │ 聊天记录 │ 100-200 │ 30 │ 本身就很短 │ └─────────────────────────────────────────────────────────────┘五、实体抽取配置最影响图谱质量的环节5.1 核心参数extraction:num_threads:16# 并发抽取的线程数max_gleanings:1# 多轮补充抽取轮数0只抽一轮# 设为1时每段文本最多抽2轮# 可选自定义实体类型entity_types:-ORGANIZATION-PERSON-LOCATION-EVENT-CONCEPT-TECHNOLOGY-PRODUCT# 可选自定义抽取 Prompt覆盖默认# prompt: path/to/entity_extraction_prompt.yaml5.2 max_gleanings 参数详解这个参数控制多轮抽取的轮数是成本和召回率的折中max_gleanings 0 (只抽一轮): - 成本最低但容易漏掉实体和关系 - 适合预算极其有限、快速验证场景 max_gleanings 1 (最多抽两轮): - 平衡方案绝大多数实体在第一轮被捕获 - 第二轮补充遗漏的边缘实体 - 适合大多数生产场景 ← 推荐从此起步 max_gleanings 2 (最多抽三轮): - 召回率最高但 Token 消耗增加约 40% - 适合数据质量要求极高的场景如法律、金融合规5.3 自定义实体类型示例# 对于金融知识库添加专业实体类型extraction:entity_types:-PERSON-ORGANIZATION-LOCATION-EVENT-PRODUCT-FINANCIAL_INSTRUMENT# 金融工具股票、债券、基金-REGULATORY_DOCUMENT# 监管文件法律、规定、指引-MARKET_INDEX# 市场指数沪深300、标普500六、社区检测与摘要配置6.1 图构建参数graph:max_graph_degree:100# 单个节点的最多邻居数防稀疏图膨胀max_input_tokens:5000# 社区摘要输入的最大 Token 数link_weights:true# 累加关系权重compute_rdf_triples:false# 是否计算 RDF 三元组通常关闭6.2 社区报告参数community_report:max_length:2000# 社区摘要最大长度tokensdepth:2# 摘要生成的层级深度prompt:null# 使用默认 Prompt可自定义# 摘要质量的控制参数generate_an_edge_reports:false# 是否为边也生成摘要关闭以节省成本max_nodes_per_generation:1000# 单次摘要调用最多处理多少个节点七、存储配置数据持久化的选择7.1 三种存储模式# 方案1: 本地文件存储默认最简单storage:type:filebase_dir:./output# 输出目录结构# ./output/# ├── entities.parquet# ├── relationships.parquet# ├── communities.parquet# ├── community_reports/# └── embeddings/# 方案2: Azure Blob Storage分布式团队storage:type:blobconnection_string:${AZURE_STORAGE_CONNECTION_STRING}container:graphrag-outputbase_dir:/# 方案3: 内存存储仅测试用重启丢失storage:type:memory7.2 向量存储配置# 默认使用 LanceDB嵌入式无需额外部署vector_store:type:lancedb# 可选切换到 Milvus需要 Milvus 服务vector_store:type:milvusuri:http://localhost:19530collection:graphrag_entities# 可选PostgreSQL pgvector已有 PG 环境时vector_store:type:pgvectorconnection_string:${PG_CONNECTION_STRING}table_name:graphrag_embeddings八、生产环境完整配置示例# settings.yaml - 生产环境配置llm:api_key:${OPENAI_API_KEY}api_base:https://api.openai.com/v1model:gpt-4omax_tokens:2000max_retries:3timeout:120# 摘要和 Map 阶段用小模型省钱summarization_llm:api_key:${OPENAI_API_KEY}api_base:https://api.openai.com/v1model:gpt-4o-minimax_tokens:2000embeddings:llm:api_key:${OPENAI_API_KEY}model:text-embedding-3-smallbatch_size:500chunks:size:300overlap:100overlap_subsample:0.3extraction:num_threads:8max_gleanings:1entity_types:-ORGANIZATION-PERSON-LOCATION-EVENT-CONCEPT-TECHNOLOGY-PRODUCTgraph:max_graph_degree:100max_input_tokens:4000link_weights:truecommunity_report:max_length:1500depth:2generate_an_edge_reports:falsestorage:type:filebase_dir:./graphrag_outputinput:type:filesource_dir:./input九、常见配置错误及排查┌─────────────────────────────────────────────────────────────┐ │ 常见配置错误与排查 │ └─────────────────────────────────────────────────────────────┘ 错误1: API Key 未设置 Error: No API key provided → 检查环境变量是否正确 export在 YAML 中用 ${VAR} 引用 错误2: Model 不存在 Error: Invalid model name → 确认 API Provider 支持该模型名称Azure 的模型名称格式不同 错误3: Token 超出限制 Error: This models maximum context length is... → 降低 chunk_size或增加 overlap 时启用 overlap_subsample 错误4: 存储目录无写入权限 Error: Permission denied: ./output → 检查 output 目录权限或切换到有权限的路径 错误5: 抽取结果为空 → 检查文档解析是否成功PDF 乱码Markdown 格式问题 → 检查 entity_types 是否与文档内容匹配 错误6: 索引内存溢出 (OOM) → 降低 num_threads并发数 → 降低 batch_sizeEmbedding 批次大小 → 减少 chunk_size十、总结配置的核心原则 1. 模型选择抽取用强模型gpt-4o摘要用小模型gpt-4o-mini 2. 并发控制num_threads 和 batch_size 不要贪多内存扛不住 3. 切分策略先做小规模测试确定 chunk_size 再全量跑 4. 存储选型小团队用文件存储有 Azure 基础设施用 Blob 5. 向量库LanceDB 是默认最优解够用且零运维相关阅读GraphRAG 生产环境部署从源码安装到 Docker 容器化实践GraphRAG FastGraphRAG 优化实战成本削减与速度提升的混合策略GraphRAG 索引工作流深度拆解从原始文本到知识图谱的构建 pipeline觉得有用点赞 收藏更多 GraphRAG 实战文章持续更新。
