Metadata-Version: 2.4
Name: bengo
Version: 0.3.0
Summary: Fine-tune causal language models from one YAML file, on one GPU
Author-email: saidabror552@gmail.com
License-Expression: MIT
Keywords: fine-tuning,lora,qlora,peft,llm,transformers,quantization,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7,>=6
Requires-Dist: rich<16,>=13
Requires-Dist: torch<3,>=2.6
Requires-Dist: transformers<5,>=4.51
Requires-Dist: peft<0.19,>=0.15
Requires-Dist: accelerate<2,>=1.6
Requires-Dist: datasets<5,>=3.5
Provides-Extra: qlora
Requires-Dist: bitsandbytes<0.50,>=0.45.5; extra == "qlora"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

# bengo

Matnli causal language modellarni **full fine-tuning**, **LoRA** yoki **4-bit QLoRA** orqali o‘qitish uchun Python kutubxona. Python API va YAML konfiguratsiyali CLI mavjud.

Bu 0.3 versiya: Transformers + PEFT + bitsandbytes ustidagi sodda boshqaruv qatlami. Yangi quantization algoritmi emas. Faqat bir process va bir CPU yoki NVIDIA CUDA GPU qo‘llanadi. TTS, diffusion, vision, encoder-only va encoder-decoder modellar bu versiya doirasiga kirmaydi.

## O‘rnatish

Python 3.10+ bilan yangi virtual muhit yarating. Buyruqlarni loyiha papkasida bajaring:

```bash
python -m venv .venv
# Linux / WSL2:
source .venv/bin/activate
# Windows PowerShell uchun yuqoridagi satr o‘rniga:
# .\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
```

