Flower 应用配置指南如何用 pyproject.toml 定义依赖、组件与运行时参数【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flowerFlower 框架中每一个 Flower App 都必须依赖根目录下的pyproject.toml文件来声明自身的身份与行为。本文以官方文档 how-to-configure-pyproject-toml 为主线系统讲解pyproject.toml的完整结构——应用元数据与依赖、FABFlower App Bundle文件的包含/排除规则、ServerApp/ClientApp组件声明以及运行时配置run_config的读取与覆盖机制并结合 Flower 框架源码展示这些配置项在构建与运行阶段的实际处理逻辑帮助你在flwr run、flwr build等命令下正确打包和部署应用。一、pyproject.toml 在 Flower 中的角色使用flwr new创建一个新的 Flower App 时脚手架会同时生成一个pyproject.toml文件。它承担两类职责标准 Python 包元数据遵循uv、pip等工具通用的pyproject.toml格式Flower 直接复用这些标准字段用于配置解析与打包分发Flower 专属配置通过[tool.flwr.app]系列 section 声明应用发布者、组件入口与运行时参数。一份完整的pyproject.toml示例如下对应文档中的示例其中|stable_flwr_version|在渲染时会替换为当前稳定版本号[build-system] requires [hatchling] build-backend hatchling.build [project] name flower-app version 1.0.0 description A Flower app example license Apache-2.0 dependencies [ flwr[simulation]|stable_flwr_version|, numpy2.0.2, ] [tool.hatch.build.targets.wheel] packages [.] [tool.flwr.app] publisher your-name-or-organization fab-include [path/to/include_file.py] # Optional fab-exclude [path/to/exclude_file.py] # Optional [tool.flwr.app.components] serverapp your_module.server_app:app clientapp your_module.client_app:app [tool.flwr.app.config] num-server-rounds 3 any-name-you-like any value supported by TOML下面逐节拆解各配置项并用 framework/py/flwr/common/config.py 中的校验逻辑说明哪些字段是必填的。二、应用元数据与依赖[project] 与 [tool.flwr.app][project] name your-flower-app-name version 1.0.0 description license Apache-2.0 dependencies [ flwr[simulation]|stable_flwr_version|, numpy2.0.2, ] [tool.flwr.app] publisher your-name-or-organization fab-include [path/to/include_file.py] # Optional fab-exclude [path/to/exclude_file.py] # Optional各字段含义字段是否必填说明name是Flower 应用的名称version是应用当前版本用于打包与分发需遵循语义化版本如1.0.0description建议填写应用的简短摘要license建议填写应用的分发许可证如 Apache-2.0dependencies是运行应用所需的 Python 包列表publisher是发布该应用的个人或组织名称fab-include/fab-exclude否gitignore 风格模式控制 FAB 中包含/排除的文件详见下节添加依赖后执行pip install -e .即可安装应用所需的全部包。源码中的校验逻辑validate_fields_in_config 函数在读取pyproject.toml时会逐项检查上述字段——[project]section 缺失、name/version缺失、[tool.flwr.app]section 缺失、publisher缺失都会报错而description和license缺失仅产生警告。此外fab-include/fab-exclude的格式校验由 check_pattern_list_value 完成它们必须是字符串列表、不能是空列表若想使用内置默认规则应直接省略该键而不是写成空数组。FAB ID 的构成应用分发时的唯一标识由publisher和name组合而成。get_metadata_from_config 将fab_id生成为{publisher}/{name}fab_version取自project.version解压后的项目目录命名规则见 get_project_dirapps/{publisher}.{name}.{version}.{hash前8位}。因此修改publisher或name会直接改变应用的包坐标。三、定义 FAB 的包含/排除文件fab-include / fab-excludeFABFlower App Bundle是承载应用代码、传递到 SuperLink 和 SuperNode 的结构化包。fab-include与fab-exclude用于精细控制哪些文件进入 FAB[tool.flwr.app] publisher your-name-or-organization fab-include [src/**/*.py, conf/*.yaml] # Optional fab-exclude [src/scratch.py] # Optional两个字段均可选。省略时Flower 使用内置默认规则包含常见源文件和顶层LICENSE/LICENSE并排除虚拟环境、构建产物、__pycache__目录和测试文件。两个字段的语义并不对称这是最容易踩坑的地方fab-include收窄候选集。一旦设置Flower 从空集出发只加入匹配至少一个模式的文件随后再叠加内置约束——如果你的模式拉入了不支持的文件类型如.txt或二进制文件Flower 会报错并列出冲突文件。fab-exclude精确剔除。匹配任意一个排除模式的文件会在内置约束执行前被移除因此你可以安全地排除默认规则本来会保留的任何文件。错误处理规则文档明确强调将字段设为空列表[]是错误——应整个省略该字段以启用内置默认值你提供的每个模式必须至少匹配一个文件未解析的模式会在构建时直接报错防止拼写错误悄悄改变包内容。实际过滤流程源码印证构建逻辑位于 framework/py/flwr/cli/build.py其中 get_filtered_fab_paths 实现了文档所述的两阶段过滤Publish filter发布阶段先将文件收窄为支持的类型并应用.gitignore中的模式剔除被忽略的文件FAB filter构建 FAB 时依次应用你的fab-include、fab-exclude模式最后叠加不可覆盖的内置约束强制文件类型白名单并排除.venv/、__pycache__/等目录。具体执行顺序为先用 get_user_fab_patterns 读取并校验用户模式_raise_on_unresolved_patterns 对无法匹配任何文件的模式抛出ValueError随后用户 include 模式收窄候选集、exclude 模式剔除文件最后 _raise_on_built_in_pattern_conflicts 检查是否有文件被用户 include 拉入但被内置白名单拒绝若有则列出受影响文件并报错。此外FAB 总大小受 10 MB 上限约束build.py 中的FAB_MAX_SIZE检查超限时会提示你收窄fab-include或补充fab-exclude。一句话总结fab-include/fab-exclude只能让 FAB 在 Flower 支持范围内变得更小不能用来引入不支持的文件类型——任何此类冲突都会被清晰的错误信息拦截。示例只打包源码包和一个配置文件假设项目结构如下my-flower-app/ ├── pyproject.toml ├── README.md ├── conf/ │ └── config.yaml └── your_module/ ├── client_app.py ├── server_app.py └── scratch.py ← 你希望将此文件排除出 FAB在pyproject.toml中添加[tool.flwr.app] publisher your-name-or-organization fab-include [your_module/**/*.py, conf/*.yaml] fab-exclude [your_module/scratch.py]执行flwr run或flwr build后生成的 FAB 将包含pyproject.toml、your_module/client_app.py、your_module/server_app.py和conf/config.yaml但不含your_module/scratch.py和README.mdREADME 为.md类型虽然属于支持类型但未被任何 include 模式匹配因此不进入候选集。四、FAB 内置默认规则可包含与必排除的清单FAB 的消费方是 SuperLink 与 SuperNode它们只认识特定文件类型。若允许任意文件进入 FAB不仅会破坏联邦间的兼容性、撑大包体积还会带来安全风险——凭据、私钥、环境变量配置等敏感文件可能被意外打包并分发到联邦中每个 SuperNode。因此 Flower 在你自定义规则之上强制叠加一组不可覆盖的内置模式定义于 framework/py/flwr/common/constant.py 中的FAB_INCLUDE_PATTERNS与FAB_EXCLUDE_PATTERNS允许的文件类型FAB_INCLUDE_PATTERNS构成典型 Flower 应用的源码、配置、文档与数据描述集外文件如.txt或二进制一律不可包含**/*.py Python 源文件 **/*.toml TOML 配置文件 **/*.md Markdown 文档 **/*.yaml YAML 配置文件 **/*.yml YAML 配置文件备选扩展名 **/*.json JSON 数据文件 **/*.jsonl JSON Lines 数据文件 /LICENSE 顶层许可证文件始终排除的路径FAB_EXCLUDE_PATTERNS不应跨网络传输的产物.flwr/** Flower 内部目录 **/__pycache__/** Python 字节码缓存 pyproject.toml 会被单独重新序列化原始文件不作为原样打包 **/*_test.py 测试文件 **/test_*.py 测试文件 build/** 构建输出 eggs/** Egg 构建产物 .eggs/** lib/** lib64/** parts/** *.egg .venv/** 虚拟环境 env/** venv/** ENV/** env.bak/** venv.bak/**两条实践要点若fab-include引入的文件不匹配任何内置包含模式例如.txtFlower 会报错并列出冲突文件修复方式是从fab-include中移除相应模式同时匹配内置包含和内置排除的文件例如.venv/内的*.py会被静默丢弃这是预期行为而非 bug。五、声明应用组件[tool.flwr.app.components][tool.flwr.app.components] serverapp your_module.server_app:app clientapp your_module.client_app:app两个字段均必填serverapp指向你的ServerApp对象导入路径clientapp指向ClientApp对象格式为module:object。只有在你重命名模块或存放ServerApp/ClientApp实例的变量时才需要更新这些导入路径。从源码看该 section 缺失会被 validate_fields_in_config 直接拒绝当配置中声明的是agentapp组件agent 类应用束时serverapp/clientapp则不再是硬性要求。此外validate_config 还会对每个组件引用执行object_ref.validate确认module:object形式可解析避免运行时才发现入口路径失效。六、应用运行时配置[tool.flwr.app.config] 与 run_config[tool.flwr.app.config] num-server-rounds 3 any-name-you-like any value supported by TOML该 section 用于定义运行时可访问的配置值键值对数量不限且全部为可选值。在应用代码中通过context.run_config读取例如server_rounds context.run_config[num-server-rounds]命令行覆盖执行flwr run时可用--run-config标志传入keyvalue形式的键值对来覆盖文件中的值多个键值对以空格分隔值类型限定为 bool、int、string 或 float也可传一个.toml文件但不能与键值对混用。这一解析逻辑见 parse_config_args它先按 TOML 语法解析每个片段再通过 flatten_dict 将嵌套键压平用.连接层级最终在 get_fused_config / get_fused_config_from_fab 中与pyproject.toml里的默认值做融合——即命令行覆盖优先于文件默认值。配置值类型也受校验约束UserConfig 校验 要求值为int、float、bool、str或这些类型的嵌套 dict其他类型会抛出ValueError。七、注意SuperLink 连接配置已迁移原先在pyproject.toml中承载的 federation configSuperLink 连接配置已被重命名并迁移现在称为SuperLink connection configuration统一放在 Flower 配置文件中定义不再写于pyproject.toml。构建 FAB 时build.py 也会主动剥离tool.flwr.federations这一节确保连接信息不会随应用包分发。涉及 SuperLink 连接参数时请参考 framework/docs/source 目录下的 Flower Configuration 相关文档。小结pyproject.toml是 Flower App 的单一事实来源[project]与[tool.flwr.app]决定应用的包坐标与依赖fab-include/fab-exclude配合 constant.py 中的内置白/黑名单共同决定 FAB 内容边界[tool.flwr.app.components]声明ServerApp/ClientApp入口[tool.flwr.app.config]提供可被flwr run --run-config覆盖的运行时参数。掌握这套结构后你可以参考仓库内现成的应用模板如 examples/quickstart-pytorch 等目录下的pyproject.toml快速搭建并验证自己的 Flower 应用。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Flower 应用配置指南：如何用 pyproject.toml 定义依赖、组件与运行时参数
Flower 应用配置指南如何用 pyproject.toml 定义依赖、组件与运行时参数【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flowerFlower 框架中每一个 Flower App 都必须依赖根目录下的pyproject.toml文件来声明自身的身份与行为。本文以官方文档 how-to-configure-pyproject-toml 为主线系统讲解pyproject.toml的完整结构——应用元数据与依赖、FABFlower App Bundle文件的包含/排除规则、ServerApp/ClientApp组件声明以及运行时配置run_config的读取与覆盖机制并结合 Flower 框架源码展示这些配置项在构建与运行阶段的实际处理逻辑帮助你在flwr run、flwr build等命令下正确打包和部署应用。一、pyproject.toml 在 Flower 中的角色使用flwr new创建一个新的 Flower App 时脚手架会同时生成一个pyproject.toml文件。它承担两类职责标准 Python 包元数据遵循uv、pip等工具通用的pyproject.toml格式Flower 直接复用这些标准字段用于配置解析与打包分发Flower 专属配置通过[tool.flwr.app]系列 section 声明应用发布者、组件入口与运行时参数。一份完整的pyproject.toml示例如下对应文档中的示例其中|stable_flwr_version|在渲染时会替换为当前稳定版本号[build-system] requires [hatchling] build-backend hatchling.build [project] name flower-app version 1.0.0 description A Flower app example license Apache-2.0 dependencies [ flwr[simulation]|stable_flwr_version|, numpy2.0.2, ] [tool.hatch.build.targets.wheel] packages [.] [tool.flwr.app] publisher your-name-or-organization fab-include [path/to/include_file.py] # Optional fab-exclude [path/to/exclude_file.py] # Optional [tool.flwr.app.components] serverapp your_module.server_app:app clientapp your_module.client_app:app [tool.flwr.app.config] num-server-rounds 3 any-name-you-like any value supported by TOML下面逐节拆解各配置项并用 framework/py/flwr/common/config.py 中的校验逻辑说明哪些字段是必填的。二、应用元数据与依赖[project] 与 [tool.flwr.app][project] name your-flower-app-name version 1.0.0 description license Apache-2.0 dependencies [ flwr[simulation]|stable_flwr_version|, numpy2.0.2, ] [tool.flwr.app] publisher your-name-or-organization fab-include [path/to/include_file.py] # Optional fab-exclude [path/to/exclude_file.py] # Optional各字段含义字段是否必填说明name是Flower 应用的名称version是应用当前版本用于打包与分发需遵循语义化版本如1.0.0description建议填写应用的简短摘要license建议填写应用的分发许可证如 Apache-2.0dependencies是运行应用所需的 Python 包列表publisher是发布该应用的个人或组织名称fab-include/fab-exclude否gitignore 风格模式控制 FAB 中包含/排除的文件详见下节添加依赖后执行pip install -e .即可安装应用所需的全部包。源码中的校验逻辑validate_fields_in_config 函数在读取pyproject.toml时会逐项检查上述字段——[project]section 缺失、name/version缺失、[tool.flwr.app]section 缺失、publisher缺失都会报错而description和license缺失仅产生警告。此外fab-include/fab-exclude的格式校验由 check_pattern_list_value 完成它们必须是字符串列表、不能是空列表若想使用内置默认规则应直接省略该键而不是写成空数组。FAB ID 的构成应用分发时的唯一标识由publisher和name组合而成。get_metadata_from_config 将fab_id生成为{publisher}/{name}fab_version取自project.version解压后的项目目录命名规则见 get_project_dirapps/{publisher}.{name}.{version}.{hash前8位}。因此修改publisher或name会直接改变应用的包坐标。三、定义 FAB 的包含/排除文件fab-include / fab-excludeFABFlower App Bundle是承载应用代码、传递到 SuperLink 和 SuperNode 的结构化包。fab-include与fab-exclude用于精细控制哪些文件进入 FAB[tool.flwr.app] publisher your-name-or-organization fab-include [src/**/*.py, conf/*.yaml] # Optional fab-exclude [src/scratch.py] # Optional两个字段均可选。省略时Flower 使用内置默认规则包含常见源文件和顶层LICENSE/LICENSE并排除虚拟环境、构建产物、__pycache__目录和测试文件。两个字段的语义并不对称这是最容易踩坑的地方fab-include收窄候选集。一旦设置Flower 从空集出发只加入匹配至少一个模式的文件随后再叠加内置约束——如果你的模式拉入了不支持的文件类型如.txt或二进制文件Flower 会报错并列出冲突文件。fab-exclude精确剔除。匹配任意一个排除模式的文件会在内置约束执行前被移除因此你可以安全地排除默认规则本来会保留的任何文件。错误处理规则文档明确强调将字段设为空列表[]是错误——应整个省略该字段以启用内置默认值你提供的每个模式必须至少匹配一个文件未解析的模式会在构建时直接报错防止拼写错误悄悄改变包内容。实际过滤流程源码印证构建逻辑位于 framework/py/flwr/cli/build.py其中 get_filtered_fab_paths 实现了文档所述的两阶段过滤Publish filter发布阶段先将文件收窄为支持的类型并应用.gitignore中的模式剔除被忽略的文件FAB filter构建 FAB 时依次应用你的fab-include、fab-exclude模式最后叠加不可覆盖的内置约束强制文件类型白名单并排除.venv/、__pycache__/等目录。具体执行顺序为先用 get_user_fab_patterns 读取并校验用户模式_raise_on_unresolved_patterns 对无法匹配任何文件的模式抛出ValueError随后用户 include 模式收窄候选集、exclude 模式剔除文件最后 _raise_on_built_in_pattern_conflicts 检查是否有文件被用户 include 拉入但被内置白名单拒绝若有则列出受影响文件并报错。此外FAB 总大小受 10 MB 上限约束build.py 中的FAB_MAX_SIZE检查超限时会提示你收窄fab-include或补充fab-exclude。一句话总结fab-include/fab-exclude只能让 FAB 在 Flower 支持范围内变得更小不能用来引入不支持的文件类型——任何此类冲突都会被清晰的错误信息拦截。示例只打包源码包和一个配置文件假设项目结构如下my-flower-app/ ├── pyproject.toml ├── README.md ├── conf/ │ └── config.yaml └── your_module/ ├── client_app.py ├── server_app.py └── scratch.py ← 你希望将此文件排除出 FAB在pyproject.toml中添加[tool.flwr.app] publisher your-name-or-organization fab-include [your_module/**/*.py, conf/*.yaml] fab-exclude [your_module/scratch.py]执行flwr run或flwr build后生成的 FAB 将包含pyproject.toml、your_module/client_app.py、your_module/server_app.py和conf/config.yaml但不含your_module/scratch.py和README.mdREADME 为.md类型虽然属于支持类型但未被任何 include 模式匹配因此不进入候选集。四、FAB 内置默认规则可包含与必排除的清单FAB 的消费方是 SuperLink 与 SuperNode它们只认识特定文件类型。若允许任意文件进入 FAB不仅会破坏联邦间的兼容性、撑大包体积还会带来安全风险——凭据、私钥、环境变量配置等敏感文件可能被意外打包并分发到联邦中每个 SuperNode。因此 Flower 在你自定义规则之上强制叠加一组不可覆盖的内置模式定义于 framework/py/flwr/common/constant.py 中的FAB_INCLUDE_PATTERNS与FAB_EXCLUDE_PATTERNS允许的文件类型FAB_INCLUDE_PATTERNS构成典型 Flower 应用的源码、配置、文档与数据描述集外文件如.txt或二进制一律不可包含**/*.py Python 源文件 **/*.toml TOML 配置文件 **/*.md Markdown 文档 **/*.yaml YAML 配置文件 **/*.yml YAML 配置文件备选扩展名 **/*.json JSON 数据文件 **/*.jsonl JSON Lines 数据文件 /LICENSE 顶层许可证文件始终排除的路径FAB_EXCLUDE_PATTERNS不应跨网络传输的产物.flwr/** Flower 内部目录 **/__pycache__/** Python 字节码缓存 pyproject.toml 会被单独重新序列化原始文件不作为原样打包 **/*_test.py 测试文件 **/test_*.py 测试文件 build/** 构建输出 eggs/** Egg 构建产物 .eggs/** lib/** lib64/** parts/** *.egg .venv/** 虚拟环境 env/** venv/** ENV/** env.bak/** venv.bak/**两条实践要点若fab-include引入的文件不匹配任何内置包含模式例如.txtFlower 会报错并列出冲突文件修复方式是从fab-include中移除相应模式同时匹配内置包含和内置排除的文件例如.venv/内的*.py会被静默丢弃这是预期行为而非 bug。五、声明应用组件[tool.flwr.app.components][tool.flwr.app.components] serverapp your_module.server_app:app clientapp your_module.client_app:app两个字段均必填serverapp指向你的ServerApp对象导入路径clientapp指向ClientApp对象格式为module:object。只有在你重命名模块或存放ServerApp/ClientApp实例的变量时才需要更新这些导入路径。从源码看该 section 缺失会被 validate_fields_in_config 直接拒绝当配置中声明的是agentapp组件agent 类应用束时serverapp/clientapp则不再是硬性要求。此外validate_config 还会对每个组件引用执行object_ref.validate确认module:object形式可解析避免运行时才发现入口路径失效。六、应用运行时配置[tool.flwr.app.config] 与 run_config[tool.flwr.app.config] num-server-rounds 3 any-name-you-like any value supported by TOML该 section 用于定义运行时可访问的配置值键值对数量不限且全部为可选值。在应用代码中通过context.run_config读取例如server_rounds context.run_config[num-server-rounds]命令行覆盖执行flwr run时可用--run-config标志传入keyvalue形式的键值对来覆盖文件中的值多个键值对以空格分隔值类型限定为 bool、int、string 或 float也可传一个.toml文件但不能与键值对混用。这一解析逻辑见 parse_config_args它先按 TOML 语法解析每个片段再通过 flatten_dict 将嵌套键压平用.连接层级最终在 get_fused_config / get_fused_config_from_fab 中与pyproject.toml里的默认值做融合——即命令行覆盖优先于文件默认值。配置值类型也受校验约束UserConfig 校验 要求值为int、float、bool、str或这些类型的嵌套 dict其他类型会抛出ValueError。七、注意SuperLink 连接配置已迁移原先在pyproject.toml中承载的 federation configSuperLink 连接配置已被重命名并迁移现在称为SuperLink connection configuration统一放在 Flower 配置文件中定义不再写于pyproject.toml。构建 FAB 时build.py 也会主动剥离tool.flwr.federations这一节确保连接信息不会随应用包分发。涉及 SuperLink 连接参数时请参考 framework/docs/source 目录下的 Flower Configuration 相关文档。小结pyproject.toml是 Flower App 的单一事实来源[project]与[tool.flwr.app]决定应用的包坐标与依赖fab-include/fab-exclude配合 constant.py 中的内置白/黑名单共同决定 FAB 内容边界[tool.flwr.app.components]声明ServerApp/ClientApp入口[tool.flwr.app.config]提供可被flwr run --run-config覆盖的运行时参数。掌握这套结构后你可以参考仓库内现成的应用模板如 examples/quickstart-pytorch 等目录下的pyproject.toml快速搭建并验证自己的 Flower 应用。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
