Configuration Flower

Note

La configuration Flower est une nouvelle fonctionnalité introduite dans Flower 1.26.0. Même si sa fonctionnalité évoluera au fil du temps, elle sert en tant que remplaçant direct de la section federations dans le fichier pyproject.toml des applications Flower dans les anciennes versions.

Note

À partir de Flower 1.28.0, il n’est plus recommandé de définir les paramètres de Simulation Runtime (c’est-à-dire les champs commençant par options.) dans la configuration Flower. Consultez le Simulation Runtime documentation pour savoir comment configurer les simulations.

Qu’est-ce que c’est?

La configuration Flower est un système de gestion des connexions SuperLink, stockées dans un fichier TOML (que nous appelons le fichier de configuration Flower) qui vit dans le répertoire spécifié par la variable d’environnement FLWR_HOME (qui prend par défaut la valeur $HOME/.flwr lorsqu’elle n’est pas définie). Il est conçu pour faciliter l’utilisation des commandes Flower CLI.

Pourquoi l’utiliser?

La configuration Flower permet de définir des configurations de connexion réutilisables que vous pouvez référencer par nom lors de l’exécution de commandes flwr. Par exemple, vous pouvez configurer les configurations pour les tests locaux, les serveurs d’étape et les déploiements de production, puis passer facilement entre elles.

La plupart des commandes flwr (comme flwr log, flwr list et flwr stop) peuvent utiliser la configuration Flower depuis n’importe où sur votre système. L’exception est flwr run, qui doit être exécutée à partir d’un répertoire d’application Flower pour accéder au code de l’application.

Astuce

Première mise en place : Si le fichier de configuration Flower n’existe pas dans votre système, il sera créé automatiquement la première fois que vous exécutez une commande CLI Flower.

Mise à niveau des versions anciennes : Si vous êtes en train de mettre à niveau une version précédente de Flower, la section federations dans votre fichier pyproject.toml sera automatiquement migrée vers la configuration Flower. La syntaxe reste la même, sauf pour le nom de la section et l’utilisation du mot-clé superlink au lieu de tool.flwr.federations.

Structure du fichier de configuration Flower

Comprendre les termes

Le fichier de configuration Flower utilise le terme « superlink » pour désigner les configurations de connexion SuperLink. Chaque configuration de connexion décrit comment se connecter à un serveur central Flower (composant qui coordonne l’apprentissage fédéré). Vous pouvez définir plusieurs configurations de connexion SuperLink pour différents scénarios, tels que des simulations locales ou des déploiements distants.

La structure de la configuration est similaire à la section federations ancienne dans pyproject.toml avant Flower 1.26.0, mais elle vit maintenant dans un emplacement central et utilise des noms plus clairs.

Exemple de base

[superlink]
default = "local"

[superlink.local]
address = ":local:"

[superlink.local-poc]
address = "127.0.0.1:9093"
insecure = true

Explanation

  • [superlink] définit quelle configuration de connexion utiliser par défaut

  • default = "local" signifie que la configuration superlink.local sera utilisée lorsque vous n’avez pas spécifié explicitement une connexion dans vos commandes flwr

  • [superlink.local] définit un profil local géré de SuperLink. La valeur d’adresse spéciale ":local:" indique à Flower de lancer ou de réutiliser le SuperLink local en arrière-plan avec son état par défaut sur disque. La valeur alternative ":local-in-memory:" démarre le SuperLink local géré avec une base de données en mémoire au lieu d’un disque. Le SuperLink exécutera des simulations utilisant la configuration par défaut du Simulation Runtime.

  • [superlink.local-poc] defines a configuration for connecting to a locally running SuperLink at address 127.0.0.1:9093

Les noms des configurations de connexion doivent être uniques et commencer par le préfixe superlink..

Lister vos connexions

Vous pouvez lister toutes vos configurations de connexion en utilisant la commande flwr config list. En supposant que le fichier de configuration par défaut soit affiché plus tôt, l’sortie attendu sera :

$ flwr config list

Flower Config file: /path/to/your/.flwr/config.toml
SuperLink connections:
  local (default)
  local-poc

Cela vous montre que vous avez deux configurations de connexion disponibles, avec local défini comme configuration par défaut.

Exemple de simulation locale

Les simulations locales vous permettent de tester votre application Flower sur votre propre machine en utilisant des SuperNodes virtuels au lieu de vrais environnements répartis. Cela est utile pour le développement et la mise au point avant de déployer vers des environnements réels.

