bg-tts-v7/README.md

---
language:
  - bg
  - en
license: apache-2.0
tags:
  - tts
  - text-to-speech
  - speech-synthesis
  - bulgarian
  - miocodec
  - qwen3
pipeline_tag: text-to-speech
base_model: Qwen/Qwen3-0.6B-Base
datasets:
  - custom
---

# BG-TTS-V7 — Българско Text-to-Speech с MioCodec

Open-source TTS модел за български език, базиран на Qwen3-0.6B-Base и MioCodec аудио кодек. Втора версия след [mio-tts-0.6b-bg-finetuned](https://huggingface.co/beleata74/mio-tts-0.6b-bg-finetuned).

## Описание

BG-TTS-V7 е decoder-only езиков модел, дообучен (fine-tuned) да генерира реч от текст на български език. Моделът приема текст в ChatML формат и генерира поредица от аудио токени, които след това се декодират до реч чрез [MioCodec](https://huggingface.co/Aratako/MioCodec-25Hz-24kHz).

Проектът е базиран на [Aratako/MioTTS-0.6B](https://huggingface.co/Aratako/MioTTS-0.6B) — японски TTS модел, чийто подход адаптирахме за български език.

### Оригинален модел

Базиран на **[Qwen/Qwen3-0.6B-Base](https://huggingface.co/Qwen/Qwen3-0.6B-Base)** — pre-trained езиков модел от Alibaba с 608M параметри. Оригиналният Qwen3 tokenizer е разширен с 12,800 специални speech токени (`<|s_0|>` до `<|s_12799|>`), съответстващи на кодбука на MioCodec.

### Какво направихме

1. **Взехме Qwen3-0.6B-Base** с оригиналните pre-trained тегла (разбиране на текст на 100+ езика, включително български)
2. **Добавихме 12,800 speech токена** в tokenizer-а и resize на embedding слоя (151,669 → 164,469 vocab)
3. **Подготвихме 769 часа аудио данни** — български реч, кодирана с MioCodec (25 Hz, 1 codebook, 24 kHz)
4. **Fine-tune** с ChatML формат: текстът е в `user` ролята, speech токените — в `assistant` ролята
5. **Loss само върху speech токените** — моделът учи mapping text → audio, без да разваля текстовото разбиране

### Данни за обучение

| Датасет | Часове | Семпли | Описание |
|---------|--------|--------|----------|
| encoded_dataset_v3 | ~660ч | 292K | Мулти-датасет, български |
| encoded_dataset_v4 | ~49ч | 52K | Чист български (4 източника) |
| encoded_dataset_v4_d12 | ~105ч | 54K | Допълнителен български |
| **Общо** | **~769ч** | **389K** | |

Всички аудио файлове са кодирани с [MioCodec-25Hz-24kHz](https://huggingface.co/Aratako/MioCodec-25Hz-24kHz) — 25 fps, 1 codebook, 12,800 кода.

### Резултати от обучението

- **Training loss**: 4.56 (min)
- **Validation loss**: 5.06 (best @ step 12000)
- **Epochs**: ~2 от 5 (step 12000 от 30,355)
- **Effective batch size**: 64 (4 × 16 gradient accumulation)
- **Learning rate**: 2e-4 (cosine decay, 910 warmup steps)
- **Hardware**: NVIDIA RTX 5090 (32GB VRAM)
- **Време за обучение**: ~8 часа до step 12000

## Как да се ползва

### Подход 1: С MioTTS-Inference (препоръчителен)

Моделът е съвместим с [MioTTS-Inference](https://github.com/Aratako/MioTTS-Inference) — същият inference pipeline като оригиналния MioTTS.

```bash
# 1. Зареди модела с vLLM
python -m vllm.entrypoints.openai.api_server \
  --model beleata74/bg-tts-v7 \
  --dtype bfloat16 \
  --gpu-memory-utilization 0.4 \
  --max-model-len 2048 \
  --port 8000

# 2. Стартирай MioTTS сървъра
cd MioTTS-Inference
MIOTTS_CODEC_MODEL=Aratako/MioCodec-25Hz-24kHz \
MIOTTS_LLM_BASE_URL=http://localhost:8000/v1 \
python run_server.py --host 0.0.0.0 --port 8001

# 3. Стартирай Gradio UI
GRADIO_SERVER_PORT=7861 \
MIOTTS_API_BASE=http://127.0.0.1:8001 \
python run_gradio.py
```

### Подход 2: Директно с transformers

```python
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_name = "beleata74/bg-tts-v7"
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    model_name, torch_dtype=torch.bfloat16, device_map="auto"
)

# ChatML формат: user = текст, assistant = speech токени
text = "Здравейте, как сте днес?"
messages = [{"role": "user", "content": text}]
prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)

inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
output = model.generate(
    **inputs,
    max_new_tokens=500,
    temperature=0.7,
    top_p=0.9,
    repetition_penalty=1.1,
)

# Извлечи speech токени (offset 151669)
generated = output[0][inputs["input_ids"].shape[1]:]
speech_offset = 151669
audio_codes = [t.item() - speech_offset for t in generated 
               if speech_offset <= t.item() < speech_offset + 12800]

# Декодирай с MioCodec
# audio_codes -> numpy array -> MioCodec decode -> wav
```

### Подход 3: Декодиране на audio кодовете до wav

```python
import numpy as np
import torch
from miocodec import MioCodec

codec = MioCodec.from_pretrained("Aratako/MioCodec-25Hz-24kHz")

# audio_codes е списък с MioCodec индекси (0-12799)
codes_tensor = torch.tensor([audio_codes], dtype=torch.long).unsqueeze(0)  # [1, 1, T]
wav = codec.decode(codes_tensor)  # -> [1, 1, num_samples]

import soundfile as sf
sf.write("output.wav", wav[0, 0].cpu().numpy(), 24000)
```

## Архитектура

| Параметър | Стойност |
|-----------|----------|
| Базов модел | Qwen3-0.6B-Base |
| Параметри | 608.9M |
| Hidden size | 1024 |
| Attention heads | 16 (8 KV heads) |
| Layers | 28 |
| Vocab size | 164,469 (151,669 оригинални + 12,800 speech) |
| Max seq length | 2048 |
| Precision | bfloat16 |

## Формат на данните

```
<|im_start|>user
Здравейте, как сте?<|im_end|>
<|im_start|>assistant
<|s_2559|><|s_3752|><|s_2751|>...<|s_1234|><|im_end|>
```

- **User**: Текст на български (subword tokenization от Qwen3)
- **Assistant**: Поредица от MioCodec токени (`<|s_N|>`, N ∈ [0, 12799])
- **Loss**: Изчислява се САМО върху assistant частта (speech + `<|im_end|>`)

## Ограничения

- Обучен предимно на български — може да генерира и английски, но с по-ниско качество
- 769 часа данни е относително малко за TTS задача (MioTTS е обучен на 100K часа)
- Validation loss стига плато при ~5.06 — вътрешна ентропия на MioCodec кодбука
- Кратки думи (2-4 букви) понякога се грешат — alignment проблем при малко контекст
- Не поддържа voice cloning в промпта — speaker характеристиката идва от MioCodec decode

## Благодарности

- **[Aratako/MioTTS-0.6B](https://huggingface.co/Aratako/MioTTS-0.6B)** — оригиналният проект, чийто подход следваме
- **[Aratako](https://huggingface.co/Aratako)** — за MioCodec и MioTTS архитектурата
- **[Qwen Team](https://huggingface.co/Qwen)** — за Qwen3-0.6B-Base
- **[MioTTS-Inference](https://github.com/Aratako/MioTTS-Inference)** — inference pipeline
- **[beleata74/mio-tts-0.6b-bg-finetuned](https://huggingface.co/beleata74/mio-tts-0.6b-bg-finetuned)** — първата ни версия на български TTS

## Лиценз

Apache 2.0 (следва лиценза на Qwen3)