Qlib记录仪：实验管理

实验管理器 (Experiment Manager)

Qlib 中的 ExpManager 模块负责管理不同的实验。ExpManager 的大多数 API 与 QlibRecorder 类似，其中最重要的 API 是 get_exp 方法。用户可以直接参考上面的文档，获取有关如何使用 get_exp 方法的一些详细信息。

class qlib.workflow.expm.ExpManager(uri: str, default_exp_name: str | None)

这是用于管理实验的 ExpManager 类。其 API 设计类似于 mlflow。（链接：https://mlflow.org/docs/latest/python_api/mlflow.html）

ExpManager 预期是一个单例（顺便说一下，我们可以有多个 URI 不同的 Experiment。用户可以从不同的 URI 获取不同的实验，然后比较它们的记录）。全局配置（即 C）也是一个单例。

因此，我们试图将它们对齐。它们共享同一个变量，称为 default uri。有关变量共享的详细信息，请参阅 ExpManager.default_uri。

当用户启动一个实验时，他们可能希望将 URI 设置为特定的 URI（在此期间它将覆盖 default uri），然后取消设置该特定 URI 并回退到默认 URI。ExpManager._active_exp_uri 就是那个特定 URI。

__init__(uri: str, default_exp_name: str | None)

start_exp(*, experiment_id: str | None = None, experiment_name: str | None = None, recorder_id: str | None = None, recorder_name: str | None = None, uri: str | None = None, resume: bool = False, **kwargs) -> Experiment

启动一个实验。此方法首先获取或创建一个实验，然后将其设置为活动状态。

_active_exp_uri 的维护包含在 start_exp 中，其余实现应包含在子类中的 _end_exp 中。

参数：

• experiment_id (str) – 活动实验的 ID。

• experiment_name (str) – 活动实验的名称。

• recorder_id (str) – 要启动的记录器 ID。

• recorder_name (str) – 要启动的记录器名称。

• uri (str) – 当前跟踪 URI。

• resume (boolean) – 是否恢复实验和记录器。

  返回类型：

  一个活动实验。

end_exp(recorder_status: str = 'SCHEDULED', **kwargs)

结束一个活动实验。

_active_exp_uri 的维护包含在 end_exp 中，其余实现应包含在子类中的 _end_exp 中。

参数：

• experiment_name (str) – 活动实验的名称。

• recorder_status (str) – 实验中活动记录器的状态。

create_exp(experiment_name: str | None = None)

创建一个实验。

参数：

• experiment_name (str) – 实验名称，必须是唯一的。

  返回类型：

  一个实验对象。

  引发：

  ExpAlreadyExistError –

search_records(experiment_ids=None, **kwargs)

获取符合实验搜索条件的记录的 pandas DataFrame。输入是用户想要应用的搜索条件。

返回：

一个 pandas.DataFrame 记录，其中每个指标、参数和标签分别扩展为名为 metrics.*、params.* 和 tags.* 的列。对于没有特定指标、参数或标签的记录，它们的值将分别为 (NumPy) Nan、None 或 None。

get_exp(*, experiment_id=None, experiment_name=None, create: bool = True, start: bool = False)

检索一个实验。此方法包括获取一个活动实验，以及获取或创建一个特定实验。

当用户指定实验 ID 和名称时，该方法将尝试返回特定实验。当用户未提供记录器 ID 或名称时，该方法将尝试返回当前活动实验。create 参数决定了如果实验之前未创建，该方法是否会自动根据用户的规范创建一个新实验。

如果 create 为 True：

• 如果活动实验存在：

  • 未指定 ID 或名称，返回活动实验。

  • 如果指定了 ID 或名称，则返回指定的实验。如果找不到此类实验，则使用给定 ID 或名称创建一个新实验。如果 start 设置为 True，则将实验设置为活动状态。

• 如果活动实验不存在：

  • 未指定 ID 或名称，创建默认实验。

  • 如果指定了 ID 或名称，则返回指定的实验。如果找不到此类实验，则使用给定 ID 或名称创建一个新实验。如果 start 设置为 True，则将实验设置为活动状态。

    否则，如果 create 为 False：

