README.md

---
license: mit
library_name: transformers
pipeline_tag: text-generation
language:
- ru
tags:
- llama
- russian
- small-language-model
- sovereign-ai
- text-generation
- instruct
---

<p align="center">
  <img src="https://huggingface.co/longtimedevs/Ru-Small-Instruct/resolve/main/RuSmallInstruct.png" alt="RuSmallInstruct" width="100%" />
</p>

# Ru-Small-Instruct (94.4M): Sovereign Lightweight Language Model

<!-- markdownlint-disable first-line-h1 -->
<!-- markdownlint-disable html -->
<!-- markdownlint-disable no-duplicate-header -->

<div align="center" style="line-height: 1.6; margin-bottom: 12px;">
  <a href="https://long-time.ru" target="_blank" style="margin: 2px;">
    <img alt="Website" src="https://img.shields.io/badge/🌐%20Website-long--time.ru-0284c7?style=for-the-badge&logoColor=white" style="display: inline-block; vertical-align: middle;"/>
  </a>
  <a href="https://huggingface.co/longtimedevs/Ru-Small-Instruct" target="_blank" style="margin: 2px;">
    <img alt="Hugging Face" src="https://img.shields.io/badge/🤗%20Hugging%20Face-Ru--Small--Instruct-ffc107?style=for-the-badge&logoColor=white" style="display: inline-block; vertical-align: middle;"/>
  </a>
  <a href="https://huggingface.co/longtimedevs/Ru-Small-Instruct/blob/main/LICENSE" target="_blank" style="margin: 2px;">
    <img alt="License" src="https://img.shields.io/badge/License-MIT-10b981?style=for-the-badge&logoColor=white" style="display: inline-block; vertical-align: middle;"/>
  </a>
</div>

<div align="center" style="line-height: 1.4; margin-bottom: 20px;">
  <img alt="Parameters" src="https://img.shields.io/badge/Backbone-94.4M%20(~182MB)-818cf8?style=flat-square"/>
  <img alt="Hardware" src="https://img.shields.io/badge/Hardware-RTX%205060%20Ti%20(16GB)-76b900?style=flat-square&logo=nvidia&logoColor=white"/>
  <img alt="Time" src="https://img.shields.io/badge/Trained%20in-~4%20Hours-orange?style=flat-square"/>
  <img alt="Language" src="https://img.shields.io/badge/Language-Russian%20(ru)-ef4444?style=flat-square"/>
  <img alt="Status" src="https://img.shields.io/badge/Zero--Fingerprint-Sovereign%20Weights-emerald?style=flat-square"/>
</div>

<p align="center">
  <a href="https://long-time.ru"><b>Project Homepage & Dev Blog</b> 🚀</a>
</p>

---

> **Обновление от 21.09: Произошло обновление модели — она сильно уменьшила свой вес до ~182 МБ, став моделью на 94.4M параметров. Это было сделано для существенного снижения галлюцинаций.**

---

## Introduction

**Ru-Small-Instruct** — экспериментальная компактная русскоязычная языковая модель класса **SLM (Small Language Model)** с объемом параметров **94.4M** (~182 МБ). Разработана с упором на суверенность весов (**Zero-Fingerprint**): модель обучена с нуля без заимствования базовых чекпоинтов у сторонних корпоративных сетей (Llama 3 от Meta, Qwen от Alibaba, Mistral).

Модель предназначена для исследований локального инференса, работы на маломощном оборудовании, CPU и мобильных чипах, где критичны нулевая задержка (Time-To-First-Token) и полная независимость весов.

---

## ⚠️ Текущий статус модели и честный взгляд (Limitations)

Модель **находится на ранней стадии и пока далека от совершенства**. При компактном объеме в 94.4M параметров она может иногда выдавать неожиданные ассоциации, путать факты или уходить в галлюцинации на коротких или неоднозначных запросах.

> **Этому не стоит удивляться:**  
> Модель **Ru-Small-Instruct** была создана с нуля **всего за 4 часа на одной домашней видеокарте NVIDIA GeForce RTX 5060 Ti (16GB)** — от обучения собственного BPE-токенизатора и фундаментального чтения статей Википедии до финальной диалоговой огранки (SFT).

### Пример реального диалога с текущей версией:

```text
Вы: Привет!
Бот: Здравствуйте! Чем я могу вам помочь?

Вы: Ты кто?
Бот: Я искусственный интеллект — русскоязычная языковая модель, которая позволяет компьютерам 
     понимать и интерпретировать человеческий язык. Он включает в себя использование алгоритмов 
     для обучения и прогнозирования будущих событий на основе данных.
```

Для ультракомпактной модели в 94.4M параметров (~182 МБ), обученной на одном домашнем GPU за 4 часа, способность держать роль, грамотно формулировать сложные термины и помнить синтаксис русского языка — это отличный практический результат.

---

## Architecture & Specifications

<div align="center">

