LoRa_Ngoc_Huyen_2.0

<div align="center">

🎤 OmniVoice LoRA V2

Finetune LoRA trên OmniVoice-Vietnamese — Được tinh chỉnh cho giọng nói tiếng Việt (~48 giờ dữ liệu)

---

</div>

📦 Thông số Model

<table align="center"> <tr><th>Tham số</th><th>Giá trị</th></tr> <tr><td><b>Base model</b></td><td><a href="https://huggingface.co/k2-fsa/OmniVoice"><code>k2-fsa/OmniVoice</code></a> (Qwen3-0.6B)</td></tr> <tr><td><b>Phương pháp</b></td><td>LoRA (PEFT) — <code>TaskType.FEATURE_EXTRACTION</code></td></tr> <tr><td><b>Rank / Alpha</b></td><td><b>64 / 128</b> (scale 2.0)</td></tr> <tr><td><b>Target modules</b></td><td><code>q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj</code></td></tr> <tr><td><b>Trainable</b></td><td>~20M / 605M (~3.3%)</td></tr> <tr><td><b>Learning rate</b></td><td><b>1e-5</b> LoRA | <b>5e-5</b> — audio_heads/embeddings (tách param groups)</td></tr> <tr><td><b>Schedule</b></td><td>cosine, warmup 3%</td></tr> <tr><td><b>Epochs</b></td><td>6 (data lớn — tránh overfit)</td></tr> <tr><td><b>Batch</b></td><td>8 × 4 grad-accum = effective 32</td></tr> </table>

📚 Dataset — 3 Nguồn Cùng Giọng (~48h)

✅ Đã verify speaker similarity (Resemblyzer): 0.873 và 0.787 — cùng giọng Ngọc Huyền

<table align="center"> <tr><th>Dataset</th><th>Mẫu</th><th>Nội dung</th><th>Sim với base</th></tr> <tr><td><code>Teedyyy-rm/Voice_Ngoc_Huyen</code></td><td>14,937</td><td>Truyện (Phi Thăng Thất Bại)</td><td>—</td></tr> <tr><td><code>pnnbao-ump/ngochuyen_voice</code></td><td>7,540</td><td>Tin tức</td><td>0.873</td></tr> <tr><td><code>thangnzt/NgocHuyenViVoice</code></td><td>3,776</td><td>Truyện ma</td><td>0.787</td></tr> <tr><td><b>Tổng</b></td><td><b>26,253</b></td><td colspan="2"><b>~48 giờ audio — đa dạng ngữ cảnh</b></td></tr> </table>

🔥 So sánh với OmniVoice GỐC (base model, không finetune)

⚠️ So sánh TRỰC TIẾP với bản OmniVoice-Vietnamese gốc — cùng câu test + cùng voice prompt

<table align="center"> <tr><th>Metric</th><th>OmniVoice GỐC</th><th><b>OmniVoice LoRA V2</b></th><th>Cải thiện</th></tr> <tr><td>Dải giọng nói (100-4000Hz)</td><td>82%</td><td><b>83-91%</b></td><td>✅ Sạch hơn</td></tr> <tr><td>Speaker similarity (giống mồi)</td><td>~0.78</td><td><b>0.85-0.90</b></td><td>✅ <b>+12%</b></td></tr> <tr><td>WER (đọc đúng chữ, câu ngắn)</td><td>~5%</td><td><b>0%</b></td><td>✅ Chuẩn hơn</td></tr> <tr><td>Chất giọng</td><td>Giọng chung chung</td><td><b>Giọng Ngọc Huyền đặc trưng</b></td><td>🎯 Mục tiêu</td></tr> <tr><td>Khả năng clone giọng khác</td><td>✅ Đầy đủ</td><td>✅ <b>Giữ nguyên</b> (LoRA không phá base)</td><td>✅ An toàn</td></tr> </table>

🎯 Vì sao chọn LoRA thay vì Full Finetune?

🔬 Nghiệm thức kỹ thuật (Aug 2)

<details open> <summary><b>🎭 1. Audio Masking đúng chuẩn Flow-Matching</b></summary>

• Che ngẫu nhiên 0-100% token audio = 1024 (audio_mask_id), loss CHỈ trên token bị che
• Prompt 0-30% giữ nguyên không loss — đúng processor.py gốc OmniVoice
• <b>mask_beta=true</b>: dùng Beta(2,1) (mean 0.67) thay vì uniform — model được train NHIỀU hơn ở chế độ mask cao = đúng inference thật (sinh toàn bộ audio từ text) → giảm vang/robot

</details> <details open> <summary><b>🔀 2. Tách Learning Rate — LoRA vs audio_heads/embeddings</b></summary>

→ audio_heads/embeddings là nơi biểu diễn <b>timbre/giọng nói</b> ở tầng ra — LR riêng giúp giọng đích bám mạnh mà LoRA không overfit sớm

</details> <details open> <summary><b>🧠 3. CFG Dropout 10% + Special Tokens</b></summary>

• <code>drop_cond_ratio: 0.1</code> — 10% mẫu mù chữ (text=∅) → guidance_scale 2.0 khuếch đại ĐÚNG text
• Text bọc chuẩn: <code><|lang_start|>vi<|lang_end|>...<|text_start|>{text}<|text_end|></code>
• Text điền cả 8 layers (num_channels)

</details>

📊 Kết quả đo (evaluate_voice.py — 3 trục chuyên nghiệp)

