pauvanbr/synthetic-data-es

🇪🇸 Synthetic Data ES — Pipelines de Datos Sintéticos para Español

Colección de pipelines para generar datos sintéticos de alta calidad en español usando distilabel. Diseñados para:

1. SFT (Supervised Fine-Tuning) de modelos de lenguaje
2. Fine-tuning de modelos de embedding (sentence-transformers)

Cada pipeline implementa un paper del estado del arte adaptado al español. Todos los imports están verificados con distilabel 1.5.3+.

---

📁 Estructura del Repo

├── pipelines/                              # Pipelines de distilabel (lógica completa)
│   ├── 01_magpie_sft.py                    # SFT zero-seed con Magpie
│   ├── 02_embedding_triplets.py            # Triplets de embedding E5-style
│   ├── 03_personas_es.py                   # SFT con personas hispanas
│   ├── 04_evol_instruct.py                 # Escalado de complejidad
│   ├── 05_glan_es.py                       # Taxonomía educativa GLAN
│   ├── 06_quality_filter.py                # Filtrado DEITA
│   ├── 07_rag_grounded_sft.py              # 🆕 SFT grounded en documentos reales
│   └── 08_rag_grounded_embeddings.py       # 🆕 Embedding triplets grounded
├── jobs/                                   # Scripts listos para lanzar como HF Jobs
│   ├── job_01_magpie.py
│   ├── job_02_embedding.py
│   ├── job_03_personas.py
│   ├── job_04_evol.py
│   ├── job_05_glan.py
│   ├── job_06_filter.py
│   ├── job_07_rag_sft.py                   # 🆕
│   └── job_08_rag_embed.py                 # 🆕
└── launcher.py                             # Launcher genérico

#	Pipeline	Paper	Objetivo	Output
01	01_magpie_sft.py	Magpie	SFT zero-seed	instruction, response
02	02_embedding_triplets.py	E5-Mistral	Embedding triplets	query, positive, negative
03	03_personas_es.py	PersonaHub	SFT con diversidad cultural	instruction, response, persona
04	04_evol_instruct.py	WizardLM	Escalado de complejidad	evolved_instruction, answer
05	05_glan_es.py	GLAN	Cobertura temática completa	instruction por taxonomía
06	06_quality_filter.py	DEITA	Filtrado de calidad	complexity_score, quality_score
07	07_rag_grounded_sft.py	RAFT + Backtranslation	SFT grounded en docs reales	messages, groundedness_score
08	08_rag_grounded_embeddings.py	E5 + docs reales	Embedding triplets grounded	query, positive, negative

---

🆕 Pipelines RAG-Grounded (07 & 08)

¿Por qué grounded > generación pura?

La literatura es clara: fundamentar la generación en documentos reales mejora significativamente la calidad:

Método	Calidad
Self-Instruct (LLM puro, sin docs)	54% instrucciones válidas
Backtranslation (doc → pregunta)	74.4% AlpacaEval (+9.3pp)
AgentInstruct (docs como semillas)	+40% AGIEval sobre misma base
RAFT (doc-grounded QA)	+12pp accuracy en QA de dominio

Pipeline 07: RAG-Grounded SFT

Toma documentos reales en español → genera preguntas inversas (reverse instruction) → responde citando el documento (estilo RAFT) → filtra por groundedness.

Documento real (Wikipedia, mC4, tu corpus)
    → ChunkDocuments (~800 palabras)
    → TextGeneration: genera pregunta desde el chunk
    → TextGeneration: genera respuesta CoT con citas
    → TextGeneration: evalúa groundedness (1-5)
    → PostProcess: filtra + formato ChatML messages

Fuentes de documentos soportadas:

• wikimedia/wikipedia (config 20231101.es) — enciclopédico
• allenai/c4 (config es) — web general
• Cualquier dataset HF con columna de texto — tu corpus de dominio

# Desde Wikipedia en español
python pipelines/07_rag_grounded_sft.py \
    --model_id "meta-llama/Meta-Llama-3.1-70B-Instruct" \
    --source_repo "wikimedia/wikipedia" \
    --source_config "20231101.es" \
    --num_docs 10000 \
    --output_repo "tu-org/rag-sft-es"

