Skip to main content
同步任务负责把外部资源元数据拉入 UOSE系统，并发布为 ontology snapshot 与实体关系投影。同步成功后，资源才具备可搜索、可分析、可执行的语义上下文。

​
同步模式

UOSE 支持两类同步模式：
  • incremental：基于当前资源状态做增量 upsert。
  • full：先清空当前资源已同步的实体、关系和动作实例，再重新拉取。
同步请求还可以携带 cursor 类型：
  • time：按时间游标。
  • version：按版本游标。
  • event_offset：按事件偏移。
不同 adapter 对游标的支持程度不同。对于首版资源接入，full sync 通常是最稳定的初始化方式。

​
同步链路

一次同步通常经过：
  1. 读取 resource 和 capabilities。
  2. 解析 connectionRef。
  3. 调用对应 adapter 的 pullSemanticMetadata。
  4. 把外部元数据归一化为 canonical ontology IR。
  5. 发布 ontology snapshot。
  6. 投影到实体、关系和动作实例表。
  7. 更新 sync checkpoint。
  8. 记录失败事件或同步结果。
如果开启 RDF sidecar，发布过程还会把本体图写入 RDF 图数据库，支持 schema、邻域和 SPARQL 查询。

​
异步队列

对耗时或大规模资源，UOSE 提供基于 Redis 的 resource sync queue：
  • 注册资源时自动排入首次同步。
  • 手动提交 sync job。
  • 对相同 resourceId + mode + cursorType 做去重。
  • 展示 waiting、active、completed、failed 等状态。
  • 支持失败重试、取消进行中任务、清理历史任务。
  • 通过 progress 展示当前处理阶段和服务进度。
队列适合 SAP OData 多服务同步、数据库大 schema 同步等场景。

​
Dead-letter

当同步过程中出现无法立即恢复的错误，系统会记录 dead-letter event。它用于保留失败上下文，避免错误只停留在日志中。 常见 dead-letter 场景包括：
  • 连接配置错误。
  • 源系统认证失败。
  • SAP OData metadata 无法作为支持的 V2/V4 EDMX 获取或解析。
  • Knowledge GraphRAG 未 ready。
  • 上游 API 返回不可解析结构。
  • 元数据过大并触发截断或限制。
处理方式通常是：查看 event payload、修正 Secret 或 capabilities、重新触发同步。

​
最佳实践

  • 初次接入使用 full sync，验证本体图谱后再切换到增量策略。
  • 对 SAP OData 使用服务选择框为每次同步选择服务根路径。
  • 对数据库设置 maxTables 和 maxColumns，避免一次同步过大。
  • 对知识图谱设置 maxRelations 和 mention 样本数，保持上下文可控。
  • 对失败 job 优先查看 failedReason 和 dead-letter，再决定 retry。
  • 每次重大 capabilities 调整后执行一次 full sync，以避免旧投影残留。

​
Web 操作路径

在数据与本体 → 资源接入打开资源卡片，进入同步作业页。首次接入点击全量同步；日常更新使用增量同步。队列页可刷新、重试失败任务、取消进行中任务和清理历史记录。进入错误页查看 dead-letter 和处理阶段。 **成功信号：**作业状态为 completed，资源概览出现最近同步时间和 snapshotId，本体空间健康状态变为 ready。waiting 或 active 期间不要重复提交同一模式的作业。 **最小权限：**需要触发同步和查看错误的资源运营权限；只读用户只能查看作业和失败原因。

​
验收清单

  • 首次同步使用 full 模式并记录 job ID。
  • job 最终为 completed，没有未处理 dead-letter。
  • 资源有当前 Snapshot 和 graph version。
  • 后续增量同步使用 adapter 支持的 cursor 类型。
  • 失败后先修复 Secret 或 capabilities，再执行 retry。