SPIDER → TEXT-TO-SQL FRANÇAIS

Du dataset brut
aux données prêtes à l’emploi.

Un parcours commun pour préparer, traduire et contrôler les questions.
Puis deux destinations distinctes : l’apprentissage et l’évaluation.

7 étapes4 splitsFichiers & contrats JSON

Lire les fichiers Les noms sont relatifs au dossier indiqué en tête de carte. {split} = train_spider, train_others, dev ou test.

Lire les clés Un point indique un objet imbriqué ; [] indique une liste. Un fichier JSONL contient un objet JSON par ligne. Les contrats décrivent les scripts actuels.

BRUT_spider-original/data/spider_data/

Partir de Spider en anglais

Les questions anglaises et leurs requêtes SQL de référence constituent le point de départ. Les bases SQLite fournissent la structure des tables.

Entrées

Dataset Spider original.

Fichiers sources · aucun fichier créé

train_spider.json · train_others.json · dev.json ·
                  test.json

Clés JSON

db_idquestionquery

Clés utilisées par le pipeline ; les autres champs du dataset brut ne sont pas conservés.

database/ · test_database/

Bases sqlite. Le test utilise test_database/. Le dossier test_database contient les memes bases que database + les 40 bases de test.

01_data/01_01_prepare/01_01_02_output/

Préparer les exemples

Vérifie la présence des bases (est-ce que chaque base de chaque requête existe), retire les doublons exacts (si même base, même requête, même SQL) au sein de chaque split et extrait les instructions CREATE TABLE (des dossiers des bases directement). La question anglaise, le db_id et la requête SQL viennent du dataset brut.

Entrées

Les 4 fichiers JSON Spider + les bases SQLite.

Le script de vérification affiche son résultat dans le terminal ; il ne crée pas de fichier.

Scripts

01_check_original_dataset.py02_prepare_english_dataset.py

Fichiers créésClés JSON

train_spider.jsonl · train_others.jsonl · dev.jsonl ·
                  test.jsonl

Clés JSON

db_idquestion_original_enschemasql

question devient question_original_en ; query devient sql. Le schéma est ajouté dans schema.

01_data/01_02_translation_batches/01_02_03_production/

Demander les traductions

Prépare et soumet les lots à Mistral avec le modèle zai-glm-5-3. Le prompt contient la question anglaise, le SQL attendu et le schéma pour guider la traduction.

Entrées

Les fichiers 01_01_prepare/01_01_02_output/{split}.jsonl.

custom_id = split:index relie chaque requête à son exemple source. La réponse demandée est une simple phrase française.

Scripts

01_create_and_send_batches.py

Fichiers créésClés JSON

{split}_requests.jsonl Clés JSON

custom_idbody.max_tokensbody.temperaturebody.messages[].rolebody.messages[].content

Le contenu du message user est une chaîne JSON avec question_original_en, sql et schema.

État des lots

batch_state.json Clés JSON

environmentmodelsubmitted_atbatches[].splitbatches[].request_filebatches[].batch_idbatches[].input_file_id

Écrit après la soumission des lots.

01_data/01_03_batch_responses/01_03_03_production/

Récupérer les réponses

Vérifie le statut des lots et télécharge les réponses brutes une fois le traitement terminé.

Entrées

Les identifiants de lots dans 01_02_translation_batches/01_02_03_production/01_02_03_02_batch_state/batch_state.json.

Scripts

01_download_batch_responses.py

Fichiers créésClés JSON

output_{NN}.jsonl Clés JSON

idcustom_idresponseerror

Un fichier par lot, numéroté à partir de 01. L’enveloppe fournisseur est conservée sans transformation.

Où se trouve la traduction ?

Champs imbriqués utiles Clés JSON

response.status_coderesponse.body.choices[].message.contentresponse.body.choices[].finish_reasonresponse.body.usage

Le texte se trouve dans message.content (texte ou blocs de contenu). D’autres métadonnées fournisseur peuvent être présentes.

01_data/01_04_merge_translations/01_04_03_production/

Rattacher le français à la source

Extrait la traduction et la rattache à l’exemple anglais grâce à son identifiant. Le SQL et le schéma source sont conservés.

Entrées

Les données de 01, les réponses de 03.

Scripts

01_merge_translations.py

Fichiers créésClés JSON

train_spider.jsonl · train_others.jsonl · dev.jsonl ·
                  test.jsonl

Clés JSON

db_idquestion_original_enschemasqlquestion

question_original_en reste la source anglaise ; question contient la traduction française.

01_data/01_05_quality_control/01_05_03_production/

Vérifier la fidélité

2 juges distincts :
Un script qui vérifie quelques erreurs potentielles,
par exemple : La source contient 56, mais la traduction contient 65 ;
La source contient 20 %, mais la traduction omet le pourcentage ;
La traduction contient une requête SQL, telle que SELECT ... FROM ....
Un modèle plus puissant qui juge une seconde fois les cas détectés par le premier, si il y a, et prend aussi 200 exemples au hasard parmi les réussites pour vérifier que le modèle de traduction a bien traduit. Il ne corrige pas, il valide ou non.

Entrées

Les erreurs notifiées par le premier juge et les traductions de l'étape 04.

2 étapes distinctes, 1 par script. Le second juge est appelé en batch.

Scripts

01_check_translations.py02_judge_translations.py

Fichiers créésClés JSON

{split}_deterministic_checks.jsonl