• 如果活动实验存在：

  • 未指定 ID 或名称，返回活动实验。

  • 如果指定了 ID 或名称，则返回指定的实验。如果找不到此类实验，则引发错误。

• 如果活动实验不存在：

  • 未指定 ID 或名称。如果默认实验存在，则返回它，否则引发错误。

  • 如果指定了 ID 或名称，则返回指定的实验。如果找不到此类实验，则引发错误。

    参数：

• experiment_id (str) – 要返回的实验 ID。

• experiment_name (str) – 要返回的实验名称。

• create (boolean) – 如果实验之前未创建，则创建它。

• start (boolean) – 如果创建了新实验，则启动它。

  返回类型：

  一个实验对象。

delete_exp(experiment_id=None, experiment_name=None)

删除一个实验。

参数：

• experiment_id (str) – 实验 ID。

• experiment_name (str) – 实验名称。

property default_uri

从 qlib.config.C 获取默认跟踪 URI。

property uri

获取默认跟踪 URI 或当前 URI。

返回类型：

跟踪 URI 字符串。

list_experiments()

列出所有现有实验。

返回类型：

一个存储的实验信息字典（名称 -> 实验）。

对于 create_exp、delete_exp 等其他接口，请参阅实验管理器 API。

实验 (Experiment)

Experiment 类只负责一个单独的实验，它将处理与实验相关的任何操作。包括 start、end 实验等基本方法。此外，与记录器相关的方法也可用：此类方法包括 get_recorder 和 list_recorders。

class qlib.workflow.exp.Experiment(id, name)

这是每个正在运行的实验的 Experiment 类。其 API 设计类似于 mlflow。（链接：https://mlflow.org/docs/latest/python_api/mlflow.html）

__init__(id, name)

start(*, recorder_id=None, recorder_name=None, resume=False)

启动实验并将其设置为活动状态。此方法还将启动一个新的记录器。

参数：

• recorder_id (str) – 要创建的记录器 ID。

• recorder_name (str) – 要创建的记录器名称。

• resume (bool) – 是否恢复第一个记录器。

  返回类型：

  一个活动记录器。

end(recorder_status='SCHEDULED')

结束实验。

参数：

• recorder_status (str) – 结束时要设置的记录器状态（SCHEDULED、RUNNING、FINISHED、FAILED）。

create_recorder(recorder_name=None)

为每个实验创建一个记录器。

参数：

• recorder_name (str) – 要创建的记录器名称。

  返回类型：

  一个记录器对象。

search_records(**kwargs)

获取符合实验搜索条件的记录的 pandas DataFrame。输入是用户想要应用的搜索条件。

返回：

一个 pandas.DataFrame 记录，其中每个指标、参数和标签分别扩展为名为 metrics.*、params.* 和 tags.* 的列。对于没有特定指标、参数或标签的记录，它们的值将分别为 (NumPy) Nan、None 或 None。

delete_recorder(recorder_id)

为每个实验创建一个记录器。

参数：

• recorder_id (str) – 要删除的记录器 ID。

get_recorder(recorder_id=None, recorder_name=None, create: bool = True, start: bool = False) -> Recorder

为用户检索记录器。当用户指定记录器 ID 和名称时，该方法将尝试返回特定记录器。当用户未提供记录器 ID 或名称时，该方法将尝试返回当前活动记录器。create 参数决定了如果记录器之前未创建，该方法是否会自动根据用户的规范创建一个新记录器。

如果 create 为 True：

• 如果活动记录器存在：

  • 未指定 ID 或名称，返回活动记录器。

  • 如果指定了 ID 或名称，则返回指定的记录器。如果找不到此类实验，则使用给定 ID 或名称创建一个新记录器。如果 start 设置为 True，则将记录器设置为活动状态。

