配置¶

本节包含关于Kedro项目配置的详细信息，您可以使用这些配置来存储项目设置，例如参数、凭证、数据目录以及日志信息。

Kedro 使用配置加载器来加载任何项目配置文件，自 Kedro 0.19.0 版本起默认采用 OmegaConfigLoader。

注意

ConfigLoader 和 TemplatedConfigLoader 已在 Kedro 0.19.0 版本中移除。请参考配置加载器迁移指南了解如何更新代码库以使用 OmegaConfigLoader。

OmegaConfigLoader¶

OmegaConf 是一个用于处理和管理设置的Python库。它作为基于YAML的分层系统来组织配置，这些配置可以结构化以适应各种来源，允许您合并来自多个位置的设置。

从Kedro 0.18.5版本开始，您可以使用OmegaConfigLoader，它通过OmegaConf来加载数据。

OmegaConfigLoader 可以加载 YAML 和 JSON 文件。可接受的文件扩展名包括 .yml、.yaml 和 .json。默认情况下，Kedro中配置加载器使用的任何配置文件都是 .yml 文件。

`OmegaConf` 对比 Kedro 的 `OmegaConfigLoader`¶

OmegaConf 是一个Python配置管理库，可用于管理层级式配置。Kedro的OmegaConfigLoader使用OmegaConf来处理配置。这意味着当你在Kedro中使用OmegaConfigLoader时，你实际上是在间接使用OmegaConf的功能。

OmegaConfigLoader 在 Kedro 中旨在处理项目中常见的更复杂配置设置。它能自动合并配置文件（如目录配置），并考虑不同环境，从而以结构化方式便捷地管理配置。

当你需要手动加载配置时，例如在笔记本中进行探索，你有两种选择：

使用Kedro提供的OmegaConfigLoader类。
直接使用 OmegaConf 库。

Kedro的OmegaConfigLoader专为处理复杂项目环境而设计。如果您的使用场景仅涉及加载单个配置文件且较为简单，直接使用OmegaConf可能更为便捷。

from omegaconf import OmegaConf

parameters = OmegaConf.load("/path/to/parameters.yml")

当您的配置文件较为复杂且包含凭证或模板时，Kedro的OmegaConfigLoader更为适用，具体细节可参阅如何在代码中加载包含凭证的数据目录？和如何在代码中加载包含模板的数据目录？。

总之，虽然OmegaConf和Kedro的OmegaConfigLoader都提供了管理配置的方法，但您的选择取决于配置的复杂性以及您是否在Kedro框架的上下文中工作。

配置源¶

默认配置源文件夹是conf。我们建议您将所有配置文件保留在Kedro项目的默认conf文件夹中。

配置环境¶

配置环境是一种组织数据管道不同阶段配置设置的方式。例如，您可能针对开发、测试和生产环境拥有不同的设置。

默认情况下，Kedro项目包含base和local两个环境。

基础¶

在Kedro中，基础配置环境指的是作为所有其他配置环境基础的默认配置设置。

base文件夹包含跨管道使用的默认设置，除非被特定环境覆盖。

警告

请勿将私有访问凭证存放在基础配置文件夹或任何其他存储在版本控制中的配置环境文件夹内。

本地¶

local配置环境文件夹应用于存放用户特定（如IDE配置）或受保护（如安全密钥）的配置内容。

警告

不要将任何本地配置添加到版本控制中。

配置加载¶

Kedro特有的配置（例如用于I/O的DataCatalog配置）默认通过配置加载器类加载，通常是OmegaConfigLoader。当您通过命令行与Kedro交互时，例如运行kedro run，Kedro会通过此配置加载器从配置源加载所有项目配置。

加载器会递归扫描conf文件夹内的配置文件，首先在conf/base中查找（base是默认环境），然后在conf/local中查找（local是指定的覆盖环境）。

Kedro 根据以下规则合并配置信息并返回一个配置字典：

如果在相同环境路径（例如conf/base/）下的任意两个配置文件（参数除外）包含相同的顶级键，配置加载器将抛出ValueError错误，表明不允许存在重复项。
如果两个配置文件包含相同的顶级键但位于不同环境路径下（例如一个在conf/base/，另一个在conf/local/），那么最后加载的路径（conf/local/）将作为键值优先使用。OmegaConfigLoader.__getitem__不会引发任何错误，但会发出DEBUG级别的日志消息，其中包含被覆盖键的信息。
如果任意两个参数配置文件包含相同的顶级键，配置加载器会检查子键是否有重复。如果存在重复，则会抛出一个ValueError错误，表明不允许重复配置。

