扩展接口
概述
不同业务使用不同模型、词典、主数据和持久化设施。Graph Extractor 因此把模型调用、协议解析、质量校验、实体归一、图变更映射和长期状态拆成独立扩展接口。
扩展的目标不是复制整个流水线，而是在保持阶段契约的前提下替换一个职责。这样审核、恢复和增量语义仍然一致，也便于测试自定义实现。
抽取阶段扩展
GraphExtractor
负责从单个 GraphExtractionRequest 产生 GraphCandidateBatch。实现可以使用 LLM、规则引擎或外部 NLP 服务。
必须保证：
- 只返回候选，不直接写 GraphStore；
- 不把
context当作当前 evidence； - 保留 documentId、chunkId 和来源 metadata；
- 对并发调用提供明确的线程安全保证；
- 将模型超时、协议失败等包装为可诊断异常。
GraphExtractionPromptBuilder
负责把 Schema、请求选项和正文组织为模型输入。它可以加入领域示例、术语表和供应商结构化输出要求，但不能绕过后续 Validator。
Prompt 变化应进入 extraction fingerprint，否则同一内容可能在配置变化后被错误判定为 UNCHANGED。
GraphCandidateParser
只负责把原始响应解析为候选协议。它应隔离单条坏候选、保留原始响应并产生稳定 issue code，不负责实体消歧、业务真伪判断或写图。
GraphCandidateValidator
负责从全部候选中得到可以进入实体归一的合法子集，并保留解析阶段已有问题。自定义实现适合增加租户词表、属性约束、证据策略和领域合规规则。
Validator 不应静默修复不可解释的数据；若执行规范化或默认值填充，应产生可审核记录。
身份和图投影扩展
GraphEntityResolver
负责把候选提及映射为规范实体及稳定 nodeId。它可以结合名称、别名、上下文、向量相似度或业务主数据，但不能把低确定性的同名匹配静默合并。
GraphEntityRegistry
负责跨文档和跨批次保存长期实体身份。生产实现应按 Space 隔离，使用唯一约束处理并发注册，并能返回同名歧义而不是最后写入覆盖。
Registry 是身份存储，Resolver 是身份决策，两者职责不同。常见组合是 Resolver 查询 Registry，增量服务在写图成功后幂等保存注册项。
GraphEntityIdGenerator
负责在无法复用已有实体时产生 nodeId。接入业务主键优先于名称哈希；任何算法变化都可能让历史实体产生新 ID，应进行迁移或保持版本兼容。
GraphMutationMapper
负责把合法候选和归一结果映射成节点 Upsert、边 Upsert，并按 GraphEdgeKey 去重；默认重复关系保留置信度更高的候选。
它不负责：
- 删除旧关系；
- 人工审核；
- 调用数据库；
- 判断多来源冲突的业务真相；
- 自动回收孤立节点。
旧关系删除由增量计划结合文档状态和事实来源决定。
长期运行扩展
GraphDocumentStateStore
保存文档当前状态、版本历史和事实来源查询。生产实现必须为 revision 提供原子 CAS，并为 Space、documentId、edgeKey 和状态建立索引。
GraphIngestionOperationStore
保存 operationId、planFingerprint、原始计划和操作阶段。操作和计划应原子创建，阶段推进使用 CAS，并支持稳定扫描未完成操作。
GraphIngestionLockProvider
限制同一 Space + documentId 的并发执行。默认本地实现只适合单 JVM；分布式实现需要租约、持有者校验和超时，但锁仍不能替代 revision CAS。
并发与异常契约
生产自定义组件应满足：
- 服务级组件可被多个任务并发调用，或明确由调用方按任务创建；
- 返回集合和状态对象不被调用方后续修改；
- 不吞掉异常，也不依赖异常 message 做程序分流；
- 持久化操作具有唯一约束、幂等语义和明确的 CAS 结果；
- 不在一个扩展点中偷偷调用下游阶段；
- 配置变化能通过版本或 fingerprint 被识别；
- 日志不泄露完整原文、模型响应或凭据。
选择最小扩展面
| 需求 | 优先扩展 |
|---|---|
| 更换模型或规则引擎 | GraphExtractor |
| 使用供应商工具调用格式 | GraphCandidateParser 和 Prompt Builder |
| 增加业务校验 | GraphCandidateValidator |
| 接入主数据或别名库 | GraphEntityResolver / Registry |
| 使用业务节点主键 | GraphEntityIdGenerator |
| 调整图属性和投影 | GraphMutationMapper |
| 多实例长期增量 | 三个 Store/Lock 接口 |
仅增加业务校验时，不应复制 Pipeline；仅改变图投影时，也不应把数据库写入放进 Mapper。
测试建议
每个自定义接口至少验证：
- 正常输入、空结果、局部坏候选和异常输入；
- 同一输入重复执行是否稳定；
- 并发调用和唯一约束冲突；
- Schema、Space、Chunk 和身份边界；
- 敏感数据是否进入日志；
- 与 Pipeline、增量计划和恢复流程的契约集成；
- Neo4j、Nebula 等真实后端中的最终投影是否符合预期。