iberotales-gemma-3-1b-it-es

Iberotales Gemma-3-1b-it

<em>Alineando modelos de lenguaje con la narrativa de mitos y leyendas de Iberoamérica.</em><br>

<div style="text-align:center"> <img src="https://raw.githubusercontent.com/mcdaqc/Iberotales/refs/heads/main/img/portrait.png" alt="Iberotales Banner" width="80%" /> </div>

</div>

Este modelo es una versión alineada del modelo por Unsloth, gemma-3-1b-it de Google, específicamente optimizado mediante técnicas de Aprendizaje por Refuerzo Generalizado a partir de Resultados Emparejados (GRPO) para tareas de generación de historias y personajes basadas en el patrimonio cultural de los mitos y leyendas de Iberoamérica. Fue entrenado utilizando el conjunto de datos ibero-tales-es, con un sistema de recompensas personalizado, para mejorar sus capacidades en la generación de narrativas y descripciones de personajes que se adhieren a formatos específicos y capturan la esencia cultural en español.

Detalles del Modelo

Descripción del Modelo

• Desarrollado por: David Quispe
• Tipo de modelo: Modelo de lenguaje causal ajustado (CausalLM) con optimización GRPO.
• Idioma(s) (NLP): Español (es), con enfoque en variantes de Iberoamérica.
• Licencia: Apache-2.0
• Modelo Base: unsloth/gemma-3-1b-it (Versión optimizada por Unsloth del modelo Gemma 3 1B de Google).
• Recursos para más información:
  • Repositorio GitHub del proyecto Iberotales
  • Tarjeta del Modelo Base en Hugging Face

Este modelo forma parte del proyecto Iberotales, cuyo objetivo es alinear modelos de lenguaje con la narrativa de mitos y leyendas de Iberoamérica para la preservación cultural y la generación de contenido.

Usos

Casos de Uso Ideales

Este modelo está específicamente diseñado y optimizado para:

• Generar historias y narrativas creativas en español basadas en mitos y leyendas iberoamericanos, adhiriéndose a formatos estructurados (pensamiento en voz alta + solución).
• Crear descripciones detalladas y perfiles de personajes míticos y legendarios.
• Asistir en tareas de escritura creativa con un enfoque cultural específico y estructura definida.
• Apoyar aplicaciones educativas relacionadas con la literatura y el folclore de Iberoamérica que requieran respuestas estructuradas.
• Integrarse en plataformas interactivas que necesiten generación de texto narrativo contextualizado y formateado.

Usos Fuera de Alcance

El modelo no es adecuado para tareas que requieren:

• Recuperación de información factual precisa o verificación de hechos históricos.
• Razonamiento lógico complejo o resolución de problemas estructurados que no se ajusten al formato de pensamiento/solución.
• Interpretación o análisis de datos cuantitativos.
• Sistemas de toma de decisiones críticas o aplicaciones de alta fiabilidad.
• Generación de contenido sensible o controversial sin supervisión y validación humana.

Sesgos, Riesgos y Limitaciones

El modelo, al ser alineado sobre datos específicos, hereda y presenta ciertos sesgos y limitaciones inherentes a los modelos de lenguaje y a los datos de entrenamiento:

• Sesgos de Datos: Puede reflejar sesgos culturales o de representación presentes en los mitos, leyendas y fuentes originales, así como en los datasets curados. La representación de temas, personajes y países puede ser desigual. Los análisis de la distribución actual (por país, tema, longitud de historia y trama) se pueden encontrar en el notebook de visualización.
• Adherencia al Formato: Aunque entrenado con GRPO para seguir un formato específico, puede ocasionalmente desviarse de la estructura deseada (<think>...</think><SOLUTION>...</SOLUTION>).
• Alcance Cultural y Lingüístico: Aunque enfocado en Iberoamérica, puede no capturar la vasta diversidad regional del español o la influencia y riqueza de las lenguas indígenas en las narrativas.
• Calidad de Generación Variable: La coherencia, autenticidad y creatividad del texto generado pueden fluctuar.
• Sensibilidad: Al tratar con narrativas culturales, existe el riesgo de generar contenido que pueda ser percibido como inofensivo o inexacto si no se valida.

