高级配置¶

关于配置的文档描述了如何满足标准Kedro项目配置的大多数常见需求：

默认情况下，Kedro配置为使用OmegaConfigLoader类。

Kedro项目的高级配置¶

本页面还包含一套针对标准Kedro项目高级配置需求的指导说明：

如何使用自定义配置加载器
如何更改加载的配置文件
如何确保加载非默认配置文件
如何绕过配置加载规则
如何使用OmegaConfigLoader进行模板化
如何在代码中使用模板加载数据目录？
如何与OmegaConfigLoader一起使用全局变量
如何使用运行时参数通过OmegaConfigLoader覆盖配置
如何在OmegaConfigLoader中使用解析器
如何通过环境变量使用OmegaConfigLoader加载凭证
如何更改OmegaConfigLoader使用的合并策略

如何使用自定义配置加载器¶

您可以通过扩展AbstractConfigLoader类来实现自定义配置加载器：

from kedro.config import AbstractConfigLoader


class CustomConfigLoader(AbstractConfigLoader):
    def __init__(
        self,
        conf_source: str,
        env: str = None,
        runtime_params: Dict[str, Any] = None,
    ):
        super().__init__(
            conf_source=conf_source, env=env, runtime_params=runtime_params
        )

        # Custom implementation

要使用此自定义配置加载器，请在src//settings.py中将其设置为项目配置加载器，如下所示：

from package_name.custom_configloader import CustomConfigLoader

CONFIG_LOADER_CLASS = CustomConfigLoader

如何更改加载的配置文件¶

如果你想修改配置加载器用于查找待加载文件的模式，需要在src//settings.py中设置CONFIG_LOADER_ARGS变量。例如，如果你的parameters文件采用params命名约定而非parameters（例如params.yml），则需要按如下方式更新CONFIG_LOADER_ARGS：

CONFIG_LOADER_ARGS = {
    "config_patterns": {
        "parameters": ["params*", "params*/**", "**/params*"],
    }
}

通过更改此设置，加载参数的默认行为将被替换，而其他配置模式将保持默认状态。

如何确保加载非默认配置文件¶

您可以通过在src//settings.py中设置CONFIG_LOADER_ARGS变量，添加配置模式来匹配除parameters、credentials和catalog之外的其他文件。例如，如果您想加载Spark配置文件，需要按以下方式更新CONFIG_LOADER_ARGS：

CONFIG_LOADER_ARGS = {
    "config_patterns": {
        "spark": ["spark*/"],
    }
}

如何绕过配置加载规则¶

您可以绕过配置模式，直接在配置加载器类的实例上设置配置。您不仅可以绕过默认配置（目录、参数和凭据），还可以绕过其他附加配置。

例如，你可以使用钩子加载外部凭证。

另外，如果您将配置加载器作为独立组件使用，可以按以下方式覆盖配置：

from kedro.config import OmegaConfigLoader
from kedro.framework.project import settings

conf_path = str(project_path / settings.CONF_SOURCE)
conf_loader = OmegaConfigLoader(conf_source=conf_path)

# Bypass configuration patterns by setting the key and values directly on the config loader instance.
conf_loader["catalog"] = {"catalog_config": "something_new"}

如何使用`OmegaConfigLoader`进行模板化¶

参数¶

模板化或变量插值（在OmegaConf中的称呼）可以直接用于参数，前提是模板值位于参数文件中，或者包含模板值的文件名遵循为参数指定的相同配置模式。默认情况下，参数的配置模式为：["parameters*", "parameters*/**", "**/parameters*"]。假设您有一个名为parameters.yml的参数文件，其中包含带有omegaconf占位符的参数，如下所示：

model_options:
  test_size: ${data.size}
  random_state: 3

以及一个包含模板值的文件，名为parameters_globals.yml：

data:
  size: 0.2

由于两个文件名（parameters.yml 和 parameters_globals.yml）都匹配参数配置模式，OmegaConfigLoader 将正确加载文件并解析占位符。

目录¶

从Kedro 0.18.10版本开始，模板功能也适用于目录文件。要在目录中启用模板功能，您需要确保模板值位于目录文件内，或者包含模板值的文件名遵循为目录指定的相同配置模式。默认情况下，目录的配置模式为：["catalog*", "catalog*/**", "**/catalog*"]。

此外，目录中的任何模板值都需要以下划线 _ 开头。这是由于目录条目验证机制决定的。模板值既不会触发键重复错误，也不会出现在最终配置字典中。

假设你有一个名为catalog.yml的目录文件，其中包含使用omegaconf占位符的条目，如下所示：

companies:
  type: ${_pandas.type}
  filepath: data/01_raw/companies.csv

以及一个包含模板值的文件，名为catalog_globals.yml：

_pandas:
  type: pandas.CSVDataset

由于两个文件名（catalog.yml 和 catalog_globals.yml）都匹配目录的配置模式，OmegaConfigLoader 将正确加载文件并解析占位符。

其他配置文件¶

除了参数和目录之外，在自定义spark或mlflow等其他配置文件中也可以使用变量插值。其工作方式与参数文件中的变量插值相同。如果需要，您仍然可以使用下划线作为模板值，但这不像目录文件那样是强制性的。

