cf-data-keeper

name	cf-data-keeper
description	在 common_func 项目中需要选择或配置 DataKeeper 的 data_type、save_load_method、dict/OrderedDataContainer、separate/lmdb 存储后端、key 设计、保存读取策略，或需要在 AbstractTool._config_data_keeper 中设置 self.data_keeper_kwargs 时触发。若问题主要是 Experiment/ComposedExperiment 的 tool 组织、目录复用或整体调试，改用 cf-experiment。

CF DataKeeper 约定

这个 skill 用于选择和使用 common_functions.py 中的 DataKeeper、DataContainer 和 OrderedDataContainer。它关注结果容器、key 设计、保存后端和读取方式；不负责解释 Experiment / ComposedExperiment 的整体数据流。

选择规则

默认选择是 dict + separate：

self.data_keeper_kwargs = {'data_type': 'dict', 'save_load_method': 'separate'}

普通少量结果、summary、数组、DataFrame、模型指标等，优先用默认 dict + separate。写入时显式给 key：

self.data_keeper.set_value(result, key='result')
result = self.data_keeper.get_value(key='result')

大量参数化结果需要用多个参数定位时，用 OrderedDataContainer。必须提供 param_order；读取和写入用同一组参数：

self.data_keeper_kwargs = {
    'data_type': 'OrderedDataContainer',
    'save_load_method': 'separate',
    'param_order': ['dataset', 'seed', 'alpha'],
}

self.data_keeper.set_value(value, dataset='demo', seed=0, alpha=0.1)
value = self.data_keeper.get_value(dataset='demo', seed=0, alpha=0.1)

需要单文件数据库式存储、key 很多且不希望产生大量子文件时，再考虑 lmdb。separate 更容易人工查看、删除和局部排查；lmdb 更像一个数据库文件，适合稳定的大量 key 存储。

在 Tool 中配置

在 experiment tool 里只在 _config_data_keeper 中设置 self.data_keeper_kwargs，不要在 run_detail 临时替换 data_keeper：

def _config_data_keeper(self):
    super()._config_data_keeper()
    self.data_keeper_kwargs = {'data_type': 'dict', 'save_load_method': 'separate'}

如果只使用默认 dict + separate，可以不重写 _config_data_keeper。Experiment 初始化 tool 时会根据 data_keeper_kwargs 创建 DataKeeper(name=self.data_keeper_name, basedir=self.dir_manager.outcomes_dir, ...)，保存目录通常是 outcomes/{tool_name}。

Key 设计

dict 模式下，key 应该是稳定、可读、与结果语义直接对应的字符串，例如 result、summary、weights、score_by_area。不要把随机顺序、worker id、临时文件名或运行日志混进 key。

OrderedDataContainer 模式下，param_order 应该只包含定位结果所需的语义参数，并保持长期稳定。不要把只影响运行方式的参数放进 key，例如 process_num、task_list、threshold_gb。

included_name_list 不决定哪些参数参与 key；传给 set_value(...) / get_value(...) 的参数仍都会参与 key。它只决定哪些参数在生成 key 时同时写入参数名和值；未列入的参数只写入参数值。默认 included_name_list=[]，即按 param_order 拼接参数值。只有当不同参数可能取到相同值、容易生成歧义 key 时，才把这些参数名加入 included_name_list。参数名和值应尽量短且稳定，方便后续 get_subcontainer(...) 和局部读取。

保存和读取

在 Experiment 里通常不用手动 save()；tool 的 after_run 会调用 self.data_keeper.save()，并在 enable_skip=True 时写入 {tool_name}_all_saved 标记。

独立使用 DataKeeper 时，需要自己保存：

keeper = cf.DataKeeper(name='results', basedir=outcomes_dir, data_type='dict', save_load_method='separate')
keeper.set_value(summary, key='summary')
keeper.save()
summary = keeper.get_value(key='summary')

get_value(...) 会先查内存；内存没有时，会尝试从磁盘按 key 局部加载。大对象用完后可以调用：

self.data_keeper.release_memory(keys_to_keep=['summary'])

下游 tool 接收到的前置 {previous_tool_name}_data_keeper 是 read-only。下游只读取前置结果，不要往前置 keeper 写入；新结果写入当前 tool 的 self.data_keeper。

separate 与 lmdb 注意点

separate 使用 save_dict_separate_merge_to_saved / load_dict_separate_merge_to_exist，适合可检查、可局部加载和可分 key 删除的结果目录。

lmdb 使用 save_dict_lmdb / load_dict_lmdb_merge_to_exist。如果结果特别大，可能需要关注 save_dict_lmdb 的 size、unit、max_size 等参数；Experiment 默认 after_run 不传额外保存参数，复杂场景应在项目内写薄 subclass 或 wrapper。

常见错误应直接修正而不是静默绕过：

• OrderedDataContainer 没有 param_order 会报错。
• dict 模式下 get_value() 不给 key 会报错。
• 对 read-only 的前置 DataKeeper 调用 set_value 或 save 会报错。
• key 不稳定会导致复用、局部加载和后续分析难以追溯。

验证重点

先用小数据写入、保存、释放内存、重新读取同一个 key。对 OrderedDataContainer，至少检查一个完整参数 key。若在 experiment 中使用，还要确认 outcomes/{tool_name} 下的实际文件或 lmdb 目录符合预期，并且下游 tool 能通过 {previous_tool_name}_data_keeper.get_value(...) 读取。