Ray Tune 实验结果分析指南ResultGrid、Result 与 ExperimentAnalysis 全解【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray本指南以 Ray Tune 官方 API 文档 doc/source/tune/api/result_grid.rst 为核心系统讲解 Ray Tune 调参实验完成后三类结果对象的完整用法tune.ResultGridTuner.fit()的标准返回对象、tune.Result单个 Trial 的最终结果以及tune.ExperimentAnalysistune.run()时代的经典分析接口。读完本文你将掌握如何从一次完整的调参实验中定位最优 Trial、提取最优检查点、把全部 Trial 的指标导出为 Pandas DataFrame并正确处理运行失败error的 Trial。一、三类 API 的关系从调参运行到结果分析在 Ray Tune 中实验结果的获取经历了两代 API 演进理解它们的关系是掌握结果分析的第一步新一代推荐Tuner.fit()返回一个ResultGrid对象它是Result对象的集合对应文档中tune.ResultGrid一节单次运行结果ResultGrid中的每个元素是一个tune.Result封装了单个 Trial 的最终指标、检查点、错误信息与存储路径对应文档中tune.Result一节经典 APItune.run()返回ExperimentAnalysis对象。官方文档在 result_grid.rst 中明确指出ExperimentAnalysis是tune.runAPI 的输出如今推荐使用Tuner.fit其输出为ResultGrid对象。从源码看这种兼容并包的设计非常清晰python/ray/tune/result_grid.py 中ResultGrid的构造函数直接接收一个ExperimentAnalysis实例并将其中每个 Trial 通过_trial_to_result()转换为Resultdef __init__(self, experiment_analysis: ExperimentAnalysis): self._experiment_analysis experiment_analysis self._results [ self._trial_to_result(trial) for trial in self._experiment_analysis.trials ]也就是说ResultGrid是建立在ExperimentAnalysis之上的轻量封装它把ExperimentAnalysis中面向 Trial 的底层 API改造成面向Result的、更易用的高层 API。而Tuner.fit()的返回类型注解也正是ResultGrid见 python/ray/tune/tuner.py。二、ResultGridTuner.fit()的标准输出2.1 快速上手示例官方文档result_grid.rst给出了一段可直接运行的示例展示如何在存在失败 Trial 的情况下安全地遍历ResultGridimport random from ray import tune def random_error_trainable(config): if random.random() 0.5: return {loss: 0.0} else: raise ValueError(This is an error) tuner tune.Tuner( random_error_trainable, run_configtune.RunConfig(nameexample-experiment), tune_configtune.TuneConfig(num_samples10), ) try: result_grid tuner.fit() except ValueError: pass for i in range(len(result_grid)): result result_grid[i] if not result.error: print(fTrial finishes successfully with metrics {result.metrics}.) else: print(fTrial failed with error {result.error}.)这段代码揭示了ResultGrid的三个核心特性可索引、可求长度ResultGrid实现了__len__与__getitem__result_grid.py因此可以直接用result_grid[i]按下标取第 i 个Result失败 Trial 也被保留文档特别说明所有状态的 Trial 都会被包含在最终的 result grid 中——即使某个 Trial 抛出了异常它对应的Result依然存在只是其error字段非空错误可逐个检查通过result.error判断每个 Trial 是否失败从而在分析时跳过或单独处理错误 Trial。2.2 错误统计属性除了遍历检查ResultGrid还提供了三个与 Trial 状态相关的只读属性result_grid.py属性返回值源码逻辑errors所有失败 Trial 的异常对象列表遍历所有Result收集result.error非空项num_errors失败ERROR 状态Trial 的数量统计trial.status Trial.ERRORnum_terminated正常结束TERMINATEDTrial 的数量统计trial.status Trial.TERMINATED这在批量调参场景中非常实用例如提交了 50 个 Trial可以先检查result_grid.num_errors是否为 0再决定是否需要重跑或分析失败原因。2.3 存储路径与文件系统ResultGrid暴露了两个与持久化存储相关的属性experiment_path实验目录在持久化存储上的路径可以是本地路径head node 上的路径也可以是远程路径如 S3filesystem访问experiment_path所需的pyarrow.fs.FileSystem实现。有了这两个属性即使实验存储在不同节点或云端也能以统一的方式读取结果文件。三、get_best_result定位最优 TrialResultGrid.get_best_result()是实验分析中最常用的方法其完整签名result_grid.py为def get_best_result( self, metric: Optional[str] None, mode: Optional[str] None, scope: str last, filter_nan_and_inf: bool True, ) - Result:3.1 核心参数metric 与 modemetric排序依据的指标键名。默认使用Tuner的TuneConfig中指定的metric若调用时未传且TuneConfig也未配置会抛出ValueError提示信息见 result_grid.pymode取值为min或max表示指标越小越好还是越大越好。同样默认继承TuneConfig中的mode。嵌套指标的扁平化键如果 Trial 上报的是嵌套字典如{eval: {metrics: {loss: 0.1}}}Tune 会用/作为默认分隔符将指标扁平化后再跟踪因此传入的metric应写作eval/metrics/loss。这也是文档给出的官方示例best_result result_grid.get_best_result(metriceval/metrics/loss, modemin)这一行为在 python/ray/tune/analysis/experiment_analysis.py 中通过flatten_dict工具实现且分隔符可通过环境变量TUNE_RESULT_DELIM覆盖默认/。3.2 比较范围scope 的五种取值scope决定每个 Trial 用哪个数值参与跨 Trial 比较共五种取值scope 取值语义last默认只看每个 Trial 最后一步上报的metric值avg使用该指标在所有步骤上的简单平均值last-5-avg使用最后 5 步的简单平均值last-10-avg使用最后 10 步的简单平均值all按mode找出每个 Trial 该指标的最优值min 找最小、max 找最大再跨 Trial 比较在 experiment_analysis.py 中可以看到其底层实现scope in [last, avg, last-5-avg, last-10-avg]时读取trial.metric_analysis[metric][scope]否则读取trial.metric_analysis[metric][mode]。注意scope的值会在 experiment_analysis.py 被校验非法值会抛出ValueError。3.3 过滤无效值filter_nan_and_inf默认filter_nan_and_infTrue即自动忽略值为NaN或无穷大inf的 Trial使其永远不被选为最优。如果所有 Trial 的该指标都是NaN或缺失get_best_result会抛出RuntimeError错误信息会提示没有任何 Trial 上报该指标或该指标全部为 NaN并建议若不想忽略 NaN 值可将filter_nan_and_inf设为 False见 result_grid.py。3.4 提取最优检查点拿到best_result之后最优 Trial 对应的最新检查点只需一行best_checkpoint best_result.checkpointResult.checkpoint字段封装了该 Trial 最新的持久化检查点其构建逻辑见_trial_to_result从checkpoint_manager.latest_checkpoint_result提取result_grid.py可直接用于后续的模型加载与推理。四、get_dataframe把全部结果导出为 DataFrameResultGrid.get_dataframe()将所有 Trial 及其配置、上报指标汇总成一个 Pandas DataFrame签名如下result_grid.pydef get_dataframe( self, filter_metric: Optional[str] None, filter_mode: Optional[str] None, ) - pd.DataFrame:默认行为不传任何参数时返回每个 Trial最后一次上报的结果每行是一个 Trial列是其上报的指标与超参数配置按指标过滤传入filter_metric与filter_mode后会对每个 Trial 的历史结果做筛选。例如filter_metricaccuracy, filter_modemax表示对每个 Trial 而言返回其历史上accuracy最大的那一行——注意这不一定是最后一次上报。官方文档给出的完整示例import ray.tune def training_loop_per_worker(config): ray.tune.report({accuracy: 0.8}) result_grid ray.tune.Tuner( trainabletraining_loop_per_worker, run_configray.tune.RunConfig(namemy_tune_run) ).fit() # 每个 Trial 最后一次上报的结果 df result_grid.get_dataframe() # 每个 Trial 历史上 accuracy 最大的一次结果 df result_grid.get_dataframe( filter_metricaccuracy, filter_modemax )底层实现上该方法直接委托给ExperimentAnalysis.dataframe(metric, mode)result_grid.py而dataframe()会通过_retrieve_rowsexperiment_analysis.py逐 Trial 读取其指标序列modemax时取df[metric].idxmax()modemin时取df[metric].idxmin()否则取最后一行随后还会把每个 Trial 的超参配置以config/为前缀展平与 logdir 合并进每一行。因此导出后的 DataFrame 天然带有超参列可直接交给 pandas/sklearn 做进一步分析。五、Result单个 Trial 的最终产出Result定义在 python/ray/air/result.py是一个dataclass同时是Tuner.fit输出集合的元素、Trainer.fit的直接输出。官方文档将其列为推荐的结果访问方式可用于获取检查点Result.checkpoint、指标历史Result.metrics_dataframe、Result.metrics与运行错误Result.error。5.1 核心字段一览字段类型含义metricsDict[str, Any]最新一次上报的指标集合未展平的原始字典checkpointCheckpoint最新的检查点errorException若 Trial 失败为对应的异常TuneError或RayTaskError成功则为Nonepathstr结果目录在持久化存储上的路径本地或 S3 等远程路径metrics_dataframepd.DataFrame该 Trial 的完整指标历史按迭代索引列使用扁平化后的指标键名best_checkpointsList[Tuple[Checkpoint, Dict]]最优检查点及其关联指标的列表数量由ray.train.CheckpointConfig控制默认保存全部检查点需要注意一个容易混淆的点Result.metrics是未扁平化的字典与上报格式一致而Result.metrics_dataframe的列名是扁平化后的键以/连接两者格式略有差异。5.2 辅助属性与方法result.config返回metrics中config键对应的超参配置无则返回Noneresult.pyresult.filesystem访问result.path所需的pyarrow.fs.FileSystem未显式指定时默认本地文件系统result.pyresult.get_best_checkpoint(metric, mode)alpha 稳定性基于指定指标从best_checkpoints中选出最优检查点mode仅接受min/maxresult.py。5.3 从磁盘恢复 ResultResult.from_pathResult的构造函数是私有 API但官方提供了Result.from_path(path, storage_filesystemNone)类方法可以从本地或远程 Trial 目录恢复出Result对象result.py。其内部逻辑依次为读取result.json每行一个 JSON若不存在则回退读取progress.csv构建metrics_dataframe并取最后一行作为latest_metrics扫描目录下所有checkpoint_*子目录构建Checkpoint列表与对应的指标列表得到best_checkpoints与latest_checkpoint若存在错误文件pickle 化的异常文件反序列化为error字段。这意味着即使实验早已结束、进程已退出只要磁盘上的实验目录还在就能完整恢复出可分析的结果对象。六、ExperimentAnalysis经典分析接口的完整能力ExperimentAnalysispython/ray/tune/analysis/experiment_analysis.py是tune.run()时代的产物官方文档明确建议新代码改用Tuner.fit() ResultGrid。但由于ResultGrid内部正是基于它实现理解其能力有助于深入掌握底层机制也便于维护存量代码。6.1 构造方式from ray.tune import ExperimentAnalysis analysis ExperimentAnalysis(experiment_checkpoint_path~/ray_results/example-experiment)experiment_checkpoint_path可以指向experiment_state.json文件也可以指向包含该文件的目录。构造时会自动从实验状态文件恢复出全部 TrialTrial.from_json_state并逐个读取每个 Trial 的result.json/progress.csv构建指标 DataFrame见_fetch_trial_dataframesexperiment_analysis.py。官方文档同时提醒这套机制依赖默认的日志落盘行为即result.json与progress.csv被写入实验目录若通过环境变量TUNE_DISABLE_AUTO_CALLBACK_LOGGERS1显式禁用了默认 logger则无法使用。6.2 常用方法与属性成员说明analysis.trials所有 Trial 对象列表analysis.trial_dataframestrial_id - DataFrame映射每个 DataFrame 按迭代索引、包含上报指标analysis.get_all_configs(prefixFalse)返回trial_id - config映射prefixTrue时键展平并加config/前缀analysis.get_best_trial(metric, mode, scope, filter_nan_and_inf)返回最优 Trial 对象参数语义与ResultGrid.get_best_result完全一致analysis.get_best_config(metric, mode, scope)返回最优 Trial 的超参配置Dictanalysis.get_best_checkpoint(trial, metric, mode)返回指定 Trial 的最优检查点自动过滤指标为 NaN 的检查点experiment_analysis.pyanalysis.best_trial/best_config/best_checkpoint/best_result/best_dataframe依赖tune.run()时传入的metric/mode即default_metric/default_mode未传时会抛ValueErroranalysis.dataframe(metricNone, modeNone)构建所有 Trial 的汇总 DataFramemodemin/max时取每 Trial 历史最优行否则取最后一行analysis.results_df/analysis.results所有 Trial 的最后一次结果以 DataFrame /trial_id - result字典形式返回analysis.get_last_checkpoint(trialNone)默认取训练迭代数最大的 Trial 的最新检查点一个典型用法是用get_best_trial得到最优 Trial 后通过trial.config拿到最优超参或通过get_best_checkpoint拿到对应检查点用于部署。七、实战要点与踩坑提醒优先在TuneConfig中声明 metric/mode无论ResultGrid.get_best_result()还是ExperimentAnalysis的best_*系列属性都会优先回退到TuneConfig(metric..., mode...)中配置的默认值。未配置且调用时不传会直接抛ValueError在调参开始时声明可避免后续所有分析代码都要重复传参。不要假设所有 Trial 都成功ResultGrid包含所有状态的 Trial。分析前先用num_errors/errors或遍历result.error做防御性检查避免把失败 Trial 的残缺指标混入统计。scope改变最优的含义默认scopelast只看最后一步若指标在训练后期振荡剧烈改用scopeavg或scopelast-10-avg往往能选出更稳健的 Trial。嵌套指标用扁平键上报{eval: {metrics: {loss: 0.1}}}后所有 API 中引用它都要写作eval/metrics/loss查看get_dataframe()的列名即可确认扁平化后的实际键。结果可离线恢复实验目录保留result.json/progress.csv与checkpoint_*子目录的前提下Result.from_path()与ExperimentAnalysis(...)都能在进程重启后还原全部结果无需重跑实验。八、进一步阅读官方 API 参考文档doc/source/tune/api/result_grid.rst结果分析综合示例notebookdoc/source/tune/examples/tune_analyze_results.ipynbResultGrid源码实现python/ray/tune/result_grid.pyResult数据类定义python/ray/air/result.pyExperimentAnalysis底层实现python/ray/tune/analysis/experiment_analysis.pyTuner.fit()的定义与文档python/ray/tune/tuner.py【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考