README.ru.md

# Giga Embeddings 0826 3B GGUF — русские текстовые эмбеддинги для llama.cpp и Ollama

[English](README.md) ·
[Коллекция GGUF](https://huggingface.co/collections/ai-babai/giga-embeddings-0826-gguf-llamacpp-and-ollama) ·
[Исходная модель](https://huggingface.co/ai-sage/Giga-Embeddings-instruct-3B-0826) ·
[Компактная GGUF-версия 480M](https://huggingface.co/ai-babai/giga-embeddings-0826-480m-gguf) ·
[Оригинальная статья](https://arxiv.org/abs/2608.23806)

**Русские текстовые эмбеддинги** для семантического поиска, RAG, сравнения
текстов, кластеризации и классификации на русском и английском языках. В
репозитории лежат эталонный BF16 и три прямых кванта двунаправленной модели
Giga Embeddings 3B 0826 для stock `llama.cpp` и Ollama.

**Это только embedding-модель:** используйте `llama-server --embeddings` или
Ollama `POST /api/embed`. Она не предназначена для чата или генерации текста.

**Начинайте с `Q8_0`.** Это рекомендуемый баланс качества и размера.
`Q4_K_M` стоит выбирать, только если важнее всего размер загрузки и память: это
явно экспериментальный лёгкий вариант. BF16 — высокоточный reference. Q6_K
сохранён для исследований, но не является лучшим default вместо Q8 или Q4.

Это независимая GGUF-конверсия `ai-babai`, а не официальный релиз `ai-sage`.

![Выбор GGUF-кванта по размеру файла, памяти, скорости и качеству](assets/giga-embeddings-0826-gguf-choice.png)

## Выбор кванта за 10 секунд

| Вариант | Для чего | Размер файла | Экономия к BF16 | Память Metal | Peak VRAM CUDA |
|---|---|---:|---:|---:|---:|
| [BF16](giga-embeddings-0826-3b-bf16.gguf) | высокоточный reference | 6,31 ГБ | — | 8,00 ГБ | не измерялось |
| [**Q8_0**](giga-embeddings-0826-3b-q8_0.gguf) | **рекомендуемый default** | **3,35 ГБ** | **46,8%** | **5,04 ГБ** | **5,38 ГБ** |
| [Q6_K](giga-embeddings-0826-3b-q6_k.gguf) | исследование / owner review | 2,59 ГБ | 58,9% | 4,28 ГБ | 4,62 ГБ |
| [Q4_K_M](giga-embeddings-0826-3b-q4_k_m.gguf) | лёгкий / экспериментальный | 1,96 ГБ | 68,9% | 3,65 ГБ | 3,99 ГБ |

На Apple Silicon unified memory общая: Metal allocation и RSS — разные срезы
одной памяти, их нельзя складывать. Peak RSS в тех же Mac-тестах составил
8,21 / 5,20 / 4,45 / 3,84 ГБ для BF16 / Q8_0 / Q6_K / Q4_K_M. В этом разделе
используются десятичные гигабайты (`1 ГБ = 10^9 байт`); исходные измерения в
MiB пересчитаны в ГБ.

[SHA256SUMS](SHA256SUMS) · [Машиночитаемый manifest](manifest.json)

## Быстрый старт

```bash
hf download ai-babai/giga-embeddings-0826-3b-gguf \
  giga-embeddings-0826-3b-q8_0.gguf \
  --local-dir .
```

```bash
llama-server \
  -m giga-embeddings-0826-3b-q8_0.gguf \
  --embeddings \
  -c 2048 -b 2048 -ub 2048 -np 1 \
  --cache-type-k f32 --cache-type-v f32 \
  --flash-attn auto -ngl 99 \
  --host 127.0.0.1 --port 8080
```

Для запуска только на CPU замените `-ngl 99` на `-ngl 0`.

В retrieval-задачах инструкция добавляется только к **запросу**, а документы
кодируются без префикса:

```bash
curl http://127.0.0.1:8080/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "giga-embeddings-0826-3b-q8_0.gguf",
    "input": [
      "Instruct: Given a query, retrieve relevant passages\nQuery: Где находится Москва?",
      "Москва — столица Российской Федерации.",
      "Париж — столица Франции."
    ]
  }'
```

Результат — L2-нормированные векторы размерности 2048. Их можно сравнивать
скалярным произведением, эквивалентным cosine similarity. Для симметричных
задач вроде STS или дедупликации используйте одну инструкцию с обеих сторон
или не используйте её. В GGUF уже записан правильный mean pooling; CLS или
last-token pooling дадут неверный результат.

## Быстрый старт с Ollama

После загрузки `giga-embeddings-0826-3b-q8_0.gguf` создайте рядом `Modelfile`:

```dockerfile
FROM ./giga-embeddings-0826-3b-q8_0.gguf
```

Импортируйте embedding-модель и вызовите API:

```bash
ollama create giga-embeddings-0826-3b-q8 -f Modelfile

curl http://127.0.0.1:11434/api/embed \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "giga-embeddings-0826-3b-q8",
    "input": [
      "Instruct: Given a query, retrieve relevant passages\nQuery: Где находится Москва?",
      "Москва — столица Российской Федерации."
    ]
  }'
```

BF16, Q8_0, Q6_K и Q4_K_M проверены с Ollama 0.33.3 на Apple M4 Pro Metal.
Каждый файл импортируется как embedding-only Qwen3 и возвращает конечные
L2-нормированные 2048-мерные векторы. Это compatibility smoke test, а не
Ollama-бенчмарк качества или скорости.

## Качество

Авторы исходной модели приводят 74,57 Russian MTEB, 71,93 English MTEB, 76,93
code MTEB и 63,9 multilingual MTEB. Это метрики оригинального BF16; полный MTEB
для этих GGUF мы не перезапускали.

Наш `giga-embeddings-external-retrieval-v1` использовал полные зафиксированные
test splits RuBQ (`e19b6ffa60b3bc248e0b41f4cc37c26a55c2a67b`) и SciFact
(`d56462d0e63a25450459c4f213e49ffdb866f7f9`), instruction-prefixed queries,
документы в формате `title + "\n" + text` и лимит 512 токенов. Ниже — равный
macro-average двух задач. Это не полный MTEB, не leaderboard submission и не
сравнение разных моделей.

| Вариант | NDCG@10 | MRR@10 | Recall@10 | Изменение NDCG к BF16 |
|---|---:|---:|---:|---:|
| BF16 | 0,778758 | 0,767285 | 0,895762 | reference |
| **Q8_0** | **0,778431** | **0,767302** | **0,893750** | **−0,0327 points** |
| Q6_K | 0,779334 | 0,768964 | 0,895146 | +0,0576 points¹ |
| Q4_K_M | 0,778297 | 0,769349 | 0,888652 | −0,0461 points |

¹Небольшой положительный delta не доказывает улучшение Q6_K. Отдельное
сравнение сохранения представлений выявило один воспроизводимый длинный
пример с кодом, на котором Q6_K отклоняется сильнее.

Более строгий frozen multilingual/code holdout сравнивал кванты с нашим BF16:

| Вариант | Min / mean cosine | Top-1 | Mean top-10 overlap |
|---|---:|---:|---:|
| Q8_0 | 0,993540 / 0,999734 | 100,00% | 99,06% |
| Q6_K | 0,974783 / 0,997845 | 99,61% | 97,07% |
| Q4_K_M | 0,950085 / 0,982052 | 96,88% | 91,37% |

Все четыре файла прошли функциональную runtime-проверку. Q4 помечен
экспериментальным из-за большего отклонения представлений, хотя его потеря
полного RuBQ+SciFact NDCG невелика. Более низкий минимум Q6_K относится к
одному воспроизводимому длинному примеру с кодом.

## Измеренная скорость

Median total throughput после двух прогревов и по пяти повторам, context 2048,
parallelism 1:

| Backend / нагрузка | BF16 | Q8_0 | Q6_K | Q4_K_M |
|---|---:|---:|---:|---:|
| Apple M4 Pro Metal, 1×512 | 976 tok/s | 834 tok/s | 907 tok/s | 799 tok/s |
| Apple M4 Pro Metal, 16×1024 | 864 tok/s | 788 tok/s | 661 tok/s | 732 tok/s |
| Apple M4 Pro CPU, 1×512 | 243 tok/s | 345 tok/s | 149 tok/s | 189 tok/s |
| Apple M4 Pro CPU, 16×1024 | 298 tok/s | 275 tok/s | 140 tok/s | 205 tok/s |
| RTX PRO 4500 CUDA, 1×512 | не измерялось | 10 031 tok/s | 8 460 tok/s | 9 393 tok/s |
| RTX PRO 4500 CUDA, 16×1024 | не измерялось | 11 185 tok/s | 9 141 tok/s | 10 263 tok/s |

Mac — Apple M4 Pro с 48 ГБ unified memory. На Metal BF16 оказался быстрее всех
квантов: здесь квантизация нужна прежде всего для экономии хранения и памяти.
Q6_K также оказался необычно медленным на проверенных CPU и CUDA.

## Проверенные runtime

Валидация выполнена на чистом stock `ggml-org/llama.cpp` commit
`e750b887a82719c27200b71545f63ed78ec24719` (Linux build 10763).

| Runtime/backend | BF16 | Q8_0 | Q6_K | Q4_K_M |
|---|---|---|---|---|
| macOS Apple Silicon / Metal, CLI + server | проверено | проверено | проверено | проверено |
| macOS Apple Silicon / CPU, server resource API | проверено | проверено | проверено | проверено |
| Clean stock Linux / CUDA, CLI + server | проверено | проверено | проверено | проверено |
| Clean stock Linux x86 CPU, CLI + server | не проверено | проверено | не проверено | проверено |
| Ollama 0.33.3 / Apple Metal | проверено | проверено | проверено | проверено |

Все Linux-lanes прошли `llama-embedding`, `llama-server --embeddings`, single,
batch, repeat, permutation, dimension, finiteness и unit-norm checks. Отдельный
перезапуск server process повторил те же восемь эмбеддингов на каждом
проверенном Linux backend: cosine 1,0 и максимальная покомпонентная delta 0.

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

- Назначение: dense retrieval/RAG, semantic similarity, clustering и
  classification на русском и английском. Это не генеративная модель и не
  cross-encoder reranker.
- BF16 прошёл строгий Mac Metal → CUDA numerical parity gate. Q8_0 и Q6_K
  сохранили 8/8 top-1, но едва не прошли frozen mean-cosine порог: наблюдалось
  около 0,99987 при требовании 0,99990. У Q4_K_M drift больше: mean cosine
  около 0,99929–0,99937, top-1 от 6/8 до 8/8 между lanes.
- Portability sample содержит восемь exact prompts. Все within-backend repeat,
  permutation и fresh-process проверки прошли: это backend arithmetic drift,
  а не признак повреждения GGUF.
- Resource-тесты ограничены context 2048; workload 4096 и настоящий
  cold-cache startup не измерялись.
- Во внешнем retrieval использовался лимит 512 токенов; 10,3% документов
  SciFact были обрезаны.
- Ollama сохраняет Q8_0/Q6_K/Q4_K_M как побайтово идентичные GGUF model
  layers. При импорте BF16 он выполняет внутреннюю COPY-перезапись того же
  размера с сохранением типа модели и metadata: функциональная совместимость
  подтверждена, но после импорта BF16 исполняется не byte-for-byte.
- Windows, Linux Ollama, LM Studio, Jan и старые версии `llama.cpp`/Ollama не
  тестировались.

## Целостность и происхождение

| Файл | Байты | SHA-256 |
|---|---:|---|
| `giga-embeddings-0826-3b-bf16.gguf` | 6 307 610 848 | `61820afd79134c8b3691fba0442aa203916d9a0c6101438a5e0a0bee61217919` |
| `giga-embeddings-0826-3b-q8_0.gguf` | 3 354 067 168 | `429f2d04a968ffe73137fe65c2e458a08236056168b905d208b4d81ecab08c22` |
| `giga-embeddings-0826-3b-q6_k.gguf` | 2 591 068 384 | `e7956ee5c0f0e6f776cc67c643f1cd99575697b928c373b644a31fb34b3dc247` |
| `giga-embeddings-0826-3b-q4_k_m.gguf` | 1 960 915 168 | `9f81d6e5015fc981d1c4ac9d66b8179efa4af21c7b2ce6d39acf04d0cdc9f5b5` |

- Исходник: `ai-sage/Giga-Embeddings-instruct-3B-0826`
- Exact revision: `ed7db5c91b900b39381b27b6e9c0a3d31137cd29`
- Лицензия исходника: MIT
- Source `model.safetensors` SHA-256:
  `de8519bef7ee360043970b0081088c5294e2a9196ad2d0570a33c4f51bb2e134`
- Source `tokenizer.json` SHA-256:
  `6fb1280bd7fd529f425929b5df823a5a44485cd7fa9679d1ec1acaac4962e8ca`
- Source `tokenizer_config.json` SHA-256:
  `843eeba481465c1485a5b5f24bd24d6c12c4e502c16f093c3ab6a0f058c2c5f2`
- Converter: локальный bidirectional-model patch
  `409723a88b12071974ed5924a2dc1c8b2b2064f7` поверх upstream `llama.cpp`
  `e750b887a82719c27200b71545f63ed78ec24719`
- Clean stock Linux validation runtime:
  `ggml-org/llama.cpp@e750b887a82719c27200b71545f63ed78ec24719`, build 10763
- Validation harness: `7ba4e00e76b27316b1b3709476d807958bcd1e9d`
- Q8_0, Q6_K и Q4_K_M квантованы напрямую из принятого BF16 GGUF, без cascade
  или requantization
- Сохранены bidirectional Qwen3, 398/398 tensors, mean pooling и dimension 2048

Машиночитаемые provenance и хеши лежат в `manifest.json` и `SHA256SUMS`.

## Цитирование

Пожалуйста, указывайте и этот GGUF-релиз, и оригинальную работу
Giga-Embeddings:

```bibtex
@software{popkov2026gigaembeddingsgguf,
  author  = {Maksim Popkov},
  title   = {Giga Embeddings 0826 GGUF},
  year    = {2026},
  url     = {https://huggingface.co/ai-babai/giga-embeddings-0826-3b-gguf}
}

@misc{kolodin2026gigaembeddings,
  title         = {Giga-Embeddings: Mixture-of-Experts Encoders for High-Throughput Text Embeddings},
  author        = {Egor Kolodin and Egor Krasnoperov and Evgeniy Kosarev and Fyodor Minkin},
  year          = {2026},
  eprint        = {2608.23806},
  archivePrefix = {arXiv},
  url           = {https://arxiv.org/abs/2608.23806}
}
```