如何在代码中使用模板加载数据目录？¶

您可以使用OmegaConfigLoader直接加载包含代码模板的数据目录。OmegaConfigLoader会在底层解析所有模板，因此无需额外步骤即可正确加载目录条目。

# Example catalog with templating
companies:
  type: ${_dataset_type}
  filepath: data/01_raw/companies.csv

_dataset_type: pandas.CSVDataset

from kedro.config import OmegaConfigLoader
from kedro.framework.project import settings

# Instantiate an `OmegaConfigLoader` instance with the location of your project configuration.
conf_path = str(project_path / settings.CONF_SOURCE)
conf_loader = OmegaConfigLoader(conf_source=conf_path)

conf_catalog = conf_loader["catalog"]
# conf_catalog["companies"]
# Will result in: {'type': 'pandas.CSVDataset', 'filepath': 'data/01_raw/companies.csv'}

如何在`OmegaConfigLoader`中使用全局变量¶

从Kedro 0.18.13版本开始，您可以通过OmegaConfigLoader使用"globals"在配置文件中实现变量插值。与常规变量插值相比，使用全局变量的优势在于这些变量可以在不同配置类型（如目录和参数）之间共享。默认情况下，这些全局变量假定位于您任何环境中的globals.yml文件中。如果您想配置包含全局变量的文件命名模式，可以通过覆盖config_patterns中的globals键来实现。您还可以绕过配置加载直接在OmegaConfigLoader中设置全局变量。

假设您的全局变量位于文件 conf/base/globals.yml 中：

my_global_value: 45
dataset_type:
  csv: pandas.CSVDataset

您可以在目录或参数配置文件中通过globals解析器访问这些全局变量，例如： conf/base/parameters.yml：

my_param : "${globals:my_global_value}"

conf/base/catalog.yml:

companies:
  filepath: data/01_raw/companies.csv
  type: "${globals:dataset_type.csv}"

如果全局变量不存在，你也可以提供一个默认值来使用：

my_param: "${globals: nonexistent_global, 23}"

如果基础环境和运行时环境中的全局文件存在重复键，则运行时环境中的值会覆盖基础环境中的值。

如何使用运行时参数覆盖配置与`OmegaConfigLoader`¶

Kedro允许您通过--params CLI选项为kedro run命令指定运行时参数。这些运行时参数会被添加到KedroContext中，并与配置文件中的参数合并，用于项目管道和节点。从Kedro 0.18.14版本开始，您可以使用runtime_params解析器来表明希望通过CLI选项提供的运行时参数覆盖配置中特定键的值。该解析器可用于不同类型的配置，如参数、目录等，但不包括"globals"。

考虑这个 parameters.yml 文件：

model_options:
  random_state: "${runtime_params:random}"

这将允许你通过CLI传递一个名为random的运行时参数，用于指定项目中参数model_options.random_state的值：

kedro run --params random=3

如果未使用kedro run命令指定运行时参数，您还可以指定要使用的默认值。考虑以下目录条目：

companies:
  type: pandas.CSVDataset
  filepath: "${runtime_params:folder, 'data/01_raw'}/companies.csv"

如果未通过CLI --params选项与kedro run传递folder参数，则filepath将使用默认值'data/01_raw/'。

注意

当在代码中手动实例化OmegaConfigLoader时，通过CLI --params选项传递的运行时参数将无法被解析器获取。这是因为手动创建的配置加载器实例无法访问通过CLI提供的运行时参数。如果您需要在手动实例化OmegaConfigLoader的代码中访问运行时参数，应该改用Kedro上下文来访问参数。

如何使用 `globals` 和 `runtime_params`¶

如上所述，runtime_params并非设计用于覆盖globals配置。这样做是为了避免隐式覆盖并简化参数解析。因此，globals只有一个入口点——yaml文件。

不过，您可以通过将globals指定为默认值来使用globals和runtime_params，以便在未传递运行时参数时使用。

考虑这个 parameters.yml：

model_options:
  random_state: "${runtime_params:random, ${globals:my_global_value}}"

以及这个 globals.yml 文件：

my_global_value: 4

这将允许你通过CLI传递一个名为random的运行时参数，用于指定项目中参数model_options.random_state的值：

kedro run --params random=3

如果未通过CLI --params选项与kedro run传递random参数，则会使用globals.yml中的my_global_value作为model_options.random_state的值。

如何在`OmegaConfigLoader`中使用解析器¶

除了在配置文件中硬编码值之外，您还可以使用OmegaConf的解析器功能动态计算这些值。您可以使用解析器定义自定义逻辑来计算参数或目录条目的值，或从其他地方注入这些值。要在Kedro中使用此功能，请通过项目中的src//settings.py文件里的CONFIG_LOADER_ARGS参数，将自定义解析器的dict传递给OmegaConfigLoader。下面的示例说明了这一点：

import polars as pl
from datetime import date


def date_today():
    return date.today()