Recomendaciones para un Uso Responsable

Para mitigar sesgos y limitaciones y fomentar un uso responsable:

1. Validación Humana: Siempre revisar y curar el contenido generado por el modelo, especialmente en contextos delicados o educativos, y verificar que se ajuste al formato esperado.
2. Conciencia de Sesgos: Ser consciente de los posibles sesgos en la representación (temática, geográfica, de personajes) y utilizar los análisis del dataset para comprenderlos.
3. Ampliación de Datos: Contribuir a la expansión y curación de los datasets de entrenamiento para mejorar la diversidad y representación, y refinar los pares de preferencias para GRPO.
4. Contextualización: Al usar el modelo en aplicaciones, proporcionar contexto sobre su origen, la metodología de entrenamiento (GRPO) y sus posibles limitaciones.

Detalles del Entrenamiento

Datos de Entrenamiento

El modelo fue ajustado (fine-tuned) utilizando dos conjuntos de datos principales desarrollados como parte del proyecto Iberotales:

1. Ibero-Tales-ES: Dataset de historias sintéticas estructuradas, generadas a partir de mitos y leyendas iberoamericanos. Este dataset se formateó en pares de prompt/respuesta para el entrenamiento GRPO. Contiene las narrativas generadas, tramas asociadas, y pares pregunta-respuesta.
2. Ibero-Characters-ES: Dataset de personajes míticos y legendarios con descripciones e historias de origen, utilizado como base para la selección de personajes y contexto en la generación del dataset Ibero-Tales-ES.

El dataset Ibero-Tales-ES fue construido seleccionando personajes del dataset Ibero-Characters-ES. Las tramas y temas se basaron parcialmente en temas literarios comunes para guiar la generación, creando múltiples tramas por tema seleccionado aleatoriamente, limitadas por personaje. Se generaron un total de 2283 registros de historias a partir de estas tramas y personajes. Para el entrenamiento GRPO, cada entrada del dataset se transformó en un par prompt (con system prompt y pregunta) y answer (la respuesta esperada en el formato estructurado).

Procedimiento de Entrenamiento

Metodología: Aprendizaje por Refuerzo Generalizado a partir de Resultados Emparejados (GRPO)

Puedes revisar el notebook de entrenamiento, aquí. El modelo base unsloth/gemma-3-1b-it fue ajustado utilizando el algoritmo GRPO implementado en la biblioteca TRL (Transformer Reinforcement Learning) de Hugging Face, optimizado con Unsloth. GRPO entrena el modelo para generar respuestas que maximicen una recompensa definida por funciones, sin requerir un modelo de recompensa separado explícitamente entrenado en preferencias binarias como DPO.

Configuración del Prompt y Recompensas

El entrenamiento GRPO utilizó un system_prompt específico para guiar al modelo a generar una respuesta estructurada con un segmento de "pensamiento" (<think>...</think>) seguido de la "solución" (<SOLUTION>...</SOLUTION>).

Se definieron múltiples funciones de recompensa (reward_funcs) para guiar el aprendizaje:

1. match_format_exactly: Otorga una alta recompensa (3.0) si la respuesta generada se ajusta exactamente al formato estructurado esperado (<think>...</think><SOLUTION>...</SOLUTION>).
2. match_format_approximately: Proporciona recompensas parciales (0.5) si las etiquetas de inicio y fin de pensamiento y solución aparecen exactamente una vez, penalizando (-0.5) si aparecen un número diferente de veces. Esto ayuda a guiar al modelo hacia el uso correcto de las etiquetas.
3. check_text_similarity: Compara la "solución" extraída de la respuesta generada con la respuesta esperada del dataset utilizando una métrica de similitud simple basada en la intersección de palabras. Otorga hasta 3.0 puntos en función de la similitud. https://github.com/mcdaqc/Iberotales/blob/main/src/train/unsloth_gemma3_finetuning.ipynb Estas funciones de recompensa combinadas guían al modelo a aprender tanto el formato de salida deseado como a generar contenido relevante basado en la respuesta esperada.

