Projet : Démo NL-to-SQL avec Swagger et Docker

Ce dépôt fournit un service FastAPI qui convertit des requêtes en langage naturel en SQL via un pipeline LLM (LlamaIndex + Azure OpenAI), exécute les requêtes sur PostgreSQL et renvoie les résultats de façon conversationnelle. Le service embarque une interface Swagger et un Dockerfile pour un déploiement simplifié.

---

Structure du projet

├── app.py           # Construction du pipeline et fonctions utilitaires
├── main.py          # Application FastAPI
├── requirements.txt # Dépendances Python
├── bdnb.sql         # Dump SQL non fourni (disponible sur le site de la BDNB)
├── Dockerfile       # Définition du conteneur
├── tests/           # Tests automatisés
├── documentation/   # Explication du fonctionnement du code
├── images/          # Images utilisées dans la documentation
├── legacy/          # Le code du test préliminaire (non utilisé ici)
├── .env_template    # Modèle de fichier d'environnement
├── .gitignore       # Fichiers à ignorer par Git
└── README.md        # Ce document

---

Prérequis

• Docker (et Docker Compose en option)
• Python 3.10+
• Service PostgreSQL
• Identifiants Azure OpenAI

---

1. Initialisation de la base PostgreSQL

Nous utilisons un dump SQL appelé bdnb.sql contenant le schéma complet et les données de démonstration. Pour le restaurer :

1. Installer PostgreSQL (Ubuntu) :

   sudo apt update
   sudo apt install postgresql postgresql-contrib

2. Démarrer le service :

   sudo systemctl start postgresql
   sudo systemctl enable postgresql

3. Restaurer le dump :

   sudo -u postgres psql -f bdnb.sql

Cette commande créera la base de données, les utilisateurs, les schémas, les tables et insérera les données telles que définies dans bdnb.sql.

---

2. Variables d’environnement

Créez un fichier .env à la racine du projet avec :

# Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://<votre-ressource>.openai.azure.com/
AZURE_OPENAI_API_KEY=<votre-clé>
OPENAI_API_VERSION=<version>
AZURE_OPENAI_ENGINE=<nom-du-deploiement>

# PostgreSQL
DB_USER=
DB_PASSWORD=
DB_HOST=
DB_PORT=
DB_NAME=bdnb
DB_SCHEMA=bdnb_2024_10_a_open_data

---

3. Exécution locale en Python

1. Créer un environnement virtuel :

   python3.10 -m venv .venv
   source .venv/bin/activate

2. Installer les dépendances :

   pip install --upgrade pip
   pip install -r requirements.txt

3. Lancer l’application :

   uvicorn main:app --reload --host 0.0.0.0 --port 8000

4. Accéder à Swagger UI : ouvrez http://localhost:8000/docs

---

4. Déploiement Docker

1. Construire l’image :

   docker build -t nl-sql-demo .

2. Lancer le conteneur :

   docker run -p 80:80 --env-file .env nl-sql-demo

3. Vérifier : rendez-vous sur http://localhost/docs

---

5. Utilisation

Envoyez une requête POST à /query avec un corps JSON :

{
  "query": "Quelle est la surface moyenne des logements de l'Hérault non chauffés au gaz et construits avant 1975 ?"
}

Exemple de réponse :

{
  "query": "Quelle est la surface moyenne des logements de l'Hérault non chauffés au gaz et construits avant 1975 ?",
  "answer": "La surface moyenne des logements de l'Hérault non chauffés au gaz et construits avant 1975 est de 80.5 m²."
}

---

6. Tests

En local

# Depuis la racine du projet, avec votre environnement activé
pytest -q

Dans Docker

Construire l’image et exécuter les tests :

docker build -t nl-sql-demo .

docker run --rm nl-sql-demo pytest -q