CONFIG_LOADER_ARGS = {
    "custom_resolvers": {
        "add": lambda *my_list: sum(my_list),
        "polars": lambda x: getattr(pl, x),
        "today": date_today,
    }
}

这些自定义解析器随后会在底层通过OmegaConf.register_new_resolver()进行注册，并可在项目中的任何配置文件中使用。例如，您可以在parameters.yml中使用上述定义的add或today解析器，如下所示：

model_options:
  test_size: "${add:1,2,3}"
  random_state: 3

date: "${today:}"

这些参数的值将在访问时计算，并传递给您的节点。解析器也可用于您的catalog.yml中。在下面的示例中，我们使用上面定义的polars解析器将非基本类型传递给目录条目。

my_polars_dataset:
  type: polars.CSVDataset
  filepath: data/01_raw/my_dataset.csv
  load_args:
    dtypes:
      product_age: "${polars:Float64}"
      group_identifier: "${polars:Utf8}"
    try_parse_dates: true

OmegaConf 还提供了一些内置解析器，您可以在 Kedro 的 OmegaConfigLoader 中使用。除 oc.env 外，所有内置解析器默认都已启用。oc.env 仅用于加载凭证。不过，您可以通过项目中的 src//settings.py 以类似方式为所有配置启用此功能：

注意

这是一项高级功能，使用时需谨慎。我们建议仅将环境变量用于凭证配置，而非其他配置项。

from omegaconf.resolvers import oc

CONFIG_LOADER_ARGS = {
    "custom_resolvers": {
        "oc.env": oc.env,
    }
}

如何通过环境变量加载凭证¶

OmegaConfigLoader 允许您从环境变量中加载凭证。要实现这一点，您需要使用 OmegaConfigLoader 和 omegaconf 的 oc.env 解析器。您可以使用 oc.env 解析器在 credentials.yml 中访问环境变量中的凭证：

dev_s3:
  client_kwargs:
    aws_access_key_id: ${oc.env:AWS_ACCESS_KEY_ID}
    aws_secret_access_key: ${oc.env:AWS_SECRET_ACCESS_KEY}

注意

请注意，您只能在credentials.yml中使用解析器，而不能在目录或参数文件中使用。这是因为我们不鼓励在凭证以外的任何场景使用环境变量。

如何更改`OmegaConfigLoader`使用的合并策略¶

默认情况下，OmegaConfigLoader会以覆盖方式合并不同环境中的配置以及运行时参数。这意味着当基础环境和覆盖环境（默认为local）中存在相同的顶级键时，覆盖环境中的配置将优先生效。除了覆盖环境中提供的配置外，该键下的其他所有配置都将被丢弃。同样的行为也适用于运行时参数覆盖base环境中的任何配置。您可以在项目的src//settings.py中为每种配置类型更改合并策略。可接受的合并策略包括soft和destructive。

from kedro.config import OmegaConfigLoader

CONFIG_LOADER_CLASS = OmegaConfigLoader

CONFIG_LOADER_ARGS = {
    "merge_strategy": {
        "parameters": "soft",
        "spark": "destructive",
        "mlflow": "soft",
    }
}

如果未定义合并策略，将应用默认的破坏性策略。请注意，此合并策略设置仅适用于不同环境中的配置文件。当文件属于同一环境时，它们总是以软方式合并。当同一环境中的文件包含相同的顶级键时，将抛出错误。

无需完整Kedro项目的高级配置¶

在某些情况下，您可能只想使用OmegaConfigLoader而不需要Kedro项目。默认情况下，Kedro项目包含base和local环境。然而，当您直接使用OmegaConfigLoader时，它会假设没有环境。您可能会发现将Kedro添加到现有笔记本中很有帮助。

读取配置¶

配置加载器可以在没有Kedro项目结构的情况下工作。

tree .
.
└── parameters.yml

考虑以下 parameters.yml 文件和示例 Python 脚本：

learning_rate: 0.01
train_test_ratio: 0.7

from kedro.config import OmegaConfigLoader
config_loader = OmegaConfigLoader(conf_source=".")

# Optionally, you can also use environments
# config_loader = OmegaConfigLoader(conf_source=".", base_env="base", default_run_env="local")

print(config_loader["parameters"])

如果你从放置parameters.yml的同一目录运行它，将得到以下输出：

{'learning_rate': 0.01, 'train_test_ratio': 0.7}

完整功能列表请参阅configuration_basics和advanced_configuration

如何在`OmegaConfigLoader`中使用自定义解析器¶

您可以注册自定义解析器以使用非基本类型作为参数。

考虑以下parameters.yml文件作为注册自定义解析器的Python脚本示例：

polars_float64: "${polars: Float64}"
today: "${today:}"

import polars as pl
from datetime import date

from kedro.config import OmegaConfigLoader

custom_resolvers = {"polars": lambda x: getattr(pl, x),
                    "today": lambda: date.today()}

# Register custom resolvers
config_loader = OmegaConfigLoader(conf_source=".", custom_resolvers=custom_resolvers)

print(config_loader["parameters"])

如果你从放置parameters.yml的相同目录运行它，将得到以下输出：

{'polars_float64': Float64, 'today': datetime.date(2023, 11, 23)}