README.md

---
language:
- es
license: cc-by-sa-4.0
tags:
- Paraguay
- Culture
- Custom Code
- Guaraní
- unsloth
datasets:
- somosnlp/dataset-cultura-guarani_corpus-it
pipeline_tag: text-generation
---

# Gua'a - Conoce la Cultura Guaraní

<p align="center">
    <img src="https://cdn-uploads.huggingface.co/production/uploads/65f4605f4c2a1312c4d0a4b2/SfnV8yd8Zfp3dtFhX6HV1.png" style="width: 25%;">
</p>

*En la mitología guarani: El padre de la sabiduria usaba un gua'a o loro para intentar comunicarse con su dios supremo Tupã. Haciendo la misma analogía creamos el modelo "gua-a" para difundir la cultura guarani a todos los hispanohablantes.*

## Tabla de Contenidos

- [Gua'a - Conoce la Cultura Paraguaya](#model-description-)
  * [Detalles del modelo 📈](#model-description-)
    + [Descripción del modelo 📘](#model-description-)
    + [Características 📘](#model-description-)
  * [Usos 🛠️](#uses-)
    + [Uso directo 🎯](#direct-use-)
  * [Como puedo empezar a utilizar el modelo 🚀](#how-to-get-started-with-the-model-)
  * [Evaluación](#eval)
  * [Sesgos, Riesgos, y Limitaciones ⚠️](#bias-risks-and-limitations-)
  * [Licencia](#environmental-impact)
  * [Impacto Ambiental](#environmental-impact)
  * [Más Información](#environmental-impact)

## Detalles del modelo 📈

### Descripción del modelo 📘

**gua-a** es un modelo de Inteligencia Artificial innovador enfocado específicamente en responder preguntas relacionadas a la cultura guaraní. 
Se basa en el finetuning del modelo *Mistral* de 7B de parámetros para la generación de respuestas. 

### Características

- **Generador LLM Mistral**: Emplea <ins>"unsloth/mistral-7b-bnb-4bit"</ins> un modelo de Unsloth, quantizado a 4-bits para generar respuestas concisa y contextualmente adecuadas basadas en las preguntas del usuario.
- **Dataset Especializado**: Creamos un dataset exclusivo, corregido y centrado en la cultura guaraní, tomando como texto base el libro <ins>"Ñande Ypykuéra" de Narciso R. Colmán</ins>, asegurando respuestas precisas y culturalmente relevantes.
- **Finetuning**: Se detallan los siguientes parametros de entrenamiento:

```python

  ### LoRA

    r = 64,
    target_modules = ["q_proj", "k_proj", "v_proj", "o_proj","gate_proj", "up_proj", "down_proj"],
    lora_alpha = 128,
    lora_dropout = 0,
    bias = "none",
    use_gradient_checkpointing = True,
    random_state = 42,
    use_rslora = False, 
    loftq_config = None

  ### Trainer
      
    per_device_train_batch_size = 2,
    gradient_accumulation_steps = 32,
    warmup_steps = 10,
    num_train_epochs = 5,
    learning_rate = 2e-4,
    fp16 = not torch.cuda.is_bf16_supported(),
    bf16 = torch.cuda.is_bf16_supported(),
    logging_steps = 1,
    optim = "adamw_8bit",
    weight_decay = 0.01,
    lr_scheduler_type = "linear",
    save_strategy="epoch",
    seed = 42,
    report_to="tensorboard"
```

## Usos 🛠️

A continuación compartimos algunos fragmentos de código sobre cómo empezar rápidamente a ejecutar el modelo. Primero asegúrate de instalar pip install -U transformers, luego copia el fragmento de la sección que sea relevante para tu caso de uso.

### Uso directo 🎯

El modelo responde directamente a las preguntas que haga, basandose en datos del libro <ins>"Ñande Ypykuéra"</ins>.

## Como puedo empezar a utilizar el modelo 🚀

### Realizar Inferencias 🎯

Obs: El modelo corre en GPUs simples como T4. ~5.7GB de GPU RAM.

#### Running the model on a single / multi GPU

```python

major_version, minor_version = torch.cuda.get_device_capability()
# Must install separately since Colab has torch 2.2.1, which breaks packages
!pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
if major_version >= 8:
    # Use this for new GPUs like Ampere, Hopper GPUs (RTX 30xx, RTX 40xx, A100, H100, L40)
    !pip install --no-deps packaging ninja einops flash-attn xformers trl peft accelerate bitsandbytes
else:
    # Use this for older GPUs (V100, Tesla T4, RTX 20xx)
    !pip install --no-deps xformers trl peft accelerate bitsandbytes
pass

from unsloth import FastLanguageModel
import torch
max_seq_length = 512 
dtype = None
load_in_4bit = True 

base_prompt = """Responde a preguntas de forma clara, amable, concisa y solamente en el lenguaje español, sobre el libro Ñande Ypykuéra.

### Pregunta:
{}

### Respuesta:
{}"""

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "somosnlp/gua-a",
    max_seq_length = max_seq_length,
    dtype = dtype,
    load_in_4bit = load_in_4bit,
)

FastLanguageModel.for_inference(model) # Enable native 2x faster inference

pregunta = "Quien es gua'a?"

inputs = tokenizer([ft_prompt.format(pregunta,"",)], return_tensors = "pt").to("cuda")

outputs = model.generate(**inputs, max_new_tokens = 128, temperature = 0.1, repetition_penalty=1.15, pad_token_id=tokenizer.eos_token_id)

tokenizer.batch_decode(outputs[0][inputs["input_ids"].shape[1]:].unsqueeze(0), skip_special_tokens=True)[0]

```

## Evaluación

El aparatado de evaluación se divide en las siguientes partes:

  - Inferencia del modelo **gua-a** sobre el conjunto de entrenamiento (*train*) y el conjunto de pruebas (*test*)
  - Evaluación de las respuestas usando el modelo *TheBloke/prometheus-13B-v1.0-GGUF* , con el prompt en español, con las siguientes rúbricas de desempeño.

```
eval_prompt_template = """###Descripción de la tarea: Se da una instrucción (puede incluir un Input en su interior), una consulta, una respuesta a evaluar, una respuesta de referencia que obtiene una puntuación de 5, y una rúbrica de puntuación que representa un criterio de evaluación.
    1. Escribir un feedback detallado que evalúe la calidad de la respuesta basándose estrictamente en la rúbrica de puntuación dada, no evaluando en general.
    2. Después de redactar el comentario, escriba una puntuación de 1, 2, 3, 4 ó 5. Debe remitirse a la rúbrica de puntuación.
    3. El formato de salida debe ser el siguiente "Feedback: (escriba una retroalimentación para los criterios) [RESULT] (1 o 2 o 3 o 4 o 5)"
    4. Por favor, no genere ninguna otra apertura, cierre y explicaciones.
    5. Evalúe únicamente los puntos en común entre la respuesta generada y la respuesta de referencia. No evalúe cosas que están presentes en la respuesta de referencia pero no en la respuesta generada.

    ###La instrucción de evaluar: Tu tarea es evaluar la respuesta generada y la respuesta de referencia para la consulta: {query}

    ###Respuesta generada a evaluar: {generated_answer}

    ###Respuesta de referencia (Puntuación 5): {reference_answer}

    ###Rúbricas de puntuación:
    Puntuación 1: Si la respuesta generada no tiene similitud con la respuesta de referencia.
    Puntuación 2: Si la respuesta generada es similar según la respuesta de referencia, pero contiene múltiples errores significativos o omisiones.
    Puntuación 3: Si la respuesta generada es similar según la respuesta de referencia, pero incluye errores menores o falta de detalles.
    Puntuación 4: Si la respuesta generada es correcta que la respuesta de referencia, pero no es tan concisa.
    Puntuación 5: Si la respuesta generada es es totalmente correcta según la respuesta de referencia.

    ###Feedback:"""
```

Se obtuvieron los siguientes puntajes:

  - Suma de scores para el modelo 'gua-a-7b-bnb-4bit-ft-epoch-5' en train: **37.89 %**
  - Suma de scores para el modelo 'gua-a-7b-bnb-4bit-ft-epoch-5' en test: **17.76 %**

Si bien estos valores pueden representar sesgos del modelo de evaluación o del modelo propuesto, es un punto de partida para mejorar el modelo **gua-a** y generar nuevos modelos enfocados en la cultura guaraní. 

## Sesgos, Riesgos, y Limitaciones ⚠️

El modelo **gua-a** es un modelo muy experimental, con poco tiempo de desarrollo. Las respuestas pueden ser imprecisas y de baja calidad. 
El dataset utilizado por el modelo solo refleja parte de la cultura guaraní, limitandose a la visión del autor del libro.

## Licencia

- gua-a se ditribuye bajo la licencia **cc-by-sa-4.0**.

## Impacto Ambiental

                        
CO2 Emission Related to Experiments

Experiments were conducted using a private infrastructure, which has a carbon efficiency of 0.432 kg CO_2eq/kWh. 

A cumulative of 8 hours of computation was performed on hardware of type RTX 3080 TI (TDP of 350W).

Total emissions are estimated to be 1.21 kg CO_2eq of which 0 percents were directly offset.

Estimations were conducted using the https://mlco2.github.io/impact - MachineLearning Impact calculator

  @article{lacoste2019quantifying,
    title={Quantifying the Carbon Emissions of Machine Learning},
    author={Lacoste, Alexandre and Luccioni, Alexandra and Schmidt, Victor and Dandres, Thomas},
    journal={arXiv preprint arXiv:1910.09700},
    year={2019}
  }              
            
## Más Información

Este proyecto fue desarrollado durante el Hackathon #Somos600M organizado por SomosNLP. El conjunto de datos se creó utilizando distilabel de Argilla y endpoints patrocinados por HuggingFace.

Team:
  - Enrique Paiva (https://huggingface.co/enpaiva)
  - Daniel Cabrera
  - Leticia Bogado
  - Alberto Benítez
  - Emmanuel