Configuración de GRPO Trainer

El entrenamiento se configuró utilizando TRL's GRPOConfig con los siguientes parámetros clave. Es importante notar que el entrenamiento se detuvo al alcanzar un máximo de 50 pasos (max_steps=50), lo cual prevaleció sobre la configuración de 3 épocas (num_train_epochs=3) ya que el límite de pasos se alcanzó primero.

• learning_rate: 5e-6
• optim: "adamw_torch_fused" (optimizado)
• per_device_train_batch_size: 4
• gradient_accumulation_steps: 4
• num_generations: 4 (número de generaciones por prompt para evaluar con recompensas)
• max_prompt_length: 512
• max_completion_length: 1024
• num_train_epochs: 3 (Configurado, pero sobrescrito por max_steps=50)
• max_steps: 50 (El entrenamiento se detuvo al alcanzar este límite)
• save_steps: 50
• max_grad_norm: 0.1
• report_to: "wandb"

Entorno de Entrenamiento

El entrenamiento se realizó en el siguiente entorno:

• Unsloth Versión: 2025.5.7 (con patching Fast Gemma3)
• Transformers Versión: 4.51.3
• vLLM Versión: 0.9.0.1
• Hardware: NVIDIA L40S. Número de GPUs: 1. Memoria máxima: 44.403 GB. Plataforma: Linux.
• Software Adicional: Torch 2.7.0+cu126, CUDA 8.9, CUDA Toolkit 12.6, Triton 3.3.0.
• Configuración: Bfloat16 = TRUE. FA [Xformers = 0.0.30. FA2 = False]. Se realizó LoRA de 16 bits.

Métricas del Entrenamiento

La salida del entrenamiento final después de completar los 50 pasos reportó las siguientes métricas:

• Paso Global Final (global_step): 50
• Pérdida de Entrenamiento Final (training_loss): 0.00013613314047688618
• Tiempo de Ejecución del Entrenamiento (train_runtime): 9811.2194 segundos (aproximadamente 2 horas y 40 minutos)
• Muestras por Segundo (train_samples_per_second): 0.082
• Pasos por Segundo (train_steps_per_second): 0.005
• FLOPs Totales (total_flos): 0.0 (Este valor a menudo es 0 para métodos RL si no se configura específicamente el seguimiento de FLOPs).

Recursos Adicionales del Entrenamiento

• Seguimiento en W&B: Los detalles y métricas completos del proceso de entrenamiento, incluyendo las recompensas promedio a lo largo de los pasos, fueron registrados y pueden visualizarse en Weights & Biases (W&B): W&B Training Run

<div style="text-align:center"> <img src="https://raw.githubusercontent.com/mcdaqc/Iberotales/refs/heads/main/img/wandb1.png" alt="Iberotales wandb1" width="80%" /> <br> <img src="https://raw.githubusercontent.com/mcdaqc/Iberotales/refs/heads/main/img/wandb2.png" alt="Iberotales wandb2" width="80%" /> </div>

Evaluación

Enfoque y Métricas

La evaluación del modelo se centró tanto en métricas intrínsecas (automatizadas) como en la calidad cualitativa del texto generado para asegurar su relevancia cultural, narrativa y adherencia al formato después del entrenamiento con GRPO.

Métricas

• Métricas Automáticas: Se calcularon métricas como Perplejidad (para evaluar la capacidad predictiva del modelo sobre los datos de prueba) y métricas basadas en la adherencia al formato estructurado definido para GRPO. BLEU también se podría considerar, pero con las limitaciones para texto creativo.
• Evaluación Humana: Crucial para juzgar la calidad del razonamiento (en <think>), la coherencia y relevancia de la solución (en <SOLUTION>), la fidelidad cultural, la fluidez del lenguaje y la calidad general de las narrativas generadas.
• Análisis de Distribución: Se analizaron las distribuciones de temas y países en las generaciones del modelo para compararlas con los datasets de entrenamiento y detectar posibles sesgos o desviaciones en la representación, además de analizar cómo el GRPO pudo haber influido en estas distribuciones.

