---
base_model: unsloth/Qwen3.8-27B
library_name: transformers
pipeline_tag: text-generation
license: cc-by-sa-4.0
language:
  - eu
  - es
  - en
datasets:
  - HiTZ/RAG_eu
  - HiTZ/magpie-en-eu-reasoning-instructions-qwen3
  - HiTZ/ALIA_syntethic_MT_V2
tags:
  - unsloth
  - trl
  - sft
  - lora
  - peft
  - qwen3_8
  - basque
  - euskara
  - translation
---

# qwen3.8-27b_euskara

**Qwen3.8-27B** modeloaren doikuntza fina (SFT LoRArekin), **euskarara**
bideratua, gaztelania eta ingelesa laguntza-hizkuntza gisa erabilita.
[HiTZ](https://huggingface.co/HiTZ) taldearen corpusekin entrenatu da hiru
gaitasun lantzeko: elkarrizketa bidezko instrukzioak, norabide anitzeko
itzulpena eta testu batean oinarritutako lana (laburpena eta erantzun
daitekeen erabakitzea).

> **Egoera: ebaluatu gabe.** Ez da benchmarkik exekutatu modelo honekin.
> Errendimendu-atala nahita dago hutsik; oraindik ez dago kalitateari buruzko
> baieztapenik bermatuko duen daturik.

---

## Modeloaren xehetasunak

| | |
|---|---|
| Oinarrizko modeloa | [`unsloth/Qwen3.8-27B`](https://huggingface.co/unsloth/Qwen3.8-27B) (`Qwen3_5ForConditionalGeneration`) |
| Metodoa | LoRA (PEFT), [Unsloth](https://github.com/unslothai/unsloth) + TRL `SFTTrainer` bidez |
| Zehaztasuna | BF16 (entrenamenduan kuantizaziorik gabe) |
| Sekuentzia-luzera | 4096 |
| Hizkuntzak | euskara (eu), gaztelania (es), ingelesa (en) |

Qwen3.8-27B **arreta linealeko modelo hibridoa** da (*gated delta rule*).
Zentzuzko errendimenduarekin entrenatu edo zerbitzatzeko,
`flash-linear-attention` instalatuta edukitzea komeni da; hura gabe,
`transformers` PyTorch hutsezko inplementazio askoz motelago batera igarotzen
da.

Oinarrizko modeloa **multimodala** da (irudiak eta bideoak onartzen ditu).
Doikuntza honek testu-dorreko moduluak baino ez ditu ukitu, eta **ikusmen-bidea
ez da entrenatu edo egiaztatu**: oinarrizko modelotik heredatutakotzat hartu.

### LoRA konfigurazioa

| Parametroa | Balioa |
|---|---|
| `r` | 32 |
| `lora_alpha` | 32 |
| `lora_dropout` | 0 |
| `bias` | `none` |
| Moduluak | `q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj` |
| Gradient checkpointing | `True` |

### Entrenamenduaren hiperparametroak

| Parametroa | Balioa |
|---|---|
| Epokak | 1 |
| Gailu bakoitzeko lotea | 8 |
| Gradiente-metaketa | 2 (lote eraginkorra: **8**) |
| Learning rate | 1.5e-4 |
| Scheduler | cosine, warmup 3 % |
| Optimizatzailea | `adamw_8bit` |
| Weight decay | 0.01 |
| Hazia | 3407 |
| Hardware | 1 × NVIDIA RTX PRO 6000 Blackwell (96 GB) |

---

## Entrenamendu-datuak

Hiru corpusak `text` eremu bakarrean homogeneizatzen dira, **modeloaren
berezko txat-txantiloia** aplikatuta, eta ausaz nahasten dira (3407 hazia).

### 1. `HiTZ/magpie-en-eu-reasoning-instructions-qwen3` — instrukzioak

`accepted_eu` eta `accepted_en` splitak, bakoitzetik 25 000 adibide (~50 000).
`rejected_*` splitak baztertu egiten dira. Elkarrizketak `messages` eremutik
hartzen dira, txanda bakoitzeko `reasoning_content` kenduta.

### 2. `HiTZ/ALIA_syntethic_MT_V2` — itzulpena

Hiru konfigurazioetako bakoitzetik 5 000 errenkada (`berria_eu_en_es`,
`bopv_eu_en_es`, `parliament_eu_en_es`). Errenkada bakoitzak norabide **bat**
sortzen du, indizearen arabera txandakatuz laurak neurri berean betetzeko:

`eu → es` · `es → eu` · `eu → en` · `en → eu`

`berria` konfigurazioan, SONAR puntuazioa < 0.6 duten itzulpenak baztertzen
dira.

### 3. `HiTZ/RAG_eu` — testuan oinarritzea

`RAG_eu` **ebaluazio-bankua** da, ez entrenamendu-corpusa: ez du erantzunen
zutaberik. Daukan edukitik bi ataza gainbegiratu sortu ziren:

- **Testuan oinarritutako laburpena** — `documents` konfigurazioa (1 492
  dokumentu): `text` → `summary`.
- **Erantzun daitekeen erabakitzea** — `QAP` konfigurazioa (~7 465 pare),
  `documents` konfigurazioarekin `text_id` bidez lotuta, galdera bakoitzari
  benetako testuingurua eransteko.

> ⚠️ **Ebaluazio-kutsadura.** Modeloak `HiTZ/RAG_eu` ikusi du entrenamenduan;
> beraz, **ez da baliozkoa benchmark horrekin ebaluatzea**. RAG_eu gainean
> neurtu behar baduzu, berriro entrenatu `train.py` fitxategian
> `USE_RAG_EU = False` ezarrita.

Guztira, gutxi gorabehera: **~74 000 adibide** (kalitate-iragazkiak aplikatu
eta `text_id` umezurtzak baztertu aurretik).

---

## Prompt-formatuak

Entrenamenduak Qwen3.5 modeloaren berezko txantiloia erabiltzen du
**`enable_thinking=False`** aukerarekin, target guztiak erantzun zuzenak baitira.
Arrazoiketa-moduan horrek duen eragina ikusteko, irakurri mugen atala.

**Itzulpena** — system:

```
Itzultzaile profesionala zara. Eres un traductor profesional.
```

user:

```
Itzuli ondorengo testua euskarara / Traduce el siguiente texto al euskera:
{texto}
```

(erabilitako hizkuntza-helburu pareak hauek izan ziren:
`euskarara`/`al euskera`, `gaztelaniara`/`al español`,
`ingelesera`/`al inglés`)

**Testuan oinarritzea** — system:

```
Laguntzaile zehatza zara. Erantzun emandako testuan oinarrituta soilik.
Eres un asistente preciso. Responde basándote estrictamente en el texto proporcionado.
```

user (laburpena):

```
Testua / Texto:
"""
{texto}
"""

Laburtu testua / Resume el texto.
```

user (erantzun daitekeen erabakitzea):

```
Testua / Contexto:
"""
{contexto}
"""

Galdera / Pregunta: {pregunta}

Testuak galdera erantzun dezake? / ¿Puede el texto responder a la pregunta?
```

**Instrukzio orokorrak**: sistema-mezurik gabe, elkarrizketa zuzena.

---

## Erabilera

### Transformers

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "TU_USUARIO/qwen27b_alia"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, dtype="bfloat16", device_map="auto")

messages = [
    {"role": "system", "content": "Itzultzaile profesionala zara. Eres un traductor profesional."},
    {"role": "user", "content": "Itzuli ondorengo testua euskarara / Traduce el siguiente texto al euskera:\nBuenos días a todos."},
]

inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    enable_thinking=False,   # entrenamenduarekin bat dator
    return_tensors="pt",
).to(model.device)

out = model.generate(inputs, max_new_tokens=512)
print(tokenizer.decode(out[0][inputs.shape[-1]:], skip_special_tokens=True))
```

Arreta linealeko geruzak bizkortzeko:

```bash
pip install flash-linear-attention
```

### GGUF (llama.cpp / Ollama)

**Q4_K_M** esportazio kuantizatu bat ere badago:

```bash
llama-cli -m qwen27b_alia-q4_k_m.gguf -p "..." -cnv
```

---

## Mugak eta alborapenak

- **Ebaluatu gabe.** Ez dago metrikarik. Ez erabili modelo hau produkzioan
  aurrez zeure atazan neurtu gabe.
- **Entrenatu gabeko arrazoiketa.** SFT osoa `enable_thinking=False` aukerarekin
  eta target zuzenekin egin zen. Oinarrizko modeloaren arrazoiketa-modua ez da
  indartu, eta baliteke okerrera egin izana; sortu edukia
  `enable_thinking=False` erabilita, kontrakoa egiaztatu ezean.
- **Ezin da `HiTZ/RAG_eu` erabiliz ebaluatu**, kutsadura dela eta (ikus goian).
- **Epoka bakarra** ~74 000 adibiderekin: estiloaren eta formatuaren doikuntza
  arina da, ez ezagutzaren injekzio sakona.
- **Itzulpen sintetikoa.** `ALIA_syntethic_MT_V2` datu-multzoak automatikoki
  sortutako itzulpenak ditu; haien errore sistematikoak modelora hedatzen dira.
  SONAR iragazkia `berria` partizioari soilik aplikatu zitzaion.
- **Domeinu-alborapena.** Corpusak prentsatik (*Berria*), aldizkari ofizialetik
  (EHAA) eta Eusko Legebiltzarreko aktetatik datoz. Erregistroak formala eta
  instituzionala izateko joera du, eta euskal politika garaikidean ardazten da.
- **Egiaztatu gabeko bide multimodala** (ikus goian).
- Qwen3.8-27B modeloaren alborapenak eta mugak heredatzen ditu.

---

## Lizentzia

Modelo honen lizentzia aukeratzea **ez da erraza**, eta berrikustea komeni da:

- Oinarrizko modeloa, `Qwen3.8-27B`, **Apache-2.0** lizentziapean dago.
- `HiTZ/RAG_eu` eta `HiTZ/ALIA_syntethic_MT_V2` **CC-BY-SA-4.0** dira
  (*share-alike*); `HiTZ/magpie-...-qwen3`, berriz, **CC-BY-4.0** da.

Metadatu hauetan **CC-BY-SA-4.0** ezarri da, interpretazio kontserbadoreari
jarraituz: entrenamendu-datuen *share-alike* baldintza hedatzea. Kontrako
interpretazioa ere badago, pisuak ez direla corpusaren lan eratorria dioena;
kasu horretan, Apache-2.0 nahikoa litzateke. Adostasunik gabeko auzi juridikoa
da. **Erabaki eta egokitu `license` eremua horren arabera.**

Edonola ere, corpusengatik HiTZ aitortu behar da.

---

## Kredituak

- Corpusak: [HiTZ Zentroa](https://huggingface.co/HiTZ) (UPV/EHU), Eusko
  Jaurlaritzak (IKER-GAITU proiektua) eta Eraldaketa Digitalerako Ministerioak /
  NextGenerationEUk (ILENIA eta ALIA proiektuak) finantzatuak.
- Oinarrizko modeloa: Qwen Team,
  [Unsloth](https://huggingface.co/unsloth)ek paketatua.
- Entrenamendua: Unsloth + TRL.