# Desde tu propio corpus (cambia source_repo y source_column)
python pipelines/07_rag_grounded_sft.py \
    --source_repo "tu-org/mi-corpus-legal" \
    --source_config "none" \
    --source_column "contenido" \
    --num_docs 5000 \
    --output_repo "tu-org/rag-sft-legal-es"

# Multi-pregunta por chunk (3 preguntas variadas)
python pipelines/07_rag_grounded_sft.py \
    --questions_per_doc 3 \
    --output_repo "tu-org/rag-sft-es-multi"

Pipeline 08: RAG-Grounded Embeddings

Usa documentos reales como positive_document (cero alucinación) → genera queries y hard negatives condicionados.

Documento real
    → ChunkForEmbeddings (~300 palabras, más corto para retrieval)
    → GenerateSentencePair(action="query", triplet=True)
    → FormatForSentenceTransformers: swap anchor↔query
    → Output: (query, positive_doc_real, hard_negative)

# Single action: solo queries de búsqueda
python pipelines/08_rag_grounded_embeddings.py \
    --source_repo "wikimedia/wikipedia" \
    --source_config "20231101.es" \
    --num_docs 10000 \
    --output_repo "tu-org/rag-embed-es"

# Multi-action: query + semantic-similarity en paralelo
python pipelines/08_rag_grounded_embeddings.py \
    --multi_action \
    --num_docs 10000 \
    --output_repo "tu-org/rag-embed-es-multi"

---

🚀 Quick Start (local)

Instalación

pip install "distilabel[hf-inference-endpoints]>=1.5.0"

Ejemplo: Generar datos SFT con Magpie

export HF_TOKEN="hf_..."

python pipelines/01_magpie_sft.py \
    --model_id "meta-llama/Meta-Llama-3.1-8B-Instruct" \
    --num_rows 1000 \
    --output_repo "tu-org/magpie-es-sft" \
    --batch_size 50

Ejemplo: Generar triplets para embedding

python pipelines/02_embedding_triplets.py \
    --model_id "meta-llama/Meta-Llama-3.1-70B-Instruct" \
    --num_generations_per_task 50 \
    --output_repo "tu-org/embedding-triplets-es"

---

☁️ Lanzar como HF Jobs

Los pipelines usan InferenceEndpointsLLM (API serverless de HF), así que los jobs solo necesitan CPU — el trabajo pesado lo hace la API de inferencia remota. HF_TOKEN se inyecta automáticamente.

Cada script jobs/job_XX.py descarga el pipeline correspondiente del repo y lo ejecuta. Edita las variables de configuración al principio de cada fichero (MODEL_ID, NUM_ROWS, OUTPUT_REPO, etc.) antes de lanzar.

Job 01 — Magpie-ES (SFT zero-seed) · ~50K filas

Script:   jobs/job_01_magpie.py
Hardware: cpu-basic
Timeout:  8h
Deps:     distilabel[hf-inference-endpoints]
Output:   → pauvanbr/magpie-es-sft

Job 02 — E5-ES Embedding Triplets · ~4.5K triplets

Script:   jobs/job_02_embedding.py
Hardware: cpu-basic
Timeout:  6h
Deps:     distilabel[hf-inference-endpoints]
Output:   → pauvanbr/embedding-triplets-es

Job 03 — Personas-ES · ~50K filas

Script:   jobs/job_03_personas.py
Hardware: cpu-basic
Timeout:  12h  (2 llamadas LLM por fila: instrucción + respuesta)
Deps:     distilabel[hf-inference-endpoints]
Output:   → pauvanbr/personas-es-sft

Job 04 — EvolInstruct-ES · 25 seeds × 3 evoluciones

Script:   jobs/job_04_evol.py
Hardware: cpu-basic
Timeout:  4h
Deps:     distilabel[hf-inference-endpoints]
Output:   → pauvanbr/evol-instruct-es

Job 05 — GLAN-ES · ~120 topics × 20 instrucciones

Script:   jobs/job_05_glan.py
Hardware: cpu-basic
Timeout:  6h
Deps:     distilabel[hf-inference-endpoints]
Output:   → pauvanbr/glan-es-sft

Job 06 — Quality Filter · filtrar un dataset existente

Script:   jobs/job_06_filter.py
Hardware: cpu-basic
Timeout:  6h
Deps:     distilabel[hf-inference-endpoints]
Output:   → pauvanbr/magpie-es-sft-filtered
⚠️ Requiere que el dataset de input (ej: pauvanbr/magpie-es-sft) ya exista