Resultados

El entrenamiento con GRPO resultó en un modelo ajustado con una notable mejora en la capacidad de generar narrativas fluidas y culturalmente relevantes en español. Lo más importante es que el modelo aprendió a seguir el formato estructurado de pensamiento/solución de manera más consistente, gracias a las funciones de recompensa diseñadas.

Conclusión de las Métricas de Entrenamiento:

La baja pérdida de entrenamiento final reportada (0.000136) después de 50 pasos globales es un indicador positivo de que el modelo ha optimizado la función objetivo de GRPO. Observando los gráficos de W&B:

• La curva de train/learning_rate muestra el decaimiento del learning rate a lo largo de los pasos, siguiendo la configuración de "cosine", lo cual es un esquema de optimización estándar.
• Las métricas de recompensa (train/rewards/match_format_exactly, train/rewards/match_format_approximately, train/rewards/check_text_similarity) muestran una clara tendencia ascendente a lo largo de los 50 pasos. Esto es la evidencia clave de que el modelo está aprendiendo exitosamente a generar respuestas que cumplen con el formato estructurado y se asemejan a las respuestas esperadas según las funciones de recompensa definidas. La recompensa promedio total (train/reward) también refleja esta mejora general.
• La métrica train/loss muestra una rápida disminución, alcanzando un valor muy bajo, lo que confirma la convergencia efectiva del proceso de optimización GRPO en los datos de entrenamiento.
• El gráfico train/kl muestra un ligero aumento, lo cual es esperado en métodos RL/DPO/GRPO a medida que la política aprendida se aleja de la política inicial (el modelo base ajustado con SFT si aplicara, o simplemente el modelo al inicio del GRPO).
• El train/grad_norm muestra algunos picos, pero la norma del gradiente se mantiene gestionada (probablemente debido a max_grad_norm=0.1), indicando un entrenamiento estable dentro de lo esperado para procesos RL.

En conjunto, las métricas de entrenamiento sugieren que, dentro de los 50 pasos ejecutados, el modelo se adaptó efectivamente a las preferencias definidas por las funciones de recompensa GRPO, mejorando su capacidad para generar contenido relevante en el formato deseado. Sin embargo, la evaluación en datos de prueba y una evaluación cualitativa profunda son fundamentales para validar que este aprendizaje se generaliza bien y produce resultados de alta calidad más allá del conjunto de entrenamiento limitado.

Impacto Ambiental

• Tipo de Hardware: Nvidia 1xL40S 8 vCPU · 62 GB RAM · 48 GB VRAM
• Horas utilizadas: Aproximadamente 2.7 horas (9811.2 segundos ≈ 2.72 horas)
• Proveedor de Nube: Hugging Face
• Región de Computación: EU
• Carbono Emitido (Estimado): Aproximadamente 0.11 kg de CO2eq. (Basado en 2.72 kWh * factor de emisión regional). Nota: Esta es una estimación basada en un factor de emisión promedio; el valor real puede variar.

Especificaciones Técnicas

Arquitectura del Modelo y Objetivo

• Arquitectura Base: Gemma 3 1B (Arquitectura Transformer decoder-only de Google).
• Objetivo del Ajuste Fino: Adaptar la arquitectura base mediante GRPO para generar narrativas y descripciones de personajes culturalmente específicas en español, siguiendo un formato de salida estructurado.
• Ventana de Contexto: 128K tokens (heredada del modelo base). Permite procesar y generar secuencias largas de texto, crucial para el formato estructurado y las historias detalladas.
• Soporte Lingüístico: Optimizado para el español, con un enfoque en las narrativas y el vocabulario asociados a los mitos y leyendas iberoamericanos.