• 如果活动记录器不存在：

  • 未指定 ID 或名称，创建一个新的记录器。

  • 如果指定了 ID 或名称，则返回指定的实验。如果找不到此类实验，则使用给定 ID 或名称创建一个新记录器。如果 start 设置为 True，则将记录器设置为活动状态。

    否则，如果 create 为 False：

• 如果活动记录器存在：

  • 未指定 ID 或名称，返回活动记录器。

  • 如果指定了 ID 或名称，则返回指定的记录器。如果找不到此类实验，则引发错误。

• 如果活动记录器不存在：

  • 未指定 ID 或名称，引发错误。

  • 如果指定了 ID 或名称，则返回指定的记录器。如果找不到此类实验，则引发错误。

    参数：

• recorder_id (str) – 要删除的记录器 ID。

• recorder_name (str) – 要删除的记录器名称。

• create (boolean) – 如果记录器之前未创建，则创建它。

• start (boolean) – 如果创建了新记录器，则启动它。

  返回类型：

  一个记录器对象。

list_recorders(rtype: Literal['dict', 'list'] = 'dict', **flt_kwargs) -> List[Recorder] | Dict[str, Recorder]

列出此实验的所有现有记录器。在调用此方法之前，请先获取实验实例。如果用户想使用 R.list_recorders() 方法，请参阅 QlibRecorder 中的相关 API 文档。

• flt_kwargs dict

  • 按条件筛选记录器，例如 list_recorders(status=Recorder.STATUS_FI)

    返回：

• 如果 rtype == "dict"：

  • 一个存储的记录器信息字典（ID -> 记录器）。

• 如果 rtype == "list"：

  • 一个 Recorder 列表。

    返回类型：

    返回类型取决于 rtype。

    对于 search_records、delete_recorder 等其他接口，请参阅实验 API。

    Qlib 还提供了一个默认的 Experiment，当用户使用 log_metrics 或 get_exp 等 API 时，在某些情况下会创建和使用它。如果使用默认的 Experiment，在运行 Qlib 时会有相关的日志信息。用户可以在 Qlib 的配置文件中或在 Qlib 的初始化期间更改默认 Experiment 的名称，该名称设置为“Experiment”。

记录器 (Recorder)

Recorder 类负责一个单独的记录器。它将处理一些详细的操作，例如一次运行的 log_metrics、log_params。它旨在帮助用户轻松跟踪在一次运行中生成的结果和事物。

以下是一些未包含在 QlibRecorder 中的重要 API：

class qlib.workflow.recorder.Recorder(experiment_id, name)

这是用于记录实验的 Recorder 类。其 API 设计类似于 mlflow。（链接：https://mlflow.org/docs/latest/python_api/mlflow.html）

记录器的状态可以是 SCHEDULED、RUNNING、FINISHED、FAILED。

__init__(experiment_id, name)

save_objects(local_path=None, artifact_path=None, **kwargs)

将预测文件或模型检查点等对象保存到工件 URI。用户可以通过关键字参数（名称:值）保存对象。

请参阅 qlib.workflow:R.save_objects 的文档。

参数：

• local_path (str) – 如果提供，则将文件或目录保存到工件 URI。

• artifact_path=None (str) – 要存储在 URI 中的工件的相对路径。

load_object(name)

加载预测文件或模型检查点等对象。

参数：

• name (str) – 要加载的文件名。

  返回类型：

  保存的对象。

start_run()

启动或恢复记录器。返回值可以用作 with 块中的上下文管理器；否则，您必须调用 end_run() 来终止当前运行。（请参阅 mlflow 中的 ActiveRun 类）

返回类型：

一个活动运行对象（例如 mlflow.ActiveRun 对象）。

end_run()

结束一个活动记录器。

log_params(**kwargs)

为当前运行记录一批参数。

参数：

• arguments (keyword) – 要记录为参数的键值对。

log_metrics(step=None, **kwargs)

为当前运行记录多个指标。

参数：

• arguments (keyword) – 要记录为指标的键值对。

log_artifact(local_path: str, artifact_path: str | None = None)

