Skip to content

README_fr.md

Latest commit

 

History

History
272 lines (213 loc) · 14.3 KB

README_fr.md

File metadata and controls

272 lines (213 loc) · 14.3 KB

MEDIATECH

License English version Collection Hugging Face

📝 Description

Ce projet traite les données publiques mises à disposition par divers administrations afin de faciliter l'accès à des données publiques vectorisées et prêtes à l'emploi pour des usages IA dans la fonction publique. Il inclut des scripts pour télécharger, traiter, embedder, insérer ces données dans une base PostgreSQL et faciliter leur exportation via divers moyens.

💡 Démarrer

𖣘 Méthode 1 : Airflow

Installation et configuration des dépendances

  1. Exécutez le script de déploiement initial :

    sudo chmod +x ./scripts/initial_deployment.sh
./scripts/initial_deployment.sh

  2. Configurez les variables d'environnement dans un fichier .env en vous basant sur l'exemple contenu dans .env.example.

    La variable AIRFLOW_UID doit être obtenue en exécutant :

    echo $(id -u)

    La variable JWT_TOKEN sera obtenue plus tard en utilisant l'API d'Airflow. Laissez-la vide pour le moment.

Initialisation des conteneurs Airflow et PostgreSQL (PgVector)

  1. Exécutez le script containers_deployment.sh :

    sudo chmod +x ./scripts/containers_deployment.sh
./scripts/containers_deployment.sh

  2. Configurez les variables d'environnement dans un fichier .env en vous basant sur l'exemple contenu dans .env.example.

  3. Exportez les variables du fichier .env :

    export $(grep -v '^#' .env | xargs)

  4. Assurez-vous de supprimer le volume PostgreSQL (PgVector) :

    docker compose down -v

    ⚠️ Cette opération supprimera tous les volumes !

  5. Utilisez l'API d'Airflow pour obtenir la variable JWT_TOKEN :

    curl -X 'POST' \
'http://localhost:8080/auth/token' \
-H 'Content-Type: application/json' \
-d "{\"username\": \"${_AIRFLOW_WWW_USER_USERNAME}\", \"password\": \"${_AIRFLOW_WWW_USER_PASSWORD}\"}"

  6. Définissez la variable JWT_TOKEN dans le fichier .env avec le access_token obtenu.

  7. Définissez la variable Airflow full_pipeline_schedule pour configurer la planification d'exécution du DAG full_pipeline de l'une des façons suivantes :

  • En exécutant la commande bash :

    docker exec -it airflow-scheduler airflow variables set full_pipeline_schedule "0 19 * * 5"

    L'expression cron 0 19 * * 5 programme le DAG tous les vendredis à 19:00. Remplacez l'expression cron par la planification souhaitée ou None.

  • Depuis l'interface Airflow : Admin > Variable > + Add Variable

Optionnel : Configurer les notifications Tchap

Pour recevoir des notifications en temps réel sur l'exécution des DAGs (démarrage, succès, échec) dans un salon Tchap, vous devez configurer une connexion Apprise dans Airflow.

Si vous ne souhaitez pas le faire, vous pouvez simplement supprimer les lignes suivantes dans chaque DAG situé dans airflow_config/dags/ :

  on_execute_callback=get_start_notifier(),
  on_success_callback=get_success_notifier(),
  on_failure_callback=get_failure_notifier(),