在使用任何配置加载器时，任何以_开头的最上层键名都会被视作隐藏（或保留）键而被忽略。这些键既不会触发键名重复错误，也不会出现在最终生成的配置字典中。但您仍可使用这类键，例如作为YAML锚点与别名，或在使用OmegaConfigLoader时为目录启用模板功能。

配置文件名称¶

配置文件将根据文件名和类型规则进行匹配。假设配置加载器需要获取目录配置，它将按照以下规则进行搜索：

以下任一条件成立：
- 文件名以 catalog 开头
- 文件位于名称以catalog为前缀的子文件夹中
并且文件扩展名是以下之一：yaml, yml, 或 json

配置模式¶

在底层实现中，Kedro配置加载器通过正则表达式模式来加载文件，这些模式指定了配置文件的命名规范。这些模式由配置加载器类中的config_patterns参数定义。

默认情况下，以下模式针对目录配置、参数、日志记录和凭证设置如下：

config_patterns = {
    "catalog": ["catalog*", "catalog*/**", "**/catalog*"],
    "parameters": ["parameters*", "parameters*/**", "**/parameters*"],
    "credentials": ["credentials*", "credentials*/**", "**/credentials*"],
    "logging": ["logging*", "logging*/**", "**/logging*"],
}

如果你想更改配置加载的方式，可以按照高级配置章节所述，自定义配置模式或绕过配置加载。

如何使用Kedro配置¶

本节提供了一套针对标准Kedro项目最常见配置需求的指导说明：

如何更改配置源文件夹的设置
如何在运行时更改配置源文件夹
如何从压缩文件中读取配置
如何从远程存储读取配置
如何在代码中访问配置
如何在代码中加载带有凭证的数据目录？
如何指定额外的配置环境
如何更改默认覆盖环境
如何仅使用一个配置环境

如何更改配置源文件夹的设置¶

要将Kedro项目配置存储到不同于conf的文件夹中，请通过设置src//settings.py中的CONF_SOURCE变量来更改配置源，如下所示：

CONF_SOURCE = "new_conf"

如何在运行时更改配置源文件夹¶

在运行时使用kedro run CLI命令配合--conf-source标志来指定配置文件的源文件夹，如下所示：

kedro run --conf-source=<path-to-new-conf-folder>

如何从压缩文件中读取配置¶

您可以通过使用OmegaConfigLoader从tar.gz或zip格式的压缩文件中读取配置。

如何引用一个tar.gz文件：

kedro run --conf-source=<path-to-compressed-file>.tar.gz

如何引用一个zip文件：

kedro run --conf-source=<path-to-compressed-file>.zip

要压缩您的配置，可以使用Kedro的kedro package命令，该命令会将包构建到项目的dist/文件夹中，并创建一个.whl文件以及包含项目配置的tar.gz文件。压缩后的配置文件会排除local文件夹内的所有文件。

或者，您可以运行以下命令来创建一个tar.gz文件：

