Update README.md

README.md

@@ -1,10 +1,57 @@
-**Guillaume Tell** is a French LLM based on Mistral Open-Hermes 2.5 optimized for Retrieval-Augmented Generation with source tracability and explainability.
+# Carte du modèle : Guillaume Tell
 
-## Purpose
+[Version française](#Version-française1) / [English version](#English-version)
 
-Guillaume Tell aims to enhance the verifiability of text generation based on French administrative sources. Given a question and a selection of five chunks/sources it will generate a sourced answer, with a special parameters for quotations.
+---
+# Version française
+---
+**Guillaume Tell** est un Large Language Model (LLM) français basé sur Mistral Open-Hermes 2.5 optimisé pour le RAG (Retrieval Augmented Generation) avec traçabilité des sources et explicabilité.
 
-For instance:
+---
+## Sommaire
+1. [Détails du modèle](#Détails-du-modèle)
+2. [Utilisation](#Utilisation)
+    - [Contexte de création](#Contexte-de-création)
+    - [Finalités et limites du modèle](#Finalités-et-limites-du-modèle)
+    - [Cas d'usage et utilisateurs](#Cas-d’usage-et-utilisateurs)
+    - [Exemple](#Exemple)
+3. [Prompt](#Prompt)
+4. [Informations sur le finetuning](#Informations-sur-le-finetuning)
+5. [Utilisation d'Albert pour des tâches de RAG](#Utilisation-d’Albert-pour-des-tâches-de-RAG)
+5. [Glossaire](#Glossaire)
+---
+
+## Détails du modèle
+
+### Description du modèle
+
+<!-- Provide a longer summary of what this model is. -->
+
+Le modèle "Guillaume Tell" vise à améliorer la vérifiabilité de la génération de textes basés sur des sources administratives françaises. À partir d'une question et d'une sélection de cinq sources, il génère une réponse sourcée, avec des paramètres spéciaux pour les citations.
+
+
+- **Développé par :** Etalab (Service du Datalab) - Direction Interministérielle du Numérique 
+- **Version:** Guillaume-Tell-base
+- **Type de modèle :** Transformers, Text-Generation
+- **Licence :** [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
+- **Entraîné depuis le modèle :** OpenHermes-2.5-Mistral-7B
+
+---
+## Utilisation
+### Contexte de création
+Guillaume Tell a été developpé pour **ALBERT**, l’outil d’IA Générative interministérielle de l’État, et plus particulièrement dans le cadre de [l'expérimentation d'un modèle d'assistance aux conseillers numériques](https://www.france-services.gouv.fr/actualites/experimentation-dun-modele-dassistance-france-services-IA) [France services](#Glossaire) basé sur l’intelligence artificielle. Guillaume Tell vise à répondre aux besoins spécifiques des conseillers face à un LLM, en l'occurence la vérification des réponses générées par Albert pour s'assurer de leur justesse avant de les transmettre à des usagers accueillis en maison France services. 
+
+### Finalités et limites du modèle
+Guillaume Tell est un modèle de langage, avec des capacités conversationnelles et de recherche d'information sourcée. Il peut être utilisé pour formuler une réponse à des questions relatives à l'administration française (eg. démarches administratives) en allant récupérer des informations pertinentes dans sa base de connaissances (RAG) et en synthétisant une réponse à partir de celles-ci. 
+
+Guillaume Tell fournit des réponses de premier niveau et n'est pas en capacité de donner des réponses administratives complexes. Il n'est pas en capacité de répondre à des questions sortant du champ administratif français. Il formule des réponses seulement en français. 
+
+### Cas d'usage et utilisateurs
+Son usage est prévu par les agents publics des administrations françaises afin de faciliter la recherche d'information administrative. Il est déconseillé de mettre Guillaume Tell directement entre les mains de personnes qui n'ont pas été formées spécifiquement à son usage et qui manquent d'expertise sur les démarches administratives, comme par exemple les usagers des services publics. En effet, comme  tout LLM, Guillaume Tell présente des risques d'erreurs ("hallucinations") ou d'oublis qu'une personne non formée ne sera pas en capacité de détecter. 
+
+### Exemple
+
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
 
 > Question: Quelles sont les étapes de la procédure de rétablissement en cas de surendettement ?
 > 
@@ -15,21 +62,246 @@ For instance:
 > * **n28e7fcf81deee0ff_0** : Surendettement : rétablissement personnel avec liquidation judiciaire. Conditions. Personnes concernées. Une procédure de rétablissement personnel avec liquidation judiciaire est engagée…
 > * **568bebd8fb112ee_0** : Peut-on être saisi pendant la procédure de surendettement ? Dès que le dossier est recevable…
 > 
-> Result:
-> La proc&eacute;dure de r&eacute;tablissement en cas de surendettement comporte plusieurs &eacute;tapes. Tout d'abord, la personne concern&eacute;e doit r&eacute;pondre &agrave; certaines conditions pour &ecirc;tre &eacute;ligible &agrave; cette proc&eacute;dure. Ensuite, la commission de surendettement ouvre la proc&eacute;dure avec l'accord du surendett&eacute;. Si le surendett&eacute; poss&egrave;de un patrimoine pouvant &ecirc;tre vendu, une liquidation judiciaire est prononc&eacute;e&lt;ref text=&quot;Lorsque le surendett&eacute; poss&egrave;de un patrimoine pouvant &ecirc;tre vendu, la proc&eacute;dure de r&eacute;tablissement consiste &agrave; effacer les dettes et est prononc&eacute;e avec liquidation judiciaire (vente des biens).&quot;&gt;[28e7fcf81deee0ff_0]&lt;/ref&gt;. Dans le cas contraire, une proc&eacute;dure sans liquidation judiciaire est engag&eacute;e&lt;ref text=&quot;Elle est prononc&eacute;e sans liquidation judiciaire (c'est-&agrave;-dire sans vente des biens) lorsque la personne surendett&eacute;e ne poss&egrave;de pas de patrimoine.&quot;&gt;[4c4511d1c0e6dc4c_0]&lt;/ref&gt;. 
-
+> Résultat :
+> La proc&eacute;dure de r&eacute;tablissement en cas de surendettement comporte plusieurs &eacute;tapes. Tout d'abord, la personne concern&eacute;e doit r&eacute;pondre &agrave; certaines conditions pour &ecirc;tre &eacute;ligible &agrave; cette proc&eacute;dure. 
+> Ensuite, la commission de surendettement ouvre la proc&eacute;dure avec l'accord du surendett&eacute;. Si le surendett&eacute; poss&egrave;de un patrimoine pouvant &ecirc;tre vendu, une liquidation judiciaire est prononc&eacute;e&lt;ref text=&quot;Lorsque le surendett&eacute; poss&egrave;de un patrimoine pouvant &ecirc;tre vendu, la proc&eacute;dure de r&eacute;tablissement consiste &agrave; effacer les dettes et est prononc&eacute;e avec liquidation judiciaire (vente des biens).&quot;&gt;[28e7fcf81deee0ff_0]&lt;/ref&gt;. 
+> Dans le cas contraire, une proc&eacute;dure sans liquidation judiciaire est engag&eacute;e&lt;ref text=&quot;Elle est prononc&eacute;e sans liquidation judiciaire (c'est-&agrave;-dire sans vente des biens) lorsque la personne surendett&eacute;e ne poss&egrave;de pas de patrimoine.&quot;&gt;[4c4511d1c0e6dc4c_0]&lt;/ref&gt;.
+>  
 > Pendant la proc&eacute;dure, la suspension de toute action juridique contre le surendett&eacute; est possible&lt;ref text=&quot;D&egrave;s le d&eacute;p&ocirc;t du dossier de surendettement. Dur&eacute;e de la suspension. La suspension, si elle est accord&eacute;e, est acquise selon les cas jusqu'&agrave; l'un des &eacute;v&eacute;nements suivants : D&eacute;cision d'irrecevabilit&eacute; du dossier Approbation du plan conventionnel de redressement D&eacute;cision de mesures impos&eacute;es Jugement pronon&ccedil;ant un r&eacute;tablissement personnel sans liquidation judiciaire Jugement d'ouverture d'une proc&eacute;dure de r&eacute;tablissement personnel avec liquidation judiciaire Elle ne peut toutefois pas d&eacute;passer 2 ans.&quot;&gt;[b8d3342e4ac89fe9_0]&lt;/ref&gt;. 
+> 
+> Enfin, la cl&ocirc;ture de la proc&eacute;dure se fait par jugement qui permet l'effacement des dettes&lt;ref text=&quot;Jugement pronon&ccedil;ant un r&eacute;tablissement personnel sans liquidation judiciaire Jugement d'ouverture d'une proc&eacute;dure de r&eacute;tablissement personnel avec liquidation judiciaire&quot;&gt;[28e7fcf81deee0ff_0]&lt;/ref&gt;.
+> 
+
+
+<!-- Provide the basic links for the model.
+### Model Sources [optional]
+
+- **Repository:** 
+- **Paper [optional]:** 
+- **Demo [optional]:** 
+-->
+
+
+---
+## Prompt
+
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+
+### Format du prompt
+
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+
+Comme Mistral, Open-Hermes 2.5, la syntaxe de Guillaume Tell est basée sur chatml. Elle nécessite un prompt spécifique, ainsi qu'une syntaxe prédéfinie pour ajouter les sources à la question.
+
+**Exemple de prompt:**
+```
+<|im_start|>system
+Tu es Albert, le chatbot des Maisons France Service qui donne des réponses sourcées.<|im_end|>
+<|im_start|>user
+Ecrit un texte référencé en réponse à cette question : Quelles sont les étapes de la procédure de rétablissement en cas de surendettement ?
+
+Les références doivent être citées de cette manière : texte rédigé<ref text=\"[passage pertinent dans la référence]\">[\"identifiant de la référence\"]</ref>Si les références ne permettent pas de répondre, qu'il n'y a pas de réponse.
+
+Les cinq références disponibles :
+
+10965c7bc7a8e185_0 :(…)
+
+4c4511d1c0e6dc4c_0 :(…)
+
+b8d3342e4ac89fe9_0 :(…)
+
+28e7fcf81deee0ff_0 :(…)
+
+e568bebd8fb112ee_0 :(…)
+```
+
+
+Guillaume-Tell est actuellement entraîné et testé sur une sélection fixe de cinq sources. Il devrait fonctionner sur un ensemble plus petit ou plus grand, mais cela n'a pas encore été expérimenté.
+
+---
+
+## Informations sur le finetuning
+
+<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+
+Guillaume Tell a été fine tuné en utilisant l'approche LORA et une quantization sur 4 bits sur : 
+- 3880 instructions RAG synthétiques basées sur les données de service-public.fr ;
+- 5000 instructions chatRAG basées sur les données de service-public.fr et d'Open Hermes.
+
+Le code de finetuning `finetuning.py` est disponible dans la section `Files and versions`.
+
+---
+## Utilisation d'Albert pour des tâches de [RAG](#Glossaire) 
+
+Il est possible d'utiliser des techniques de RAG afin d'optimiser la pertinence de la réponse du modèle. Nous pouvons ainsi obtenir des réponses basées sur les bonnes données adaptées à la question.
+C'est ce que nous faisons actuellement en production avec ALBERT.
+
+À la date de la sortie du modèle, les données pour effectuer le RAG d'ALBERT sont constituées de:
+- Fiches service-public.fr decoupées en chunks de 300 mots.
+
+---
+## Glossaire
+
+<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+
+- **France services** : réseau de structures territoriales qui combinent accueil physique et accompagnement numérique pour aider les publics reçus dans les démarches administratives de plusieurs services publics.
+- **LLM** (Large Language Model): modèle de Deep Learning capable de comprendre et de générer du langage humain en traitant de grandes quantités de données textuelles.
+- **RAG** (Retrieval Augmented Generation) : Technique améliorant les performances des IA génératives en permettant aux LLM d'utiliser des ressources de données supplémentaires sans besoin de réentraînement.
+
+
+
+---
+# English version
+
+
+---
+**Guillaume Tell** is a French LLM based on Mistral Open-Hermes 2.5 optimized for RAG (Retrieval Augmented Generation) with source traceability and explicability.
+
+---
+## Table of contents
+1. [Model details](#Model-details)
+2. [Uses](#Uses)
+    - [Creation context](#Creation-context)
+    - [Purposes and limitations of the model](#Purposes-and-limitations-of-the-model)
+    - [Use-cases-and-users](#Use-cases-and-users)
+    - [Example](#Example)
+3. [Prompt](#Prompt1)
+4. [Finetuning information](#Finetuning-information)
+5. [Using Albert for RAG tasks](#Using-Albert-for-RAG-tasks)
+5. [Glossary](#Glossary)
+---
 
+## Model details
+
+### Model Description
+
+<!-- Provide a longer summary of what this model is. -->
+
+Guillaume Tell vise à améliorer la vérifiabilité de la génération de textes basés sur des sources administratives françaises. A partir d'une question et d'une sélection de cinq sources, il génère une réponse sourcée, avec des paramètres spéciaux pour les citations.
+
+
+- **Developed by:** Etalab (Service du Datalab) - Direction Interministérielle du Numérique 
+- **Version:** Guillaume-Tell-base
+- **Model type:** Transformers, Text-Generation
+- **License:** [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
+- **Finetuned from model :** OpenHermes-2.5-Mistral-7B
+
+---
+## Uses
+### Creation context
+Guillaume Tell has been developed for **ALBERT**, the French government's interministerial Generative AI tool, and more specifically as part of the [experimentation of a France services advisor assistance model](https://www.france-services.gouv.fr/actualites/experimentation-dun-modele-dassistance-france-services-IA) based on artificial intelligence. Guillaume Tell is designed to meet the specific needs of advisors faced with an LLM, in this case the verification of answers generated by Albert to ensure their accuracy before transmitting them to users welcomed in France services centers. 
+
+### Purposes and limitations of the model
+Guillaume Tell is a language model, with conversational and sourced information retrieval capabilities. It can be used to formulate an answer to questions relating to the French administration (eg. administrative procedures) by retrieving relevant information from its knowledge base (RAG) and synthesizing an answer from it. 
+
+Guillaume Tell provides first-level answers and is not able to give complex administrative answers. He is not able to answer questions outside the French administrative field. He provides answers in French only. 
+
+### Use cases and users
+It is intended for use by public officials of French administrations to facilitate the search for administrative information. It is not recommended to put Guillaume Tell directly into the hands of people who have not been specifically trained in its use and who lack expertise in administrative procedures, such as users of public services. Indeed, like any LLM, Guillaume Tell presents risks of hallucination or forgetfulness that an untrained person will not be able to detect. 
+
+
+### Example
+
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+
+> Question: Quelles sont les étapes de la procédure de rétablissement en cas de surendettement ?
+> 
+> Sources:
+> * **10965c7bc7a8e185_0** : Surendettement : rétablissement personnel avec liquidation judiciaire. La procédure de rétablissement consiste à effacer les dettes d'une personne surendettée…
+> * **4c4511d1c0e6dc4c_0** : Surendettement : rétablissement personnel sans liquidation judiciaire. La procédure de rétablissement personnel consiste à effacer les dettes
+> * **b8d3342e4ac89fe9_0** : Peut-on être saisi pendant la procédure de surendettement ? Dès le dépôt du dossier de surendettement. Durée de la suspension…
+> * **n28e7fcf81deee0ff_0** : Surendettement : rétablissement personnel avec liquidation judiciaire. Conditions. Personnes concernées. Une procédure de rétablissement personnel avec liquidation judiciaire est engagée…
+> * **568bebd8fb112ee_0** : Peut-on être saisi pendant la procédure de surendettement ? Dès que le dossier est recevable…
+> 
+> Result:
+> La proc&eacute;dure de r&eacute;tablissement en cas de surendettement comporte plusieurs &eacute;tapes. Tout d'abord, la personne concern&eacute;e doit r&eacute;pondre &agrave; certaines conditions pour &ecirc;tre &eacute;ligible &agrave; cette proc&eacute;dure. 
+> Ensuite, la commission de surendettement ouvre la proc&eacute;dure avec l'accord du surendett&eacute;. Si le surendett&eacute; poss&egrave;de un patrimoine pouvant &ecirc;tre vendu, une liquidation judiciaire est prononc&eacute;e&lt;ref text=&quot;Lorsque le surendett&eacute; poss&egrave;de un patrimoine pouvant &ecirc;tre vendu, la proc&eacute;dure de r&eacute;tablissement consiste &agrave; effacer les dettes et est prononc&eacute;e avec liquidation judiciaire (vente des biens).&quot;&gt;[28e7fcf81deee0ff_0]&lt;/ref&gt;. 
+> Dans le cas contraire, une proc&eacute;dure sans liquidation judiciaire est engag&eacute;e&lt;ref text=&quot;Elle est prononc&eacute;e sans liquidation judiciaire (c'est-&agrave;-dire sans vente des biens) lorsque la personne surendett&eacute;e ne poss&egrave;de pas de patrimoine.&quot;&gt;[4c4511d1c0e6dc4c_0]&lt;/ref&gt;.
+>  
+> Pendant la proc&eacute;dure, la suspension de toute action juridique contre le surendett&eacute; est possible&lt;ref text=&quot;D&egrave;s le d&eacute;p&ocirc;t du dossier de surendettement. Dur&eacute;e de la suspension. La suspension, si elle est accord&eacute;e, est acquise selon les cas jusqu'&agrave; l'un des &eacute;v&eacute;nements suivants : D&eacute;cision d'irrecevabilit&eacute; du dossier Approbation du plan conventionnel de redressement D&eacute;cision de mesures impos&eacute;es Jugement pronon&ccedil;ant un r&eacute;tablissement personnel sans liquidation judiciaire Jugement d'ouverture d'une proc&eacute;dure de r&eacute;tablissement personnel avec liquidation judiciaire Elle ne peut toutefois pas d&eacute;passer 2 ans.&quot;&gt;[b8d3342e4ac89fe9_0]&lt;/ref&gt;. 
+> 
 > Enfin, la cl&ocirc;ture de la proc&eacute;dure se fait par jugement qui permet l'effacement des dettes&lt;ref text=&quot;Jugement pronon&ccedil;ant un r&eacute;tablissement personnel sans liquidation judiciaire Jugement d'ouverture d'une proc&eacute;dure de r&eacute;tablissement personnel avec liquidation judiciaire&quot;&gt;[28e7fcf81deee0ff_0]&lt;/ref&gt;.
+> 
+
+
+<!-- Provide the basic links for the model.
+### Model Sources [optional]
+
+- **Repository:** 
+- **Paper [optional]:** 
+- **Demo [optional]:** 
+-->
+---
+## Prompt
+
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+
+### Prompt format
+
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+
+Like Mistral Open-Hermes 2.5, Guillaume Tell's syntax is based on chatml. It requires a specific prompt, as well as a predefined syntax for adding sources to the question.
+
+**Prompt example :**
+```
+<|im_start|>system
+Tu es Albert, le chatbot des Maisons France Service qui donne des réponses sourcées.<|im_end|>
+<|im_start|>user
+Ecrit un texte référencé en réponse à cette question : Quelles sont les étapes de la procédure de rétablissement en cas de surendettement ?
+
+Les références doivent être citées de cette manière : texte rédigé<ref text=\"[passage pertinent dans la référence]\">[\"identifiant de la référence\"]</ref>Si les références ne permettent pas de répondre, qu'il n'y a pas de réponse.
+
+Les cinq références disponibles :
+
+10965c7bc7a8e185_0 :(…)
+
+4c4511d1c0e6dc4c_0 :(…)
+
+b8d3342e4ac89fe9_0 :(…)
+
+28e7fcf81deee0ff_0 :(…)
+
+e568bebd8fb112ee_0 :(…)
+```
+
+
+Guillaume-Tell is currently being trained and tested on a fixed selection of five sources. It should work on a smaller or larger set, but this has not yet been tested.
+
+---
+## Finetuning information
+
+<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+
+Guillaume Tell was fine-tuned using the LORA approach and 4-bit quantization on : 
+- 3880 synthetic RAG instructions based on service-public.fr data
+- 5000 chatRAG instructions based on service-public.fr and Open Hermes data.
+
+The finetuning code `finetuning.py` is available in the `Files and versions` section.
+
+---
+## Using Albert for [RAG](#Glossary)  tasks
+
+RAG techniques can be used to optimize the relevance of the model's response. In this way, we can obtain answers based on the right data for the right question.
+This is what we are currently doing in production with ALBERT.
+
+At the time of the model's release, the data for ALBERT's RAG consisted of the following:
+- service-public.fr sheets cut into 300-word chunks
+---
+## Glossary
+
+<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+- **France services** : network of local structures that combine physical reception with digital support to help visitors with administrative procedures for several public services.
+
+- **LLM** (Large Language Model): Deep Learning model capable of understanding and generating human language by processing large amounts of textual data.
 
-Guillaume-Tell is currently trained and tested on a fixed selection of five sources. It should be working on a smaller or larger set but this has not been experimented yet.
+- **RAG** (Retrieval Augmented Generation): Technique improving the performance of generative AI by enabling LLMs to use additional data resources without the need for retraining.
+---
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
 
-## Use
+<!--
 
-Like Mistral Open-Hermes 2.5, Guillaume Tell syntax is based on chatml. It requires a special system prompt, as well as a predefined syntax to append the sources to the question.
+## Evaluation
 
-```<|im_start|>system\nTu es Albert, le chatbot des Maisons France Service qui donne des réponses sourcées.<|im_end|>\n<|im_start|>userEcrit un texte référencé en réponse à cette question : Quelles sont les étapes de la procédure de rétablissement en cas de surendettement ?\n\nLes références doivent être citées de cette manière : texte rédigé<ref text=\"[passage pertinent dans la référence]\">[\"identifiant de la référence\"]</ref>Si les références ne permettent pas de répondre, qu'il n'y a pas de réponse.\n\nLes cinq références disponibles :10965c7bc7a8e185_0 :(…)\n\n4c4511d1c0e6dc4c_0 :(…)\n\nb8d3342e4ac89fe9_0 :(…)\n\n28e7fcf81deee0ff_0 :(…)\n\ne568bebd8fb112ee_0 :(…)```
+<!-- This section describes the evaluation protocols and provides the results. -->
 
-We recommend to use the following parameters for text generation:
 
-```sampling_params = SamplingParams(temperature=.7, top_p=.95, max_tokens=2000, presence_penalty = 1.5, stop = ["``"])```