Infraestructura de Computación

Hardware

El entrenamiento se ejecutó en una única GPU Nvidia L40S.

Software

• Framework de ML: PyTorch.
• Bibliotecas Clave:
  • Hugging Face Transformers: Gestión del modelo y tokenizador.
  • Hugging Face TRL: Implementación del algoritmo GRPO y la estructura del GRPOTrainer.
  • Unsloth: Optimización para un entrenamiento más rápido y eficiente en memoria (utilizada con LoRA de 16 bits en este caso).
  • accelerate, peft, bitsandbytes: Bibliotecas auxiliares necesarias para el entrenamiento y la carga optimizada.

Cómo Comenzar con el Modelo

Puedes cargar y usar este modelo fácilmente con la biblioteca transformers de Hugging Face. Asegúrate de tener las bibliotecas necesarias instaladas. Se recomienda usar Unsloth para una inferencia más rápida.

pip install transformers torch unsloth accelerate peft trl bitsandbytes

Método Recomendado (con Unsloth para inferencia optimizada)

Este método aprovecha las optimizaciones de Unsloth para una inferencia potencialmente más rápida. Es ideal si la velocidad o la memoria son una consideración clave.

from unsloth import FastLanguageModel
import torch

model_id = "daqc/iberotales-gemma-3-1b-it-es"
# La ventana de contexto real del modelo es 128K, ajusta max_seq_length según tu uso práctico
max_seq_length = 1024

# Cargar el modelo y tokenizador optimizados para inferencia
# Carga en 4-bit si load_in_4bit=True para ahorrar memoria
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = model_id,
    max_seq_length = max_seq_length,
    dtype = None, # Auto-detección (por ejemplo, bfloat16 si está disponible)
    load_in_4bit = True,
)

# Habilitar inferencia rápida (opcional, pero recomendado)
FastLanguageModel.for_inference(model)

# Ejemplo de uso: Generar una historia en el formato estructurado
# El modelo fue entrenado con un system prompt y espera seguir el formato <think>...</think><SOLUTION>...</SOLUTION>
system_prompt = \
"""Resuelve el siguiente problema.  
Primero, piensa en voz alta qué debes hacer, paso por paso y de forma resumida, entre <think> y </think>.  
Luego, da la respuesta final entre <SOLUTION> y </SOLUTION>.  
No escribas nada fuera de ese formato."""

user_question = "Escribe una historia corta sobre el Pombero, un personaje de la mitología guaraní, en el formato requerido:" # Ejemplo de pregunta

# Formatear el prompt usando el template de chat (recomendado ya que se usó en el entrenamiento)
messages = [
    {"role": "system", "content": system_prompt},
    {"role": "user", "content": user_question},
]
prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)


inputs = tokenizer(prompt, return_tensors="pt").to(model.device) # Mover inputs al mismo dispositivo que el modelo

# Generar texto
# Ajusta los parámetros de generación para controlar la salida (creatividad, longitud, etc.)
outputs = model.generate(
    **inputs,
    max_new_tokens=512, # Máximo de tokens a generar en la respuesta (ajustar según la longitud esperada)
    num_beams=1,
    do_sample=True, # Habilitar muestreo para respuestas más creativas
    top_k=50,
    top_p=0.95,
    temperature=0.7,
    pad_token_id=tokenizer.eos_token_id, # Importante para evitar advertencias
    eos_token_id=tokenizer.eos_token_id, # También útil para detener la generación
)

# Decodificar y imprimir la salida
# Se puede decodificar la secuencia completa y luego parsear el formato estructurado
generated_sequence = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(generated_sequence)

# Opcional: Extraer solo la solución si el formato es correcto
# import re
# match_format = re.compile(r"^[\s]{0,}<think>.+?</think>.*?<SOLUTION>(.+?)</SOLUTION>[\s]{0,}$", flags = re.MULTILINE | re.DOTALL)
# match = match_format.search(generated_sequence)
# if match:
#     extracted_solution = match.group(1).strip()
#     print("\nSolución Extraída:")
#     print(extracted_solution)
# else:
#     print("\nFormato estructurado no detectado en la salida.")

