Metadata-Version: 2.4
Name: quovantiq
Version: 0.4.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Summary: HF -> GGUF конвертер на чистом Rust
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Quovantiq

Конвертер моделей Hugging Face в формат GGUF на чистом Rust без внешних зависимостей для скачивания.

## Особенности

- **Скачивание моделей** с Hugging Face через встроенный HTTP-клиент (без `huggingface_hub`)
- **Чтение safetensors** через mmap (ленивая загрузка тензоров)
- **Поддержка архитектур**: LLaMA, Mistral, Qwen2, Qwen3, Gemma, Phi, GPT-NeoX, **LFM2 (Liquid AI)** и другие
- **Квантизация**: f32, f16, bf16, q4_0, q4_1, q5_0, q5_1, q8_0, q2_k, q3_k, q4_k, q5_k, q6_k
- **Работает в Termux** на Android
- **Высокая производительность** благодаря Rust и оптимизированному коду

## Установка

```bash
pip install quovantiq
```

Или из исходников:

```bash
git clone https://github.com/lev73748/quovantiq
cd quovantiq
pip install maturin
maturin develop --release
```

Или собрать wheel:

```bash
maturin build --release
pip install target/wheels/quovantiq-*.whl
```

## Использование

### Скачивание и конвертация модели с Hugging Face

```bash
quovantiq --hf microsoft/phi-2 model.gguf
```

### С указанием типа квантизации

```bash
quovantiq --hf microsoft/phi-2 model.gguf q4_k_m
```

### Конвертация локальной модели

```bash
quovantiq /path/to/model/folder model.gguf q4_k_m
```

### Для приватных моделей

```bash
export HF_TOKEN=your_token_here
quovantiq --hf meta-llama/Llama-2-7b-hf llama.gguf
```

### Отладочный вывод

```bash
quovantiq --hf microsoft/phi-2 model.gguf -v
```

## Доступные типы квантизации

| Тип | Описание |
|-----|----------|
| `f32` | Float32, оригинальная точность, самый большой размер |
| `f16` | Float16, баланс размера и точности (по умолчанию) |
| `bf16` | BFloat16 |
| `q4_0` | 4-битная квантизация, базовая |
| `q4_1` | 4-битная квантизация, улучшенная |
| `q5_0` | 5-битная квантизация |
| `q5_1` | 5-битная квантизация, улучшенная |
| `q8_0` | 8-битная квантизация |
| `q2_k` | K-квантизация 2 бита |
| `q3_k_s` | K-квантизация 3 бита, маленькая |
| `q3_k_m` | K-квантизация 3 бита, средняя |
| `q3_k_l` | K-квантизация 3 бита, большая |
| `q4_k_s` | K-квантизация 4 бита, маленькая |
| `q4_k_m` | K-квантизация 4 бита, средняя (рекомендуется) |
| `q5_k_s` | K-квантизация 5 бита, маленькая |
| `q5_k_m` | K-квантизация 5 бита, средняя |
| `q6_k` | K-квантизация 6 бит |

## Поддерживаемые архитектуры

| Архитектура Hugging Face | GGUF |
|--------------------------|------|
| `LlamaForCausalLM` | `LLAMA` |
| `MistralForCausalLM` | `LLAMA` |
| `MixtralForCausalLM` | `LLAMA` |
| `Qwen2ForCausalLM` | `QWEN2` |
| `Qwen3ForCausalLM` | `QWEN3` |
| `GemmaForCausalLM` | `GEMMA` |
| `Gemma2ForCausalLM` | `GEMMA2` |
| `Gemma3ForCausalLM` | `GEMMA3` |
| `PhiForCausalLM` | `PHI2` |
| `Phi3ForCausalLM` | `PHI3` |
| `GPTNeoXForCausalLM` | `GPTNEOX` |
| `StableLmForCausalLM` | `STABLELM` |
| `FalconForCausalLM` | `FALCON` |
| `Lfm2ForCausalLM` | `LFM2` |
| `OlmoForCausalLM` | `OLMO` |
| `OpenELMForCausalLM` | `OPENELM` |
| `InternLM2ForCausalLM` | `INTERNLM2` |
| `MiniCPMForCausalLM` | `MINICPM` |

## Структура проекта

```
quovantiq/
├── Cargo.toml              # Rust зависимости и конфигурация
├── pyproject.toml          # Python-упаковка через maturin
├── src/
│   ├── main.rs             # CLI точка входа
│   ├── lib.rs              # PyO3 обёртки для Python
│   ├── gguf_convert.rs     # Основная логика конвертации
│   ├── gguf_writer.rs      # Запись GGUF файлов
│   ├── hf_downloader.rs    # Скачивание с Hugging Face
│   ├── safetensors.rs      # Чтение safetensors через mmap
│   ├── tensor.rs           # Структура тензоров
│   ├── tensor_source.rs    # Ленивая загрузка тензоров
│   ├── tensor_name_map.rs  # Маппинг имён тензоров
│   ├── hf_config.rs        # Парсинг config.json
│   ├── arch_map.rs         # Маппинг архитектур
│   ├── arch_handlers.rs    # Обработчики специфичных архитектур
│   ├── quantize.rs         # Алгоритмы квантизации
│   └── own_vocab.rs        # Парсинг токенизатора
└── python/
    └── quovantiq/
        ├── __init__.py     # Python API
        └── __main__.py     # Entry point для pip
```

## Требования

- **Rust** 1.70+ (для сборки из исходников)
- **Python** 3.8+ (для установки через pip)
- **maturin** (только для разработки)

Для скачивания моделей с Hugging Face не требуется `huggingface_hub`.

## Примеры

### Конвертация Phi-2 с квантизацией q4_k_m

```bash
quovantiq --hf microsoft/phi-2 phi-2-q4.gguf q4_k_m
```

### Конвертация Qwen3 для русского языка

```bash
quovantiq --hf Lev384501/qwen3-0.6b-russian-dialogues qwen-russian.gguf q4_k_m
```

### Конвертация LFM2 (Liquid AI)

```bash
quovantiq --hf liquid-ai/LFM2-1.6B lfm2.gguf f16
```

## Производительность

Благодаря Rust и оптимизациям:
- Конвертация модели на 1.6B параметров занимает ~15-20 секунд
- Минимальное потребление памяти благодаря mmap
- Параллельная обработка тензоров

## Известные ограничения

- **MoE архитектуры** (Mixtral, QwenMoE) требуют специальной обработки экспертов
- **Некоторые экзотические архитектуры** могут требовать ручного добавления в `arch_map.rs`
- **Приватные модели** требуют `HF_TOKEN` в переменных окружения

## Отличие от Python-версии

Этот проект полностью переписан на Rust для:
- ✅ Значительно более высокой производительности (в 5-10 раз быстрее)
- ✅ Минимального потребления памяти
- ✅ Отсутствия зависимостей от numpy/gguf
- ✅ Более надёжной работы на мобильных устройствах
- ✅ Поддержки архитектур с SSM (Mamba, LFM2)

## Лицензия

MIT

## Вклад в проект

Приветствуются pull request'ы! Основные направления для развития:

- Добавление новых архитектур (особенно MoE)
- Оптимизация производительности
- Поддержка дополнительных типов квантизации
- Добавление тестов
- Улучшение документации

## Автор

Lev73748

## Ссылки

- [GitHub](https://github.com/lev73748/quovantiq)
- [PyPI](https://pypi.org/project/quovantiq/)
- [GGUF формат](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md)

