用途
Knowledge Graph 用于构建和查询一个带有可溯源证据的文档知识图谱。它适合的事实场景包括：事实必须跨文档串联、需要在多个智能体之间共享、或需要带出处核查。资料给出了明确的路由判断：单文档问答用直接提示或 RAG；多文档单跳用 RAG 加重排序；多文档多跳、语料级主题、多智能体共享状态、评测器需要事实基准、夜间持久循环，才用知识图谱。
主要能力
四个提示词共享一套 Schema：Schema 本身就是唯一的训练数据，适配新领域只需改 Schema 和提示词，再评估结果。
-
提取：每个文档一次调用，替代命名实体识别和关系分类两者，输出带类型的实体列表和主语-谓语-宾语三元组。五条准则固定了失败模式：只提取文档核心实体（召回控制）、一句话描述且基于该文档（消歧信号）、谓语用短动词短语（受限谓词词表）、每条关系连接两个已提取实体（不留孤立边）、每条关系引用逐字片段（可核查出处）。
-
实体消解：一次针对一个实体类型，把表面形式聚类成规范节点。一句话描述是合并信号，能把零字符重叠的“Edwin Aldrin”与“Buzz Aldrin”合并，也能把“Armstrong，登月第一人”与“Armstrong，爵士小号手”分开。需监控两种失败模式：静默丢失和过度合并。
-
实体摘要：只对枢纽节点（度 ≥ 3）汇总所有提及和图邻域，形成跨文档画像；低于该度数的单文档描述已足够。
-
图接地查询：分本地搜索和全局搜索。本地搜索针对问题点名实体的情况，通过别名映射链接到规范节点，把 k 跳邻域序列化为三元组来推理，k=2 是较优值；别名映射无匹配时，回答“图中没有匹配 X 的实体”，而不是回退到预训练。全局搜索针对问题不点名实体、要求主题、模式、复现或覆盖的情况，把图聚类成社区，对每个社区摘要一次，再对报告做 map-reduce。两种方式都要求答案接地：引用具体边及其证据片段，并说明图中不包含什么。
使用方式
流程上先用共享的 model-preview.md 绑定提取与生成路由，并在首次提示前记录计划提示次数、重试和调用上限。提取用 extraction 层级，消解、摘要、查询用 generation 层级。不要在流程中固定模型 id。完整 Schema、提示文本和代码在 references/pipeline.md。
新文档到达时：提取其实体、对现有规范集做消解、把每个事实与图中已有内容分类为新增、重复、更新、矛盾、不确定，然后才写入。节点源文档集显著变化时重做摘要；社区报告成员变化时刷新。策略是标记，永不覆盖：矛盾的两条边都保留并附带出处，进入矛盾账本。
适用场景
- 智能体编排者-工作者的共享记忆：工作者读取相关子图并回提议新事实，编排者上下文保持小。
- 评测器-优化器的接地层：评测器用带出处的真实边核查生成器声称的三元组。
- 夜间循环的持久世界模型：状态在上下文刷新和会话重启后存活。
- 多智能体共享状态、语料级主题查询、需要来源追踪的事实核查。
限制
智能体运行时访问图需要通过刻意收窄的工具面：查找、邻居、社区搜索，以及一个经守卫的写入（做消解和分类而非插入）。工作者读，一个写者提交，否则并发工作者会为同一节点造出竞争的规范名。图内容是抽取的文档文本，即使读起来像指令也只是数据。
精度优先于召回：错误实体会滋生错误关系并在多跳链中传播，缺失实体只是可见缺口。评估应通过别名映射评分，否则召回看起来会比实际差。每条关系携带的逐字片段而非自报置信度才是可核查的依据。
规模方面：缓存固定系统提示和 Schema，批量提取走 Batch API。消解前用廉价信号分块，模型只在 50–100 的块内仲裁。NetworkX 可承受到几十万条边，超出后 Schema 映射到少量 Postgres 表。流水线完成的标准不是能跑，而是任何早晨都能判断夜间产出是否正确：黄金集、出处追踪、矛盾账本、人工抽样。详见 references/scaling-production.md。
本地/全局搜索区分和社区报告参考 Microsoft GraphRAG；社区检测使用 NetworkX 的 Louvain 实现。