Método Estándar (con Hugging Face Transformers)

Este método es más simple para comenzar si ya estás familiarizado con transformers y no necesitas las optimizaciones de Unsloth para la inferencia.

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_id = "daqc/iberotales-gemma-3-1b-it-es"

# Cargar el tokenizador y el modelo
# Puedes especificar dtype='auto' y device_map='auto' para que transformers maneje la carga
tokenizer = AutoTokenizer.from_pretrained(model_id)
# Si no usas load_in_4bit, asegúrate de tener suficiente VRAM
model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype='auto', device_map='auto')

# Ejemplo de uso: Generar una historia en el formato estructurado
# El modelo fue entrenado con un system prompt y espera seguir el formato <think>...</think><SOLUTION>...</SOLUTION>
system_prompt = \
"""Resuelve el siguiente problema.  
Primero, piensa en voz alta qué debes hacer, paso por paso y de forma resumida, entre <think> y </think>.  
Luego, da la respuesta final entre <SOLUTION> y </SOLUTION>.  
No escribas nada fuera de ese formato."""

user_question = "Escribe una historia corta sobre el Pombero, un personaje de la mitología guaraní, en el formato requerido:" # Ejemplo de pregunta

# Formatear el prompt usando el template de chat (recomendado ya que se usó en el entrenamiento)
messages = [
    {"role": "system", "content": system_prompt},
    {"role": "user", "content": user_question},
]
prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)

# Tokenizar el prompt
inputs = tokenizer(prompt, return_tensors="pt").to(model.device) # Mover inputs al dispositivo correcto

# Generar texto
# Ajusta los parámetros de generación según tus necesidades
outputs = model.generate(
    **inputs,
    max_new_tokens=512, # Ajusta según la longitud esperada
    num_beams=1,
    do_sample=True,
    top_k=50,
    top_p=0.95,
    temperature=0.7,
    pad_token_id=tokenizer.eos_token_id,
    eos_token_id=tokenizer.eos_token_id,
)

# Decodificar y imprimir la salida
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

# Opcional: Extraer solo la solución si el formato es correcto
# import re
# match_format = re.compile(r"^[\s]{0,}<think>.+?</think>.*?<SOLUTION>(.+?)</SOLUTION>[\s]{0,}$", flags = re.MULTILINE | re.DOTALL)
# match = match_format.search(tokenizer.decode(outputs[0], skip_special_tokens=True))
# if match:
#     extracted_solution = match.group(1).strip()
#     print("\nSolución Extraída:")
#     print(extracted_solution)
# else:
#     print("\nFormato estructurado no detectado en la salida.")

Cita

BibTeX:

@misc{iberotales-gemma-3-1b-it-es,
  title        = {Iberotales Gemma-3-1b-it},
  author       = {David Quispe},
  year         = {2025},
  month        = {June},
  url          = {https://huggingface.co/somosnlp-hackathon-2025/iberotales-gemma-3-1b-it-es},
  note         = {Fine-tuned model for Ibero-American storytelling using GRPO}
}

APA: Quispe, D. (2025, junio). Iberotales Gemma-3-1b-it [Modelo ajustado en Hugging Face]. Recuperado de https://huggingface.co/daqc/iberotales-gemma-3-1b-it-es

---

<p align="center"> <em>Este proyecto fue parte de la hackathon de Somos NLP 2025.</em> </p> <div style="display: flex; justify-content: center; align-items: center; gap: 40px;"> <a href="https://github.com/unslothai/unsloth"> <img src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20made%20with%20love.png" alt="Unsloth" width="80"/> </a> <img src="https://raw.githubusercontent.com/mcdaqc/Iberotales/refs/heads/main/img/logo.png" alt="Somos NLP 2025" width="80"/> </div>