如何处理 Semantica kg.ProvenanceTracker 弃用警告？迁移到 ProvenanceManager 完整对照

如何处理 Semantica kg.ProvenanceTracker 弃用警告迁移到 ProvenanceManager 完整对照【免费下载链接】semanticaGraph-Native Infrastructure for Context and Accountable AI Systems项目地址: https://gitcode.com/GitHub_Trending/sema/semantica如果你的代码还在调用semantica.kg.ProvenanceTracker运行时会在每个方法上收到一条DeprecationWarning提示改用semantica.provenance.ProvenanceManager。Semantica 的迁移文档docs/migration/kg-provenance-tracker.md明确了这一现状kg.ProvenanceTracker已弃用将在未来某个大版本中移除它是一个独立的纯内存实现从未委托给统一的 provenance 后端。ProvenanceManager就是该后端目前是所有 Semantica 模块跟踪实体与关系 provenance 的受支持方式。文档同时说明现有代码在旧类被移除之前继续可用目前没有强制迁移期限。也就是说警告不阻断运行但每次调用旧类方法都会触发一次警告且旧实现缺少 SQLite 持久化、版本链、完整性校验等能力。本文按迁移文档给出的方法映射表给出一条完整的迁移路径逐方法替换、处理返回值字段差异、处理没有直接等价方法的情况最后验证警告消失。警告的具体行为查看 弃用类源码 可以看到ProvenanceTracker的构造函数和每个受支持方法track_entity、get_all_sources、query_recorded_between、revision_history、export_audit_log都会调用warnings.warn(..., DeprecationWarning, stacklevel2)警告文本固定指向迁移指南ProvenanceTracker is deprecated and will be removed in a future major version. Use semantica.provenance.ProvenanceManager instead. See migration guide: docs/migration/kg-provenance-tracker.mdCHANGELOG 解释了弃用原因#744、#751 条目kg.ProvenanceTracker与ProvenanceManager长期不同步测试曾断言其存在get_lineage、track_relationship、track_entities_batch等从未实现的方法。维护者选择不补完这个兼容层而是让旧类整体发出弃用警告。所以迁移方向是单向的把调用点搬到ProvenanceManager而不是等待旧类补齐功能。方法映射完整对照以下对照表来自 迁移文档是迁移时的核对基准kg.ProvenanceTrackerProvenanceManager等价物差异说明ProvenanceTracker()ProvenanceManager()ProvenanceManager另接受storage_path用 SQLite 持久化替代纯内存track_entity(entity_id, source, metadata)track_entity(entity_id, source, metadata)调用形状相同ProvenanceManager每次更新会通过parent_entity_id自动链接到上一版本get_all_sources(entity_id)get_all_sources(entity_id)字段名不同旧类返回的时间键是recorded_atProvenanceManager返回timestampclear(entity_idNone)clear()ProvenanceManager.clear()清空全部 provenance 数据暂无按单实体清空query_recorded_between(start, end)query_recorded_between(start, end)调用形状相同按timestamp过滤所有已跟踪条目而非单一实体revision_history(fact_id)revision_history(fact_id)调用与返回形状相同version、valid_from、valid_until、recorded_at、author可选revision_type/supersedes实现改为沿previous_version_id链遍历export_audit_log(fact_ids, format)暂无直接等价文档建议从get_lineage()输出构建导出或序列化get_statistics()得到汇总视图两点需要特别注意clear()行为收窄旧类支持clear(entity_idX)只清一个实体ProvenanceManager.clear()是整体存储重置源码注释明确说它是 dev/test 用途的批量重置不是单条事实撤回。如果你的代码依赖按实体清理迁移后只能清全部或改用文档提到的invalidate()做单条撤回。export_audit_log没有等价方法且文档明确旧类上不会补实现这些缺失方法。重度依赖的话需要在调用方写一个小适配器或向ProvenanceManager提功能请求。迁移步骤替换导入与调用迁移文档给出的最小前后对照原文示例# Before from semantica.kg import ProvenanceTracker tracker ProvenanceTracker() tracker.track_entity(entity_1, sourcedoc_1, metadata{confidence: 0.9}) sources tracker.get_all_sources(entity_1) # [{source: ..., recorded_at: ..., confidence: 0.9}] # After from semantica.provenance import ProvenanceManager prov ProvenanceManager() prov.track_entity(entity_1, sourcedoc_1, metadata{confidence: 0.9}) sources prov.get_all_sources(entity_1) # [{source: ..., timestamp: ..., metadata: {...}, ...}]迁移时逐文件把from semantica.kg import ProvenanceTracker改为from semantica.provenance import ProvenanceManager实例名按你的代码习惯保留即可。替换后需要核对三处返回值差异它们都会影响下游解析代码时间字段改名get_all_sources()返回的记录中旧类的时间键是recorded_at新类是timestampProvenanceManager 源码 中该方法的返回字典还包含source、location、confidence、metadata键。下游按字段名取值的代码要同步改。metadata 不再摊平旧类把metadata字典直接展开进每条记录示例中confidence出现在顶层ProvenanceManager把 metadata 作为嵌套字典返回示例中为metadata: {...}。track_entity()有返回值旧类返回NoneProvenanceManager.track_entity()返回Optional[ProvenanceEntry]成功时带自动计算的 SHA-256checksum全新实体写入失败时返回None。不接收返回值的老代码不受影响但新代码可以顺便用上校验和。如果实体数据需要跨会话保留迁移时可以一并换成 SQLite 后端Provenance 指南 中给出的写法from semantica.provenance import ProvenanceManager prov ProvenanceManager(storage_pathprovenance.db)这是可选分支ProvenanceManager()不加参数仍是纯内存与旧类行为最接近。没有直接等价方法的两个处理办法export_audit_log(fact_ids, format)文档给出的替代是「从get_lineage()输出构建导出或序列化get_statistics()做汇总视图」。如果你的旧代码只是把export_audit_log(..., formatjson)的结果落盘最小改法是改用get_lineage(entity_id)的返回自行序列化。clear(entity_id...)如前所述没有按实体清空的等价。依赖它的逻辑要么整体重写为「重建该实体的数据」要么在迁移完成前暂时留在旧类上。迁移期间的临时压警告可选分支如果切换需要时间迁移文档给出了一段压警告写法只用于规划期间不是最终方案import warnings with warnings.catch_warnings(): warnings.simplefilter(ignore, DeprecationWarning) tracker ProvenanceTracker()文档原话提醒This is a stopgap, not a fix —— 计划在kg.ProvenanceTracker被移除前迁到ProvenanceManager。另外这个catch_warnings只覆盖with块内的实例化旧类的每次方法调用也各自发警告压警告的范围要覆盖到实际调用处。验证迁移完成文档没有单独的「验证清单」但基于其明确描述的行为可以按这两点核对警告不再出现。文档断言旧类每个方法「on use」都发DeprecationWarning而ProvenanceManager的对应方法不发。用与上面压警告片段相同的warnings.catch_warningsAPI 把警告记下来做断言即可例如把迁移后的调用放进catch_warnings(recordTrue)块检查捕获列表中没有针对ProvenanceTracker的警告。返回值字段符合新形状。迁移文档给出的 after 示例标注为文档示例非固定预期值# get_all_sources(entity_1) 的文档示例返回 [{source: ..., timestamp: ..., metadata: {...}, ...}]检查点记录里是timestamp而不是recorded_atmetadata 在嵌套字典里对同一实体重复调用track_entity()后get_lineage(entity_id)能返回完整的版本链文档中 lineage 示例输出标注为示例结果说明版本链机制已生效。版本兼容注意有一个版本细节决定你能否一次迁完query_recorded_between()和revision_history()这两个ProvenanceManager方法是后来补齐的。CHANGELOG#825 条目记录了它们在ProvenanceManager上新增「closing the two no direct equivalent yet rows in docs/migration/kg-provenance-tracker.md」。如果你安装的是较旧版本ProvenanceManager上可能还没有这两个方法——此时先升级 semantica 再迁移这两个调用点或让这两个调用暂时留在旧类上并用上文的方式压警告。其余方法的等价关系不受版本影响可以先迁。迁移完成后旧类仍会保留到未来某个大版本才移除没有强制期限但export_audit_log类缺失方法在旧类上也不会被补实现依赖越久适配器成本越高。后续深入存储后端、InMemoryStorage/SQLiteStorage与ProvenanceEntryschema 的细节可查 Provenance 参考 与 kg 模块参考。【免费下载链接】semanticaGraph-Native Infrastructure for Context and Accountable AI Systems项目地址: https://gitcode.com/GitHub_Trending/sema/semantica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考