<table align="center"> <tr><th>Trục</th><th>Thư viện</th><th>Cách đo</th><th>Chuẩn tốt</th></tr> <tr><td>1. Độ sạch</td><td>FFT spectral</td><td>% năng lượng 100-4000Hz</td><td>≥70%</td></tr> <tr><td>2. Giống giọng</td><td>Resemblyzer / ECAPA-TDNN</td><td>Cosine similarity vs voice prompt</td><td>≥0.75 (cùng giọng)</td></tr> <tr><td>3. Đúng chữ</td><td>faster-whisper</td><td>WER transcript vs text gốc</td><td>&lt;10%</td></tr> </table>

🚀 Cách Load & Sử dụng

<details open> <summary><b>💻 Python — load adapter + generate</b></summary>

import torch, pickle
import omnivoice
from peft import PeftModel

# 1. Load base + chuyển GPU TRƯỚC khi wrap PEFT
m = omnivoice.OmniVoice.from_pretrained(
    "splendor1811/omnivoice-vietnamese",
    torch_dtype=torch.float16,
)
m = m.to("cuda")
if hasattr(m, "audio_tokenizer"):
    m.audio_tokenizer = m.audio_tokenizer.to("cpu")  # tiết kiệm VRAM

# 2. Patch + load LoRA adapter
if not hasattr(m.llm, "prepare_inputs_for_generation"):
    m.llm.prepare_inputs_for_generation = lambda **kw: kw
m.llm = PeftModel.from_pretrained(
    m.llm, "Teedyyy-rm/Omnivoice_Lora_v2/adapters/checkpoint-XXX"
)
torch.cuda.empty_cache()

# 3. Load audio_specific — THIẾU = NHIỄU! (missing=1230, unexpected=0 = OK)
audio_sd = torch.load("audio_specific.pt", map_location="cpu", weights_only=True)
m.load_state_dict(audio_sd, strict=False)

# 4. Voice prompt + generate
vp = pickle.load(open("voice_prompt.pkl", "rb"))  # 8-15s audio giọng Ngọc Huyền
with torch.inference_mode():
    audio = m.generate(
        text="Xin chào các bạn!",
        voice_clone_prompt=vp,
        language="vi",
        num_step=48,          # diffusion steps (64-100 nếu muốn mượt hơn)
        guidance_scale=2.0,   # model có CFG dropout → 2.0 hoạt động tối ưu
    )

</details>

⚙️ Hướng dẫn Chạy Chuyên Nghiệp

<details open> <summary><b>🛠️ 1. Clone code & cài môi trường</b></summary>

git clone https://github.com/Teedyyy-rm/omnivoice-ngochuyen-lora.git
cd omnivoice-ngochuyen-lora

# V100 (16GB): cài tự động mọi thứ
bash setup_v100.sh
# → venv /root/venv_lora + torch 2.6.0+cu126 (BẮT BUỘC cho V100 sm_70)
# → base model + dataset tự clone

</details> <details open> <summary><b>🚀 2. Chạy training</b></summary>

# Train COMBINED 3 dataset (config có sẵn trong script)
bash start_train_combined.sh
# hoặc trực tiếp:
source /root/venv_lora/bin/activate
python3 train_lora.py --dataset combined --config config_combined.yaml

# ⚠️ PHẢI chạy trong tmux (SSH đóng không kill):
tmux attach -t train        # xem log realtime (Ctrl+B rồi D để thoát)
tail -f /root/train_lora.log

</details> <details open> <summary><b>🧪 3. Test & đánh giá checkpoint giữa chừng</b></summary>

# Adapter tự push lên HF mỗi nửa epoch → tải về test ngay
python3 validate_lora.py \
    --lora_path Teedyyy-rm/Omnivoice_Lora_v2/adapters/checkpoint-390 \
    --voice_prompt voice_prompt.pkl \
    --text "Xin chào các bạn!" \
    --output test.wav

# Đánh giá 3 trục (sạch + giống giọng + đúng chữ)
python3 evaluate_voice.py \
    --wav test.wav \
    --ref_wav voice_prompt_source.wav \
    --text "Xin chào các bạn!"

</details> <details open> <summary><b>🔁 4. Tinh chỉnh tham số (config.yaml — KHÔNG cần sửa code)</b></summary>

# config_combined.yaml
training:
  learning_rate: 1e-5        # LoRA (chuẩn tác giả)
  audio_lr: 5e-5             # audio_heads/embeddings (tách LR)
  lora_rank: 64
preprocess:
  mask_beta: true            # mask thiên cao — đúng chế độ inference
  drop_cond_ratio: 0.1       # CFG dropout — guidance hoạt động

Ưu tiên: <code>CLI --dataset</code> > <code>config.yaml</code> > default code

</details>

---

📁 Cấu trúc Checkpoint

Teedyyy-rm/Omnivoice_Lora_v2/
├── adapters/checkpoint-{step}/     ← push tự động mỗi nửa epoch (PushAdapterOnSave)
│   ├── adapter_config.json         ← đã sanitize (peft 0.20 → 0.12 tương thích)
│   ├── adapter_model.safetensors   ← LoRA weights (~160MB, rank 64)
│   └── audio_specific.pt           ← audio_embeddings + audio_heads (~67MB) ⚠️ BẮT BUỘC
└── README.md

⚠️ Luôn tải đủ audio_specific.pt — thiếu file này model sinh nhiễu hoàn toàn. ⚠️ Chọn checkpoint bằng NGHE + 3 trục metric — eval_loss thấp nhất ≠ giọng hay (overfit).

---

<div align="center">

Repo PRIVATE — chỉ dành cho Teedyyy-rm 🔒 © 2026 — OmniVoice LoRA V2 (Ngọc Huyền)

</div>