本地跑 GraphRAG 最容易卡在两处：抽实体抽取阶段一跑就是几小时甚至卡死，查询阶段又慢到没法用。多数教程只告诉你装哪个包、改哪个配置文件，不讲清楚哪一步该用大模型哪一步该用小模型、并发开到几、超时怎么设、失败怎么退回向量检索。这篇按搭建顺序把每个环节的判断标准和排查动作列出来，方便你照着调。
本地跑 GraphRAG，卡住人的通常不是代码本身，而是两件事：抽取阶段一开跑就是几小时，甚至中途崩掉重来；查询阶段慢到没法用，用户等两秒就跑了。多数教程只教你装哪个包、改哪一行配置，不讲清楚哪一步该用大模型、哪一步该用小模型、并发开到几、超时怎么设、失败之后往哪退。
这篇按搭建顺序拆一遍：先决定模型分工，再定抽取管线的落地方式，然后是超时并发内存这三个数值怎么定，最后是降级和日志。排查顺序也会给一份，方便你照着往上套。涉及的模型价格、参数规模、性能数字，站内都有对应页面，读的时候顺手核对当时的数字就行。
先决定哪几个模型干哪几件事
整条链路其实有三类活：实体关系抽取、文本向量化、查询时的问答生成。这三者对模型的要求完全不同。抽取要的是吞吐和稳定输出结构化格式，向量化要的是中文语义区分度，问答要的是表达质量和上下文理解力。指望一个模型全包，结果往往是一头好一头垮。
- 抽取阶段
- 用本地小参数模型批量跑，追求单位时间能处理多少文档，输出格式靠提示词约束死
- 问答阶段
- 可以单独换成参数更大的本地模型，或者走中转站调用，这里拼的是答案质量不是速度
- 嵌入模型
- 单独挑，别跟生成模型混在一起选，中文语料上先做小样本召回对比再定
- 什么情况不该上图谱
- 文档只有几百页、实体关系本来就稀疏时，抽取成本可能盖过收益，直接向量检索更划算
嵌入模型这块特别容易被榜单带偏。正确做法是：从你自己的语料里抽几十条真实文档，构造一批查询，比 Top 命中率。榜单上的名次和你的领域相关性可能完全不一样。要横向看不同嵌入模型的定位，可以到 /embeddings 对照着看，再决定换不换。
抽取管线的落地顺序与断点续跑
- 文档清洗去掉页眉页脚、目录、重复段落。验证方式：随机抽十篇看清洗后的文本，有没有把正文误删。
- 切块按语义边界切，别一刀切固定字数。验证方式：抽几条块看是否包含完整的一句话或一个事实。
- 抽取实体关系模型输出固定成三元组格式，格式错的直接丢弃并记原因。
- 归并同义实体先定规则：大小写统一、别名映射表。别让模型自己合并，中文里很容易把两个不同的人合成一个。
- 入图建索引前四步验收完再进这一步，否则建出来的图得推倒重来。
抽取必须做成可续跑。每条文档的抽取结果单独落盘，带上状态标记：待处理、成功、失败、失败原因。中断之后从断点接着跑，不然一次显存溢出就整批重来，那才是真的浪费。验收动作也别省：随机抽二十条三元组人工核对一遍，错得离谱就回头调提示词和切块粒度，别急着一口气全量跑。
超时、并发与内存这三件事怎么定
这三个数值都不能凭感觉。先量基线：拿一条文档完整跑一遍，记下平均耗时和峰值显存。并发数是在显存能装下的范围内往上试探，不是越高越好。超时则要分阶段设，抽取的单条超时给得宽一些，查询的超时要短到用户愿意等，具体秒数按你实测的基线来定，别照抄别人的配置。
| 参数 | 判断依据 | 调过头会怎样 |
|---|---|---|
| 并发数 | 显存能同时装下几份上下文 | 显存溢出直接崩，比串行还慢 |
| 抽取超时 | 单条文档实测耗时的若干倍 | 设太短大量失败被丢弃 |
| 查询超时 | 用户愿意等的上限 | 设太长用户以为卡死直接离开 |
| 重试次数 | 失败是否为瞬时错误 | 无脑重试会放大显存压力 |
有一种情况要特别提醒：本地只有一张消费级卡，却想同时做嵌入和生成，硬开并发基本等于自杀。这时候串行跑反而更稳，速度上的损失远小于崩溃重启的代价。别为了看起来快，把显存打满。
降级路径与日志该记什么
查询链路一定要有兜底。图谱检索结果为空，或者超时了，直接退到向量检索；两条路都空，再回一句「没找到」。用户看到报错栈的那一刻，你的服务在心理上就已经挂了。降级要用开关控制，而不是改代码，出问题时能临时关掉图谱那一段，先保证服务能用。
- 降级开关：配置项控制是否启用图谱检索，出问题一键关，不动代码
- 请求标识：每个请求一个 ID，方便把整条链路的日志串起来
- 检索路径：记录这次走的是图谱还是向量，还是降级后的向量
- 节奏耗时：抽取、检索、生成各阶段耗时分开记，别只记总时长
- 模型信息：这条请求用的哪个生成模型、哪个嵌入模型
- 失败原因：超时、格式错、空结果、还是模型返回异常，分开归类
这六个字段能复盘绝大多数「慢」和「不准」的投诉。另外，评测别靠单次体感。准备二三十条真实问题做成固定用例集，改完提示词或换模型之后重跑一遍，看命中变化。没有固定用例集，你永远说不清这次改动是变好还是变差。
上线前的排查顺序清单
慢的时候，多数人第一反应是「模型不行」。但经验上，十有八九是切块粒度和并发配置的问题。排查要从最慢的那一步开始，按固定顺序走，别东一榔头西一棒子。
- 单条链路一条文档能不能从头跑到尾，中间哪里断了先修哪里。
- 抽取质量抽出来的三元组对不对，错得多先调提示词和切块，不是换模型。
- 并发压测把并发往上加，看显存峰值，一旦逼近上限就回退一档。
- 超时校准拿实测耗时校准各阶段超时，确保正常请求不会被误杀。
- 降级验证手动让图谱那段失败，看是否平滑退到向量检索，用户侧无感知。
- 日志复盘拿一次真实慢请求，看日志能不能定位到具体阶段。
换模型版本、换检索库之后，按同样这套顺序重跑一遍。图谱类项目对切块粒度和提示词改动非常敏感，一个不起眼的调整都可能让整批结果变样。想横向看不同嵌入模型和检索组件的位置，可以到 /embeddings 和 /stacks/vector-dbs 对照着看，再决定要不要动。
下一步把站内的模型价格、延迟基线和组件对比对一遍，再定你自己的并发和超时参数，比照抄任何一份配置都靠谱。→常见问题
抽取阶段跑得特别慢，是模型不行还是配置问题？
先分清是吞吐问题还是单条问题。单条就慢，多半是切块太大或提示词让模型输出太长；单条正常但整批慢，是并发没开起来或落盘方式太碎。拿单条文档计时，再逐步加并发对比总耗时，比直接换模型更容易定位。
本地模型抽取出来的实体和关系质量差怎么办？
先看切块粒度，中文文档按段落切通常比按固定字数切好；再收紧提示词，明确要求输出格式并给两个示例。如果还是差，把抽取换成质量更高但更慢的方式，只对重要文档跑，其余走向量检索，别指望全量都抽得干净。
图谱检索和向量检索要不要都保留？
建议都保留，图谱负责跨文档的关系型问题，向量检索负责语义相近的片段召回。实际查询里两者命中率在不同问题上互有高低，做成可切换的两条路径，哪条空就退到另一条，成本和稳定性都更好。