Job 07 — 🆕 RAG-Grounded SFT · ~10K docs → ~30K Q&A grounded

Script:   jobs/job_07_rag_sft.py
Hardware: cpu-basic
Timeout:  12h  (3 llamadas LLM por chunk: pregunta + respuesta + groundedness)
Deps:     distilabel[hf-inference-endpoints]
Output:   → pauvanbr/rag-sft-es
Source:   wikimedia/wikipedia (20231101.es) — configurable

Job 08 — 🆕 RAG-Grounded Embeddings · ~10K docs → ~50K triplets

Script:   jobs/job_08_rag_embed.py
Hardware: cpu-basic
Timeout:  8h
Deps:     distilabel[hf-inference-endpoints]
Output:   → pauvanbr/rag-embedding-triplets-es
Source:   wikimedia/wikipedia (20231101.es) — configurable
Mode:     Multi-action (query + semantic en paralelo)

Orden recomendado

Fase 1 (en paralelo):  Job 01 (Magpie) + Job 02 (Embeddings)
Fase 1b (en paralelo): Job 07 (RAG SFT) + Job 08 (RAG Embeddings)  ← 🆕
Fase 2 (en paralelo):  Job 03 (Personas) + Job 04 (Evol) + Job 05 (GLAN)
Fase 3 (secuencial):   Job 06 (Filter) — sobre output de Fase 1-2

Launcher genérico

También puedes usar el launcher para ejecutar cualquier pipeline directamente:

python launcher.py 01_magpie_sft.py \
    --model_id "meta-llama/Meta-Llama-3.1-8B-Instruct" \
    --num_rows 1000 \
    --output_repo "tu-org/magpie-es-sft"

---

🔬 Detalle de cada Pipeline

Pipeline 01: Magpie-ES (SFT Zero-Seed)

Paper: Magpie: Alignment Data Synthesis from Scratch

Método: Explota el template de chat de modelos alineados. No necesita datos semilla — solo el system prompt en español.

Resultado de referencia: Llama-3-8B + 300K Magpie ≈ Llama-3-8B-Instruct oficial (entrenado con 10M datos)

8 system prompts con pesos de probabilidad: general, técnico, educativo, creativo, datos, profesional, divulgación, pensamiento crítico.

Pipeline 02: E5-ES (Embedding Triplets)

Paper: Improving Text Embeddings with Large Language Models

Método: Two-step prompting — taxonomía de tareas → triplets. Output compatible con sentence-transformers MultipleNegativesRankingLoss.

• 25 tareas short-long (retrieval), 10 short-short (STS), 10 long-short (clasificación)

Pipeline 03: Personas-ES (SFT con Diversidad Cultural)

Paper: PersonaHub

60+ personas hispanas de 🇪🇸🇲🇽🇦🇷🇨🇴🇨🇱🇵🇪🇨🇷🇨🇺🇪🇨🇺🇾🇵🇦🇬🇹🇩🇴 × 21 dominios temáticos.

Pipeline 04: EvolInstruct-ES

Paper: WizardLM / Evol-Instruct

Escalado de complejidad iterativo + scoring DEITA integrado.

Pipeline 05: GLAN-ES (Taxonomía Educativa)

Paper: GLAN

~120 topics en 9 campos: Ciencias, Matemáticas, Tecnología, Humanidades, Derecho, Economía, Medicina, Cultura, Medio Ambiente.

Pipeline 06: Quality Filter (DEITA)

Paper: DEITA

Filtrado complexity × quality con LLM-as-judge. 6K muestras DEITA > 50K random.

Pipeline 07: RAG-Grounded SFT 🆕

Papers:

• RAFT: Adapting Language Model to Domain Specific RAG — +12pp accuracy
• Instruction Back-and-Forth Translation — 74.4% AlpacaEval
• AgentInstruct — +40% AGIEval

Método: Documento real → reverse instruction (pregunta) → respuesta CoT con citas → evaluación de groundedness → filtro.

Por qué es mejor: La generación pura (Magpie, Self-Instruct) tiende hacia conocimiento genérico y alucina. Con documentos reales como ancla, los datos son fieles al dominio y factuales.

2 modos:

