| # CMF v2 — Спецификация формата |
|
|
| *Языки: [English](SPEC.md) · **Русский** · [中文](SPEC.zh.md)* |
|
|
| **Cortiq Model Format** — единый файл, несущий всё необходимое для |
| разреженного, маршрутизируемого по задачам инференса: квантованные веса, |
| токенизатор, маски по задачам, предвычисленный разреженный |
| индекс — и, что уникально, **рой скиллов**, разделяющих одну базовую модель |
| (Patent 15). |
|
|
| > Нормативный источник: этот документ. Референсные |
| > реализации: Rust-ридер/рантайм (`crates/cortiq-core`, |
| > `crates/cortiq-engine`), Python-райтер (`converter/`) и |
| > ридер на Python без зависимостей (`python/cmf_reader.py`, только numpy). |
| |
| Три требования, в порядке приоритета: |
| |
| 1. **Корректность.** Никаких режимов тихого повреждения: строгий magic, |
| версия, `required_features`, границы на каждую секцию, 64-битный хэш на |
| каждый тензор. Файл либо валиден, либо open() возвращает ошибку — третьего |
| состояния нет. |
| 2. **Скорость.** Секция весов выровнена по странице для mmap, каждый тензор |
| выровнен по 64 байтам (SIMD без копирования), каталог тензоров бинарный — |
| читается без разбора. Холодные (замаскированные) веса не стоят RSS. |
| 3. **Компактность.** Маски упакованы побитово (1 бит на нейрон), веса — |
| q4/q8/переменной битности, весь файл адресуется одним 128-байтовым |
| конвертом. |
|
|
| Гармония достигается не количеством фич, а **единым каноном**: одна |
| раскладка на уровень (конверт, каталог, квант-блок, маска), байт-в-байт |
| совместимая с валидированным форматом `.vmfc` v2 там, где домены |
| пересекаются (каталог тензоров, раскладки квантования, `hash64`). Никогда |
| двух определений одного и того же. |
|
|
| Физическая основа (VMF): модель — это вакуумный конденсат 𝒲; скилл — его |
| регулярный кор выше критической плотности; маска задачи выбирает активное |
| подмножество, не меняя веса. Формат несёт следствия |
| этой физики (двухполевое 𝒲×θ квантование, Born-важность, критический порог |
| маски) — но **только те, что подтверждены измерением**. |
|
|
| --- |
|
|
| ## 1. Конверт (фиксированные 128 байт) |
|
|
| Все целые числа — little-endian. |
|
|
| ``` |
| [0x00 : 0x04] magic = b"CMF\x01" (4 bytes) |
| [0x04 : 0x08] version : u32 = 2 |
| [0x08 : 0x0C] flags : u32 (reserved, 0) |
| [0x0C : 0x10] required_features : u32 (bitmask, §1.1) |
| [0x10 : 0x18] header_off : u64 (= 128) |
| [0x18 : 0x20] header_len : u64 — JSON header (§2) |
| [0x20 : 0x28] dir_off : u64 — tensor directory (§3) |
| [0x28 : 0x30] dir_len : u64 |
| [0x30 : 0x38] data_off : u64 — weight blob; multiple of 4096 (§4) |
| [0x38 : 0x40] data_len : u64 |
| [0x40 : 0x48] masks_off : u64 — masks section (§5); 0 = absent |
| [0x48 : 0x50] masks_len : u64 |
| [0x50 : 0x58] vocab_off : u64 — tokenizer (§6); 0 = absent |
| [0x58 : 0x60] vocab_len : u64 |
| [0x60 : 0x68] index_off : u64 — sparse index (§7); 0 = absent |
| [0x68 : 0x70] index_len : u64 |
| [0x70 : 0x80] reserved : 16 bytes (§8.1: header/dir hashes) |
| ``` |
|
|
| Порядок секций на диске: конверт → JSON-заголовок → каталог → **блоб |
| весов (выровнен по 4096)** → маски → словарь → разреженный индекс. Ридер |
| ОБЯЗАН адресовать секции ТОЛЬКО через конверт, никогда не предполагая |
| порядка. |
|
|
| ### 1.1 `required_features` |
| |
| Бит, которого ридер не знает → ошибка `UnsupportedFeature` (fail-fast; |
| никакого «читаем как можем»). |
| |
| | bit | name | значение | |
| |-----|----------------|---------| |
| | 0 | `TENSOR_DIR` | бинарный каталог тензоров (всегда установлен в v2) | |
| | 1 | `BINARY_MASKS` | секция масок (§5) присутствует | |
| | 2 | `QUANT_2F` | каталог содержит тензоры `q8_2f`/`vbit` (двухполевое 𝒲×θ квантование) | |
| | 3 | `DELTA_MASKS` | reserved: XOR-дельты масок от родителя | |
| | 4 | `HOT_PACKS` | reserved: материализованные плотные срезы | |
| | 5 | `LOOP_MASKS` | ряды масок хранятся ПО ВИЗИТАМ (физические слои × циклы, проход-мажорно) — у зацикленного трансформера каждый проход несёт независимую маску (§5.1) | |
| | 6 | `SKILL_FILE` | файл — САМОСТОЯТЕЛЬНЫЙ СКИЛЛ: частичный набор тензоров, вырезанный против конкретной базы и привязанный ключом `SkillRecord.base_dir_hash` (§9.1). Не запускается — прикладывается через `cortiq skill apply` | |
|
|
| Неизвестные поля **header-JSON** игнорируются (аддитивная эволюция); |
| ломающие изменения проходят только через биты фич или инкремент `version`. |
|
|
| ### 1.2 Правила валидации (нормативные) |
|
|
| Ридер ОБЯЗАН вернуть ошибку (не значение по умолчанию, не предупреждение), |
| когда: |
|
|
| - magic ≠ `CMF\x01` → `InvalidMagic`; |
| - `version` ≠ 2 → `UnsupportedVersion` (v1 мертва: реальных файлов v1 |
| не существует, программа поддержки не будет запущена); |
| - установлен неизвестный бит `required_features` → `UnsupportedFeature`; |
| - любая секция выходит за EOF, `data_off` не кратен 4096, |
| `off + nbytes` тензора превышает `data_len` → `Bounds`; |
| - имя тензора не UTF-8, dtype неизвестен, `ndim > 6` → `Parse`. |
|
|
| Проверка хэша тензоров — по требованию (`cortiq verify`, флаг загрузчика), |
| не при каждом open: страницы mmap читаются лениво. |
|
|
| ## 2. JSON-заголовок |
|
|
| UTF-8 JSON, без выравнивания. Критичные для машины данные живут в бинарных |
| секциях; JSON несёт архитектуру и происхождение — те части, что читает |
| человек. |
|
|
| ```jsonc |
| { |
| "format": "cmf", |
| "version": 2, |
| "arch": { |
| "arch_name": "qwen3.5", |
| "hidden_size": 5120, "intermediate_size": 17408, |
| "num_layers": 64, "num_attention_heads": 24, "num_kv_heads": 4, |
| "head_dim": 256, "vocab_size": 248320, |
| "layer_types": ["LinearAttention", "...", "FullAttention"], |
| "rms_norm_eps": 1e-6, |
| "norm_style": "qwen", // "qwen": x̂·w | "gemma": x̂·(1+w) |
| "rope_theta": 1000000.0, |
| "tie_word_embeddings": false, |
| "max_position_embeddings": 262144, |
| "linear_conv_kernel_dim": 4, |
| "linear_num_key_heads": 16, "linear_num_value_heads": 48 |
| }, |
| "quant_type": "Q4_BLOCK", // informational default; truth = per-tensor dtype in the directory |
| "provenance": { "tool": "…", "source_model": "…" } // optional, free-form |
| } |
| ``` |
|
|
| `norm_style` обязателен для движка: gemma-стиль `(1+w)`, применённый к |
| весам Qwen, — это тихий мусор во всех ~130 нормализациях |
| прямого прохода. |
|
|
| Диспетчеризация возможностей **управляется наличием тензоров**: движок |
| решает по-слойно, какие операторы применять, по тому, что есть в каталоге |
| (q/k-смещения, qk-нормы, выходной гейт по ширине проекции, MoE-роутер, |
| GDN-проекции) — а не по совпадению имён моделей. Новые модели известного |
| семейства загружаются с нулевыми изменениями движка. |
|
|
| ### 2.1 MTP — предсказание нескольких токенов (опционально) |
|
|
| Если модель несёт MTP-голову (в стиле DeepSeek/Qwen), arch объявляет: |
|
|
| ```jsonc |
| "mtp": { "num_layers": 1, "share_lm_head": true, "share_embed": true } |
| ``` |
|
|
| Тензоры MTP — обычные записи каталога под каноническими именами |
| (`model.mtp.*`): `enorm.weight`, `hnorm.weight`, |
| `eh_proj.weight [hidden, 2·hidden]`, `layers.{i}.*` (стандартный |
| блок трансформера), `norm.weight`. |
|
|
| Семантика: `x = eh_proj·[enorm(embed(t_{p+1})); hnorm(h_p)]` — эмбеддинг |
| ПЕРВЫМ (проверено оракулом: обратный порядок даёт ровно 0% принятия) |
| → блок → общий lm_head → черновик токена `t_{p+2}`. Ридер не |
| обязан исполнять MTP (метаданные + обычные тензоры, аддитивная |
| эволюция, без бита фичи); рантайм CMF использует голову для |
| спекулятивного декодинга со строгой гарантией: **выход в точности равен |
| обычному жадному декодингу** — отклонённый черновик откатывается из KV. |
|
|
| ### 2.2 MoE — FFN со смесью экспертов (опционально) |
|
|
| Если модель несёт MoE-слои (Qwen2-MoE / Qwen3-MoE / Qwen3.5-MoE), |
| arch объявляет: |
|
|
| ```jsonc |
| "moe": { |
| "num_experts": 256, "top_k": 8, "moe_intermediate_size": 512, |
| "norm_topk_prob": true, // Qwen2-MoE: false |
| "shared_expert_intermediate_size": 512 // absent if no shared expert |
| } |
| ``` |
|
|
| Тензоры — обычные записи каталога под HF-именами: |
|
|
| ``` |
| model.layers.{i}.mlp.gate.weight [num_experts, hidden] router |
| model.layers.{i}.mlp.experts.{e}.{gate,up,down}_proj.weight |
| model.layers.{i}.mlp.shared_expert.{gate,up,down}_proj.weight |
| model.layers.{i}.mlp.shared_expert_gate.weight [1, hidden] |
| ``` |
|
|
| Какие слои являются MoE — определяется ПРИСУТСТВИЕМ роутера в |
| каталоге (по-слойно, не по-модельно): `mlp_only_layers`/ |
| `decoder_sparse_step` у Qwen2-MoE дают смешанные модели, и плотные |
| слои сохраняют обычные `mlp.*_proj`. |
|
|
| Семантика исполнения (паритет с HF, под воротами `tests/moe_parity.sh` по |
| четырём семействам, включая фьюженную раскладку AgentWorld): softmax по ВСЕМ |
| логитам роутера → top-k (ничьи: меньший индекс, порядок torch.topk) → если |
| `norm_topk_prob`, перенормировка выбранных k → Σwₑ·FFNₑ(x); общий |
| эксперт всегда добавляется с весом `sigmoid(shared_expert_gate·x)`. |
| Эксперты остаются квантованными в mmap; на токен затрагиваются только |
| страницы выбранных k — та же история резидентности, что и у скиллов. |
| Райтерам СЛЕДУЕТ раскладывать тензоры экспертов слоя ролево-смежно |
| (все `gate_proj` экспертов 0…N−1 подряд, затем все `up_proj`, затем все |
| `down_proj`) — GPU-бэкенды тогда работают с банком экспертов слоя как с |
| одним регионом вместо сборки сотен слайсов; нативный импортёр и |
| `moe-defrag` оба пишут такой порядок. Каждый |
| эксперт — отдельная запись каталога со СВОИМ dtype: это и есть носитель |
| по-экспертного распределения битов (P15 claim 12) — реализовано, под воротами |
| `tests/moe_vbit.sh`; B-поле (частоты выбора роутером через |
| `--route-stats`) измерено end-to-end на модели 35B. |
|
|
| ## 3. Каталог тензоров |
|
|
| Байт-в-байт раскладка `.vmfc` v2 (единый канон, общий референсный |
| парсер): |
|
|
| ``` |
| [0 : 8 ] count : u64 |
| [8 : 16] pool_off : u64 (name-pool offset from section start) |
| [16 : 16 + count·56] 56-byte records: |
| name_off : u32 (relative to pool_off) |
| name_len : u16 |
| dtype : u8 (§3.1) |
| ndim : u8 (≤ 6) |
| shape : u32 × 6 (zero-padded tail) |
| off : u64 (RELATIVE to data_off; multiple of 64) |
| nbytes : u64 |
| hash : u64 (hash64 of the tensor bytes, §8) |
| [pool_off : …] UTF-8 name pool |
| ``` |
|
|
| Имена тензоров **1:1 с исходной моделью** |
| (`model.layers.{i}.mlp.gate_proj.weight`, `model.embed_tokens.weight`, |
| `lm_head.weight`, …). Формат не предписывает набор тензоров: |
| каталог — единственный источник истины о том, что содержит блоб. |
| «Вычисляемой раскладки» не существует. |
|
|
| ### 3.1 `dtype` |
|
|
| Нумерация общая с `.vmfc` (id никогда не переиспользуются): |
|
|
| | id | name | статус в CMF v2 | |
| |----|-----------|------------------| |
| | 0 | `f32` | ✅ чтение/запись | |
| | 1 | `f16` | ✅ чтение/запись (нормы и 1-D всегда f16) | |
| | 2 | `bf16` | ✅ чтение/запись | |
| | 3 | `q8_row` | ✅ чтение/запись | |
| | 4 | `q4_block`| ✅ чтение/запись | |
| | 5 | `mix8_4` | reserved | |
| | 6 | `u8` | reserved | |
| | 7 | `q4_col` | reserved | |
| | 8 | `vbit` | ✅ чтение/запись (бит `QUANT_2F`), переменная 3–8 бит | |
| | 9 | `q8_2f` | ✅ чтение/запись (бит `QUANT_2F`), 𝒲×θ | |
| | 10 | `vbit_ro` | ✅ чтение/запись — `vbit` + таблица row-offsets в файле (O(1) доступ к строке); дефолт конвертера для `--quant vbit` | |
| | 11 | `q4_tiled`| ✅ чтение/запись — q4 интерливными тайлами `[f16 scale][16B nibbles]` (`--quant q4t`) | |
| | 12 | `q1` | ✅ чтение/запись — 1-битные бинарные веса, только для 1-бит-ОБУЧЕННЫХ моделей (`--quant q1`); тайл `[f16 scale][4B бит-знаков]` на 32-группу, `w = s·(2·bit−1)` | |
| | 13 | `q1s` | ✅ чтение/запись — база `q1` + разреженный оверлей выбросов высокой точности (1-битный PTQ обычных чекпойнтов) | |
| | 14 | `q1t` | ✅ чтение/запись — тернарные `{−s, 0, +s}` base-3-тайлы + построчный оверлей выбросов (~2.25 bpw + оверлей) | |
| | 15 | `q4tp` | ✅ чтение/запись — ниббли `q4_tiled`, но масштаб тайла — 5-битная ступень на лестнице строки (`--quant q4tp`, либо `requant` на месте) | |
|
|
| ### 3.2 Раскладки квантования (канон = `.vmfc`: «сначала кванты, затем скейлы») |
|
|
| - **`q8_row`** (только 2-D `[out, in]`): |
| `[int8 : out·in][f16 : out]` — один скейл на строку, |
| `w = q[o,i]·scale[o]`, `scale[o] = absmax(row_o)/127`. |
| - **`q4_block`**: группы по 32 над уплощённым тензором, с нулевым добиванием; |
| `[u8 : ceil(n/32)·16][f16 : ceil(n/32)]`. |
| - **`q4tp`** (только 2-D, `in % 32 == 0`): |
| `[ниббли: rows·gpr·16][параметры строки: rows × (f16 lo, f16 step)] |
| [коды: rows × ceil(gpr·5/8), 5 бит LSB-first, выровнено по строке]`, |
| `gpr = in/32`. Масштаб тайла — `2^(lo[r] + code·step[r])`, поэтому читатель |
| раскрывает 32-ступенчатую лестницу строки один раз и дальше берёт масштабы |
| из таблицы. Значения и порядок нибблов совпадают с `q4_tiled`, отличается |
| только представление масштаба: 4.17 бит/вес против 4.50 — f16-масштаб |
| занимал 11% q4t-файла. `lo`/`step` берутся из точных min/max логарифма |
| масштаба по строке, поэтому код никогда не выходит за диапазон и |
| escape-механизм не нужен. Кодировщик ОБЯЗАН округлить `lo`/`step` до f16 |
| **перед** выбором кодов и квантовать ниббли по восстановленному масштабу — |
| иначе писатель и читатель разойдутся (та же ловушка, из-за которой q4-кодер |
| сначала округляет свой масштаб). |
| Ниблы: элемент `2k` младший, `2k+1` старший; `w = (q − 8)·scale`, |
| `scale = absmax(group)/7`. |
| - **1-D тензоры и тензоры < 32 элементов всегда `f16`** |
| (точность нормализации при максимальном сжатии матриц). |
| - **`q8_2f`**: `[int8][f16 row-scale][f16 col-field]`, |
| `w = q·scale[o]·col[i]` — двухполевой Madelung-сплит 𝒲×θ, валидирован |
| в vmfcore (+37% при равном размере; восстанавливает ~75% разрыва q8→f16 |
| на выбросных входных каналах). |
| - **`vbit`** (только 2-D, `in % 32 == 0`; P13 FIG.3): |
| `[u8 bits: rows][f16 scales: rows·in/32][bit-packed rows, MSB-first, |
| each row padded to a byte]`; `w = (u − L)·scale[r,g]`, |
| `L = 2^{b−1}−1`, уровни b ∈ {3,4,5,6,8}, пол 3 (claim 13). |
| Распределение b_r: water-filling по логарифму амплитуды строки к |
| средней битности тензора; для MoE-экспертов бюджет ОБЩИЙ на всё |
| семейство (слой × проекция): сдвиг `ā_expert − ā_family` |
| эквивалентен совместному water-filling по строкам всех экспертов — громкий |
| эксперт получает больше бит, тихий прижимается к полу (P15 |
| claim 12; ворота `tests/moe_vbit.sh`). Опционально распределение берёт |
| произведение с B-полем — частотами выбора роутером, собранными |
| на калибровке (`b ∝ log2(A·B)`, усечённый Fisher). |
| - **`q1s`** (только 2-D, `in % 32 == 0`): база `q1` (те же 6-байтные |
| тайлы; выбросы ИСКЛЮЧЕНЫ из группового скейла), затем разреженный |
| оверлей: `[u32 count]` и `count × { [u32 плоский-индекс][f16 значение] }` |
| — веса-выбросы, сохранённые в полной точности (голографический |
| перенос / стиль SpQR) и восстанавливаемые дословно при деквантовании. |
| Переменная длина: `expected_nbytes` не определён, ридер доверяет |
| записанному в каталоге размеру. Позволяет ОБЫЧНОМУ чекпойнту пережить |
| 1 бит там, где чистый `q1` не может. |
| - **`q1t`** (только 2-D, `in % 32 == 0`, `in` должен помещаться в |
| `u16`): тернарный BitNet-b1.58-стиль `{−s, 0, +s}`. База: |
| `на 32-группу { [f16 scale][7B base-3 коды] }` — 9-байтные тайлы, |
| 5 тернарных значений на байт (3⁵ = 243 ≤ 256; код 0 → 0, 1 → +s, |
| 2 → −s), ~2.25 бит/вес. Затем построчный оверлей выбросов: |
| `[u32 row_ptr[rows+1]]` и записи `{ [u16 col][f16 значение] }`, |
| сгруппированные по строкам (выбросы строки `r` — диапазон |
| `[row_ptr[r], row_ptr[r+1])`; `col` — индекс внутри строки) — 4 |
| байта на выброс, без бинарного поиска. Точное сохранение множества |
| почти нулевых весов — решающий PTQ-выигрыш над бинарным. Переменная |
| длина, правило размера как у `q1s`. |
|
|
| ## 4. Блоб весов |
|
|
| `data_off` кратен 4096 (выровненный по странице mmap); каждый тензор |
| внутри начинается на границе 64 байт (SIMD-загрузки, кэш-линии). Нулевое |
| добивание между тензорами. Ридер интерпретирует блоб только через |
| каталог. |
|
|
| ## 5. Секция масок |
|
|
| Маска задачи = битовые поля «что активно» над общими весами |
| (веса не меняются — принцип VMF: скилл выбирает подмножество |
| конденсата). |
|
|
| ``` |
| [0 : 4] n_masks : u32 |
| [4 : 8] meta_len : u32 |
| [8 : 8 + meta_len] JSON meta (§5.1) |
| […] mask blobs, each aligned to 8 from the section start |
| ``` |
|
|
| Один блоб маски (размеры выводятся из arch, без внутренних заголовков): |
|
|
| ``` |
| [n_layers × ffn_bytes] FFN bitfields ffn_bytes = ceil(intermediate_size / 8) |
| [n_layers × head_bytes] head bitfields head_bytes = ceil(num_attention_heads / 8) |
| [gates_bytes] layer_gates gates_bytes = ceil(num_layers / 8) |
| [n_layers × expert_bytes] expert bitfields ОПЦИОНАЛЬНО — только когда мета маски |
| ставит "has_expert_fields": true; |
| expert_bytes = ceil(moe.num_experts / 8) |
| ``` |
|
|
| Порядок битов LSB-first: нейрон `i` = бит `i % 8` байта `i / 8`; бит |
| установлен → активен. **Хвостовые биты за пределами размерности ОБЯЗАНЫ |
| быть нулём** (иначе popcount видит фантомные нейроны/головы). |
|
|
| Опциональная экспертная область (аддитивно: старые ридеры не читают |
| дальше gates, а `blob_len` каждой маски явный) позволяет задачной маске |
| сужать РОУТИНГ MoE: бит `e` строки слоя `l` установлен → эксперт `e` |
| маршрутизируем для этой задачи; выбор идёт только по маршрутизируемым, |
| softmax роутера ренормализуется по ним. Это переключаемый в рантайме |
| близнец физического дефрага экспертов из §11.1 — один файл с полным |
| набором экспертов обслуживает много специалистов (`cortiq moe-mask` |
| пишет такие маски, `run --task <имя>` активирует; проверено |
| токен-в-токен с эквивалентным рантайм-ограничением). Слой со строкой |
| все-единицы — без ограничения; маска без области ничего не сужает. |
|
|
| ### 5.1 JSON-мета маски |
|
|
| ```jsonc |
| { |
| "default_task": "general", |
| "masks": [{ |
| "task_id": 0, "name": "general", "description": null, |
| "sparsity": 0.62, |
| "quality": { // null = NOT MEASURED (declaring 1.0 is forbidden) |
| "metric": "heldout_ppl_ratio", "value": 0.97, |
| "baseline_dense": 6.10, "n_samples": 512, "dataset_sha256": "…" |
| }, |
| "parent": null, "priority": "Fallback", "has_hot_pack": false, |
| "blob_off": 4096, "blob_len": 139328 // relative to section start |
| }] |
| } |
| ``` |
|
|
| `quality` — это **контракт на held-out**, а не декларация: конвертер |
| без измеренной метрики пишет `null`; рантайм логирует предупреждение при |
| переключении на неизмеренную маску. |
|
|
| ## 6. Секция токенизатора |
|
|
| Байты HuggingFace `tokenizer.json`, дословно. Модель |
| самодостаточна: один файл = одна единица распространения. Sidecar-файл |
| остаётся отладочным запасным вариантом. |
|
|
| ### 6.1 Chat-бандл (`header.tokenizer_config`) |
| |
| Файл — а не рантайм-бинарник — определяет поведение чата. Заголовок |
| несёт опциональный блок (аддитивная эволюция, без бита фичи): |
| |
| ```json |
| "tokenizer_config": { |
| "chat_template": "<Jinja template from chat_template.jinja or tokenizer_config.json>", |
| "eos_token_ids": [248044, 248045], |
| "bos_token_id": null, |
| "pad_token_id": 248055 |
| } |
| ``` |
| |
| Рантайм рендерит шаблон с семантикой HF (trim_blocks, |
| lstrip_blocks, управление циклами, строковые методы Python) и |
| останавливает генерацию на любом id из `eos_token_ids`. Ворота: |
| `tests/chat_template_parity.sh` — рендер рантайма равен референсному |
| jinja2 байт-в-байт. Файлы без блока получают ChatML-fallback. |
| |
| ## 7. Разреженный индекс |
| |
| Предвычисленный мост «маска → пропуск вычислений»: активные квант-группы |
| FFN (по 32 нейрона каждая) и головы, на пару (задача, слой). |
| |
| > Честный статус: движок берёт активные индексы напрямую из битовых |
| > полей маски; индекс читается и отображается CLI, но в исполнении не |
| > использовался никогда. **Кандидат на деприкацию**: райтерам СЛЕДУЕТ |
| > перестать его писать (ридеры продолжают понимать существующие файлы); |
| > он оживёт, только если путь «маски × квантованный mmap» |
| > материализуется с измеренным выигрышем. |
| |
| ``` |
| [0 : 4] n_entries : u32 |
| [4 : 8] reserved : u32 (0) |
| entry (4-aligned): |
| task_id : u32 |
| layer_idx : u32 |
| n_groups : u32 |
| n_heads : u32 |
| [u16 × n_groups] active FFN-group indices (sorted) |
| [u8 × n_heads] active head indices (sorted) |
| zero padding to a multiple of 4 |
| ``` |
| |
| Группа активна, если содержит хотя бы один активный бит маски. |
| |
| ## 8. `hash64` |
| |
| Некриптографический 64-битный хэш байтов тензора: murmur3 `fmix64` над |
| 64-битными LE-словами с позиционной солью `i·0x9E3779B97F4A7C15`, XOR-свёртка, |
| `xor len`, финальный `fmix64`. Бит-в-бит совместим с |
| `vmfcore.hash64` (Python) и `vmfcore::hash64` (Rust) — хэши |
| общих тензоров совпадают между `.cmf` и `.vmfc` (дедупликация базовой модели между |
| файлами скиллов бесплатна). |
| |
| Использование: `cortiq verify` (детекция повреждений), дедупликация, ключи кэша. |
| |
| ### 8.1 Хэши секций |
| |
| Целостность метаданных (не только тензоров): |
| |
| - Резерв конверта `[0x70:0x78]` = hash64(JSON-заголовок), `[0x78:0x80]` = |
| hash64(каталог). Ноль = «отсутствует» (старые файлы проходят). |
| - JSON-заголовок несёт `section_hashes` — hex hash64 |
| масок/словаря/индекса (u64 как JSON-число потерял бы точность за |
| 2^53). Хэш заголовка в конверте транзитивно покрывает их. |
| - Сам конверт (первые 0x70 байт) не хэшируется: хэш не может |
| защитить сам себя; повреждённые смещения ловятся границами/хэшами дальше |
| по цепочке. |
| - `cortiq verify` проверяет всю цепочку; единственный перевёрнутый байт |
| заголовка — это ошибка. |
| |
| ### 8.2 Отсоединённая подпись (аутентичность, опционально) |
| |
| Хэш-цепочка доказывает целостность, но не авторство. `cortiq sign` |
| пишет отсоединённый `<model>.sig` — JSON `{alg: "ed25519-sha256", |
| pubkey, sha256, sig}`, Ed25519 поверх SHA-256 файла — сам контейнер не |
| переписывается, старый инструментарий не затронут. `cortiq verify` |
| проверяет подпись автоматически, когда `.sig` лежит рядом с моделью; |
| отсутствие — не ошибка. Ключ — файл с 32-байтовым hex-сидом, который |
| подписант хранит приватно. |
| |
| ## Анти-фичи — чего формат намеренно НЕ имеет |
| |
| - **Вычисляемой раскладки весов** — баг-класс #1 в v1 (райтер и ридер |
| «вычисляли» раскладку независимо и расходились). |
| - **Тихих fallback'ов** — v1 интерпретировала любой мусорный файл как «модель |
| 27B»; v2 обязана падать. |
| - **JSON для битовых данных** — маски v1 в JSON раздувались в 3–4×. |
| - **Декларативных полей** — `quality_score: 1.0` по умолчанию, «ёмкости» по |
| закону площади, Born-множители в динамике: метафора не становится |
| полем формата, пока не измерена. |
| |
| ## 9. Скиллы — рой в одном файле (Patent 15, claims 2/12/15) |
| |
| Одна общая базовая модель + K записей на скилл; ни одна запись не хранит полную |
| модель. Хранилище масштабируется как |backbone| + Σ|deltas|. |
| |
| **Замещающие тензоры** — обычные записи каталога с именами |
| `skill.{skill_id}.{name_of_replaced_tensor}`, напр. |
| `skill.sql.model.layers.3.mlp.gate_proj.weight`. Полная логическая форма |
| замещаемого тензора (full-shape — НЕ low-rank, НЕ список diff, НЕ |
| маска), в любой кодировке §3. Помасочный delta-индекс (claim 2) |
| материализуется каталогом: префиксный фильтр даёт скилл → |
| байт-смещения; ленивая пейджинг = mmap-доступ ровно к тем смещениям |
| (claim 12). |
| |
| **Реестр** — JSON-заголовок, аддитивный: |
| |
| ```json |
| "skills": [{ |
| "id": "sql", |
| "name": "SQL assistant", |
| "layers": [3, 4, 5], |
| "selection": {"metric": "mse", "phi_layer": 20, |
| "mean": "<f16 base64>", "basis": "<f16 base64>"}, |
| "input_mask_task": null, |
| "quality": {"metric": "ppl", "backbone": 21.4, "overlaid": 17.9, |
| "dataset_sha256": "…"} |
| }] |
| ``` |
| |
| `selection` держит параметры аффинного подпространства для маршрутизации |
| recon-argmin (`E = ‖r − BBᵀr‖²/‖φ‖²`, выбирается скилл с минимальным E); |
| файл самодостаточен для отбора. `quality` — честный контракт claim-16 |
| (overlaid против backbone на held-out данных). |
| |
| **Семантика исполнения (claims 1/3/18)**: индирекция источника тензора — для |
| каждого тензора рантайм читает ЛИБО запись базовой модели, ЛИБО |
| `skill.{active}.{name}`, если она есть; замещение вместо сложения, |
| полная модель на скилл никогда не собирается (все тензоры — указатели в |
| один mmap). Мягкая суперпозиция (claim 14): смешанные рабочие тензоры |
| `Σwᵢ·Tᵢ`, `wᵢ = softmax(−E/T)`. |
| |
| **Только-добавочный рост (claim 11)**: добавление скилла = дописывание новых |
| тензоров в хвост файла + переиздание каталога/заголовка/индекса в |
| хвост + обновление смещений конверта на месте (смещение 0 фиксировано). Байты и |
| смещения ранее записанных тензоров никогда не меняются; старые байты |
| dir/header становятся мёртвыми хвостами секций (совместимо: ридеры навигируют |
| только через конверт). Компактификация (`converter/cmf_compact.py`) = обычная |
| перезапись. |
| |
| ### 9.1 Самостоятельные скилл-файлы (`SKILL_FILE`, бит 6) |
| |
| Скилл может путешествовать БЕЗ своей базы: `.cmf`, чей набор тензоров — |
| только то, что изменил бейк (плюс каталог масок), привязанный к базе |
| ключами идентичности в записи реестра: |
| |
| ```json |
| "skills": [{ |
| "id": "gfx-html", |
| "layers": [0, 1, "...", 21], |
| "base_dir_hash": "9f22593eb458bc6f", |
| "base_arch": "nanbeige", |
| "task": "specialist", |
| "provenance": {"corpus": "…", "tensors": 30} |
| }] |
| ``` |
| |
| - `base_dir_hash` — hex `hash64` байтов каталога тензоров БАЗЫ (то же |
| значение конверт несёт по адресу `[0x78]`). Скилл — дельта против |
| точных байтов, а не против архитектуры: `apply` ОБЯЗАН отвергнуть |
| базу с другим хешем каталога (явный `--force` может переопределить; |
| результат вне спецификации). |
| - `base_arch`, `task`, `provenance` — информационные ключи: человеческая |
| проверка, задача каталога масок, происхождение. |
|
|
| Любая запись с `base_dir_hash` поднимает бит 6: читатель до этого бита |
| откажет громко, а рантайм, знающий бит, откажется ЗАПУСКАТЬ файл |
| (частичный набор тензоров — не модель) и укажет на |
| `cortiq skill apply <база> <скилл> -o out.cmf`, который проверит ключ, |
| наложит тензоры и маски поверх базы и запишет полный файл — |
| байт-эквивалент специалиста, из которого скилл был вырезан. |
|
|
| Жизненный цикл: `skill bake` (специалист) → `skill export --base` |
| (дельта + ключи) → публикация маленького файла → `skill apply` на любой |
| копии базы. |
|
|
| Статус: полностью реализовано и под воротами (контейнер + индирекция, |
| продакшн-рецепты, маршрутизация recon-argmin, только-добавление + компактификация, |
| soft-blend); claim 16 подтверждён измерением (−24.9% task-PPL в |
| рантайме). |
|
|
| ## 10. Шардинг — модель в N файлах |
|
|
| Именование: `{base}-{no:05}-of-{count:05}.cmf` (духовно совместимо с |
| safetensors). Пользователь открывает ЛЮБОЕ имя; рантайм нормализует к |
| шарду 1 и подбирает соседей по паттерну. |
|
|
| **Каждый шард — самодостаточный валидный .cmf**: полный конверт, JSON-заголовок, |
| каталог СВОИХ тензоров, свой блоб данных, свои хэши |
| (`section_hashes` + по-тензорные). `cortiq verify` работает на любом отдельном |
| шарде без его соседей. |
|
|
| Заголовок каждого шарда несёт: |
|
|
| ```json |
| "shard": { "no": 1, "count": 5 } |
| ``` |
|
|
| Нет блока = обычный одиночный файл (обратно совместимо: старые ридеры видят |
| шард 1 как валидную, но неполную модель и честно падают на отсутствующем |
| тензоре). |
|
|
| **Распределение содержимого**: тензоры разбиваются жадно в каноническом порядке |
| (порог `--shard-max-gb`, грубый размер f32); секции масок/словаря/разреженного |
| индекса, `tokenizer_config` (chat-бандл) и реестр `skills` |
| живут ТОЛЬКО в шарде 1 — у остальных секции пустые и |
| `tokenizer_config: null`. Тензоры скиллов (`skill.{id}.*`) распределяются |
| как обычные записи каталога — реестр шарда 1 ссылается на них по |
| имени через объединённый каталог. |
|
|
| **Загрузка** (`CmfModel::open_sharded`): открыть шард 1 → mmap всех соседей |
| → слияние каталогов (каждая запись помнит свой индекс шарда — рантайм-поле, |
| никогда не пишется на диск) → рантайм далее работает как с одним |
| файлом. Ошибки: прямое открытие не-первого шарда, отсутствующий сосед, |
| несовпадение `count`. |
|
|
| Ворота (Qwen3.5-0.8B q8_2f, 5 шардов ≤ 0.6 GB): шардированная PPL == |
| нешардированной байт-в-байт на том же бинарнике; `verify` зелёный на каждом шарде |
| по отдельности. |
| |
| ## 11. Дефрагментация — физический прунинг (USPTO App. 19/452,464, claims 9/10 — [PATENTS.md](../PATENTS.md)) |
| |
| Маска (§5) — это **виртуальная разреженность**: вырезанные нейроны |
| помечены, но хранятся целиком (все задачи делят один бэкбон — резать |
| физически нельзя, пока не выбрана ОДНА задача). Дефрагментация |
| превращает виртуальную разреженность в **физическое сжатие**: мёртвые |
| FFN-нейроны выбрасываются из файла — они **не хранятся и не |
| вычисляются**. |
| |
| **Представление — без нового фичебита, обратная совместимость.** |
| Физический прунинг выражается ТОЛЬКО меньшими формами тензоров в |
| каталоге (§3 «нет вычислимой раскладки»; каталог — единственный |
| авторитет форм). Рантайм выводит размер FFN из формы тензора |
| (`gate_proj.rows()`), а не из `arch.intermediate_size`, поэтому |
| дефрагированный файл — обычная меньшая dense-модель, которую |
| существующие ридеры грузят без изменений. Секция масок в |
| дефрагированном файле **отсутствует** (после прунинга маска — |
| тождество). `arch.intermediate_size` становится номиналом (= максимум |
| по слоям); истинный размер живёт в каждом тензоре — и каждый слой |
| сжимается до СВОЕГО числа живых нейронов (лучше патента, который обязан |
| резать все слои под `max(active)`). |
|
|
| **Инварианты (обязательные):** тройка слоя `gate_proj.rows() == |
| up_proj.rows() == down_proj.cols() == inter'ₗ` и `down_proj.rows() == |
| hidden_size`; ось нейронов — строки для `gate/up`, столбцы для `down`; |
| квант-группа 32: `down_proj` с `inter' % 32 ≠ 0` пишется как `q8_2f` |
| (конвертер даунгрейдит сам); это НЕ байтовое усечение — деквант → выбор |
| живых → **переквант** в меньшей форме, хэши пересчитываются; |
| `hidden_size`, эмбеддинги, `lm_head` и нормы не трогаются. |
| |
| **Одна задача — автономный файл.** Дефраг деструктивен: один `.cmf` |
| запекает ровно одну задачу. Мульти-задачность остаётся на масках (§5) |
| или скиллах (§9). Провенанс — честный контракт в |
| `provenance.defrag {source_skill, pre_intermediate, |
| post_intermediate_max, kept_per_layer, pruned_ratio}`. |
|
|
| Производство (нативный Rust): `cortiq convert --model … --defrag |
| <skill_dir> --quant q8_2f --output model.cmf`. |
| |
| **Охват:** здесь — dense-FFN-нейроны; MoE-эксперты — в §11.1. Прунинг |
| голов внимания вне охвата. |
| |
| ### 11.1 MoE-дефраг экспертов (`cortiq moe-defrag`) |
| |
| MoE-близнец §11, управляемый B-полем роутинга вместо нейронной маски: |
| использование экспертов сильно задачно (замерено на кодере 34.7B: |
| top-64 наборы экспертов для кода и прозы пересекаются с Jaccard 0.25), |
| поэтому однозадачный файл может выбросить экспертов, к которым задача |
| не маршрутизирует. Из дампа `CMF_MOE_STATS` (пер-слойные счётчики |
| выбора экспертов на репрезентативном прогоне) для каждого слоя |
| сохраняется минимальный top-набор, покрывающий `--cover` записанной |
| массы роутинга; остальные выбрасываются. |
| |
| **Представление — та же философия, без фичебита.** |
| |
| - Оставленные эксперты перенумеровываются в ПЛОТНЫЙ пер-слойный префикс |
| `mlp.experts.0 … mlp.experts.{k−1}` с сохранением относительного |
| порядка; ридер перечисляет экспертов слоя по НАЛИЧИЮ тензоров до |
| `arch.moe.num_experts`, который становится номиналом (= исходное |
| число) — зеркально правилу §11 для `intermediate_size`. |
| - Строки роутера собираются в соответствие в том же порядке: |
| `mlp.gate.weight` становится `[kept_l, hidden]`, и |
| `router.rows() == (число присутствующих экспертов)` — инвариант |
| загрузки. `top_k` клампится к пер-слойному числу экспертов. |
| - Семантика выбора не меняется (§2.2): softmax просто ренормализуется |
| по оставшимся. То же ограничение применимо В РАНТАЙМЕ без перезаписи |
| файла (`CMF_MOE_MASK=<stats.json>` + `CMF_MOE_MASK_COVER`) — |
| математически идентично, так cover-уровень гейтится перплексией до |
| физического выброса. |
| - Payload'ы экспертов копируются дословно (переквант не нужен — ось |
| экспертов режет целые тензоры, не квант-группы), выжившие веса |
| байт-в-байт равны исходным, перезапись стримится из mmap источника. |
|
|
| Замеренный референс (KAT-Coder 34.7B-A3B, кодовая калибровка, cover |
| 0.95): 19.6 → 12.7 ГБ (−35%), ppl held-out кода +2.8%, а на машине с |
| 24 ГБ — где полная модель пейджилась — декод ×1.8, префилл ×3.3. |
|
|
| Вне задачи качество падает по построению; как и в §11, один |
| дефрагированный файл запекает одну задачу. |
|
|
| ## 12. Pipeline-контейнеры — text-to-image в одном файле |
|
|
| Та же машинерия конверт/каталог/блоб несёт не-LLM конвейеры. Отличия — |
| только тег `arch_name` и неймспейсы имён тензоров; ни новых секций, ни |
| фичебита (ридер, не исполняющий конвейер, всё равно валидирует и |
| инспектирует файл). |
|
|
| Текущий экземпляр — `arch_name: "lumina2-image"` (Lumina-Image 2.0, |
| `cortiq imagine-pack` / `cortiq imagine`): один файл содержит весь |
| text-to-image стек. |
|
|
| - **Неймспейсы**: `te.*` — трансформер текст-энкодера (LLM класса |
| Gemma-2; блок `arch` заголовка описывает ИМЕННО эту компоненту, так |
| что общие инструменты читают осмысленные размерности), `dit.*` — |
| денойзер Next-DiT, `vae.*` — VAE-декодер. Config-JSON'ы компонент |
| едут u8-тензорами `{prefix}.config_json` — файл самодостаточен. |
| - **Квантование**: пер-тензорное как всегда (§3, каталог — истина) — |
| обычно q4t/q8 матрицы для te/dit, f16 для свёрток VAE и норм. |
| - **Секция токенизатора** (§6) несёт токенизатор текст-энкодера; |
| `provenance.pipeline` + `provenance.components` называют рецепт. |
|
|
| --- |
|
|
| *Связанное: [COMPARISON.md](COMPARISON.md) (CMF против других форматов моделей), |
| [README проекта](../README.md) (обзор и быстрый старт), |
| `python/cmf_reader.py` (автономный ридер: stdlib + numpy, читает каждый |
| dtype, шарды, скиллы, verify).* |
|
|