Enregistre le résultat des contrôles automatiques appliqués à chaque traduction. Résultat du juge 1.

Clés JSON

iddb_idquestion_original_enquestionstatusissues[]

status vaut pass ou fail. Pour une ligne source qui n’est pas un objet, seuls id, status et issues sont écrits.

sol_judgments.jsonl · sol_judgments_test.jsonl

Regroupe les verdicts du second juge pour les traductions sélectionnées. Résulat du juge 2.

Clés JSON

idselection_reasondb_idquestion_original_enschemasqlquestionverdictissues[]

verdict vaut pass, fail ou uncertain. Le fichier suffixé _test correspond au lancement séparé avec --splits test.

Fichiers intermédiaires du second juge

judge_selection{suffix}.jsonl

Réunit les traductions à faire examiner : tous les échecs locaux et un échantillon des réussites.

Clés JSON

idselection_reasondb_idquestion_original_enschemasqlquestion

judge_requests{suffix}/requests_{NN}.jsonl

Découpe cette sélection en requêtes prêtes à envoyer en batch au second juge.

Clés JSON

custom_idmethodurlbody.modelbody.reasoning.effortbody.instructionsbody.inputbody.max_output_tokens

body.input est une chaîne JSON : id, question_original_en, question, sql, schema.

judge_batch_state{suffix}.json

Mémorise les identifiants et l’état des lots envoyés afin de pouvoir les suivre puis récupérer les résultats.

Clés JSON

environmentmodelselectionsubmitted_atbatches[].batch_idbatches[].input_file_id

judge_raw_response{suffix}/output_{NN}.jsonl

Conserve les réponses brutes reçues du Batch avant l’extraction des verdicts.

Clés JSON

idcustom_idresponseerror

Le JSON du verdict (id, verdict, issues) est extrait de response.body.output[].content[].text. Les autres métadonnées API sont conservées.

{suffix} est vide par défaut, ou _test avec --splits test ; les autres sélections utilisent les noms des splits joints par des underscores.

DEUX DESTINATIONS

Apprentissage : train et dev, filtrés après contrôle.
Évaluation : test, filtré après contrôle puis préparé pour l’évaluation.

01_data/01_06_training_dataset/01_06_03_production/

Construire les conversations

Sélectionne les exemples pour l’apprentissage à partir des contrôles et des verdicts, puis normalise leur SQL.

Entrées

Reprend train_spider, train_others et dev de l'étape 04 en supprimant les exemples non-validés en étape 05.

train_spider + train_others → train.jsonl
dev → validation.jsonl
Le split test est exclu.

Normalisation SQL : compacte les espaces, tabulations et retours à la ligne en un seul espace, retire l’espace avant une virgule et préserve exactement le contenu entre guillemets, doubles guillemets ou accents graves.

Scripts

01_build_dataset.py

Fichiers créésClés JSON

train.jsonl · validation.jsonl Clés JSON

messages[].rolemessages[].content

3 messages : system (consigne), user (chaîne JSON avec question et schema), assistant (SQL normalisé).

Manifeste de construction

manifest.json Clés JSON

source_translationssource_judgmentstotal_candidatestrain_examplesvalidation_examplesrejected[].idrejected[].reasonmanual_corrections[]format

01_data/01_07_evaluation_dataset/01_07_03_production/

Préparer l’évaluation indépendante

Prépare les données pour l’évaluation indépendante finale.

Entrées

Reprend 01_04_merge_translations/01_04_03_production/test.jsonl et supprime les lignes non validées de 01_05_quality_control/01_05_03_production/.

Comme l’étape 06, source de l'étape 04 moins les exemples non-validés en étape 05.

Normalisation SQL : compacte les espaces, tabulations et retours à la ligne en un seul espace, retire l’espace avant une virgule et préserve exactement le contenu entre guillemets, doubles guillemets ou accents graves.

Scripts

01_prepare_test.py

Fichiers créésClés JSON

test_inputs.jsonl Clés JSON

iddb_idmessages[].rolemessages[].content

2 messages : system et user. Le contenu user est une chaîne JSON avec question et schema. Aucun SQL gold dans le prompt.

test_gold.jsonl Clés JSON

iddb_idsql

SQL de référence normalisé, relié à l’entrée par id.

Manifeste d’évaluation

manifest.json Clés JSON

sourcesource_checkssource_judgmentsinputsgoldtotal_candidatesexamplesrejected[].idrejected[].reasonmanual_corrections[]prompt_contains_gold_sqlgold_sql_normalized

Partir de Spider en anglais

Entrées

Fichiers sources · aucun fichier créé

Préparer les exemples

Entrées

Scripts

Fichiers créés / Clés JSON

Demander les traductions

Entrées

Scripts

Fichiers créés / Clés JSON

Récupérer les réponses

Entrées

Scripts

Fichiers créés / Clés JSON

Rattacher le français à la source

Entrées

Scripts

Fichiers créés / Clés JSON

Vérifier la fidélité

Entrées

Scripts

Fichiers créés / Clés JSON

Construire les conversations

Entrées

Scripts

Fichiers créés / Clés JSON

Préparer l’évaluation indépendante

Entrées

Scripts

Fichiers créés / Clés JSON

Fichiers créésClés JSON

Fichiers créésClés JSON

Fichiers créésClés JSON

Fichiers créésClés JSON

Fichiers créésClés JSON

Fichiers créésClés JSON

Fichiers créésClés JSON