Configuration de simulation de base

[superlink.local]
address = ":local:"

Cela crée un profil local géré de SuperLink en utilisant la configuration de simulation par défaut, qui implique l’exécution de 10 SuperNodes simulés à travers le Simulation Runtime. Consultez le Simulation Runtime docs pour apprendre à personnaliser le nombre de SuperNodes et les ressources (CPU/GPU) allouées à vos simulations.

Simulation avec état local en mémoire

[superlink.local-in-memory]
address = ":local-in-memory:"

Cela crée un profil local géré de SuperLink qui conserve sa base de données en mémoire au lieu d’un disque. Cela peut être utile sur des filesystems réseau où les problèmes de blocage ou de performance SQLite peuvent se produire. L’inconvénient est que l’historique et les journaux de run locaux sont perdus lorsque le SuperLink local géré est arrêté.

Quand utiliser chacun

  • Utilisez la configuration de base pour la plupart des scénarios de développement et de mise au point locales, en particulier lorsque vous souhaitez conserver un historique de vos runs et journaux sur disque.

  • Utilisez address = ":local-in-memory:" lorsque le SuperLink local géré tourne sur un filesystem où SQLite se comporte mal, tels que certains drives réseau ou stockages HPC

En savoir plus dans la guide How to Run Simulations sur les autres paramètres facultatifs que vous pouvez utiliser pour configurer votre simulation locale.

Lorsque vous utilisez un profil de simulation local avec address = ":local:" ou address = ":local-in-memory:", les commande Flower CLI qui communiquent avec SuperLink utilisent l’API Control. Flower démarre automatiquement une instance locale gérée de SuperLink lorsque nécessaire et la réutilise à travers flwr run, flwr list, flwr log, et flwr stop. Voir Exécuter Flower Localement avec un SuperLink Géré pour le flux de travail local complet, le comportement du processus d’arrière-plan et les emplacements des fichiers en temps réel.

Exemple de déploiement distant

Lorsque vous êtes prêt à déployer votre application d’apprentissage fédéré sur des nœuds réels distribués, vous configurez des connexions qui pointent vers un SuperLink distant.

Configuration d’exemple

[superlink.remote-deployment]
address = "<SUPERLINK-ADDRESS>:<PORT>"
root-certificates = "/absolute/path/to/root/cert.crt"  # Optional, for TLS
# insecure = true  # Disable TLS (not recommended for production)

Explanation

  • address (obligatoire) : L’adresse du contrôle SuperLink Flower à connecter (par exemple, my-server.example.com:9093).

  • root-certificates: Chemin vers le fichier de certificat racine pour la chiffrage TLS. Cela sécurise la communication entre votre application Flower et le contrôFlower. Si omis, Flower utilise le certificat racine par défaut. Ce champ est ignoré si insecure est défini sur true.

  • insecure: Définissez-le sur true pour désactiver la chiffrage TLS (n’utilisez que pour les tests locaux, jamais en production). Les valeurs par défaut sont utilisées si omis, ce qui signifie que TLS est activé par défaut.

TLS (Sécurité de la couche de transport) expliqué

TLS chiffre la communication entre votre machine locale et le SuperLink distant pour empêcher l’écoute et la manipulation. En production, vous devriez toujours utiliser TLS en utilisant soit :

  • Providing a root-certificates file (recommended for custom certificates)

  • Omettre à la fois root-certificates et insecure pour utiliser les certificats par défaut

Only set insecure = true for local testing environments.

Référez-vous au deployment documentation pour la configuration de TLS et les configurations avancées.

Mise à niveau depuis les versions précédentes de Flower

Si vous êtes nouveau dans Flower 1.26.0+, vous pouvez passer outre cette section.

Pour les utilisateurs qui mettent à niveau des versions avant 1.26.0 : La section federations dans votre fichier pyproject.toml sera automatiquement migrée vers la configuration Flower lors de la première exécution d’une commande flwr.

Ce qui se passe pendant la migration

  1. Le fichier de configuration Flower sera créé à $HOME/.flwr/config.toml si ce n’est pas déjà le cas.

  2. Vos définitions de fédération sont copiées et renommées (federations → superlink)

  3. La section [tool.flwr.federations] ancienne dans pyproject.toml est commentée pour votre référence

Après la migration

Vous pouvez supprimer en toute sécurité la section federations commentée de votre fichier pyproject.toml. Toutes les configurations de connexion vivent maintenant dans la configuration Flower et fonctionnent sur tous vos projets Flower.