将本地文件或目录作为工件记录到当前活动的运行中。

参数：

• local_path (str) – 要写入的文件路径。

• artifact_path (Optional[str]) – 如果提供，则为要写入的 artifact_uri 中的目录。

set_tags(**kwargs)

为当前运行记录一批标签。

参数：

• arguments (keyword) – 要记录为标签的键值对。

delete_tags(*keys)

从运行中删除一些标签。

参数：

• keys (series of strs of the keys) – 要删除的所有标签名称。

list_artifacts(artifact_path: str | None = None)

列出记录器的所有工件。

参数：

• artifact_path (str) – 要存储在 URI 中的工件的相对路径。

  返回类型：

  一个存储的工件信息列表（名称、路径等）。

download_artifact(path: str, dst_path: str | None = None) -> str

将工件文件或目录从运行下载到本地目录（如果适用），并返回其本地路径。

参数：

• path (str) – 目标工件的相对源路径。

• dst_path (Optional[str]) – 用于下载指定工件的本地文件系统目标目录的绝对路径。此目录必须已存在。如果未指定，工件将下载到本地文件系统上一个新创建的、具有唯一名称的目录中。

  返回：

  目标工件的本地路径。

  返回类型：str

list_metrics()

列出记录器的所有指标。

返回类型：

一个存储的指标字典。

list_params()

列出记录器的所有参数。

返回类型：

一个存储的参数字典。

list_tags()

列出记录器的所有标签。

返回类型：

一个存储的标签字典。

对于 save_objects、load_object 等其他接口，请参阅记录器 API。

记录模板 (Record Template)

RecordTemp 类是一个能够以特定格式生成实验结果（例如 IC 和回测）的类。我们提供了三种不同的 Record Template 类：

• SignalRecord：此类生成模型的预测结果。

• SigAnaRecord：此类生成模型的 IC、ICIR、Rank IC 和 Rank ICIR。

  以下是 SigAnaRecord 中所做的一个简单示例，如果用户想用自己的预测和标签计算 IC、Rank IC、多空收益，可以参考：

  Python

  from qlib.contrib.eva.alpha import calc_ic, calc_long_short_return
  ic, ric = calc_ic(pred.iloc[:, 0], label.iloc[:, 0])
  long_short_r, long_avg_r = calc_long_short_return(pred.iloc[:, 0], label.iloc[:, 0])
  

• PortAnaRecord：此类生成回测的结果。有关回测以及可用策略的详细信息，用户可以参阅策略和回测。

  以下是 PortAnaRecord 中所做的一个简单示例，如果用户想基于自己的预测和标签进行回测，可以参考：

  Python

  from qlib.contrib.strategy.strategy import TopkDropoutStrategy
  from qlib.contrib.evaluate import (
      backtest as normal_backtest,
      risk_analysis,
  )
  # backtest
  STRATEGY_CONFIG = {
      "topk": 50,
      "n_drop": 5,
  }
  BACKTEST_CONFIG = {
      "limit_threshold": 0.095,
      "account": 100000000,
      "benchmark": BENCHMARK,
      "deal_price": "close",
      "open_cost": 0.0005,
      "close_cost": 0.0015,
      "min_cost": 5,
  }
  strategy = TopkDropoutStrategy(**STRATEGY_CONFIG)
  report_normal, positions_normal = normal_backtest(pred_score, strategy=strategy, **BACKTEST_CONFIG)
  # analysis
  analysis = dict()
  analysis["excess_return_without_cost"] = risk_analysis(report_normal["return"] - report_normal["bench"])
  analysis["excess_return_with_cost"] = risk_analysis(report_normal["return"] - report_normal["bench"] - report_normal["cost"])
  analysis_df = pd.concat(analysis)  # type: pd.DataFrame
  print(analysis_df)
  

有关 API 的更多信息，请参阅记录模板 API。

已知限制

Python 对象是基于 pickle 保存的，当转储对象和加载对象的环境不同时，可能会导致问题。