Sinon :

  1. Naviguez vers l'interface utilisateur d'Airflow (généralement http://localhost:8080).

  2. Allez dans Admin > Connections.

  3. Cliquez sur l'icône + pour ajouter une nouvelle connexion.

  4. Remplissez le formulaire de connexion avec les détails suivants :

    • Connection Id: TchapNotifier
    • Connection Type: Apprise
    • Extra fields > config: Construisez l'URL Apprise pour Matrix en utilisant vos variables d'environnement, en suivant ce format : 
      {"path": "matrixs://<TCHAP_ACCOUNT_TOKEN>@<TCHAP_SERVER>/<TCHAP_ROOM_TOKEN>/?format=markdown", "tag": "alerts"}
      • Remplacez <TCHAP_ACCOUNT_TOKEN> par la valeur de votre fichier .env.
      • Remplacez <TCHAP_SERVER> par le nom d'hôte du serveur de votre fichier .env (par exemple, matrix.agent.dinum.tchap.gouv.fr, sans le préfixe https://).
      • Remplacez <TCHAP_ROOM_TOKEN> par l'ID du salon de votre fichier .env.

  5. Cliquez sur Save.

Airflow utilisera désormais cette connexion pour envoyer des notifications formatées à votre salon Tchap spécifié.

Téléchargement, Traitement et Téléversement des Données

Vous êtes maintenant prêt à utiliser Airflow et à exécuter les DAGs disponibles. Chaque jeu de données a son propre DAG et le DAG FULL_PIPELINE est défini pour gérer tous les DAGs de jeux de données et leur ordre d'exécution.

</> Méthode 2 : Utiliser le CLI en local

Installation des dépendances

  1. Installez les dépendances apt requises :

    sudo apt-get update
sudo apt-get install -y $(cat config/requirements-apt-container.txt)

  2. Créez et activez un environnement virtuel :

    python3 -m venv .venv  # Créer l'environnement virtuel
source .venv/bin/activate  # Activer l'environnement virtuel

  3. Installez les dépendances python requises :

    pip install -e .

L'installation en mode développement (-e) permet d'utiliser la commande mediatech et de modifier le code sans réinstallation.

Note : Assurez-vous que l'environnement est correctement configuré avant de continuer.

Configuration de la base de données PostgreSQL (PgVector)

  1. Configurez les variables d'environnement dans un fichier .env en vous basant sur l'exemple contenu dans .env.example.

  2. Exportez les variables du fichier .env :

    export $(grep -v '^#' .env | xargs)

  3. Démarrez le conteneur PostgreSQL avec Docker :

    docker compose up -d postgres

  4. Vérifiez que le conteneur pgvector_container est en cours d'exécution :

    docker ps

Téléchargement, Traitement et Téléversement des Données

Utilisation de la commande mediatech

Après installation, la commande mediatech est disponible globalement et remplace python main.py :

Si vous rencontrez des soucis avec la commande mediatech, il reste tout de même possible d'utiliser la commande python main.py à la place.

Le fichier main.py est le point d'entrée principal du projet et propose une interface en ligne de commande (CLI) pour exécuter chaque étape du pipeline séparément. Vous pouvez l'utiliser ainsi :

mediatech <commande> [options]

ou

python main.py <commande> [options]

Exemples de commandes :

  • Voir l'aide : 
    mediatech --help
  • Créer les tables PostgreSQL: 
    mediatech create_tables --model BAAI/bge-m3
  • Télécharger tous les fichiers répertoriés dans data_config.json: 
    mediatech download_files --all
  • Télécharger les fichiers de la source service_public : 
    mediatech download_files --source service_public
  • Télécharger et traiter tous les fichiers répertoriés dans data_config.json: 
    mediatech download_and_process_files --all --model BAAI/bge-m3
  • Traiter toutes les données : 
    mediatech process_files --all --model BAAI/bge-m3
  • Diviser une table en sous-tables basées sur différents critères (cf: main.py) : 
    mediatech split_table --source legi
  • Exporter les tables PostgreSQL en fichier parquet: 
    mediatech export_tables --output data/parquet
  • Téléverser les datasets en format parquet sur le repository Hugging Face: 
    mediatech upload_dataset --input data/parquet/service_public.parquet --dataset-name service-public

Exécutez mediatech --help dans votre terminal pour voir toutes les options disponibles, ou consultez directement le code contenu dans main.py.

Utilisation alternative avec python main.py

Si vous préférez utiliser directement le script Python, vous pouvez toujours utiliser :

python main.py <commande> [options]

Exemples :

python main.py download_files
python main.py create_tables --model BAAI/bge-m3
python main.py process_files --all --model BAAI/bge-m3
Utilisation du script update.sh

Le script update.sh permet d'exécuter l'ensemble du pipeline de traitement des données : téléchargement, création des tables, vectorisation et export. Pour l'exécuter, lancez la commande suivante depuis la racine du projet :

./scripts/update.sh

Ce script va :

  • Attendre que la base PostgreSQL soit disponible,
  • Créer ou mettre à jour les tables nécessaires dans la base PostgreSQL,
  • Télécharger les fichiers publics répertoriés dans data_config.json,
  • Traiter et vectoriser les données,
  • Exporter les tables au format Parquet,
  • Téléverser les fichiers Parquet sur Hugging Face.

🗂️ Structure du projet

  • main.py : Point d'entrée principal pour exécuter le pipeline complet via un CLI.
  • pyproject.toml : Configuration du projet Python et des dépendances.
  • Dockerfile : Définit les instructions pour construire l'image Docker personnalisée pour Airflow, en installant les dépendances système, les paquets Python et en configurant l'environnement du projet.
  • docker-compose.yml : Orchestre la configuration multi-conteneurs, définit les services Airflow et la base de données PostgreSQL (PgVector).
  • .github/ : Contient les workflows GitHub Actions pour l'Intégration Continue et le Déploiement Continu (CI/CD), automatisant les tests et les processus de déploiement.
  • download_and_processing/ : Contient les scripts pour télécharger et extraire les fichiers.
  • database/ : Contient les scripts pour gérer la base de données (création de tables, insertion de données).
  • docs/ : Contient les différentes ressources documentaires et tutoriels.
    • docs/hugging_face_rag_tutorial.ipynb : Tutoriel : Comment charger les jeux de données de MediaTech depuis Hugging Face et les utiliser dans un système RAG ?
    • docs/reconstruct_vector_database.ipynb : Tutoriel : Comment reconstituer un jeu de donnée sans chunking et sans embedding à partir des fichiers parquets de MediaTech téléversés sur Hugging Face ?
    • docs/fr/ : Contient toutes les ressources documentaires et tutoriels traduits en langue française.
  • utils/ : Contient des fonctions utilitaires partagées entre les différents modules.
  • config/ : Contient les scripts de configuration du projet.
  • logs/ : Contient les fichiers journaux pour suivre l'exécution des scripts.
  • scripts/ : Contient l'ensemble des scripts shell, exécutés soit automatiquement, soit manuellement dans certains cas.
    • scripts/update.sh : Script shell pour exécuter l'ensemble du pipeline de traitement des données.
    • scripts/periodic_update.sh : Script shell pour automatiser le pipeline sur la machine virtuelle. Ce script est exécuté périodiquement par cron_config.txt.
    • scripts/backup.sh : Script shell pour sauvegarder le volume Pgvector (PostgreSQL) et certains fichiers de configuration. Ce script est exécuté périodiquement par cron_config.txt.
    • scripts/restore.sh : Script shell pour restaurer le volume Pgvector (PostgreSQL) et les fichiers de configuration si nécessaire.
    • scripts/initial_deployment.sh: Met en place un nouvel environnement serveur en installant Docker, Docker Compose et d'autres dépendances système.
    • scripts/containers_deployment.sh: Gère le cycle de vie de l'application en construisant, initialisant et déployant les conteneurs Docker tels que définis dans docker-compose.yml. Il doit être exécuté après chaque mise à jour du CLI Mediatech ou d'un autre script non partagé avec le conteneur Airflow.
    • scripts/check_running_dags.sh: Vérifie l'API d'Airflow pour voir si des pipelines de données (DAGs) sont en cours d'exécution, utilisé pour verrouiller en toute sécurité le processus de déploiement.
    • scripts/delete_old_files.sh : Script shell permettant de supprimer automatiquement les anciens fichiers de différents dossiers tels que logs/, airflow_config/logs et backups/. Il conserve les fichiers des X derniers jours et supprime les plus anciens. Ce script peut être exécuté manuellement ou programmé via cron pour garder les dossiers propres.
    • scripts/manage_checkpoint.sh : Script shell permettant de gérer les différents fichiers de points de contrôle pour le traitement des fichiers.
    • scripts/write_tchap_message.sh: Envoie un message formaté à un salon Tchap spécifié. Il prend le contenu du message en argument et utilise des variables d'environnement pour l'authentification et la destination.
  • airflow_config: Contient tous les fichiers relatifs à Apache Airflow, y compris les définitions de DAGs (dags/), la configuration (config/), les logs (logs/) et les plugins (plugins/). C'est ici que les pipelines d'orchestration de données sont définis et gérés.

⚖️ Licence

Ce projet est sous Licence MIT