tar --exclude=local/*.yml -czf <my_conf_name>.tar.gz --directory=<path-to-conf-dir> <conf-dir>

或者使用以下命令创建一个zip文件：

zip -x <conf-dir>/local/** -r <my_conf_name>.zip <conf-dir>

对于tar.gz和zip文件，预期具有以下结构：

<conf_dir>
├── base               <-- the files inside may be different, but this is an example of a standard Kedro structure.
│   └── parameters.yml
│   └── catalog.yml
└── local              <-- the top level local folder is required, but no files should be inside when distributed.
└── README.md          <-- optional but included with the default Kedro conf structure.

如何从远程存储读取配置¶

您可以通过云存储协议从远程存储位置读取配置。这使您能够将配置与代码分离，并安全地存储不同环境或租户的配置。

支持的协议包括：

亚马逊S3 (s3://)
Azure Blob Storage (abfs://, abfss://)
Google 云存储 (gs://, gcs://)
HTTP/HTTPS (http://, https://)
以及其他由fsspec支持的协议

要使用远程配置源，请在运行Kedro管道时指定URL：

# Amazon S3
kedro run --conf-source=s3://my-bucket/configs/

# Azure Blob Storage
kedro run --conf-source=abfs://container@account/configs/

# Google Cloud Storage
kedro run --conf-source=gs://my-bucket/configs/

远程配置的身份验证¶

远程配置源的身份验证必须通过环境变量或云平台提供的其他凭证机制进行设置。与数据目录中的数据集不同，您不能使用credentials.yml中的凭证来访问远程配置源，因为这些凭证将成为您试图访问的配置的一部分。

身份验证设置示例：

亚马逊S3:

  export AWS_ACCESS_KEY_ID=your_access_key
  export AWS_SECRET_ACCESS_KEY=your_secret_key
  kedro run --conf-source=s3://my-bucket/configs/

谷歌云存储：

gcloud auth application-default login
kedro run --conf-source=gs://my-bucket/configs/

Azure Blob 存储：

export AZURE_STORAGE_ACCOUNT=your_account_name
export AZURE_STORAGE_KEY=your_account_key
kedro run --conf-source=abfs://container@account/configs/

如需更详细的身份验证说明，请参阅您的云服务提供商文档。

远程存储应保持与本地配置相同的结构，包含适当的base和环境文件夹：

s3://my-bucket/configs/
├── base/
│   ├── catalog.yml
│   └── parameters.yml
└── prod/
    └── parameters.yml

注意

虽然Kedro支持分别从压缩文件（.tar.gz、.zip）和云存储中读取配置，但目前不支持直接从云存储（例如s3://my-bucket/configs.tar.gz）读取压缩文件。

如何在代码中访问配置¶

要直接在代码中访问配置，例如进行调试，可以按照以下方式操作：

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)

# This line shows how to access the catalog configuration. You can access other configuration in the same way.
conf_catalog = conf_loader["catalog"]

如何在代码中加载带有凭证的数据目录？¶

注意

我们不建议直接在Kedro节点中加载和操作数据目录。节点的设计初衷是作为纯函数，因此应保持对I/O的无感知性。

假设您的项目包含一个目录和凭证文件，分别位于base和local环境中，您可以使用OmegaConfigLoader加载这些配置，并将它们传递给DataCatalog对象以访问带有已解析凭证的目录条目。

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

# 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, base_env="base", default_run_env="local"
)

# These lines show how to access the catalog and credentials configurations.
conf_catalog = conf_loader["catalog"]
conf_credentials = conf_loader["credentials"]

# Fetch the catalog with resolved credentials from the configuration.
catalog = DataCatalog.from_config(catalog=conf_catalog, credentials=conf_credentials)

如何指定额外的配置环境¶

除了内置的local和base两种配置环境外，您还可以创建自己的配置环境。您的项目会加载conf/base/作为基础配置环境，但允许您用创建的其他环境（如conf/server/或conf/test/）来覆盖它。要使用额外的配置环境，请运行以下命令：

kedro run --env=<your-environment>

如果未指定env选项，将默认使用local环境来覆盖conf/base。

如果将环境变量KEDRO_ENV设置为您的环境名称，Kedro将在kedro run、kedro ipython、kedro jupyter notebook和kedro jupyter lab会话中加载该环境：

export KEDRO_ENV=<your-environment>

注意

如果您同时指定了环境变量KEDRO_ENV并为CLI命令提供了--env参数，则CLI参数具有优先权。

如何更改默认覆盖环境¶

默认情况下，local环境会覆盖base环境。如需更改文件夹，请在src//settings.py中自定义配置加载器参数设置，并将CONFIG_LOADER_ARGS键设置为新的default_run_env值。

例如，如果你想用一个名为prod的自定义环境中的配置来覆盖base，你需要在settings.py中按如下方式修改配置加载器参数：

CONFIG_LOADER_ARGS = {"default_run_env": "prod"}

如何仅使用一个配置环境¶

如果你的项目除了base环境外没有其他环境（即没有默认的local环境），请按如下方式在settings.py中自定义配置加载器参数：

CONFIG_LOADER_ARGS = {"default_run_env": "base"}

如何在不使用丰富库的情况下使用Kedro¶

如果您不希望Kedro项目中包含rich库，可以选择卸载它。但需要注意的是，2.3版本以上的cookiecutter库依赖于rich。要使Kedro在不使用rich的情况下正常工作，您需要将cookiecutter降级到2.3以下版本。

要卸载rich库，请运行：

pip uninstall rich

要将cookiecutter降级到不需要rich的版本，您可以指定2.3以下的版本。例如：

pip install cookiecutter==2.2.0

这些更改将影响Kedro日志记录、提示信息以及kedro ipython命令输出的视觉外观和格式。当使用低于2.3版本的cookiecutter时，即使安装了rich，提示信息的显示也会保持简洁样式。

配置¶