Kedro 参数与凭据完整指南从 parameters.yml 定义到运行时覆盖与类型验证【免费下载链接】kedroKedro is a toolbox for production-ready data science. It uses software engineering best practices to help you create data engineering and data science pipelines that are reproducible, maintainable, and modular.项目地址: https://gitcode.com/GitHub_Trending/ke/kedro本指南围绕 Kedro 项目中的**参数Parameters与凭据Credentials**两大主题展开系统讲解它们在conf配置目录中的定义规则、如何注入管道节点、如何在代码中加载、如何通过kedro run --params在运行时覆盖以及基于 Pydantic / dataclass 的参数类型验证。读完本文你将能够独立完成参数化管道的搭建、安全地管理凭据并用类型提示为参数加上运行前校验。参数Parameters是什么Kedro 项目参数定义在conf文件夹中文件命名以parameters开头或者位于名称以parameters开头的文件夹内。默认情况下新创建的 Kedro 项目在conf/base/parameters.yml中定义参数该文件是一个键值对字典——每个键是参数名每个值是参数值。参数可以充当节点的输入并在运行管道时被使用。通过修改parameters.yml无需改动任何 Python 代码即可改变节点行为这正是 Kedro 管道灵活性与易配置性的来源。默认配置模式config pattern从源码看OmegaConfigLoader内部为参数定义了默认的加载模式kedro/config/omegaconf_config.pyparameters: [parameters*, parameters*/**, **/parameters*],这意味着以下文件都会被识别为参数配置文件名以parameters开头的文件如parameters.yml、parameters_variables.yml位于名称以parameters开头的文件夹中的文件如parameters/my_model.yml任意层级下以parameters命名的文件如conf/base/nested/parameters.yml。OmegaConfigLoader递归扫描conf_source下的目录加载.yml、.yaml、.json格式的配置文件并通过 OmegaConf 合并后以字典形式返回。在同一个子目录下若两个配置文件出现相同的顶层键会抛出ValueError在不同目录如base与local之间出现同名键时后处理的配置路径默认运行环境local优先并覆盖该键及其子键。参数如何工作注入管道节点的三种方式方式一通过params:前缀引用单个参数将一组决定模型超参数的参数集中定义在单一位置例如conf/base/parameters.ymlstep_size: 1 learning_rate: 0.01在node定义中使用params:前缀引用def increase_volume(volume, step): return volume step # in pipeline definition Node( funcincrease_volume, inputs[input_volume, params:step_size], outputsoutput_volume, )方式二按顶层键引用嵌套参数组参数支持嵌套结构使用同样的方法按顶层键整体加载step_size: 1 model_params: learning_rate: 0.01 test_data_ratio: 0.2 number_of_train_iterations: 10000def train_model(data, model): lr model[learning_rate] test_data_ratio model[test_data_ratio] iterations model[number_of_train_iterations] ... # in pipeline definition Node( functrain_model, inputs[input_data, params:model_params], outputsoutput_data, )方式三通过parameters关键字获取全部参数将parameters作为节点输入即可在节点函数内访问完整的参数集合def increase_volume(volume, params): step params[step_size] return volume step # in pipeline definition Node( funcincrease_volume, inputs[input_volume, parameters], outputsoutput_volume )无论哪种方式Kedro 都会把参数以MemoryDataset的形式加入 Data Catalog使参数像其他数据集一样对管道节点可见见 docs/configure/parameters_and_credentials.md。从架构上看这正是 Kedro 将配置与数据统一抽象的关键设计。如何在代码中加载参数参数配置可以通过配置加载器类加载默认实现是OmegaConfigLoaderfrom kedro.config import OmegaConfigLoader from kedro.framework.project import settings conf_path str(project_path / settings.CONF_SOURCE) conf_loader OmegaConfigLoader(conf_sourceconf_path) parameters conf_loader[parameters]这段代码会加载conf下所有满足参数配置模式的文件。如果没有任何配置文件匹配给定键conf_loader[key]会抛出MissingConfigException定义于 kedro/config/abstract_config.py。若该情况在业务上合法可捕获异常并回退为空字典from kedro.config import OmegaConfigLoader, MissingConfigException from kedro.framework.project import settings conf_path str(project_path / settings.CONF_SOURCE) conf_loader OmegaConfigLoader(conf_sourceconf_path) try: parameters conf_loader[parameters] except MissingConfigException: parameters {}kedro.framework.context.KedroContext类正是采用上述方式加载项目参数的。如何在运行时指定参数kedro run --paramsKedro 允许通过 CLI 为kedro run指定运行时参数使用--params选项提供逗号分隔的键值对列表。这些值会被添加到KedroContext的参数中并可供管道节点使用。每个键值对按第一个等号分割kedro run --paramsparam_key1value1,param_key22.0CLI 提供的值优先会覆盖配置文件中的参数。默认情况下运行时参数采用**破坏性合并destructive merge**策略对于该键除运行时值之外的任何配置都会被丢弃。例如base与local环境分别有以下参数# base/parameters.yml model_options: model_params: learning_date: 2023-11-01 training_date: 2023-11-01 data_ratio: 14 data_options: step_size: 123123# local/parameters.yml features: rate: 123运行以下命令kedro run --paramsmodel_options.model_params.training_date2011-11-11最终合并结果为model_options: model_params: training_date: 2011-11-11 data_options: step_size: 123123 features: rate: 123注意model_options.model_params下的learning_date与data_ratio被丢弃只保留运行时指定的training_date——这正是破坏性合并的行为。运行时参数的解析规则参数键始终按字符串处理参数值若能被转换为浮点数或整数则进行转换否则按字符串处理若键或值包含空格需用引号包裹整个选项内容kedro run --paramskey1value with spaces,key2value由于键值对在第一个等号处分割值可以包含等号但键不能。合并策略的底层实现从源码看OmegaConfigLoader在加载parameters配置时会将运行时参数直接参与合并kedro/config/omegaconf_config.pyif key parameters: # Merge with runtime parameters only for parameters return OmegaConf.to_container( OmegaConf.unsafe_merge(*aggregate_config, self.runtime_params), resolveTrue, )而base与运行环境如local配置之间的合并策略由merge_strategy控制默认destructive也可配置为softkedro/config/omegaconf_config.py。如需修改合并策略可参考 docs/configure/how_to_configure_project.md。覆盖其他配置$runtime_params解析器如需覆盖参数之外的其他配置如 catalog 条目、文件路径或预先指定某些参数必须在运行时提供可以使用OmegaConfigLoader的$runtime_params解析器自 Kedro 0.18.14 引入。它允许通过--paramsCLI 选项对多种配置类型进行动态覆盖例如切换数据源或调整运行时设置。用法详见 docs/configure/how_to_use_templating.md。如何验证参数基于类型提示的自动校验Kedro 可以根据节点函数上的类型提示对 YAML 配置中的参数进行验证。当节点为某个params:输入声明了Pydantic 模型或dataclass类型提示时Kedro 会在任何节点运行之前自动将原始字典转换为经过验证的类型化对象。该功能是**选择加入opt-in**的添加类型提示即可为该参数启用验证不加则保持原有行为。支持的类型Pydantic 模型v2完整的字段约束、嵌套模型、自定义验证器。需要安装pip install kedro[pydantic]。Dataclasses使用 Python 内置dataclasses模块进行基础类型检查无需额外依赖。原始值int、str、float等不经验证直接透传。两种方式任选其一即可不必同时使用。Pydantic 与 dataclass 的取舍Pydantic 模型提供更丰富的验证能力字段约束ge、le、gt、lt、自定义验证器、嵌套模型支持以及详细的错误信息。Dataclass 仅检查必填字段是否存在且能从字典实例化不强制值约束。需要超出基础类型检查的验证时请选择 Pydantic。验证的工作流程执行 Kedro run 或直接访问context.params时Kedro 将parameters.yml加载为字典Kedro 检查所有已注册管道节点的函数签名对任何带 Pydantic/dataclass 类型提示的params:输入记录期望类型对每个类型化参数使用model_validatePydantic或关键字参数实例化dataclass将原始字典转换为声明类型若转换失败Kedro 在任何节点运行前抛出ParameterValidationError验证后的参数会被缓存重复访问context.params不会重新验证。源码层面的实现印证参数验证由kedro/validation模块中的三个核心类协作完成TypeExtractor遍历各管道的节点通过inspect.signature与get_type_hints提取params:输入的类型要求并将Optional[X]解包为内部类型进行判断ParameterValidator调用TypeExtractor.extract_types_from_pipelines()获取要求后逐参数解析嵌套路径、实例化模型累积错误后统一抛出ParameterValidationErrorinstantiate_modelkedro/validation/model_factory.py按类型分发到 Pydantic 的model_validate或 dataclass 的关键字实例化。Fail-fast 行为验证在任何节点执行之前进行这种fail-fast特性确保配置错误在管道运行早期被发现而不是在长管道运行中途才暴露。冲突类型与已知限制跨管道类型冲突若两个管道对同一参数键声明了不同类型Kedro 记录警告并使用最后处理的管道类型运行仍会继续。例如params:training在一个管道中标注为TrainingParamsA、另一个管道标注为TrainingParamsB即触发此警告。应避免对同一参数键使用不一致的类型。跨所有管道验证Kedro 检查所有已注册管道无论实际运行哪个无关管道中的验证错误可能阻断本次运行。不支持 Pydantic v1验证框架使用model_validatePydantic v2 API。数据集输入不参与验证验证仅针对通过params:或parameters加载的参数。多类型联合Union不验证ModelA | ModelB这类多非空类型联合会被跳过Optional[Model]单模型加None会被解包并验证。可选类型提示若参数可选可使用Optional[Model]或Model | None。Kedro 会解包可选类型并按内部类型验证from __future__ import annotations from pydantic import BaseModel class TrainingParams(BaseModel): learning_rate: float epochs: int def train(data, params: TrainingParams | None): ...实战示例一基础 Pydantic 模型定义参数模型如src/package_name/parameters.pyfrom pydantic import BaseModel, Field class ModelOptions(BaseModel): test_size: float Field(ge0.1, le0.5) random_state: int Field(ge0)在节点函数上添加类型提示如src/package_name/pipelines/data_science/nodes.pyfrom sklearn.model_selection import train_test_split from package_name.parameters import ModelOptions def split_data(data, params: ModelOptions): # params 是已验证的 ModelOptions 实例而非 dict X_train, X_test train_test_split( data, test_sizeparams.test_size, random_stateparams.random_state ) return X_train, X_test管道定义无需任何改动from kedro.pipeline import node, pipeline def create_pipeline(**kwargs): return pipeline( [ node( funcsplit_data, inputs[model_input_table, params:model_options], outputs[X_train, X_test], ), ] )parameters.yml保持原样# conf/base/parameters.yml model_options: test_size: 0.2 random_state: 3运行kedro run时Kedro 会将model_options对照ModelOptions模式验证。若test_size超出0.1~0.5范围会在任何节点执行前抛出错误。实战示例二字段约束from pydantic import BaseModel, Field class TrainingParams(BaseModel): learning_rate: float Field(gt0, le1, descriptionMust be between 0 and 1) epochs: int Field(ge1, le1000) dropout: float Field(ge0, le1, default0.5)实战示例三嵌套模型from pydantic import BaseModel class OptimizerConfig(BaseModel): name: str learning_rate: float class TrainingConfig(BaseModel): epochs: int optimizer: OptimizerConfig def train(data, params: TrainingConfig): # params.optimizer 是 OptimizerConfig 实例而非 dict opt create_optimizer(params.optimizer.name, lrparams.optimizer.learning_rate) ...training: epochs: 10 optimizer: name: adam learning_rate: 0.001嵌套子模型会保留为类型化对象params.optimizer是拥有属性访问和自身验证的OptimizerConfig实例。实战示例四自定义验证器from pydantic import BaseModel, field_validator class SplitParams(BaseModel): test_size: float val_size: float field_validator(test_size, val_size) classmethod def must_be_fraction(cls, v: float) - float: if not 0 v 1: raise ValueError(must be between 0 and 1) return v实战示例五使用 dataclassfrom dataclasses import dataclass dataclass class EvalConfig: metric: str threshold: float def evaluate_model(model, params: EvalConfig): score compute_score(model, metricparams.metric) if score params.threshold: raise ValueError(fModel score {score} below threshold {params.threshold})eval: metric: accuracy threshold: 0.85dataclass 没有内置字段验证Kedro 仅从字典实例化并检查必填字段是否存在不强制ge、le等约束。多个类型化参数与混合使用一个节点可以有多个params:输入各自独立类型化def train_and_evaluate(data, training: TrainingParams, eval_config: EvalConfig): ...node( functrain_and_evaluate, inputs[data, params:training, params:eval], outputsresult, )类型化参数也可与未类型化参数共存于同一项目——无类型提示的节点仍收到普通字典# 此节点获得已验证的 Pydantic 模型 def train(data, params: TrainingParams): ... # 此节点获得普通 dict不做验证 def preprocess(data, params): lr params[learning_rate] ...运行时参数与验证的组合--params指定的运行时参数会先合并进配置再执行验证kedro run --paramstraining.learning_rate:0.1合并后的值同样接受类型提示校验因此无效的运行时覆盖会与无效的 YAML 值一样被捕获。阅读验证错误信息验证失败时抛出ParameterValidationError包含字段与原因。例如# conf/base/parameters.yml model_options: test_size: 5.0 # 超过 le0.5 约束 random_state: 3ParameterValidationError: Parameter validation failed: - Parameter model_options: Failed to instantiate ModelOptions for parameter model_options: 1 validation error for ModelOptions test_size Input should be less than or equal to 0.5 [typeless_than_equal, ...]错误信息包含参数键名与完整的 Pydantic 验证输出可快速定位是哪个字段的值非法。凭据Credentials是什么出于安全考虑Kedro强烈建议不要将任何凭据或其他机密提交到版本控制中。默认情况下conf文件夹及其子目录内文件名包含credentials的文件会被 git 忽略。凭据配置可以独立在代码中使用也可以注入DataCatalog见 docs/catalog-data/data_catalog.md。例如本地开发环境中的conf/local/credentials.yml通常存放数据库密码、云服务访问密钥等敏感信息而conf/base中只保留非敏感的共享配置。如何在代码中加载凭据凭据配置与项目其他配置一样通过配置加载器OmegaConfigLoader加载from pathlib import Path from kedro.config import OmegaConfigLoader from kedro.framework.project import settings # 将 project_root 替换为项目根目录 conf_path str(Path(project_root) / settings.CONF_SOURCE) conf_loader OmegaConfigLoader(conf_sourceconf_path) credentials conf_loader[credentials]这会加载conf/base和conf/local中文件名以credentials开头、或位于名称以credentials开头的文件夹内的配置文件。其默认配置模式同样定义于 kedro/config/omegaconf_config.pycredentials: [credentials*, credentials*/**, **/credentials*],与参数类似conf_loader[key]在无匹配文件时抛出MissingConfigException可按需处理from pathlib import Path from kedro.config import OmegaConfigLoader, MissingConfigException from kedro.framework.project import settings conf_path str(Path(project_root) / settings.CONF_SOURCE) conf_loader OmegaConfigLoader(conf_sourceconf_path) try: credentials conf_loader[credentials] except MissingConfigException: credentials {}kedro.framework.context.KedroContext类即采用上述方式加载项目凭据。如何通过环境变量加载凭据OmegaConfigLoader支持从环境变量加载凭据这需要借助 OmegaConf 的oc.env解析器。在credentials.yml中使用oc.env解析器访问环境变量dev_s3: client_kwargs: aws_access_key_id: ${oc.env:AWS_ACCESS_KEY_ID} aws_secret_access_key: ${oc.env:AWS_SECRET_ACCESS_KEY}oc.env解析器只能在credentials.yml中使用不能用于 catalog 或参数文件。这一限制是为了避免把环境变量用于凭据之外的配置。从源码看OmegaConfigLoader.__getitem__在加载credentials键时会设置read_environment_variables Truekedro/config/omegaconf_config.py随后在 _resolve_environment_variables 中临时注册oc.env解析器并解析配置完成后立即清除从而保证该能力只对凭据配置开放。如何与 AWS 凭据协同工作在数据集上使用 AWS 凭据时无需将 AWS 凭据存储在项目配置文件中。可以直接使用环境变量AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY以及可选的AWS_SESSION_TOKEN来指定凭据。Kedro 会依据 AWS 标准环境变量约定自动完成认证。总结与进一步阅读本文完整覆盖了 Kedro 参数与凭据的两大主题参数从conf/base/parameters.yml定义、三种节点注入方式、代码加载、运行时覆盖含破坏性合并规则到基于类型提示的自动验证凭据从安全原则、代码加载、环境变量方案到 AWS 场景。相关实践细节可继续阅读参数与凭据的实战教程docs/configure/how_to_use_parameters_and_credentials.md运行时参数与模板解析$runtime_params、globals、自定义 resolverdocs/configure/how_to_use_templating.md配置加载器的高级配置合并策略、配置文件模式、加载规则docs/configure/how_to_configure_project.md数据集层面的 schema 验证区别于参数验证docs/catalog-data/dataset_validation.md【免费下载链接】kedroKedro is a toolbox for production-ready data science. It uses software engineering best practices to help you create data engineering and data science pipelines that are reproducible, maintainable, and modular.项目地址: https://gitcode.com/GitHub_Trending/ke/kedro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考