| Спецификация | Значение | Описание |
| :--- | :---: | :--- |
| **Backbone Parameters** | 94.4M (~182 МБ) | Сверхлегкая архитектура |
| **Training Hardware** | 1x NVIDIA RTX 5060 Ti 16GB | Обучение на домашнем железе |
| **Training Time** | ~4 часа | Полный сквозной цикл с нуля |
| **Hidden Dimension ($d_{model}$)** | 896 | Размерность латентного пространства |
| **Intermediate Dimension ($d_{ff}$)** | 2560 | Размерность слоев SwiGLU MLP |
| **Layers** | 16 | Глубина трансформерных блоков |
| **Attention Heads (Q / KV)** | 14 / 2 | Grouped-Query Attention (GQA) |
| **Context Length** | 512 | Окно внимания с поддержкой RoPE |
| **Vocab Size** | 28 672 | Чистый русский ByteLevel BPE |
| **Native Precision** | `bfloat16` / `float16` | Базовый формат хранения |
| **Special Chat Tags** | Custom Cyrillic | Нативная разметка без утечек английских токенов |

</div>

---

## Training Recipe

### 1. Pre-training (Фундаментальное чтение)
Модель прошла фундаментальное обучение с нуля на русскоязычном корпусе:
* **Энциклопедический блок:** срез статей русской Википедии (естественные науки, география, история, технологии).
* **Связная речь и аналитика:** очищенные новостные тексты открытого корпуса «Газета».
* **Упаковка данных:** потоковая конкатенация токенов (Data Packing) с удалением паразитных паддингов.

### 2. SFT & Alignment (Инструкционная доводка)
Для стабилизации ответов проведена диалоговая огранка (Instruction Tuning) с маскированием пользовательского ввода:
* **Инвариантность к регистру:** устойчивость к строчным и заглавным запросам (`привет`, `Привет`, `ПРИВЕТ`).
* **Фактологическое якорение:** очистка от ложных ассоциаций и деловых писем.
* **Нативный диалоговый протокол:** управляющие маркеры `<|юзер|>`, `<|юзерзакончил|>`, `<|я_начал|>`, `<|я_закончил|>`.

---

## Benchmark & Performance

Оценка производительности на локальном оборудовании (NVIDIA GeForce RTX, FP16/BF16):

<div align="center">

| Метрика | Значение |
| :--- | :---: |
| **Generation Speed (RTX Desktop)** | **180 – 210 t/s** |
| **Memory Footprint (Inference)** | **~200 – 250 MB** |
| **Cold Start Time** | **< 0.15 s** |
| **Supported Hardware** | CUDA, Apple Silicon (MPS), CPU, Edge |

</div>

---

## Prompt Encoding

Для получения точных и связных ответов структурируйте промпт с переносами строк:

```text
<|юзер|>
Кто такой слон?
<|юзерзакончил|>
<|я_начал|>
```

Генерация завершается моделью на служебном маркере `<|я_закончил|>`.

---

## Minimal Inference

Запуск инференса на чистом Python через библиотеку `transformers`:

```python
import torch
from transformers import PreTrainedTokenizerFast, LlamaForCausalLM

MODEL_ID = "longtimedevs/Ru-Small-Instruct"
DEVICE = "cuda:0" if torch.cuda.is_available() else "cpu"
DTYPE = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16

# 1. Загрузка модели и токенизатора
tokenizer = PreTrainedTokenizerFast.from_pretrained(MODEL_ID)
model = LlamaForCausalLM.from_pretrained(MODEL_ID, torch_dtype=DTYPE).to(DEVICE)
model.eval()

# 2. Подготовка запроса
user_query = "Привет! Кто ты?"
prompt = f"<|юзер|>\n{user_query}\n<|юзерзакончил|>\n<|я_начал|>\n"
inputs = tokenizer(prompt, return_tensors="pt").to(DEVICE)

# 3. Генерация с остановкой по токену
ai_end_id = tokenizer.convert_tokens_to_ids("<|я_закончил|>")

with torch.no_grad():
    output_tokens = model.generate(
        **inputs,
        max_new_tokens=120,
        temperature=0.25,
        top_p=0.85,
        repetition_penalty=1.15,
        eos_token_id=[ai_end_id, tokenizer.eos_token_id],
        pad_token_id=tokenizer.pad_token_id,
        do_sample=True
    )

# 4. Декодирование ответа
response = tokenizer.decode(output_tokens[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(f"Ru-Small-Instruct: {response.strip()}")
```

---

## Recommended Generation Parameters

| Параметр | Рекомендуемое значение | Описание |
| :--- | :---: | :--- |
| `temperature` | `0.25` | Минимизирует дрейф внимания на компактных весах |
| `top_p` | `0.85` | Отрезает маловероятные токены |
| `repetition_penalty` | `1.15` | Предотвращает зацикливание списков |
| `max_new_tokens` | `120 – 150` | Оптимальная длина реплики |

---

## License

Модель и связанные материалы распространяются под лицензией [MIT License](https://huggingface.co/longtimedevs/Ru-Small-Instruct/blob/main/LICENSE). Веса свободны для коммерческого и исследовательского применения.

---

## Author & Project Info

Разработка, поддержка и сопутствующие проекты:  
🌐 **Официальный сайт автора:** [https://long-time.ru](https://long-time.ru)