• --questions_per_doc 1 — 1 pregunta por chunk, simple y robusto (v2, recomendado)
• --questions_per_doc 3 — 3 preguntas por chunk en JSON, más datos pero requiere parsing

Output: formato ChatML messages listo para TRL SFTTrainer.

Pipeline 08: RAG-Grounded Embeddings 🆕

Papers:

• E5-Mistral — SOTA embeddings con datos sintéticos
• Gecko — embeddings 7x más eficientes

Diferencia clave con Pipeline 02: El positive_document es un chunk real (no alucinado). El LLM solo genera la query y el hard negative.

2 modos:

• --action query — solo queries de búsqueda (asymmetric retrieval)
• --multi_action — query + semantic-similarity en paralelo (entrenamiento más diverso)

Output: formato (query, positive, negative) compatible con sentence-transformers.

---

🗺️ Ruta Recomendada

FASE 1 — Quick Wins (generación pura + grounded en paralelo)
├── 01_magpie_sft.py → 100K pares SFT nativos
├── 02_embedding_triplets.py → 50K triplets embedding (sintéticos)
├── 07_rag_grounded_sft.py → 30K Q&A grounded en Wikipedia-es  ← 🆕
└── 08_rag_grounded_embeddings.py → 50K triplets grounded       ← 🆕

FASE 2 — Diversidad y Calidad
├── 03_personas_es.py → Instrucciones culturalmente diversas
├── 06_quality_filter.py → Filtrar con DEITA
└── Combinar outputs de 01 + 03 + 07

FASE 3 — Escala y Complejidad
├── 04_evol_instruct.py → Evolucionar instrucciones
├── 05_glan_es.py → Cobertura temática completa
└── 06_quality_filter.py → Filtrado final

FASE 4 — Dominio específico (con tu propio corpus) ← 🆕
├── 07_rag_grounded_sft.py --source_repo "tu-corpus"
└── 08_rag_grounded_embeddings.py --source_repo "tu-corpus"

---

📊 Papers de Referencia

Paper	Área	Idea clave	arxiv
Magpie	SFT	Zero-seed via chat template	2406.08464
E5-Mistral	Embeddings	Two-step taxonomy → triplets	2401.00368
Gecko	Embeddings	FRet: LLM como re-ranker	2403.20327
PersonaHub	Diversidad	1B personas como proxy	2406.20094
WizardLM	Complejidad	Evol-Instruct iterativo	2304.12244
GLAN	Cobertura	Taxonomía educativa	2402.13064
DEITA	Filtrado	complexity × quality × diversity	2312.15685
RAFT	RAG-SFT	Doc-grounded QA con CoT	2403.10131
Backtranslation	RAG-SFT	Doc → reverse instruction	2408.04614
AgentInstruct	Complejidad	Suggester-Editor agéntico	2407.03502
KaLM-Embedding	Embeddings	Persona-driven + ranking consistency	2501.01028
Orca	SFT	Trazas de razonamiento	2306.02707
Best Practices (Google)	Survey	Factuality, fidelity, unbiasedness	2404.07503

🔧 Modelos Recomendados

Modelo	Template	Notas
meta-llama/Meta-Llama-3.1-8B-Instruct	llama3	Rápido, buen balance
meta-llama/Meta-Llama-3.1-70B-Instruct	llama3	Mayor calidad
Qwen/Qwen2.5-72B-Instruct	qwen2	Excelente multilingüe

⚡ ¿Traducir o Generar Nativo?

Tipo	Traducir	Nativo
Clasificación/NLI	✅	No necesario
QA abierta/creatividad	❌	✅ Obligatorio
Embedding retrieval	⚠️	✅ Mejor
Contenido cultural	❌	✅ Obligatorio
QA de dominio	❌	✅ Usar Pipeline 07

📂 Fuentes de Corpus en Español para RAG-Grounded

Dataset	Tipo	Uso recomendado
wikimedia/wikipedia (config 20231101.es)	Enciclopédico	General, educación
allenai/c4 (config es)	Web crawl	Diversidad temática
oscar-corpus/OSCAR-2301	Web crawl masivo	Escala
spanish-ir/messirve	Queries Google LATAM	Eval de embeddings
Tu propio corpus	Dominio	Especialización

🤝 Herramienta

Todos los pipelines usan distilabel (Argilla) — la herramienta más completa para datos sintéticos en HuggingFace.