Avval tizimingizga mos PyTorch’ni [rasmiy o‘rnatish sahifasi](https://pytorch.org/get-started/locally/) orqali o‘rnating. GPU uchun CUDA-enabled build kerak. Keyin:

```bash
python -m pip install -e ".[qlora]"
bengo doctor
```

`bengo doctor` PyTorch, CUDA, GPU, VRAM, bf16, bitsandbytes va disk holatini bitta jadvalda ko‘rsatadi va yetishmayotgan narsa uchun aniq buyruq beradi.

Faqat full/LoRA uchun `python -m pip install -e .` yetarli. QLoRA qo‘shimchasi bitsandbytes’ni o‘rnatadi. Linux/WSL2 + NVIDIA GPU bu loyihaning dastlabki maqsadli muhiti. Mac MPS, ROCm, CPU quantization va multi-GPU backendlar implementatsiya qilinmagan.

PyPI’da chop etilmagan: `pip install bengo` deb o‘rnatishni taxmin qilmang. ZIP ichidagi manbadan yuqoridagicha o‘rnating.

## Python API

```python
from bengo import FineTuner, TrainConfig

config = TrainConfig(
    model_name="Qwen/Qwen2.5-1.5B-Instruct",
    dataset="examples/train.jsonl",
    dataset_format="alpaca",
    method="qlora",                   # "full", "lora", "qlora"
    output_dir="outputs/my-model",
    max_length=512,
    batch_size=1,
    gradient_accumulation_steps=16,
    lora_rank=8,
    lora_alpha=16,
    epochs=1,
)

metrics = FineTuner(config).train()
print(metrics)
```

`FineTuner(config, callbacks=[...])` ixtiyoriy Transformers `TrainerCallback` ro‘yxatini qabul qiladi; CLI o‘z progress ekranini shu orqali ulaydi. Callback berilganda `FineTuner` o‘zi hech nima chop etmaydi.

Model identifikatori namuna sifatida berilgan; model hajmi, sifati yoki muayyan GPU’da sig‘ishi kafolatlanmaydi. `model_name` mahalliy model papkasi ham bo‘lishi mumkin. Birinchi yuklashda model fayllari internetdan olinadi. Yopiq model bo‘lsa uning kirish ruxsati va mahalliy Hugging Face login’i talab qilinadi. `revision`ga commit SHA berish bazaviy model versiyasini mahkamlashga yordam beradi.

## CLI

Argumentsiz `bengo` buyruqlar ro‘yxatini va qisqa yo‘lni ko‘rsatadi.

| Buyruq | Vazifasi |
|---|---|
| `bengo doctor` | Muhitni tekshiradi: PyTorch, CUDA build, GPU, VRAM, bf16, bitsandbytes, disk. Har bir muammoga yechim beradi. |
| `bengo init` | Savol-javob orqali `bengo.yaml` yaratadi. GPU aniqlanib, mos retsept oldindan tanlanadi. |
| `bengo check` | Konfiguratsiyani tekshiradi, datasetni sanaydi, birinchi qatorni ko‘rsatadi, qadamlar sonini hisoblaydi. |
| `bengo estimate` | Model shakli bo‘yicha VRAM sarfini qismlarga ajratib hisoblaydi va sig‘masa aniq tavsiya beradi. |
| `bengo presets` | Tayyor kam-xotira retseptlari; kartangizga mos bo‘lgani belgilanadi. |
| `bengo train` | Jonli progress, loss trendi, learning rate, epoch va VRAM ko‘rsatkichi bilan o‘qitadi. |
| `bengo chat` | O‘qitilgan adapter yoki modelni darhol sinab ko‘rish. |
| `bengo merge` | Adapterni bazaviy modelga CPU’da qo‘shadi. |

Odatiy yo‘l:

```bash
bengo doctor          # muhit tayyormi
bengo init            # bengo.yaml yaratish
bengo check           # sozlama va dataset to‘g‘rimi
bengo estimate        # VRAM yetadimi
bengo train           # o‘qitish
bengo chat outputs/run
```

Xatoda CLI 1, sintaksis xatosida 2, Ctrl+C’da 130 exit code qaytaradi. `doctor` muhim komponent yetishmasa 1 qaytaradi, shuning uchun uni CI’da ishlatish mumkin.

### Interfeys tili

Standart til — ingliz. O‘zbekcha uchun `--lang uz` yoki `BENGO_LANG=uz`:

```bash
BENGO_LANG=uz bengo check
bengo train --lang uz
```

Umumiy flaglar: `--lang {en,uz}`, `--no-color` (rang va chizmalarsiz), `-q/--quiet` (faqat xato va yakuniy natija). `NO_COLOR` muhit o‘zgaruvchisi ham hisobga olinadi. Terminal UTF-8 qo‘llamasa, CLI avtomatik ASCII ko‘rinishga o‘tadi.

### Konfiguratsiyani buyruq satridan almashtirish

`check`, `estimate` va `train` YAML qiymatlarini faqat shu run uchun almashtiruvchi flaglarni qabul qiladi:

```bash
bengo train --method lora --epochs 3 --lr 1e-4
bengo train --max-length 256 --lora-rank 4        # xotira yetmasa
bengo estimate --params 7 --vram 8                # hali modeli yo‘q holda reja
bengo train --set lora_dropout=0.1 --set seed=7   # istalgan kalit uchun
```

`--set` YAML skalyar sintaksisini ishlatadi, shuning uchun `true`, `false`, `null` va sonlar to‘g‘ri o‘qiladi. Noto‘g‘ri kalit yozilsa CLI yaqin variantni taklif qiladi. Buyruq satridagi nisbiy yo‘llar **joriy ishchi papkaga** nisbatan olinadi, YAML ichidagilar esa **YAML fayli papkasiga** nisbatan.

Ustuvorlik tartibi: YAML → `--preset` → alohida flaglar → `--set`.

### Kam-xotira retseptlari

```bash
bengo presets                  # ro‘yxat, kartangizga mosi belgilangan holda
bengo init --preset 8gb        # shu sozlamalar bilan YAML yaratish
bengo train --preset 12gb      # faqat shu run uchun
```

| Retsept | Mo‘ljal |
|---|---|
| `cpu` | GPU yo‘q: sinov va juda kichik modellar |
| `6gb` | ~7B gacha, 256 token |
| `8gb` | ~8B gacha, 512 token |
| `12gb` | ~14B gacha, 1k token |
| `16gb` | ~20B gacha, 1k token |
| `24gb` | ~34B gacha, 1k token |
| `48gb` | ~48B gacha, 2k token |

Har bir retsept `bengo estimate` bilan bir xil hisob-kitobda o‘z byudjetiga sig‘ishi testda tekshiriladi. Bu baribir hisob, kafolat emas.

### VRAM hisobi

```bash
bengo estimate
bengo estimate --vram 12 --method qlora --max-length 1024
bengo estimate --params 34 --vram 24            # model hajmini qo‘lda berish
```

Model hajmi avval mahalliy `config.json`dan, keyin Hugging Face Hub’dan, bo‘lmasa model nomidan (`...-7B-...`) olinadi. Hech biri ishlamasa `--params` bering. Natija bazaviy og‘irliklar, o‘qitiladigan parametrlar, gradientlar, optimizer holati, aktivatsiyalar, logitlar va CUDA overhead bo‘yicha ajratiladi. Sig‘masa CLI qaysi sozlamani qanchaga tushirish kerakligini aytadi.

Hisob SDPA attention, bitta qurilma va bitta processni nazarda tutadi. Kernel tanlovi va allocator xatti-harakati haqiqiy cho‘qqini siljitadi.

### Trening ekrani

`bengo train` ishga tushganda konfiguratsiya jadvali, VRAM taxmini va jonli progress ko‘rsatiladi: bajarilgan qadamlar, foiz, o‘tgan va qolgan vaqt, joriy loss va uning trendi, learning rate, epoch, GPU xotirasi cho‘qqisi va saqlangan checkpoint. Tugaganda yakuniy metrikalar, saqlangan yo‘l va keyingi buyruqlar chiqadi.

Model yuklanishidan oldin barcha tekshiruvni bajarish uchun:

```bash
bengo train --dry-run
```

### O‘qitilgan modelni sinash

```bash
bengo chat outputs/run
bengo chat outputs/run --prompt "Fine-tuning nima?" --temperature 0
```

`chat` output papkadagi `bengo.yaml` nusxasidan `dataset_format`ni o‘qiydi va treningdagi prompt formatini aynan takrorlaydi. QLoRA adapteri uchun baza 4-bit holatda yuklanadi. Javob oqim (streaming) ko‘rinishida chiqadi. Chiqish: `/exit` yoki Ctrl+C.

### bengo init — savol-javob

Argumentsiz `bengo init` oltita savol beradi. Har birida tayyor javob qavs ichida turadi; rozi bo‘lsangiz Enter bosing:

```
  Base model (Hugging Face ID or local folder) (Qwen/Qwen2.5-1.5B-Instruct):
  Training data (.jsonl, .json, .parquet, or a dataset ID) (./train.jsonl):
  Dataset format [alpaca/prompt_completion/text/messages] (alpaca):
  Training method [qlora/lora/full] (qlora):
  Output folder (./outputs/run):
  Memory recipe [cpu/6gb/8gb/12gb/16gb/24gb/48gb] (8gb):
```

Retsept GPU’ingizga qarab oldindan tanlanadi. Savollarga bergan javobingiz retsept qiymatidan ustun turadi: `12gb` retseptini tanlab, `method` savoliga `lora` desangiz, `lora` qoladi.

Javoblarni oldindan berish ham mumkin — bu holda faqat qolgan savollar so‘raladi:

```bash
bengo init --model Qwen/Qwen2.5-7B-Instruct --dataset ./data/train.jsonl --format messages
bengo init --preset 8gb --yes          # hech narsa so‘ramaydi, standart qiymatlar
```

`--yes` bilan savollar butunlay o‘tkazib yuboriladi. Skript yoki CI ichida stdin bo‘lmasa, `init` osib qolmaydi: birinchi savolda EOF olib, standart qiymatlar bilan davom etadi. Yarim yo‘lda Ctrl+C bossangiz, shu paytgacha bergan javoblaringiz saqlanadi.

`init` faqat konfiguratsiya yaratadi — datasetni yaratmaydi va mavjud faylni qayta yozmaydi.

### bengo.yaml

Barcha trening sozlamalari `bengo.yaml`da saqlanadi. `train`, `check` va `estimate` hech qanday argumentsiz chaqirilsa, **joriy papkadagi `bengo.yaml`** ni o‘qiydi — `--config` berish shart emas:

```bash
bengo train                    # ./bengo.yaml
bengo train boshqa.yaml        # aniq fayl
bengo train --config boshqa.yaml   # xuddi shu, uzunroq shakli
```

Namuna:

```yaml
model_name: Qwen/Qwen2.5-1.5B-Instruct
dataset: ./examples/train.jsonl
dataset_format: alpaca
output_dir: ./outputs/my-model
method: qlora                 # full | lora | qlora
max_length: 512
batch_size: 1
gradient_accumulation_steps: 16
learning_rate: 2e-4
epochs: 1
lora_rank: 8
lora_alpha: 16
gradient_checkpointing: true
precision: auto
resume_from_checkpoint: null
```

```bash
bengo train --config custom.yaml
bengo check custom.yaml
bengo train --resume outputs/my-model/checkpoint-100
bengo merge outputs/my-model outputs/merged
bengo --version
```

`python -m bengo` ham shu buyruqlarni qo‘llaydi. `check` konfiguratsiyani tekshiradi, model yoki VRAM mosligini kafolatlamaydi — buning uchun `bengo estimate` va `bengo doctor` bor. Nisbiy konfiguratsiya yo‘llari **YAML faylining papkasiga** nisbatan olinadi. Model/dataset Hub ID’lari o‘zgarmaydi; mahalliy model papkasini aniq ko‘rsatish uchun `./models/my-model` kabi yo‘l bering. `--resume` override va `merge` argumentlari joriy ishchi papkaga nisbatan olinadi.

YAML’dagi `resume_from_checkpoint`ni checkpoint papkasiga o‘zgartirib, oddiy `bengo train` bilan ham davom ettirish mumkin. Har bir run output papkasida ishlatilgan sozlamalarning `bengo.yaml` nusxasi saqlanadi; Transformers model konfiguratsiyasi va checkpoint holati o‘z standart fayllarida qoladi.

Takroriy kalitlar, noma’lum parametrlar va noto‘g‘ri turlar rad etiladi. `true` / `false` qiymatlarini qo‘shtirnoqsiz yozing. 4 qatorli namuna dataset faqat sinash uchun.

0.2 versiyadan o‘tish: `bengo.yaml` formati va Python API o‘zgarmadi, mavjud konfiguratsiyalar ishlayveradi. Yangi bog‘liqlik — `rich`; `pip install -e .` uni o‘zi o‘rnatadi. `bengo check` endi dataset fayli topilmasa 1 qaytaradi. `FineTuner(config, callbacks=[...])` ixtiyoriy Trainer callback’larini qabul qiladi.

0.1 versiyadan o‘tish: import `bengo`, terminal buyrug‘i `bengo`; eski JSON sozlamalarni YAML’ga ko‘chiring. Bu versiya checkpoint parent papkasida `bengo.yaml` kutadi. Eski `auto_traine_config.json`ni YAML’ga aylantirib shu nom bilan saqlash kerak. Bazaviy trening parametrlari o‘zgarmasin.

## Rejimlar

| Rejim | Yangilanadigan parametrlar | Bazaviy og‘irliklar | Yakuniy fayllar |
|---|---|---|---|
| `full` | Barcha parametrlar | FP32 master weights, tanlangan autocast | To‘liq model + tokenizer |
| `lora` | LoRA adapterlari | Quantization qilinmagan; tanlangan dtype | Adapter + tokenizer |
| `qlora` | LoRA adapterlari | NF4 4-bit + double quantization | Adapter + tokenizer |

Full rejimda FP32 master parametrlar FP16 GradScaler bilan ishlashni ta’minlaydi, lekin ko‘proq xotira sarflaydi. `precision="auto"` CUDA’da mavjud bo‘lsa BF16, aks holda FP16 tanlaydi; CPU’da FP32 ishlatadi. Full rejim learning rate’i odatda `2e-5`, adapter rejimlarida `2e-4`; bular boshlang‘ich qiymatlar.

`warmup_ratio=0.0` standart qiymat: juda qisqa sinovda yagona optimizer qadami nol learning rate bilan o‘tib ketmaydi. Uzoq trening uchun masalan `warmup_ratio=0.03`ni alohida tanlashingiz mumkin.

Full/LoRA uchun original, quantization qilinmagan checkpoint bering. Oldindan AWQ/GPTQ bilan siqilgan modellarni bu API orqali full fine-tuning qilish qo‘llanmaydi. QLoRA uchun ham bazaviy original checkpoint bering: bitsandbytes uni yuklash vaqtida quantization qiladi.

## Qaysi resurs bilan qaysi model

Quyidagi raqamlar — **arifmetika, o‘lchov emas**. Model shakli va run sozlamalaridan hisoblangan; profiler bilan solishtirilmagan. Kernel tanlovi, kutubxona versiyasi va xotira fragmentatsiyasi haqiqiy cho‘qqini ±15–20% siljitadi. Chegaraga yaqin holatlarda yagona ishonchli tekshiruv — haqiqatan ishga tushirib ko‘rish.

### Avval: kartangiz nechta GB beradi

8 GB karta 8 GB bermaydi. Ish stoli, brauzer va displey drayveri 0.5–1.5 GB oladi:

| Holat | Haqiqiy foydalanish uchun |
|---|---|
| Windows + monitor ulangan | karta hajmining ~80–85% |
| Linux desktop | ~85–90% |
| Linux headless (monitor yo‘q) | ~95% |
| Bulut GPU (runpod, vast.ai) | ~95% |

Ya’ni 8 GB Windows kartasi amalda ~6.5–7 GB beradi. Jadvalni shu tuzatish bilan o‘qing.

### QLoRA bilan taxminiy cho‘qqi

`batch_size: 1`, `lora_rank: 8`, `gradient_checkpointing: true`, paged AdamW 8-bit. Ustunlar — `max_length`:

| Model | Aniq param | 512 | 1024 | 2048 | 4096 |
|---|---|---|---|---|---|
| 0.5B | 0.5B | 1.7 GB | 2.2 GB | 3.3 GB | 5.3 GB |
| 1.5B | 1.5B | 2.5 GB | 3.1 GB | 4.1 GB | 6.3 GB |
| 3B | 3.1B | 3.5 GB | 4.1 GB | 5.3 GB | 7.6 GB |
| 8B | 8.0B | 7.2 GB | 7.8 GB | 8.9 GB | 11.3 GB |
| 9B | 9.1B | 8.0 GB | 9.0 GB | 11.0 GB | 14.9 GB |
| 12B | 12.7B | 10.1 GB | 10.8 GB | 12.2 GB | 14.9 GB |
| 14B | 14.8B | 11.7 GB | 12.5 GB | 14.0 GB | 17.2 GB |
| 27B | 27.4B | 18.2 GB | 19.3 GB | 21.6 GB | 26.1 GB |
| 32B | 32.8B | 21.3 GB | 22.2 GB | 24.0 GB | 27.6 GB |
| 70B | 70.6B | 42.0 GB | 43.2 GB | 45.6 GB | 50.3 GB |

Har bir qator zamonaviy modellar shakli bo‘yicha hisoblangan: GQA va katta lug‘at (128k–256k token). Eski, 32k lug‘atli modellar (Llama-2 avlodi) shu hajmda 1.5–2.5 GB kamroq oladi.

### Karta bo‘yicha xulosa

| Karta | Bemalol | Tor, lekin mumkin | Sig‘maydi |
|---|---|---|---|
| 6 GB | 3B gacha | 7–8B, `max_length 256`, headless | 9B va undan katta |
| 8 GB | 3B, 512–2048 token | 8B, `max_length 512`, headless Linux | 12B va undan katta |
| 12 GB | 8B, 1024 token | 9–12B, `max_length 512` | 14B va undan katta |
| 16 GB | 12B, 1024 token | 14B, `max_length 1024` | 27B va undan katta |
| 24 GB | 14B, 2048 token | 27–32B, `max_length 512` | 70B |
| 48 GB | 32B, 2048 token | 70B — juda tor, tavsiya etilmaydi | — |
| 80 GB | 70B, 1024 token | 70B, 4096 token | — |

Amaliy chegaralar: **8 GB → ~8B**, **12 GB → ~12B**, **24 GB → ~32B**. 8 GB kartada 12B modelni sozlamalar bilan sig‘dirib bo‘lmaydi — muammo bazaviy og‘irliklarda, batch yoki kontekstda emas.

### Lug‘at hajmi kutilmagan tarzda muhim

bitsandbytes `nn.Embedding` va `lm_head`ni **4-bit qilmaydi** — ular 16-bit holatda qoladi. Shuning uchun katta lug‘atli model ancha ko‘proq joy oladi. Bir xil 12B sinfidagi modellar, `max_length 512`, `rank 8`:

| Model turi | Embedding parametrlari | Taxminiy cho‘qqi |
|---|---|---|
| 12B, lug‘at 32k (eski avlod) | 0.33B | 7.8 GB |
| 12B, lug‘at 131k (Mistral-Nemo turi) | 1.34B | 10.1 GB |
| 12B, lug‘at 262k (Gemma-3 turi) | 1.01B | 9.3 GB |

Farq 2.3 GB gacha — bu 8 GB va 12 GB karta orasidagi farqdan katta. Model tanlayotganda `config.json` dagi `vocab_size`ga qarang.

### Nima yordam beradi, nima bermaydi

8B model, QLoRA, `max_length 512`, `rank 8` — 7.2 GB dan boshlab:

| O‘zgarish | Ta’siri |
|---|---|
| `gradient_checkpointing: false` | **+2.5 GB** — hech qachon o‘chirmang |
| `batch_size: 2` | +0.6 GB |
| `max_length: 256` | −0.3 GB |
| `lora_rank: 4` | −0.1 GB |
| `gradient_accumulation_steps` ni 64 ga oshirish | **0.0 GB** — xotiraga umuman ta’sir qilmaydi |

Eng ko‘p tarqalgan xato — xotira yetmaganda `gradient_accumulation_steps` ni oshirish. U faqat effektiv batch’ni oshiradi; microbatch xotirasi o‘zgarmaydi. `lora_rank` ni tushirish ham katta modellarda deyarli befoyda: asosiy xarajat og‘irliklarda (5.3 GB), adapterda emas (0.08 GB).

Haqiqiy richaglar, ta’sir kuchi bo‘yicha: **model hajmini kichraytirish** → **`method: qlora`** → **`max_length`** → **`batch_size`**.

### Metod tanlash

Bir xil 8B model, `max_length 512`, `batch 1`:

| Rejim | Bazaviy og‘irliklar | Gradientlar | Optimizer | Jami |
|---|---|---|---|---|
| `qlora` | 5.3 GB (4-bit NF4) | 0.08 GB | 0.04 GB | **7.2 GB** |
| `lora` | 15.0 GB (16-bit) | 0.08 GB | 0.16 GB | **17.5 GB** |
| `full` | 29.9 GB (FP32) | 29.9 GB | 59.8 GB | **128.2 GB** |

`full` rejim parametr boshiga 16 bayt talab qiladi (FP32 og‘irlik + gradient + Adam’ning ikki holati). Bu 7–8B modellar uchun bitta consumer kartada amalda imkonsiz. `full` faqat eng kichik modellar uchun mantiqiy:

| Model | `full` | `lora` | `qlora` |
|---|---|---|---|
| 0.5B | 9.1 GB | 2.3 GB | 1.7 GB |
| 1.5B | 25.7 GB | 4.5 GB | 2.5 GB |
| 8B | 128.2 GB | 17.5 GB | 7.2 GB |

Ya’ni 24 GB kartada ham to‘liq fine-tuning uchun amaliy chegara — taxminan **1B parametr**.

`lora` (quantization qilinmagan 16-bit baza) faqat GPU’ingiz modelning to‘liq 16-bit nusxasini ko‘tara olsa foydali — buning evaziga 4-bit quantization xatosi bo‘lmaydi.

### O‘z modelingiz uchun tekshirish

Jadvalga emas, aniq modelingizning `config.json`iga tayaning:

```bash
bengo doctor                                              # karta va muhit
bengo estimate --model Qwen/Qwen2.5-7B-Instruct --vram 8  # aniq model
bengo estimate --params 12 --vram 8                       # faqat hajm ma'lum bo'lsa
```

`--model` berilsa, hajm va lug‘at model konfiguratsiyasidan o‘qiladi — bu jadvaldagi umumlashtirishdan aniqroq. `--params` esa umumiy shakldan foydalanadi va lug‘at kattaligini hisobga olmaydi, shuning uchun optimistik chiqadi.

### Sig‘masa nima qilish mumkin

1. **Kichikroq model.** Ko‘p vazifada yaxshi fine-tune qilingan 7B, yomon fine-tune qilingan 13B dan ustun.
2. **Kontekstni qisqartirish.** Datasetingizdagi qatorlar qancha token ekanini bilmasangiz, `bengo check` birinchi qatorni ko‘rsatadi.
3. **Karta ijaraga olish.** 24 GB karta soatiga arzon; bir necha soatlik trening uchun eng oddiy yo‘l.
4. **Boshqa vosita.** CPU/NVMe offload, DeepSpeed ZeRO, FSDP va multi-GPU bu versiyada **implementatsiya qilinmagan**. 12B ni 8 GB kartada o‘qitish shu texnikalarni talab qiladi; ular bor loyihalarga (unsloth, axolotl + DeepSpeed) murojaat qiling.

## Kichik resurs bilan ishlash

Standart sozlamalar: microbatch 1, 512 token, LoRA rank 8, gradient checkpointing, dynamic padding, QLoRA’da paged AdamW 8-bit.

- **4-bit NF4** bazaviy og‘irliklarni ixcham saqlaydi; barcha trening xotirasi 4-bitga aylanmaydi.
- **Gradient checkpointing** oraliq aktivatsiyalarni qayta hisoblab, xotira sarfini kamaytiradi; treningni sekinlashtirishi mumkin.
- **Gradient accumulation** bir necha kichik batch gradientini yig‘adi. Bitta GPU’da effective batch = `batch_size × gradient_accumulation_steps`.
- **Dynamic padding** batch ichidagi eng uzun qatorgacha to‘ldiradi. Har bir qator doim `max_length`gacha to‘ldirilmaydi.
- **Streaming** datasetni butunlay RAM’ga yuklamasdan o‘qiydi; model VRAM talabini kamaytirmaydi. Streaming uchun `max_steps` shart, evaluation bu rejimda o‘chiq.

Qaysi sozlamani o‘zgartirishni taxmin qilmaslik uchun avval hisoblang:

```bash
bengo estimate                 # joriy konfiguratsiya, aniqlangan GPU bilan
bengo estimate --vram 8        # mo‘ljaldagi karta uchun
bengo presets                  # tayyor retseptlar
```

Qaysi model qaysi kartaga sig‘ishi va qaysi richag qancha beradi — yuqoridagi [Qaysi resurs bilan qaysi model](#qaysi-resurs-bilan-qaysi-model) bo‘limida.

Muhim nuqta: 4-bit quantization faqat bazaviy og‘irliklarni ixchamlaydi. 7 milliard parametrning xom 4-bit og‘irligi taxminan 3.5 GB; quantization metadata, siqilmagan embedding va lm_head, adapter, optimizer, aktivatsiyalar, logitlar va CUDA konteksti uchun bundan tashqari xotira kerak. Bu 7B model 3.5 GB VRAM’da o‘qitiladi degani emas.

CPU/RAM/NVMe offload, DeepSpeed ZeRO va FSDP bu versiyada yo‘q. Shu sababli kichik GPU’da istalgan katta modelni o‘qitish va’da qilinmaydi. Bir nechta GPU ko‘rinsa, ishga tushirishdan oldin bittasini tanlang:

```bash
CUDA_VISIBLE_DEVICES=0 bengo train bengo.yaml
```

## Dataset formatlari

Mahalliy `.jsonl`, JSON array `.json`, `.parquet` yoki Hugging Face dataset ID qo‘llanadi. Dataset ID uchun `dataset_config` va `split` berish mumkin. Har bir qator mustaqil misol; packing yo‘q. Uzun qatorlar o‘ng tomondan `max_length`gacha kesiladi. Javob tokenlari umuman qolmasa xato qaytariladi; bunday qatorni qisqartiring yoki limitni oshiring.

**Alpaca** — instruction/input maskalanadi, faqat output va oxirgi EOS loss’ga kiradi:

```json
{"instruction":"Fine-tuning nima?","input":"","output":"Oldindan o‘qitilgan modelni vazifaga moslashtirish."}
```

**Prompt/completion** — `dataset_format="prompt_completion"`; loss faqat completion va EOS uchun:

```json
{"prompt":"Savol: 2 + 2?\nJavob: ","completion":"4"}
```

**Text** — `dataset_format="text"`; barcha matn tokenlariga causal loss:

```json
{"text":"O‘zbek tili haqida foydali matn..."}
```

**Messages** — `dataset_format="messages"`; tokenizer’ning o‘z chat template’i ishlatiladi. Ushbu versiyada system/user/assistant tokenlarining **barchasi** loss’ga kiradi, assistant-only masking yo‘q:

```json
{"messages":[{"role":"user","content":"Salom"},{"role":"assistant","content":"Assalomu alaykum!"}]}
```

Alpaca formatida `### Instruction:`, ixtiyoriy `### Input:`, `### Response:` sarlavhalari ishlatiladi. Inference’da ham ayni prompt formatidan foydalaning; chat template bilan almashtirmang. Prompt va javob alohida tokenize qilinadi — loss chegarasi aniq bo‘ladi, lekin birlashtirib tokenize qilish natijasi ayrim tokenizerlarda farq qilishi mumkin.

Katta dataset uchun:

```python
config = TrainConfig(
    model_name="YOUR_MODEL_ID",
    dataset="YOUR_DATASET_ID",
    dataset_format="text",
    streaming=True,
    max_steps=1000,
)
```

Streaming bo‘lmasa `eval_dataset="validation.jsonl"` orqali alohida validation set bering. Evaluation `save_steps` oralig‘ida validation loss hisoblaydi. Train va validation ma’lumotlari takrorlanmasin. Eng yaxshi checkpoint avtomatik tanlanmaydi.

## Checkpoint va qayta davom ettirish

Har `save_steps` optimizer qadamida `checkpoint-N` yoziladi. Gradient accumulation ichidagi har microbatch checkpoint qadami hisoblanmaydi. So‘nggi `save_total_limit=2` checkpoint saqlanadi. Trening tugaganida root output papkaga model/adapter, tokenizer, konfiguratsiya va metrics yoziladi.

```python
FineTuner(config).train(resume_from_checkpoint="outputs/my-model/checkpoint-100")
```

Resume uchun `checkpoint-N` ichidagi optimizer/scheduler/RNG holati va uning parent papkasidagi `bengo.yaml`ni saqlang. Yakuniy adapter papkasining o‘zi exact resume checkpoint emas. Asosiy konfiguratsiya mosligi tekshiriladi; odatda o‘sha konfiguratsiyani qayta ishlating. Avvaldan to‘ldirilgan output papka yangi treningda qayta yozilmaydi. Streaming’da bitma-bit bir xil davom etish kafolatlanmaydi.

## Adapterni ishlatish

Adapter bazaviy modelning o‘zi emas. QLoRA adapterini inference uchun ham 4-bit bazaga yuklash mumkin:

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
from peft import PeftConfig, PeftModel

adapter = "outputs/my-model"
info = PeftConfig.from_pretrained(adapter)
tokenizer = AutoTokenizer.from_pretrained(adapter)
dtype = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
base = AutoModelForCausalLM.from_pretrained(
    info.base_model_name_or_path,
    quantization_config=BitsAndBytesConfig(
        load_in_4bit=True, bnb_4bit_quant_type="nf4",
        bnb_4bit_use_double_quant=True, bnb_4bit_compute_dtype=dtype,
    ),
    device_map={"": 0},
    torch_dtype=dtype,
)
model = PeftModel.from_pretrained(base, adapter).eval()
model.config.use_cache = True
prompt = "### Instruction:\nFine-tuning nima?\n\n### Response:\n"
inputs = tokenizer(prompt, add_special_tokens=False, return_tensors="pt").to("cuda:0")
with torch.inference_mode():
    answer = model.generate(**inputs, max_new_tokens=128, do_sample=False,
                            pad_token_id=tokenizer.pad_token_id)
print(tokenizer.decode(answer[0, inputs["input_ids"].shape[1]:], skip_special_tokens=True))
```

Agar treningda `revision` ishlatgan bo‘lsangiz, bazani inference’da ham aynan o‘sha revision bilan yuklang.

`bengo merge ADAPTER OUTPUT` bazani CPU’da FP32 ko‘rinishda qayta yuklab, adapterni qo‘shadi. Natija quantization qilinmagan to‘liq model bo‘ladi. Masalan, 7B FP32 og‘irliklarining o‘zi taxminan 28 GB; merge uchun bundan ortiq RAM kerak. Merge majburiy emas. QLoRA adapterini original bazaga merge qilish quantized inference bilan aynan bir xil natija bermasligi mumkin. Custom remote code talab qiladigan model uchun merge helper bu versiyada mo‘ljallanmagan.

## Testlar

```bash
python -m unittest discover -s tests -v
```

Konfiguratsiya, CLI, VRAM hisobi va interfeys testlari faqat PyYAML va rich bilan, ML kutubxonalarisiz ishlaydi: YAML qat’iyligi, flag override’lari va ustuvorlik tartibi, ikkala til katalogining mosligi, xato maslahatlari, parametr sanash formulasi, retseptlarning o‘z byudjetiga sig‘ishi va ASCII fallback shular jumlasidan.

ML dependencies o‘rnatilsa, testlar internetdan model yuklamay, kichik tasodifiy GPT-2 modelini yaratib haqiqiy full/LoRA training, vazn yangilanishi, streaming, save/reload, merge ekvivalentligi va checkpoint resume’ni tekshiradi. Bu model sifati benchmark’i emas.

CUDA tekshiruvi uchun mos GPU va QLoRA dependencies mavjud bo‘lishi kerak; GPU sinovi alohida opt-in qilinadi. `VALIDATION.md`da ushbu paket tayyorlangan muhitdagi aniq natijalar berilgan. Dependency diapazonlari `pyproject.toml`da chegaralangan; barcha versiya kombinatsiyalari sinovdan o‘tgan degani emas.

```bash
# Linux / WSL2: haqiqiy 4-bit training tekshiruvi, model yuklab olishsiz
CUDA_VISIBLE_DEVICES=0 RUN_QLORA_TEST=1 python -m unittest discover -s tests -p test_training.py -v
```

## Paket

Metadata `pyproject.toml`da. Versiya bitta joyda — `src/bengo/__init__.py` ichidagi `__version__`; `pyproject.toml` uni `dynamic` orqali o'qiydi, shuning uchun ikki joyda yangilash shart emas.

```bash
python -m pip install -e ".[dev]"
python -m build              # dist/ ichiga sdist va wheel
```

Source distribution `README.md`, `LICENSE`, `bengo.yaml`, `examples/`, `VALIDATION.md` va testlarni o'z ichiga oladi (`MANIFEST.in`). Wheel faqat `bengo` paketini o'rnatadi.

`torch` majburiy bog'liqlik ro'yxatida, lekin uni **avval o'zingiz o'rnating**: PyPI'dagi standart torch wheel Windows'da CPU-only, Linux'da esa qat'iy CUDA versiyasiga bog'langan. O'rnatilgan torch talabni qanoatlantirsa, pip unga tegmaydi. `bengo doctor` CUDA build yo'qligini aniqlaydi va nima qilish kerakligini aytadi.

PyPI'da chop etilmagan; `bengo` nomi band emasligi tekshirilmagan.

## Litsenziya

MIT — `LICENSE` fayliga qarang.

## Texnik asoslar

- [PEFT quantization va k-bit training](https://huggingface.co/docs/peft/developer_guides/quantization)
- [Transformers bitsandbytes](https://huggingface.co/docs/transformers/en/quantization/bitsandbytes)
- [Transformers Trainer](https://huggingface.co/docs/transformers/v4.57.1/en/main_classes/trainer)
- [PyTorch o‘rnatish](https://pytorch.org/get-started/locally/)
