
L’orchestration des pipelines de données coordonne les étapes qui transforment une entrée en résultat exploitable. Elle suit les dépendances et l’état des exécutions, détermine les échecs qui peuvent faire l’objet d’une nouvelle tentative et aide l’opérateur à comprendre ce qui s’est passé. Le code de traitement reste responsable de la validation des données et de la livraison correcte du résultat.
Prenons un rapport quotidien de commandes : extraire un fichier, valider ses enregistrements, calculer une synthèse, puis la rendre disponible. Lancer ces quatre étapes à minuit ne garantit pas leur ordre. Relancer tout le traitement pourrait aussi répéter une écriture déjà réussie. La question utile est donc le comportement du système lorsqu’une étape intermédiaire échoue.
Ce guide utilise un petit workflow Prefect local pour rendre ces choix observables. Il complète le guide de pipeline ETL Python (en anglais), consacré à un import validé. Ici, le sujet est la coordination entre étapes, y compris les situations où les opérations suivantes doivent s’arrêter.
Un script planifié peut convenir à une tâche courte et indépendante, avec un code de sortie explicite, des résultats protégés et une personne qui reçoit les alertes d’échec. Un orchestrateur devient utile lorsque les dépendances, les reprises partielles, les exécutions qui se chevauchent et le suivi opérationnel rendent ce script difficile à maintenir.
| Approche | Ce qu’elle coordonne | Ce qui reste à concevoir |
|---|---|---|
| Script planifié | Le moment où une commande démarre | Dépendances, signalement des erreurs, contrôle des chevauchements et relances sûres |
| File de tâches | Le travail distribué aux processus consommateurs | Achèvement métier, comportement face aux doublons et reprise entre étapes |
| Orchestrateur de workflows | Exécutions, dépendances, état et règles de nouvelle tentative | Contrats de données, effets des opérations, livraison des résultats et exploitation du service |
Ces catégories se recoupent. Une file de tâches peut prendre en charge des workflows, et un orchestrateur peut lancer du travail dans d’autres systèmes d’exécution. Le guide Celery et Redis (en anglais) présente un déploiement avec file de tâches ; le guide d’hébergement n8n traite de l’exploitation de ce service d’automatisation. Choisissez le modèle en fonction du travail à reprendre après un incident, plutôt que d’ajouter un outil pour un simple déclenchement horaire.
Dans l’exemple des commandes, la validation doit réussir avant la transformation, et la transformation avant la publication du résultat. Le graphe est une chaîne simple : extraire, valider, transformer, publier. Un pipeline avec des branches pourrait traiter des partitions indépendantes en parallèle, puis attendre toutes les partitions nécessaires avant de produire son rapport final.
« La fonction a terminé » est un critère insuffisant si le résultat est incomplet, inaccessible ou fondé sur la mauvaise entrée. Définissez ce que le consommateur peut utiliser : une version identifiée de l’entrée, une validation réussie, un résultat complet et un mode de livraison convenu. Suivez le lot métier séparément de l’identifiant d’exécution de l’orchestrateur, car un même lot peut nécessiter plusieurs tentatives.
Les flows Prefect sont des fonctions Python décorées dont l’état d’exécution est suivi. Cet exemple appelle ses tâches directement et dans l’ordre. Une exception remonte hors du flow, donc les appels suivants ne sont pas atteints. Il ne soumet pas de tâches parallèles et ne démontre pas un graphe de dépendances distribué.
Périmètre de validation, 16 novembre 2026 : l’exemple a été vérifié sous Windows avec Python 3.12.14 et Prefect 3.9.3. Quatorze contrôles ont réussi : treize exécutent le véritable moteur de workflow et un contrôle isolé simule un échec de renommage lors de la livraison du fichier. Le laboratoire utilise une API et une base locales temporaires, des commandes fictives et des fichiers de sortie temporaires. Il ne teste ni déploiement cloud, ni planification, ni workers distants, ni exécutions concurrentes, ni reprise après crash, ni performances.
Utilisez un nouvel environnement virtuel Python 3.12 et installez la version directe du paquet indiquée ci-dessous. Cette commande ne fixe pas les versions des dépendances transitives. Pour un déploiement, conservez un verrouillage complet des dépendances qui a été testé.
python -m pip install prefect==3.9.3
Enregistrez ce code dans pipeline.py. Le contrat pédagogique accepte de 1 à 100 commandes avec des identifiants uniques non vides et des montants entiers positifs ou nuls en centimes, jusqu’à 1 000 000 de centimes par commande. L’entrée est limitée à 64 Kio. Ce sont des limites d’exemple, pas une capacité mesurée ni une bibliothèque générale de validation JSON.
"""Sequential, single-writer teaching flow; synthetic local orders only."""
import hashlib
import json
import os
from pathlib import Path
from tempfile import NamedTemporaryFile
from prefect import flow, task
from prefect.cache_policies import NO_CACHE
from prefect.runtime import task_run
def record(directory, event):
with (Path(directory) / "trace.txt").open("a", encoding="utf-8") as log:
log.write(event + "\n")
@task(retries=0, cache_policy=NO_CACHE, persist_result=False)
def extract(source, directory):
record(directory, "extract")
with open(source, "rb") as stream:
raw = stream.read(65537)
if len(raw) > 65536:
raise ValueError("input exceeds the example's 64 KiB limit")
return json.loads(raw.decode("utf-8")), hashlib.sha256(raw).hexdigest()
@task(retries=0, cache_policy=NO_CACHE, persist_result=False)
def validate(extracted, directory):
record(directory, "validate")
rows, digest = extracted
if not isinstance(rows, list) or not 1 <= len(rows) <= 100:
raise ValueError("expected 1 to 100 orders")
seen = set()
for row in rows:
if not isinstance(row, dict) or set(row) != {"id", "cents"}:
raise ValueError("expected id and cents fields")
key, cents = row["id"], row["cents"]
if not isinstance(key, str) or not key or key in seen:
raise ValueError("order IDs must be nonempty and unique")
if type(cents) is not int or not 0 <= cents <= 1000000:
raise ValueError("cents must be an integer from 0 to 1000000")
seen.add(key)
return rows, digest
@task(retries=1, retry_delay_seconds=0.1,
cache_policy=NO_CACHE, persist_result=False)
def transform(validated, directory, failures=0):
attempt = task_run.run_count
record(directory, f"transform:{attempt}")
if attempt <= failures:
raise ConnectionError("injected transient failure; no remote call")
rows, digest = validated
return {"source_sha256": digest, "transform_version": 1,
"orders": len(rows), "total_cents": sum(r["cents"] for r in rows)}
@task(retries=0, cache_policy=NO_CACHE, persist_result=False)
def publish(summary, directory):
"""Hand off a completed local file. No concurrent-writer guarantee."""
target = Path(directory) / (summary["source_sha256"] + ".json")
payload = (json.dumps(summary, sort_keys=True) + "\n").encode("utf-8")
if target.exists():
if target.read_bytes() != payload:
raise ValueError("existing output differs; inspect before rerunning")
record(directory, "publish:reused")
return {"status": "reused", "path": str(target)}
temporary = None
try:
with NamedTemporaryFile(dir=directory, suffix=".partial", delete=False) as f:
temporary = Path(f.name)
f.write(payload)
os.replace(temporary, target)
finally:
if temporary is not None:
temporary.unlink(missing_ok=True)
record(directory, "publish:created")
return {"status": "created", "path": str(target)}
@flow(name="local-orders-summary", retries=0, persist_result=False)
def orders_pipeline(source, directory, failures=0):
# Direct task calls are sequential; exceptions propagate to the flow.
extracted = extract(source, directory)
checked = validate(extracted, directory)
summary = transform(checked, directory, failures)
return publish(summary, directory)
Seule la tâche de transformation dispose d’une nouvelle tentative, soit deux tentatives au maximum. L’erreur de connexion injectée ne réalise aucune requête réseau et n’a aucun effet distant. Le délai court accélère la démonstration. Les erreurs de validation sont déterministes et ne sont pas retentées.
Enregistrez le lanceur suivant dans run_local.py, dans le même dossier. Il démarre un processus enfant avec un répertoire Prefect et un chemin de profil neufs, puis utilise le environnement de test temporaire de Prefect. Il exige une adresse API de boucle locale, désactive la télémétrie analytique et l’envoi des journaux à l’API pour ce laboratoire, puis supprime les fichiers temporaires. Des diagnostics d’échec attendus peuvent apparaître sur la sortie d’erreur.
"""Launch a disposable Prefect lab, without reusing an existing profile."""
import json
import os
from pathlib import Path
import subprocess
import sys
import socket
import time
from tempfile import TemporaryDirectory
def demo(root):
from pipeline import orders_pipeline
rows = [{"id": "a", "cents": 1200}, {"id": "b", "cents": 800}]
source = root / "orders.json"
source.write_text(json.dumps(rows), encoding="utf-8")
good = root / "good"
good.mkdir()
first = orders_pipeline(str(source), str(good), failures=1)
again = orders_pipeline(str(source), str(good))
assert first["status"] == "created" and again["status"] == "reused"
assert len(list(good.glob("*.json"))) == 1
print("Transient failure: retried, then created one output")
print("Same input again: reused the matching output")
bad = root / "bad"
bad.mkdir()
source.write_text('[{"id":"a","cents":-1}]', encoding="utf-8")
state = orders_pipeline(str(source), str(bad), return_state=True)
assert state.is_failed() and not list(bad.glob("*.json"))
assert (bad / "trace.txt").read_text().splitlines() == ["extract", "validate"]
print("Invalid input: failed validation; no output published")
def child(mode):
from prefect.testing.utilities import prefect_test_harness
from prefect.settings import PREFECT_API_URL
from urllib.parse import urlparse
with TemporaryDirectory(prefix="orchestration-data-") as temp:
with prefect_test_harness(server_startup_timeout=90):
url = PREFECT_API_URL.value()
assert urlparse(url).hostname == "127.0.0.1", url
if mode == "test":
import test_pipeline
test_pipeline.run(Path(temp), url)
else:
demo(Path(temp))
endpoint = urlparse(url)
# Allow the local listener to finish closing after server termination.
stopped = False
for _ in range(50):
with socket.socket() as probe:
probe.settimeout(0.2)
stopped = probe.connect_ex((endpoint.hostname, endpoint.port)) != 0
if stopped:
break
time.sleep(0.1)
assert stopped, "the lab API did not stop"
if mode == "test":
report_path = Path(__file__).with_name("test-results.json")
report = json.loads(report_path.read_text(encoding="utf-8"))
report["temporaryApiStopped"] = stopped
report_path.write_text(json.dumps(report, indent=2), encoding="utf-8")
if __name__ == "__main__":
mode = "test" if "--test" in sys.argv else "demo"
if "--child" in sys.argv:
child(mode)
else:
with TemporaryDirectory(prefix="orchestration-prefect-") as temp:
env = {k: v for k, v in os.environ.items()
if not k.startswith("PREFECT_")}
env.update(PREFECT_HOME=temp,
PREFECT_PROFILES_PATH=str(Path(temp) / "profiles.toml"),
PREFECT_SERVER_ANALYTICS_ENABLED="false",
PREFECT_SERVER_API_HOST="127.0.0.1",
PREFECT_API_URL="", PREFECT_API_KEY="",
PREFECT_LOGGING_LEVEL="ERROR",
PREFECT_LOGGING_TO_API_ENABLED="false",
PREFECT_SERVER_EPHEMERAL_ENABLED="true")
args = [sys.executable, "-X", "utf8", str(Path(__file__).resolve()),
"--child"] + (["--test"] if mode == "test" else [])
result = subprocess.run(args, env=env, cwd=temp,
capture_output=True, text=True, encoding="utf-8",
creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
print(result.stdout, end="")
print(result.stderr, end="", file=sys.stderr)
raise SystemExit(result.returncode)
Lancez la démonstration depuis ce dossier :
python run_local.py
Voici le résumé observé :
Transient failure: retried, then created one output
Same input again: reused the matching output
Invalid input: failed validation; no output published
La première exécution crée une synthèse après son échec transitoire simulé. Une deuxième exécution avec les mêmes octets en entrée réutilise le résultat correspondant. Des données invalides échouent ensuite à la validation dans un autre dossier de sortie, sans appeler la transformation ni la publication. Le fichier trace.txt enregistre l’ordre des étapes dans le laboratoire temporaire ; c’est un outil de test, pas un service d’audit durable.
Une nouvelle tentative ne prouve pas que la précédente n’a rien fait. Si une écriture distante réussit mais que sa réponse se perd, une relance peut répéter cette écriture. Utilisez une clé d’idempotence, une contrainte dans la destination ou un autre protocole adapté au système qui reçoit les données. Vérifiez le résultat lorsque l’issue est incertaine.
Prefect permet de définir des limites et conditions de nouvelle tentative par tâche. Appliquez-les aux erreurs plausiblement temporaires, avec un délai et une variation aléatoire adaptés au service. Ne soumettez pas indéfiniment des identifiants incorrects ou des données mal formées. Une relance au niveau du flow mérite aussi un examen distinct, puisqu’elle peut repasser par du travail déjà terminé.
L’exemple désactive le cache des tâches et la persistance de leurs résultats. Son comportement face à une entrée répétée vient du code applicatif : une empreinte SHA-256 de la source détermine le nom du fichier de sortie, et le fichier existant doit correspondre exactement aux nouveaux octets calculés. Une source modifiée, même uniquement dans ses espaces, possède une autre identité. Un résultat existant différent provoque un échec et reste conservé pour examen.
Ce protocole de fichiers est séquentiel et suppose un seul processus écrivain. Avant de livrer un nouveau résultat, le programme écrit et ferme un fichier temporaire dans le même dossier, puis le renomme. Cela ne constitue ni une transaction distribuée ni une garantie de traitement exactement une fois. Écritures concurrentes, arrêt du processus, coupure de courant, modification externe et envoi d’objets distants nécessitent une gestion et des tests distincts. L’exemple ne force pas la synchronisation des données vers un support durable.
Un workflow a besoin de limites de temps sur les opérations susceptibles de bloquer : connexion, lecture, requête en base et commande distante. Un état d’expiration dans l’orchestrateur ne prouve pas à lui seul que l’opération externe s’est arrêtée ou a été annulée. Définissez comment interrompre le travail et vérifier ses effets après une expiration. L’exemple local ne teste pas ce comportement.
Réglez la concurrence en fonction de la ressource limitée. Dix tâches indépendantes peuvent respecter le budget CPU tout en surchargeant une API source ou une base cible. Déterminez aussi si deux exécutions peuvent traiter le même lot métier. Une limite de tentatives, un nombre de workers et un verrou d’écriture répondent à des problèmes différents.
Une reprise historique, ou backfill, traite un intervalle de données antérieur. Donnez-lui des entrées explicites et une règle d’attribution des résultats, plutôt que de substituer la date du jour dans un traitement ancien. Consignez la version du code, celle du schéma, l’identité de l’entrée et l’intervalle visé. Testez une petite plage avant une reprise étendue, puis décidez si celle-ci peut remplacer les résultats existants ou doit produire une version à vérifier séparément.
Pour les alertes, surveillez les échecs mais aussi l’absence de réussite attendue. Un processus qui ne démarre jamais peut ne produire aucun journal d’erreur. Définissez le retard acceptable, le destinataire de l’alerte et les informations nécessaires pour relancer ou vérifier le traitement. Protégez les secrets séparément du code source et évitez de recopier des données sensibles dans les journaux ou les métadonnées de l’orchestrateur.
Une installation de production comporte plusieurs éléments à exploiter : le service d’orchestration et sa base, les processus qui effectuent le travail, et les destinations des résultats terminés. Leurs cycles de vie diffèrent. Supprimer un worker temporaire ne devrait pas effacer l’unique historique d’exécution ni l’unique copie du résultat métier.
Dans le modèle de déploiement Prefect avec workers, les workers interrogent des pools de travail et soumettent les exécutions à l’environnement configuré. Le laboratoire local ci-dessus ne constitue pas ce déploiement. Il abandonne volontairement son état et ses données à la fin. Avant d’héberger un service persistant, prévoyez le contrôle d’accès, l’exposition réseau, les mises à jour, la sauvegarde et la restauration de la base, ainsi que la reprise des workers.
Pour le stockage objet, envoyez un fichier terminé sous une clé choisie et donnez aux consommateurs un moyen distinct d’identifier les résultats exploitables. Vérifiez le contenu envoyé et tout signal de fin dans des situations d’échec. Un renommage local réussi ne démontre pas ces garanties distantes ; ne supposez pas non plus qu’un stockage objet se comporte comme un système de fichiers local.
Compute avec Hivenet fournit une infrastructure CPU pour les charges exploitées par le client. Le service d’orchestration et ses workers sont des logiciels que vous configurez et maintenez. Ce guide ne décrit pas une offre Prefect managée. Le stockage objet avec Hivenet fournit un stockage compatible S3 pour les fichiers de pipeline terminés ; l’exemple ne s’y est pas connecté.
Avant de choisir une capacité, réunissez un lot représentatif, la consommation mémoire maximale, la durée de traitement, la fréquence, le nombre d’exécutions simultanées et les besoins de conservation des résultats. Prévoyez séparément les ressources du service de contrôle et celles du travail qu’il lance. Utilisez ces mesures pour tester une instance CPU, puis validez la livraison réelle vers le stockage et la procédure de reprise avant de planifier des exécutions de production sans surveillance.
Choisissez une charge de travail d’IA, de calcul ou de stockage à tester sur Hivenet, ou échangez avec notre équipe sur sa mise en production.