Update README (#2)

- Update README (cbd36a5f3a8cb33770308b50f1c7ff8810406051)


Co-authored-by: Eduardo Muñoz Sala <[email protected]>

README.md

@@ -8,94 +8,104 @@ tags:
 - sft
 - generated_from_trainer
 base_model: google/gemma-7b
+datasets:
+- somosnlp/instruct-legal-refugiados-es
 ---
 
-# Model Card for Model ID
+<!--
+Esta plantilla de Model Card es una adaptación de la de Hugging Face: https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md
 
-<!-- Provide a quick summary of what the model is/does. -->
+¿Cómo utilizar esta plantilla? Copia el contenido en el README.md del repo de tu modelo en el Hub de Hugging Face y rellena cada sección.
 
+Para más información sobre cómo rellenar cada sección ver las docs: https://huggingface.co/docs/hub/model-cards
+-->
 
+# Model Card for gemma-7b-it-legal-refugiados-es
 
-## Model Details
+<!-- Suele haber un nombre corto ("pretty name") para las URLs, tablas y demás y uno largo más descriptivo. Para crear el pretty name podéis utilizar acrónimos. -->
+
+<!-- Resumen del modelo y motivación del proyecto (inc. los ODS relacionados). Esta sección es como el abstract. También se puede incluir aquí el logo del proyecto. -->
+
+<!-- Si queréis incluir una versión de la Dataset Card en español, enlazarla aquí al principio (e.g. `README_es.md`).-->
+
+Spain is the third country with the highest number of asylum applications, receiving each year approximately more than 100,000 applications, and the third with the lowest number of approvals within the EU.
+
+The main objective of this project is to facilitate the tasks of NGOs in this field and other institutions and help them to obtain answers to questions (QA) related to refugee legislation in Spanish. With its refined understanding of the nuances and complexities of this legal field.
 
+The objective of this model is to facilitate question answering (QA) tasks pertaining to Spanish refugee legislation. With its refined understanding of the nuances and intricacies of this legal domain
+
+## Model Details
 
 ### Model Description
 
-<!-- Provide a longer summary of what this model is. -->
-This model is a fine-tuned version of [google/gemma-7b](https://huggingface.co/google/gemma-7b) on the generator dataset.
+<!-- Resumen del modelo. -->
+The objective of this model is to facilitate question answering (QA) tasks pertaining to Spanish refugee legislation. With its refined understanding of the nuances and intricacies of this legal domain.
 
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
+This model is a fine-tuned version of [google/gemma-7b](https://huggingface.co/google/gemma-7b) on the dataset [AsistenciaRefugiados](https://huggingface.co/datasets/somosnlp/instruct-legal-refugiados-es).
 
-- **Developed by:** [Hacendado](https://huggingface.co/hacendado) and QA-legal-refugees team
+This is the model card of a 🤗 transformers model that has been pushed on the Hub to allow public access.
 
-- **Language(s) (NLP):** [Spanish]
-- **Finetuned from model [optional]:** [google/gemma-7b](https://huggingface.co/google/gemma-7b)
 
-## Uses
+- **Developed by:** <!-- Nombre de los miembros del equipo -->
+[Alvaro Hidalgo](https://huggingface.co/hacendado)
+[Eduardo Muñoz](https://huggingface.co/edumunozsala)
+[Teresa Martin](https://huggingface.co/narhim)
 
-### Direct Use
-The primary objective of this model is to facilitate question answering (QA) tasks pertaining to Spanish refugee legislation. With its refined understanding of the nuances and intricacies of this legal domain
+- **Funded by:** SomosNLP, HuggingFace <!-- Si contasteis con apoyo de otra entidad (e.g. vuestra universidad), añadidla aquí -->
+- **Model type:** Language model, instruction tuned
+- **Language(s):** es-ES, es-MX, es-VE <!-- Enumerar las lenguas en las que se ha entrenado el modelo, especificando el país de origen. Utilizar códigos ISO. Por ejemplo: Spanish (`es-CL`, `es-ES`, `es-MX`), Catalan (`ca`), Quechua (`qu`).  -->
+- **License:** apache-2.0 <!-- Elegid una licencia lo más permisiva posible teniendo en cuenta la licencia del model pre-entrenado y los datasets utilizados -->
+- **Fine-tuned from model:** [google/gemma-7b](https://huggingface.co/google/ <!-- Enlace al modelo pre-entrenado que habéis utilizado como base -->
+- **Dataset used:** [AsistenciaRefugiados](https://huggingface.co/datasets/somosnlp/instruct-legal-refugiados-es) <!-- Enlace al dataset utilizado para el ajuste -->
 
+### Model Sources
 
-### Out-of-Scope Use
+- **Repository:** Notebook in [This repo](https://huggingface.co/somosnlp/gemma-7b-it-legal-refugee-v0.1.1) <!-- Enlace al `main` del repo donde tengáis los scripts, i.e.: o del mismo repo del modelo en HuggingFace o a GitHub. -->
+- **Demo:** [Demo Space](https://huggingface.co/spaces/somosnlp/QA-legal-refugiados) <!-- Enlace a la demo -->
+- **Video presentation:** [Youtube Video](https://www.youtube.com/watch?v=1OqHDE5LKMI&list=PLTA-KAy8nxaASMwEUWkkTfMaDxWBxn-8J&index=3) <!-- Enlace a vuestro vídeo de presentación en YouTube (están todos subidos aquí: https://www.youtube.com/playlist?list=PLTA-KAy8nxaASMwEUWkkTfMaDxWBxn-8J) -->
 
-Misuse includes any application that promotes unethical practices, misinterprets refugee law, or uses the model for malicious purposes. The model is not designed to replace professional legal advice.
+### Model Family
 
+<!-- Si habéis entrenado varios modelos similares podéis enumerarlos aquí. -->
+This model is a fine-tuned version of [google/gemma-7b](https://huggingface.co/google/gemma-7b).
 
-## Bias, Risks, and Limitations
+## Uses
 
-The model, while powerful, has limitations inherent to AI, including biases present in the training data. It may not cover all nuances of refugee regulations or adapt to changes in law without updates.
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
 
+### Direct Use
 
-## Training Details
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
 
-### Training Data
+The primary objective of this model is to facilitate question answering (QA) tasks pertaining to Spanish refugee legislation. With its refined understanding of the nuances and intricacies of this legal domain.
 
-The dataset used was [instruct-legal-refugiados-es](https://huggingface.co/datasets/somosnlp/instruct-legal-refugiados-es)
-We wanted to make a conversation model so we investigated the base model prompt in order to make conversational base on [chatml format](https://github.com/MicrosoftDocs/azure-docs/blob/main/articles/ai-services/openai/includes/chat-markup-language.md#working-with-chat-markup-language-chatml)
+### Downstream Use
 
-we identified the special tokens so the model could understand the different roles in the conversation
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
 
-Example 
-```
-<bos><|im_start|>system
-You are Gemma.<|im_end|>
-<|im_start|>user
-Hello, how are you?<|im_end|>
-<|im_start|>assistant
-I'm doing great. How can I help you today?<|im_end|>\n<eos>
-```
+Intented to be use in question-answering with a context and text generation.
 
-so we used [Phil Schmid's gemma chatml tokenizer](https://huggingface.co/philschmid/gemma-tokenizer-chatml) to adapt our dataset for training
+### Out-of-Scope Use
 
-### Training Procedure
-The training was done using RTX 4090 from Vast.ai with PeRF and Lora
+<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
 
-#### Training hyperparameters
+Misuse includes any application that promotes unethical practices, misinterprets refugee law, or uses the model for malicious purposes. The model is not designed to replace professional legal advice.
 
-The following hyperparameters were used during training:
-- learning_rate: 5e-05
-- train_batch_size: 2
-- eval_batch_size: 8
-- seed: 66
-- gradient_accumulation_steps: 2
-- total_train_batch_size: 4
-- optimizer: Adam with betas=(0.9,0.999) and epsilon=1e-08
-- lr_scheduler_type: constant
-- lr_scheduler_warmup_ratio: 0.03
-- num_epochs: 3
+## Bias, Risks, and Limitations
 
-## Environmental Impact
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact/#compute) presented in Lacoste et al. (2019).
+<!-- This section is meant to convey both technical and sociotechnical limitations. -->
 
-- **Hardware Type**: 1 X RTX4090
-- **Hours used**: 4
-- **Cloud Provider**: Vast.ai
-- **Compute Region**: West Europe
-- **Carbon Emitted**: 350W x 4h = 1.4 kWh x 0.57 kg eq. CO2/kWh = 0.8 kg eq. CO2
+The model, while powerful, has limitations inherent to AI, including biases present in the training data. It may not cover all nuances of refugee regulations or adapt to changes in law without updates.
+
+### Recommendations
+
+<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+
+<!-- Example: Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations. -->
 
+## How to Get Started with the Model
 
-## Inference Example
+Use the code below to get started with the model.
 
 ```python
 import torch
@@ -107,8 +117,8 @@ from transformers import (
     pipeline
 )
 
-model_id = "somosnlp/gemma-7b-it-legal-refugee-v0.1.1"
-tokenizer_id = "somosnlp/gemma-7b-it-legal-refugee-v0.1.1"
+model_id = "somosnlp/gemma-7b-it-legal-refugiados-es"
+tokenizer_id = "somosnlp/gemma-7b-it-legal-refugiados-es"
 
 tokenizer = AutoTokenizer.from_pretrained(tokenizer_id)
 # Cargamos el modelo en 4 bits para agilizar la inferencia
@@ -143,4 +153,189 @@ input = "b) Hechos que motivan la incoación del procedimiento sucintamente expu
 
 response = test_inference(instruction, input, 0.3)
 print(f"Response:\n{response}")
-```
+```
+## Training Details
+
+### Training Data
+
+<!-- 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. -->
+The dataset used was [instruct-legal-refugiados-es](https://huggingface.co/datasets/somosnlp/instruct-legal-refugiados-es) but we adapted the dataset to a ChatML format, described in the next section.
+
+### Training Procedure
+
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+
+<!-- Detallar la técnica de entrenamiento utilizada y enlazar los scripts/notebooks. -->
+The training was done using RTX 4090 from Vast.ai with PeRF and Lora
+
+#### Preprocessing
+
+We wanted to make a conversation model so we investigated the base model prompt in order to make conversational base on [chatml format](https://github.com/MicrosoftDocs/azure-docs/blob/main/articles/ai-services/openai/includes/chat-markup-language.md#working-with-chat-markup-language-chatml)
+
+we identified the special tokens so the model could understand the different roles in the conversation
+
+Example 
+```
+<bos><|im_start|>system
+You are Gemma.<|im_end|>
+<|im_start|>user
+Hello, how are you?<|im_end|>
+<|im_start|>assistant
+I'm doing great. How can I help you today?<|im_end|>\n<eos>
+```
+So we used [Phil Schmid's gemma chatml tokenizer](https://huggingface.co/philschmid/gemma-tokenizer-chatml) to adapt our dataset for training
+
+#### Training Hyperparameters
+
+<!-- Enumerar los valores de los hiperparámetros de entrenamiento. -->
+The following hyperparameters were used during training:
+- learning_rate: 5e-05
+- train_batch_size: 2
+- eval_batch_size: 8
+- seed: 66
+- gradient_accumulation_steps: 2
+- total_train_batch_size: 4
+- optimizer: Adam with betas=(0.9,0.999) and epsilon=1e-08
+- lr_scheduler_type: constant
+- lr_scheduler_warmup_ratio: 0.03
+- num_epochs: 3
+
+
+- **Training regime:** <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+
+## Evaluation
+
+<!-- This section describes the evaluation protocols and provides the results. -->
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+<!-- This should link to a Dataset Card. -->
+
+[More Information Needed]
+
+#### Factors
+
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+
+[More Information Needed]
+
+#### Metrics
+
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+
+[More Information Needed]
+
+### Results
+
+<!-- Enlazar aquí los scripts/notebooks de evaluación y especificar los resultados. -->
+
+[More Information Needed]
+
+## Environmental Impact
+
+<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly. -->
+
+<!-- Rellenar la información de la lista y calcular las emisiones con la página mencionada. -->
+
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
+
+- **Hardware Type**: 1 X RTX4090
+- **Hours used**: 4
+- **Cloud Provider**: Vast.ai
+- **Compute Region**: West Europe
+- **Carbon Emitted**: 350W x 4h = 1.4 kWh x 0.57 kg eq. CO2/kWh = 0.8 kg eq. CO2
+
+## Technical Specifications
+
+<!-- Esta sección es opcional porque seguramente ya habéis mencionado estos detalles más arriba, igualmente está bien incluirlos aquí de nuevo como bullet points a modo de resumen. -->
+
+### Model Architecture and Objective
+
+ The base model is [google/gemma-7b](https://huggingface.co/google/gemma-7b) finetuned in 4-bit.
+
+### Compute Infrastructure
+
+#### Hardware
+
+<!-- Indicar el hardware utilizado, podéis agradecer aquí a quien lo patrocinó. -->
+1 x RTX4090 GPU by Vast.ai.
+
+#### Software
+
+<!-- Enumerar las librerías utilizadas (e.g. transformers, distilabel). -->
+
+Libraries: 
+- transformers
+- bitsandbytes 
+- accelerate
+- xformers 
+- trl 
+- peft
+- wandb
+
+## License
+
+<!-- Indicar bajo qué licencia se libera el modelo explicando, si no es apache 2.0, a qué se debe la licencia más restrictiva (i.e. herencia de las licencias del modelo pre-entrenado o de los datos utilizados). -->
+
+This model is under the license of the Gemma models by Google.
+Link to consent: https://www.kaggle.com/models/google/gemma/license/consent
+
+
+## Citation
+
+**BibTeX:**
+
+[More Information Needed]
+
+<!--
+
+Aquí tenéis un ejemplo de cita de un dataset que podéis adaptar:
+
+```
+@software{benallal2024cosmopedia,
+  author = {Ben Allal, Loubna and Lozhkov, Anton and Penedo, Guilherme and Wolf, Thomas and von Werra, Leandro},
+  title = {Cosmopedia},
+  month = February,
+  year = 2024,
+  url = {https://huggingface.co/datasets/HuggingFaceTB/cosmopedia}
+}
+```
+
+- benallal2024cosmopedia -> nombre + año + nombre del modelo
+- author: lista de miembros del equipo
+- title: nombre del modelo
+- year: año
+- url: enlace al modelo
+
+-->
+```
+@software{somosnlp2024asistenciarefugiados,
+  author = {Alvaro Hidalgo, Eduardo Muñoz, Teresa Martín},
+  title = {gemma-7b-it-legal-refugiados-es},
+  month = April,
+  year = 2024,
+  url = {somosnlp/gemma-7b-it-legal-refugee-v0.1.1}
+}
+```
+## More Information
+
+<!-- Indicar aquí que el marco en el que se desarrolló el proyecto, en esta sección podéis incluir agradecimientos y más información sobre los miembros del equipo. Podéis adaptar el ejemplo a vuestro gusto. -->
+
+This project was developed during the [Hackathon #Somos600M](https://somosnlp.org/hackathon) organized by SomosNLP. The model was trained using GPUs sponsored by HuggingFace.
+
+**Team:**
+
+[Alvaro Hidalgo](https://huggingface.co/hacendado)
+[Eduardo Muñoz](https://huggingface.co/edumunozsala)
+[Teresa Martin](https://huggingface.co/narhim)
+
+<!--
+- [Name 1](Link to Hugging Face profile)
+- [Name 2](Link to Hugging Face profile)
+-->
+
+## Contact [optional]
+
+<!-- Email de contacto para´posibles preguntas sobre el modelo. -->